diff options
| -rw-r--r-- | doc/ChangeLog | 6 | ||||
| -rw-r--r-- | doc/gawk.info | 1296 | ||||
| -rw-r--r-- | doc/gawk.texi | 107 | ||||
| -rw-r--r-- | doc/gawktexi.in | 107 |
4 files changed, 916 insertions, 600 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index cc2cabdc..5c8d469b 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,9 @@ +2021-06-21 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in (Performance bugs): New section. + (Compiling with MPFR): New section. Thanks to + Peter Lindgren <ogswd-awk@yahoo.com> for the suggestion. + 2021-06-18 Arnold D. Robbins <arnold@skeeve.com> * gawktexi.in (Internationalization): Fix indexing. Thanks to diff --git a/doc/gawk.info b/doc/gawk.info index 079c2d2b..5eef11f6 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -654,6 +654,7 @@ in (a) below. A copy of the license is included in the section entitled * Unix Installation:: Installing 'gawk' under various versions of Unix. * Quick Installation:: Compiling 'gawk' under Unix. +* Compiling with MPFR:: Building with MPFR. * Shell Startup Files:: Shell convenience functions. * Additional Configuration Options:: Other compile-time options. * Configuration Philosophy:: How it's all supposed to work. @@ -683,6 +684,7 @@ in (a) below. A copy of the license is included in the section entitled * Bugs:: Reporting Problems and Bugs. * Bug address:: Where to send reports to. * Usenet:: Where not to send reports to. +* Performance bugs:: What to do if you think there is a performance issue. * Maintainers:: Maintainers of non-*nix ports. * Other Versions:: Other freely available 'awk' implementations. @@ -30637,6 +30639,10 @@ File: gawk.info, Node: Quick Installation, Next: Shell Startup Files, Up: Uni B.2.1 Compiling 'gawk' for Unix-Like Systems -------------------------------------------- +* Menu: + +* Compiling with MPFR:: Building with MPFR. + The normal installation steps should work on all modern commercial Unix-derived systems, GNU/Linux, BSD-based systems, and the Cygwin environment for MS-Windows. @@ -30687,6 +30693,24 @@ will be asked for your password, and you will have to have been set up previously as a user who is allowed to run the 'sudo' command. +File: gawk.info, Node: Compiling with MPFR, Up: Quick Installation + +B.2.1.1 Building With MPFR +.......................... + +Use of the MPFR library with 'gawk' is an optional feature: if you have +the MPFR and GMP libraries already installed when you configure and +build 'gawk', 'gawk' automatically will be able to use them. + + You can install these libraries from source code by fetching them +from the GNU distribution site at 'ftp.gnu.org'. + + Most modern systems provide package managers which save you the +trouble of building from source. They fetch and install the library +header files and binaries for you. You will need to research how to do +this for your particular system. + + File: gawk.info, Node: Shell Startup Files, Next: Additional Configuration Options, Prev: Quick Installation, Up: Unix Installation B.2.2 Shell Startup Files @@ -31348,6 +31372,7 @@ might well want to fix it. * Bug address:: Where to send reports to. * Usenet:: Where not to send reports to. +* Performance bugs:: What to do if you think there is a performance issue. * Maintainers:: Maintainers of non-*nix ports. @@ -31414,7 +31439,7 @@ Guidelines (https://gnu.org/philosophy/kind-communication.html) in your correspondence on the list (as well as off of it). -File: gawk.info, Node: Usenet, Next: Maintainers, Prev: Bug address, Up: Bugs +File: gawk.info, Node: Usenet, Next: Performance bugs, Prev: Bug address, Up: Bugs B.4.2 Please Don't Post Bug Reports to USENET --------------------------------------------- @@ -31437,9 +31462,75 @@ web forums. The steps described here are the only officially recognized way for reporting bugs. Really. -File: gawk.info, Node: Maintainers, Prev: Usenet, Up: Bugs +File: gawk.info, Node: Performance bugs, Next: Maintainers, Prev: Usenet, Up: Bugs + +B.4.3 What To Do If You Think There Is A Performance Issue +---------------------------------------------------------- + +If you think that 'gawk' is too slow at doing a particular task, you +should investigate before sending in a bug report. Here are the steps +to follow: + + 1. Run 'gawk' with the '--profile' option (*note Options::) to see + what your program is doing. It may be that you have written it in + an inefficient manner. For example, you may be doing something for + every record that could be done just once, for every file. (Use a + 'BEGINFILE' rule; *note BEGINFILE/ENDFILE::.) Or you may be doing + something for every file that only needs to be done once per run of + the program. (Use a 'BEGIN' rule; *note BEGIN/END::.) + + 2. If profiling at the 'awk' level doesn't help, then you will need to + compile 'gawk' itself for profiling at the C language level. + + To do that, start with the latest released version of 'gawk'. + Unpack the source code in a new directory, and configure it: + + $ tar -xpzvf gawk-X.Y.Z.tar.gz + -| ... Output ommited + $ cd gawk-X.Y.Z + $ ./configure + -| ... Output ommited + + 3. Edit the files 'Makefile' and 'support/Makefile'. Change every + instance of '-O2' or '-O' to '-pg'. This causes 'gawk' to be + compiled for profiling. + + 4. Compile the program by running the 'make' command: + + $ make + -| ... Output ommited + + 5. Run the freshly compiled 'gawk' on a _real_ program, using _real_ + data. Using an artificial program to try to time one particular + feature of 'gawk' is useless; real 'awk' programs generally spend + most of their time doing I/O, not computing. If you want to prove + that something is slow, it _must_ be done using a real program and + real data. + + Use a data file that is large enough for the statistical profiling + to measure where 'gawk' spends its time. It should be at least 100 + megabytes in size. + + 6. When done, you should have a file in the current directory named + 'gmon.out'. Run the command 'gprof gawk gmon.out > gprof.out'. + + 7. Submit a bug report explaining what you think is slow. Include the + 'gprof.out' file with it. + + Preferably, you should also submit the program and the data, or + else indicate where to get the data if the file is large. + + 8. If you have not submitted your program and data, be prepared to + apply patches and rerun the profiling in order to see if the + patches were effective. + + If you are incapable or unwilling to do the steps listed above, then +you will just have to live with 'gawk' as it is. + + +File: gawk.info, Node: Maintainers, Prev: Performance bugs, Up: Bugs -B.4.3 Reporting Problems with Non-Unix Ports +B.4.4 Reporting Problems with Non-Unix Ports -------------------------------------------- If you find bugs in one of the non-Unix ports of 'gawk', send an email @@ -36883,6 +36974,7 @@ Index * Moon, Sailor: Internationalization. (line 6) * Moore, Duncan: Getline Notes. (line 40) +* MPFR library, building with: Compiling with MPFR. (line 6) * MPFR values, API ownership of: API Ownership of MPFR and GMP Values. (line 6) * MPFR, checking for: Checking for MPFR. (line 6) @@ -37115,6 +37207,7 @@ Index * percent sign (%), %= operator: Assignment Ops. (line 129) * percent sign (%), % operator: Precedence. (line 54) * percent sign (%), %= operator <1>: Precedence. (line 94) +* performance, checking issues: Performance bugs. (line 6) * period (.), regexp operator: Regexp Operator Details. (line 40) * Perl: Future Extensions. (line 6) @@ -37305,6 +37398,7 @@ Index (line 9) * profiling awk programs: Profiling. (line 6) * profiling awk programs, dynamically: Profiling. (line 185) +* profiling, compiling gawk for: Performance bugs. (line 6) * profiling, pretty printing, difference with: Profiling. (line 235) * program identifiers: Auto-set. (line 193) * program, definition of: Getting Started. (line 21) @@ -38098,603 +38192,605 @@ Index Tag Table: Node: Top1200 -Node: Foreword344780 -Node: Foreword449222 -Node: Preface50754 -Ref: Preface-Footnote-153613 -Ref: Preface-Footnote-253722 -Ref: Preface-Footnote-353956 -Node: History54098 -Node: Names56450 -Ref: Names-Footnote-157554 -Node: This Manual57701 -Ref: This Manual-Footnote-164340 -Node: Conventions64440 -Node: Manual History66809 -Ref: Manual History-Footnote-169806 -Ref: Manual History-Footnote-269847 -Node: How To Contribute69921 -Node: Acknowledgments70847 -Node: Getting Started75784 -Node: Running gawk78223 -Node: One-shot79413 -Node: Read Terminal80676 -Node: Long82669 -Node: Executable Scripts84182 -Ref: Executable Scripts-Footnote-186815 -Node: Comments86918 -Node: Quoting89402 -Node: DOS Quoting94928 -Node: Sample Data Files96984 -Node: Very Simple99579 -Node: Two Rules105681 -Node: More Complex107566 -Node: Statements/Lines109898 -Ref: Statements/Lines-Footnote-1114382 -Node: Other Features114647 -Node: When115583 -Ref: When-Footnote-1117337 -Node: Intro Summary117402 -Node: Invoking Gawk118286 -Node: Command Line119800 -Node: Options120598 -Ref: Options-Footnote-1138512 -Ref: Options-Footnote-2138743 -Node: Other Arguments138768 -Node: Naming Standard Input142779 -Node: Environment Variables143989 -Node: AWKPATH Variable144547 -Ref: AWKPATH Variable-Footnote-1147959 -Ref: AWKPATH Variable-Footnote-2147993 -Node: AWKLIBPATH Variable148364 -Ref: AWKLIBPATH Variable-Footnote-1150061 -Node: Other Environment Variables150436 -Node: Exit Status154257 -Node: Include Files154934 -Node: Loading Shared Libraries158624 -Node: Obsolete160052 -Node: Undocumented160744 -Node: Invoking Summary161041 -Node: Regexp163882 -Node: Regexp Usage165336 -Node: Escape Sequences167373 -Node: Regexp Operators173614 -Node: Regexp Operator Details174099 -Ref: Regexp Operator Details-Footnote-1181463 -Node: Interval Expressions181610 -Ref: Interval Expressions-Footnote-1183031 -Node: Bracket Expressions183129 -Ref: table-char-classes185605 -Node: Leftmost Longest188931 -Node: Computed Regexps190234 -Node: GNU Regexp Operators193661 -Node: Case-sensitivity197398 -Ref: Case-sensitivity-Footnote-1200264 -Ref: Case-sensitivity-Footnote-2200499 -Node: Regexp Summary200607 -Node: Reading Files202073 -Node: Records204342 -Node: awk split records205417 -Node: gawk split records210117 -Ref: gawk split records-Footnote-1215191 -Node: Fields215228 -Node: Nonconstant Fields217969 -Ref: Nonconstant Fields-Footnote-1220205 -Node: Changing Fields220409 -Node: Field Separators226440 -Node: Default Field Splitting229138 -Node: Regexp Field Splitting230256 -Node: Single Character Fields233933 -Node: Command Line Field Separator234993 -Node: Full Line Fields238211 -Ref: Full Line Fields-Footnote-1239733 -Ref: Full Line Fields-Footnote-2239779 -Node: Field Splitting Summary239880 -Node: Constant Size241954 -Node: Fixed width data242686 -Node: Skipping intervening246153 -Node: Allowing trailing data246951 -Node: Fields with fixed data247988 -Node: Splitting By Content249506 -Ref: Splitting By Content-Footnote-1253289 -Node: More CSV253452 -Node: Testing field creation255044 -Node: Multiple Line256669 -Node: Getline262946 -Node: Plain Getline265415 -Node: Getline/Variable267988 -Node: Getline/File269139 -Node: Getline/Variable/File270527 -Ref: Getline/Variable/File-Footnote-1272132 -Node: Getline/Pipe272220 -Node: Getline/Variable/Pipe274924 -Node: Getline/Coprocess276059 -Node: Getline/Variable/Coprocess277326 -Node: Getline Notes278068 -Node: Getline Summary280865 -Ref: table-getline-variants281289 -Node: Read Timeout282037 -Ref: Read Timeout-Footnote-1285943 -Node: Retrying Input286001 -Node: Command-line directories287200 -Node: Input Summary288106 -Node: Input Exercises291278 -Node: Printing291712 -Node: Print293546 -Node: Print Examples295003 -Node: Output Separators297783 -Node: OFMT299800 -Node: Printf301156 -Node: Basic Printf301941 -Node: Control Letters303515 -Node: Format Modifiers308679 -Node: Printf Examples314694 -Node: Redirection317180 -Node: Special FD324021 -Ref: Special FD-Footnote-1327189 -Node: Special Files327263 -Node: Other Inherited Files327880 -Node: Special Network328881 -Node: Special Caveats329741 -Node: Close Files And Pipes330690 -Ref: table-close-pipe-return-values337597 -Ref: Close Files And Pipes-Footnote-1338410 -Ref: Close Files And Pipes-Footnote-2338558 -Node: Nonfatal338710 -Node: Output Summary341048 -Node: Output Exercises342270 -Node: Expressions342949 -Node: Values344137 -Node: Constants344815 -Node: Scalar Constants345506 -Ref: Scalar Constants-Footnote-1348016 -Node: Nondecimal-numbers348266 -Node: Regexp Constants351267 -Node: Using Constant Regexps351793 -Node: Standard Regexp Constants352415 -Node: Strong Regexp Constants355603 -Node: Variables358615 -Node: Using Variables359272 -Node: Assignment Options361182 -Node: Conversion363653 -Node: Strings And Numbers364177 -Ref: Strings And Numbers-Footnote-1367240 -Node: Locale influences conversions367349 -Ref: table-locale-affects370107 -Node: All Operators370725 -Node: Arithmetic Ops371354 -Node: Concatenation374070 -Ref: Concatenation-Footnote-1376917 -Node: Assignment Ops377024 -Ref: table-assign-ops382015 -Node: Increment Ops383328 -Node: Truth Values and Conditions386788 -Node: Truth Values387862 -Node: Typing and Comparison388910 -Node: Variable Typing389730 -Ref: Variable Typing-Footnote-1396193 -Ref: Variable Typing-Footnote-2396265 -Node: Comparison Operators396342 -Ref: table-relational-ops396761 -Node: POSIX String Comparison400256 -Ref: POSIX String Comparison-Footnote-1401951 -Ref: POSIX String Comparison-Footnote-2402090 -Node: Boolean Ops402174 -Ref: Boolean Ops-Footnote-1406656 -Node: Conditional Exp406748 -Node: Function Calls408484 -Node: Precedence412361 -Node: Locales416020 -Node: Expressions Summary417652 -Node: Patterns and Actions420225 -Node: Pattern Overview421345 -Node: Regexp Patterns423022 -Node: Expression Patterns423564 -Node: Ranges427345 -Node: BEGIN/END430453 -Node: Using BEGIN/END431214 -Ref: Using BEGIN/END-Footnote-1433968 -Node: I/O And BEGIN/END434074 -Node: BEGINFILE/ENDFILE436387 -Node: Empty439618 -Node: Using Shell Variables439935 -Node: Action Overview442209 -Node: Statements444534 -Node: If Statement446382 -Node: While Statement447877 -Node: Do Statement449905 -Node: For Statement451053 -Node: Switch Statement454224 -Node: Break Statement456665 -Node: Continue Statement458757 -Node: Next Statement460584 -Node: Nextfile Statement462967 -Node: Exit Statement465656 -Node: Built-in Variables468059 -Node: User-modified469192 -Node: Auto-set476959 -Ref: Auto-set-Footnote-1493766 -Ref: Auto-set-Footnote-2493972 -Node: ARGC and ARGV494028 -Node: Pattern Action Summary498241 -Node: Arrays500671 -Node: Array Basics502000 -Node: Array Intro502844 -Ref: figure-array-elements504819 -Ref: Array Intro-Footnote-1507523 -Node: Reference to Elements507651 -Node: Assigning Elements510115 -Node: Array Example510606 -Node: Scanning an Array512365 -Node: Controlling Scanning515387 -Ref: Controlling Scanning-Footnote-1521843 -Node: Numeric Array Subscripts522159 -Node: Uninitialized Subscripts524343 -Node: Delete525962 -Ref: Delete-Footnote-1528714 -Node: Multidimensional528771 -Node: Multiscanning531866 -Node: Arrays of Arrays533457 -Node: Arrays Summary538225 -Node: Functions540318 -Node: Built-in541356 -Node: Calling Built-in542437 -Node: Numeric Functions544433 -Ref: Numeric Functions-Footnote-1548461 -Ref: Numeric Functions-Footnote-2549109 -Ref: Numeric Functions-Footnote-3549157 -Node: String Functions549429 -Ref: String Functions-Footnote-1573570 -Ref: String Functions-Footnote-2573698 -Ref: String Functions-Footnote-3573946 -Node: Gory Details574033 -Ref: table-sub-escapes575824 -Ref: table-sub-proposed577343 -Ref: table-posix-sub578706 -Ref: table-gensub-escapes580247 -Ref: Gory Details-Footnote-1581070 -Node: I/O Functions581224 -Ref: table-system-return-values587678 -Ref: I/O Functions-Footnote-1589758 -Ref: I/O Functions-Footnote-2589906 -Node: Time Functions590026 -Ref: Time Functions-Footnote-1600697 -Ref: Time Functions-Footnote-2600765 -Ref: Time Functions-Footnote-3600923 -Ref: Time Functions-Footnote-4601034 -Ref: Time Functions-Footnote-5601146 -Ref: Time Functions-Footnote-6601373 -Node: Bitwise Functions601639 -Ref: table-bitwise-ops602233 -Ref: Bitwise Functions-Footnote-1608296 -Ref: Bitwise Functions-Footnote-2608469 -Node: Type Functions608660 -Node: I18N Functions611523 -Node: User-defined613174 -Node: Definition Syntax613986 -Ref: Definition Syntax-Footnote-1619680 -Node: Function Example619751 -Ref: Function Example-Footnote-1622673 -Node: Function Calling622695 -Node: Calling A Function623283 -Node: Variable Scope624241 -Node: Pass By Value/Reference627235 -Node: Function Caveats629879 -Ref: Function Caveats-Footnote-1631926 -Node: Return Statement632046 -Node: Dynamic Typing635025 -Node: Indirect Calls635955 -Ref: Indirect Calls-Footnote-1646207 -Node: Functions Summary646335 -Node: Library Functions649040 -Ref: Library Functions-Footnote-1652647 -Ref: Library Functions-Footnote-2652790 -Node: Library Names652961 -Ref: Library Names-Footnote-1656628 -Ref: Library Names-Footnote-2656851 -Node: General Functions656937 -Node: Strtonum Function658040 -Node: Assert Function661062 -Node: Round Function664388 -Node: Cliff Random Function665928 -Node: Ordinal Functions666944 -Ref: Ordinal Functions-Footnote-1670007 -Ref: Ordinal Functions-Footnote-2670259 -Node: Join Function670469 -Ref: Join Function-Footnote-1672239 -Node: Getlocaltime Function672439 -Node: Readfile Function676181 -Node: Shell Quoting678158 -Node: Data File Management679559 -Node: Filetrans Function680191 -Node: Rewind Function684287 -Node: File Checking686196 -Ref: File Checking-Footnote-1687530 -Node: Empty Files687731 -Node: Ignoring Assigns689710 -Node: Getopt Function691260 -Ref: Getopt Function-Footnote-1706471 -Node: Passwd Functions706671 -Ref: Passwd Functions-Footnote-1715510 -Node: Group Functions715598 -Ref: Group Functions-Footnote-1723496 -Node: Walking Arrays723703 -Node: Library Functions Summary726711 -Node: Library Exercises728117 -Node: Sample Programs728582 -Node: Running Examples729352 -Node: Clones730080 -Node: Cut Program731304 -Node: Egrep Program741444 -Node: Id Program750445 -Node: Split Program760392 -Ref: Split Program-Footnote-1770282 -Node: Tee Program770455 -Node: Uniq Program773245 -Node: Wc Program780833 -Node: Bytes vs. Characters781220 -Node: Using extensions782768 -Node: wc program783522 -Node: Miscellaneous Programs788387 -Node: Dupword Program789600 -Node: Alarm Program791630 -Node: Translate Program796485 -Ref: Translate Program-Footnote-1801050 -Node: Labels Program801320 -Ref: Labels Program-Footnote-1804671 -Node: Word Sorting804755 -Node: History Sorting808827 -Node: Extract Program811052 -Node: Simple Sed819106 -Node: Igawk Program822180 -Ref: Igawk Program-Footnote-1836511 -Ref: Igawk Program-Footnote-2836713 -Ref: Igawk Program-Footnote-3836835 -Node: Anagram Program836950 -Node: Signature Program840012 -Node: Programs Summary841259 -Node: Programs Exercises842473 -Ref: Programs Exercises-Footnote-1846603 -Node: Advanced Features846689 -Node: Nondecimal Data848756 -Node: Array Sorting850347 -Node: Controlling Array Traversal851047 -Ref: Controlling Array Traversal-Footnote-1859415 -Node: Array Sorting Functions859533 -Ref: Array Sorting Functions-Footnote-1864624 -Node: Two-way I/O864820 -Ref: Two-way I/O-Footnote-1872541 -Ref: Two-way I/O-Footnote-2872728 -Node: TCP/IP Networking872810 -Node: Profiling875928 -Node: Extension Philosophy885237 -Node: Advanced Features Summary886716 -Node: Internationalization888731 -Node: I18N and L10N890405 -Node: Explaining gettext891092 -Ref: Explaining gettext-Footnote-1896984 -Ref: Explaining gettext-Footnote-2897169 -Node: Programmer i18n897334 -Ref: Programmer i18n-Footnote-1902283 -Node: Translator i18n902332 -Node: String Extraction903126 -Ref: String Extraction-Footnote-1904258 -Node: Printf Ordering904344 -Ref: Printf Ordering-Footnote-1907130 -Node: I18N Portability907194 -Ref: I18N Portability-Footnote-1909650 -Node: I18N Example909713 -Ref: I18N Example-Footnote-1912988 -Ref: I18N Example-Footnote-2913061 -Node: Gawk I18N913170 -Node: I18N Summary913819 -Node: Debugger915160 -Node: Debugging916160 -Node: Debugging Concepts916601 -Node: Debugging Terms918410 -Node: Awk Debugging920985 -Ref: Awk Debugging-Footnote-1921930 -Node: Sample Debugging Session922062 -Node: Debugger Invocation922596 -Node: Finding The Bug923982 -Node: List of Debugger Commands930456 -Node: Breakpoint Control931789 -Node: Debugger Execution Control935483 -Node: Viewing And Changing Data938845 -Node: Execution Stack942386 -Node: Debugger Info944023 -Node: Miscellaneous Debugger Commands948094 -Node: Readline Support953156 -Node: Limitations954052 -Node: Debugging Summary956606 -Node: Namespaces957885 -Node: Global Namespace958996 -Node: Qualified Names960394 -Node: Default Namespace961393 -Node: Changing The Namespace962134 -Node: Naming Rules963748 -Node: Internal Name Management965596 -Node: Namespace Example966638 -Node: Namespace And Features969200 -Node: Namespace Summary970635 -Node: Arbitrary Precision Arithmetic972112 -Node: Computer Arithmetic973599 -Ref: table-numeric-ranges977365 -Ref: table-floating-point-ranges977858 -Ref: Computer Arithmetic-Footnote-1978516 -Node: Math Definitions978573 -Ref: table-ieee-formats981889 -Ref: Math Definitions-Footnote-1982492 -Node: MPFR features982597 -Node: FP Math Caution984315 -Ref: FP Math Caution-Footnote-1985387 -Node: Inexactness of computations985756 -Node: Inexact representation986716 -Node: Comparing FP Values988076 -Node: Errors accumulate989317 -Node: Getting Accuracy990750 -Node: Try To Round993460 -Node: Setting precision994359 -Ref: table-predefined-precision-strings995056 -Node: Setting the rounding mode996886 -Ref: table-gawk-rounding-modes997260 -Ref: Setting the rounding mode-Footnote-11001191 -Node: Arbitrary Precision Integers1001370 -Ref: Arbitrary Precision Integers-Footnote-11004545 -Node: Checking for MPFR1004694 -Node: POSIX Floating Point Problems1006168 -Ref: POSIX Floating Point Problems-Footnote-11010453 -Node: Floating point summary1010491 -Node: Dynamic Extensions1012681 -Node: Extension Intro1014234 -Node: Plugin License1015500 -Node: Extension Mechanism Outline1016297 -Ref: figure-load-extension1016736 -Ref: figure-register-new-function1018301 -Ref: figure-call-new-function1019393 -Node: Extension API Description1021455 -Node: Extension API Functions Introduction1023168 -Ref: table-api-std-headers1025004 -Node: General Data Types1029253 -Ref: General Data Types-Footnote-11037883 -Node: Memory Allocation Functions1038182 -Ref: Memory Allocation Functions-Footnote-11042683 -Node: Constructor Functions1042782 -Node: API Ownership of MPFR and GMP Values1046248 -Node: Registration Functions1047561 -Node: Extension Functions1048261 -Node: Exit Callback Functions1053583 -Node: Extension Version String1054833 -Node: Input Parsers1055496 -Node: Output Wrappers1068217 -Node: Two-way processors1072729 -Node: Printing Messages1074994 -Ref: Printing Messages-Footnote-11076165 -Node: Updating ERRNO1076318 -Node: Requesting Values1077057 -Ref: table-value-types-returned1077794 -Node: Accessing Parameters1078730 -Node: Symbol Table Access1079967 -Node: Symbol table by name1080479 -Ref: Symbol table by name-Footnote-11083503 -Node: Symbol table by cookie1083631 -Ref: Symbol table by cookie-Footnote-11087816 -Node: Cached values1087880 -Ref: Cached values-Footnote-11091416 -Node: Array Manipulation1091569 -Ref: Array Manipulation-Footnote-11092660 -Node: Array Data Types1092697 -Ref: Array Data Types-Footnote-11095355 -Node: Array Functions1095447 -Node: Flattening Arrays1099945 -Node: Creating Arrays1106921 -Node: Redirection API1111688 -Node: Extension API Variables1114521 -Node: Extension Versioning1115232 -Ref: gawk-api-version1115661 -Node: Extension GMP/MPFR Versioning1117392 -Node: Extension API Informational Variables1119020 -Node: Extension API Boilerplate1120093 -Node: Changes from API V11124067 -Node: Finding Extensions1125639 -Node: Extension Example1126198 -Node: Internal File Description1126996 -Node: Internal File Ops1131076 -Ref: Internal File Ops-Footnote-11142426 -Node: Using Internal File Ops1142566 -Ref: Using Internal File Ops-Footnote-11144949 -Node: Extension Samples1145223 -Node: Extension Sample File Functions1146752 -Node: Extension Sample Fnmatch1154401 -Node: Extension Sample Fork1155888 -Node: Extension Sample Inplace1157106 -Node: Extension Sample Ord1160732 -Node: Extension Sample Readdir1161568 -Ref: table-readdir-file-types1162457 -Node: Extension Sample Revout1163524 -Node: Extension Sample Rev2way1164113 -Node: Extension Sample Read write array1164853 -Node: Extension Sample Readfile1166795 -Node: Extension Sample Time1167890 -Node: Extension Sample API Tests1169642 -Node: gawkextlib1170134 -Node: Extension summary1173052 -Node: Extension Exercises1176754 -Node: Language History1177996 -Node: V7/SVR3.11179652 -Node: SVR41181804 -Node: POSIX1183238 -Node: BTL1184619 -Node: POSIX/GNU1185348 -Node: Feature History1191126 -Node: Common Extensions1208301 -Node: Ranges and Locales1209584 -Ref: Ranges and Locales-Footnote-11214200 -Ref: Ranges and Locales-Footnote-21214227 -Ref: Ranges and Locales-Footnote-31214462 -Node: Contributors1214685 -Node: History summary1220682 -Node: Installation1222062 -Node: Gawk Distribution1223006 -Node: Getting1223490 -Node: Extracting1224453 -Node: Distribution contents1226091 -Node: Unix Installation1232571 -Node: Quick Installation1233253 -Node: Shell Startup Files1235667 -Node: Additional Configuration Options1236756 -Node: Configuration Philosophy1239071 -Node: Non-Unix Installation1241440 -Node: PC Installation1241900 -Node: PC Binary Installation1242738 -Node: PC Compiling1243173 -Node: PC Using1244290 -Node: Cygwin1247843 -Node: MSYS1249067 -Node: VMS Installation1249669 -Node: VMS Compilation1250460 -Ref: VMS Compilation-Footnote-11251689 -Node: VMS Dynamic Extensions1251747 -Node: VMS Installation Details1253432 -Node: VMS Running1255685 -Node: VMS GNV1259964 -Node: VMS Old Gawk1260699 -Node: Bugs1261170 -Node: Bug address1261833 -Node: Usenet1264815 -Node: Maintainers1265819 -Node: Other Versions1267004 -Node: Installation summary1274869 -Node: Notes1276078 -Node: Compatibility Mode1276872 -Node: Additions1277654 -Node: Accessing The Source1278579 -Node: Adding Code1280016 -Node: New Ports1286235 -Node: Derived Files1290610 -Ref: Derived Files-Footnote-11296270 -Ref: Derived Files-Footnote-21296305 -Ref: Derived Files-Footnote-31296903 -Node: Future Extensions1297017 -Node: Implementation Limitations1297675 -Node: Extension Design1298885 -Node: Old Extension Problems1300029 -Ref: Old Extension Problems-Footnote-11301547 -Node: Extension New Mechanism Goals1301604 -Ref: Extension New Mechanism Goals-Footnote-11304968 -Node: Extension Other Design Decisions1305157 -Node: Extension Future Growth1307270 -Node: Notes summary1307876 -Node: Basic Concepts1309034 -Node: Basic High Level1309715 -Ref: figure-general-flow1309997 -Ref: figure-process-flow1310682 -Ref: Basic High Level-Footnote-11313983 -Node: Basic Data Typing1314168 -Node: Glossary1317496 -Node: Copying1349381 -Node: GNU Free Documentation License1386924 -Node: Index1412044 +Node: Foreword344934 +Node: Foreword449376 +Node: Preface50908 +Ref: Preface-Footnote-153767 +Ref: Preface-Footnote-253876 +Ref: Preface-Footnote-354110 +Node: History54252 +Node: Names56604 +Ref: Names-Footnote-157708 +Node: This Manual57855 +Ref: This Manual-Footnote-164494 +Node: Conventions64594 +Node: Manual History66963 +Ref: Manual History-Footnote-169960 +Ref: Manual History-Footnote-270001 +Node: How To Contribute70075 +Node: Acknowledgments71001 +Node: Getting Started75938 +Node: Running gawk78377 +Node: One-shot79567 +Node: Read Terminal80830 +Node: Long82823 +Node: Executable Scripts84336 +Ref: Executable Scripts-Footnote-186969 +Node: Comments87072 +Node: Quoting89556 +Node: DOS Quoting95082 +Node: Sample Data Files97138 +Node: Very Simple99733 +Node: Two Rules105835 +Node: More Complex107720 +Node: Statements/Lines110052 +Ref: Statements/Lines-Footnote-1114536 +Node: Other Features114801 +Node: When115737 +Ref: When-Footnote-1117491 +Node: Intro Summary117556 +Node: Invoking Gawk118440 +Node: Command Line119954 +Node: Options120752 +Ref: Options-Footnote-1138666 +Ref: Options-Footnote-2138897 +Node: Other Arguments138922 +Node: Naming Standard Input142933 +Node: Environment Variables144143 +Node: AWKPATH Variable144701 +Ref: AWKPATH Variable-Footnote-1148113 +Ref: AWKPATH Variable-Footnote-2148147 +Node: AWKLIBPATH Variable148518 +Ref: AWKLIBPATH Variable-Footnote-1150215 +Node: Other Environment Variables150590 +Node: Exit Status154411 +Node: Include Files155088 +Node: Loading Shared Libraries158778 +Node: Obsolete160206 +Node: Undocumented160898 +Node: Invoking Summary161195 +Node: Regexp164036 +Node: Regexp Usage165490 +Node: Escape Sequences167527 +Node: Regexp Operators173768 +Node: Regexp Operator Details174253 +Ref: Regexp Operator Details-Footnote-1181617 +Node: Interval Expressions181764 +Ref: Interval Expressions-Footnote-1183185 +Node: Bracket Expressions183283 +Ref: table-char-classes185759 +Node: Leftmost Longest189085 +Node: Computed Regexps190388 +Node: GNU Regexp Operators193815 +Node: Case-sensitivity197552 +Ref: Case-sensitivity-Footnote-1200418 +Ref: Case-sensitivity-Footnote-2200653 +Node: Regexp Summary200761 +Node: Reading Files202227 +Node: Records204496 +Node: awk split records205571 +Node: gawk split records210271 +Ref: gawk split records-Footnote-1215345 +Node: Fields215382 +Node: Nonconstant Fields218123 +Ref: Nonconstant Fields-Footnote-1220359 +Node: Changing Fields220563 +Node: Field Separators226594 +Node: Default Field Splitting229292 +Node: Regexp Field Splitting230410 +Node: Single Character Fields234087 +Node: Command Line Field Separator235147 +Node: Full Line Fields238365 +Ref: Full Line Fields-Footnote-1239887 +Ref: Full Line Fields-Footnote-2239933 +Node: Field Splitting Summary240034 +Node: Constant Size242108 +Node: Fixed width data242840 +Node: Skipping intervening246307 +Node: Allowing trailing data247105 +Node: Fields with fixed data248142 +Node: Splitting By Content249660 +Ref: Splitting By Content-Footnote-1253443 +Node: More CSV253606 +Node: Testing field creation255198 +Node: Multiple Line256823 +Node: Getline263100 +Node: Plain Getline265569 +Node: Getline/Variable268142 +Node: Getline/File269293 +Node: Getline/Variable/File270681 +Ref: Getline/Variable/File-Footnote-1272286 +Node: Getline/Pipe272374 +Node: Getline/Variable/Pipe275078 +Node: Getline/Coprocess276213 +Node: Getline/Variable/Coprocess277480 +Node: Getline Notes278222 +Node: Getline Summary281019 +Ref: table-getline-variants281443 +Node: Read Timeout282191 +Ref: Read Timeout-Footnote-1286097 +Node: Retrying Input286155 +Node: Command-line directories287354 +Node: Input Summary288260 +Node: Input Exercises291432 +Node: Printing291866 +Node: Print293700 +Node: Print Examples295157 +Node: Output Separators297937 +Node: OFMT299954 +Node: Printf301310 +Node: Basic Printf302095 +Node: Control Letters303669 +Node: Format Modifiers308833 +Node: Printf Examples314848 +Node: Redirection317334 +Node: Special FD324175 +Ref: Special FD-Footnote-1327343 +Node: Special Files327417 +Node: Other Inherited Files328034 +Node: Special Network329035 +Node: Special Caveats329895 +Node: Close Files And Pipes330844 +Ref: table-close-pipe-return-values337751 +Ref: Close Files And Pipes-Footnote-1338564 +Ref: Close Files And Pipes-Footnote-2338712 +Node: Nonfatal338864 +Node: Output Summary341202 +Node: Output Exercises342424 +Node: Expressions343103 +Node: Values344291 +Node: Constants344969 +Node: Scalar Constants345660 +Ref: Scalar Constants-Footnote-1348170 +Node: Nondecimal-numbers348420 +Node: Regexp Constants351421 +Node: Using Constant Regexps351947 +Node: Standard Regexp Constants352569 +Node: Strong Regexp Constants355757 +Node: Variables358769 +Node: Using Variables359426 +Node: Assignment Options361336 +Node: Conversion363807 +Node: Strings And Numbers364331 +Ref: Strings And Numbers-Footnote-1367394 +Node: Locale influences conversions367503 +Ref: table-locale-affects370261 +Node: All Operators370879 +Node: Arithmetic Ops371508 +Node: Concatenation374224 +Ref: Concatenation-Footnote-1377071 +Node: Assignment Ops377178 +Ref: table-assign-ops382169 +Node: Increment Ops383482 +Node: Truth Values and Conditions386942 +Node: Truth Values388016 +Node: Typing and Comparison389064 +Node: Variable Typing389884 +Ref: Variable Typing-Footnote-1396347 +Ref: Variable Typing-Footnote-2396419 +Node: Comparison Operators396496 +Ref: table-relational-ops396915 +Node: POSIX String Comparison400410 +Ref: POSIX String Comparison-Footnote-1402105 +Ref: POSIX String Comparison-Footnote-2402244 +Node: Boolean Ops402328 +Ref: Boolean Ops-Footnote-1406810 +Node: Conditional Exp406902 +Node: Function Calls408638 +Node: Precedence412515 +Node: Locales416174 +Node: Expressions Summary417806 +Node: Patterns and Actions420379 +Node: Pattern Overview421499 +Node: Regexp Patterns423176 +Node: Expression Patterns423718 +Node: Ranges427499 +Node: BEGIN/END430607 +Node: Using BEGIN/END431368 +Ref: Using BEGIN/END-Footnote-1434122 +Node: I/O And BEGIN/END434228 +Node: BEGINFILE/ENDFILE436541 +Node: Empty439772 +Node: Using Shell Variables440089 +Node: Action Overview442363 +Node: Statements444688 +Node: If Statement446536 +Node: While Statement448031 +Node: Do Statement450059 +Node: For Statement451207 +Node: Switch Statement454378 +Node: Break Statement456819 +Node: Continue Statement458911 +Node: Next Statement460738 +Node: Nextfile Statement463121 +Node: Exit Statement465810 +Node: Built-in Variables468213 +Node: User-modified469346 +Node: Auto-set477113 +Ref: Auto-set-Footnote-1493920 +Ref: Auto-set-Footnote-2494126 +Node: ARGC and ARGV494182 +Node: Pattern Action Summary498395 +Node: Arrays500825 +Node: Array Basics502154 +Node: Array Intro502998 +Ref: figure-array-elements504973 +Ref: Array Intro-Footnote-1507677 +Node: Reference to Elements507805 +Node: Assigning Elements510269 +Node: Array Example510760 +Node: Scanning an Array512519 +Node: Controlling Scanning515541 +Ref: Controlling Scanning-Footnote-1521997 +Node: Numeric Array Subscripts522313 +Node: Uninitialized Subscripts524497 +Node: Delete526116 +Ref: Delete-Footnote-1528868 +Node: Multidimensional528925 +Node: Multiscanning532020 +Node: Arrays of Arrays533611 +Node: Arrays Summary538379 +Node: Functions540472 +Node: Built-in541510 +Node: Calling Built-in542591 +Node: Numeric Functions544587 +Ref: Numeric Functions-Footnote-1548615 +Ref: Numeric Functions-Footnote-2549263 +Ref: Numeric Functions-Footnote-3549311 +Node: String Functions549583 +Ref: String Functions-Footnote-1573724 +Ref: String Functions-Footnote-2573852 +Ref: String Functions-Footnote-3574100 +Node: Gory Details574187 +Ref: table-sub-escapes575978 +Ref: table-sub-proposed577497 +Ref: table-posix-sub578860 +Ref: table-gensub-escapes580401 +Ref: Gory Details-Footnote-1581224 +Node: I/O Functions581378 +Ref: table-system-return-values587832 +Ref: I/O Functions-Footnote-1589912 +Ref: I/O Functions-Footnote-2590060 +Node: Time Functions590180 +Ref: Time Functions-Footnote-1600851 +Ref: Time Functions-Footnote-2600919 +Ref: Time Functions-Footnote-3601077 +Ref: Time Functions-Footnote-4601188 +Ref: Time Functions-Footnote-5601300 +Ref: Time Functions-Footnote-6601527 +Node: Bitwise Functions601793 +Ref: table-bitwise-ops602387 +Ref: Bitwise Functions-Footnote-1608450 +Ref: Bitwise Functions-Footnote-2608623 +Node: Type Functions608814 +Node: I18N Functions611677 +Node: User-defined613328 +Node: Definition Syntax614140 +Ref: Definition Syntax-Footnote-1619834 +Node: Function Example619905 +Ref: Function Example-Footnote-1622827 +Node: Function Calling622849 +Node: Calling A Function623437 +Node: Variable Scope624395 +Node: Pass By Value/Reference627389 +Node: Function Caveats630033 +Ref: Function Caveats-Footnote-1632080 +Node: Return Statement632200 +Node: Dynamic Typing635179 +Node: Indirect Calls636109 +Ref: Indirect Calls-Footnote-1646361 +Node: Functions Summary646489 +Node: Library Functions649194 +Ref: Library Functions-Footnote-1652801 +Ref: Library Functions-Footnote-2652944 +Node: Library Names653115 +Ref: Library Names-Footnote-1656782 +Ref: Library Names-Footnote-2657005 +Node: General Functions657091 +Node: Strtonum Function658194 +Node: Assert Function661216 +Node: Round Function664542 +Node: Cliff Random Function666082 +Node: Ordinal Functions667098 +Ref: Ordinal Functions-Footnote-1670161 +Ref: Ordinal Functions-Footnote-2670413 +Node: Join Function670623 +Ref: Join Function-Footnote-1672393 +Node: Getlocaltime Function672593 +Node: Readfile Function676335 +Node: Shell Quoting678312 +Node: Data File Management679713 +Node: Filetrans Function680345 +Node: Rewind Function684441 +Node: File Checking686350 +Ref: File Checking-Footnote-1687684 +Node: Empty Files687885 +Node: Ignoring Assigns689864 +Node: Getopt Function691414 +Ref: Getopt Function-Footnote-1706625 +Node: Passwd Functions706825 +Ref: Passwd Functions-Footnote-1715664 +Node: Group Functions715752 +Ref: Group Functions-Footnote-1723650 +Node: Walking Arrays723857 +Node: Library Functions Summary726865 +Node: Library Exercises728271 +Node: Sample Programs728736 +Node: Running Examples729506 +Node: Clones730234 +Node: Cut Program731458 +Node: Egrep Program741598 +Node: Id Program750599 +Node: Split Program760546 +Ref: Split Program-Footnote-1770436 +Node: Tee Program770609 +Node: Uniq Program773399 +Node: Wc Program780987 +Node: Bytes vs. Characters781374 +Node: Using extensions782922 +Node: wc program783676 +Node: Miscellaneous Programs788541 +Node: Dupword Program789754 +Node: Alarm Program791784 +Node: Translate Program796639 +Ref: Translate Program-Footnote-1801204 +Node: Labels Program801474 +Ref: Labels Program-Footnote-1804825 +Node: Word Sorting804909 +Node: History Sorting808981 +Node: Extract Program811206 +Node: Simple Sed819260 +Node: Igawk Program822334 +Ref: Igawk Program-Footnote-1836665 +Ref: Igawk Program-Footnote-2836867 +Ref: Igawk Program-Footnote-3836989 +Node: Anagram Program837104 +Node: Signature Program840166 +Node: Programs Summary841413 +Node: Programs Exercises842627 +Ref: Programs Exercises-Footnote-1846757 +Node: Advanced Features846843 +Node: Nondecimal Data848910 +Node: Array Sorting850501 +Node: Controlling Array Traversal851201 +Ref: Controlling Array Traversal-Footnote-1859569 +Node: Array Sorting Functions859687 +Ref: Array Sorting Functions-Footnote-1864778 +Node: Two-way I/O864974 +Ref: Two-way I/O-Footnote-1872695 +Ref: Two-way I/O-Footnote-2872882 +Node: TCP/IP Networking872964 +Node: Profiling876082 +Node: Extension Philosophy885391 +Node: Advanced Features Summary886870 +Node: Internationalization888885 +Node: I18N and L10N890559 +Node: Explaining gettext891246 +Ref: Explaining gettext-Footnote-1897138 +Ref: Explaining gettext-Footnote-2897323 +Node: Programmer i18n897488 +Ref: Programmer i18n-Footnote-1902437 +Node: Translator i18n902486 +Node: String Extraction903280 +Ref: String Extraction-Footnote-1904412 +Node: Printf Ordering904498 +Ref: Printf Ordering-Footnote-1907284 +Node: I18N Portability907348 +Ref: I18N Portability-Footnote-1909804 +Node: I18N Example909867 +Ref: I18N Example-Footnote-1913142 +Ref: I18N Example-Footnote-2913215 +Node: Gawk I18N913324 +Node: I18N Summary913973 +Node: Debugger915314 +Node: Debugging916314 +Node: Debugging Concepts916755 +Node: Debugging Terms918564 +Node: Awk Debugging921139 +Ref: Awk Debugging-Footnote-1922084 +Node: Sample Debugging Session922216 +Node: Debugger Invocation922750 +Node: Finding The Bug924136 +Node: List of Debugger Commands930610 +Node: Breakpoint Control931943 +Node: Debugger Execution Control935637 +Node: Viewing And Changing Data938999 +Node: Execution Stack942540 +Node: Debugger Info944177 +Node: Miscellaneous Debugger Commands948248 +Node: Readline Support953310 +Node: Limitations954206 +Node: Debugging Summary956760 +Node: Namespaces958039 +Node: Global Namespace959150 +Node: Qualified Names960548 +Node: Default Namespace961547 +Node: Changing The Namespace962288 +Node: Naming Rules963902 +Node: Internal Name Management965750 +Node: Namespace Example966792 +Node: Namespace And Features969354 +Node: Namespace Summary970789 +Node: Arbitrary Precision Arithmetic972266 +Node: Computer Arithmetic973753 +Ref: table-numeric-ranges977519 +Ref: table-floating-point-ranges978012 +Ref: Computer Arithmetic-Footnote-1978670 +Node: Math Definitions978727 +Ref: table-ieee-formats982043 +Ref: Math Definitions-Footnote-1982646 +Node: MPFR features982751 +Node: FP Math Caution984469 +Ref: FP Math Caution-Footnote-1985541 +Node: Inexactness of computations985910 +Node: Inexact representation986870 +Node: Comparing FP Values988230 +Node: Errors accumulate989471 +Node: Getting Accuracy990904 +Node: Try To Round993614 +Node: Setting precision994513 +Ref: table-predefined-precision-strings995210 +Node: Setting the rounding mode997040 +Ref: table-gawk-rounding-modes997414 +Ref: Setting the rounding mode-Footnote-11001345 +Node: Arbitrary Precision Integers1001524 +Ref: Arbitrary Precision Integers-Footnote-11004699 +Node: Checking for MPFR1004848 +Node: POSIX Floating Point Problems1006322 +Ref: POSIX Floating Point Problems-Footnote-11010607 +Node: Floating point summary1010645 +Node: Dynamic Extensions1012835 +Node: Extension Intro1014388 +Node: Plugin License1015654 +Node: Extension Mechanism Outline1016451 +Ref: figure-load-extension1016890 +Ref: figure-register-new-function1018455 +Ref: figure-call-new-function1019547 +Node: Extension API Description1021609 +Node: Extension API Functions Introduction1023322 +Ref: table-api-std-headers1025158 +Node: General Data Types1029407 +Ref: General Data Types-Footnote-11038037 +Node: Memory Allocation Functions1038336 +Ref: Memory Allocation Functions-Footnote-11042837 +Node: Constructor Functions1042936 +Node: API Ownership of MPFR and GMP Values1046402 +Node: Registration Functions1047715 +Node: Extension Functions1048415 +Node: Exit Callback Functions1053737 +Node: Extension Version String1054987 +Node: Input Parsers1055650 +Node: Output Wrappers1068371 +Node: Two-way processors1072883 +Node: Printing Messages1075148 +Ref: Printing Messages-Footnote-11076319 +Node: Updating ERRNO1076472 +Node: Requesting Values1077211 +Ref: table-value-types-returned1077948 +Node: Accessing Parameters1078884 +Node: Symbol Table Access1080121 +Node: Symbol table by name1080633 +Ref: Symbol table by name-Footnote-11083657 +Node: Symbol table by cookie1083785 +Ref: Symbol table by cookie-Footnote-11087970 +Node: Cached values1088034 +Ref: Cached values-Footnote-11091570 +Node: Array Manipulation1091723 +Ref: Array Manipulation-Footnote-11092814 +Node: Array Data Types1092851 +Ref: Array Data Types-Footnote-11095509 +Node: Array Functions1095601 +Node: Flattening Arrays1100099 +Node: Creating Arrays1107075 +Node: Redirection API1111842 +Node: Extension API Variables1114675 +Node: Extension Versioning1115386 +Ref: gawk-api-version1115815 +Node: Extension GMP/MPFR Versioning1117546 +Node: Extension API Informational Variables1119174 +Node: Extension API Boilerplate1120247 +Node: Changes from API V11124221 +Node: Finding Extensions1125793 +Node: Extension Example1126352 +Node: Internal File Description1127150 +Node: Internal File Ops1131230 +Ref: Internal File Ops-Footnote-11142580 +Node: Using Internal File Ops1142720 +Ref: Using Internal File Ops-Footnote-11145103 +Node: Extension Samples1145377 +Node: Extension Sample File Functions1146906 +Node: Extension Sample Fnmatch1154555 +Node: Extension Sample Fork1156042 +Node: Extension Sample Inplace1157260 +Node: Extension Sample Ord1160886 +Node: Extension Sample Readdir1161722 +Ref: table-readdir-file-types1162611 +Node: Extension Sample Revout1163678 +Node: Extension Sample Rev2way1164267 +Node: Extension Sample Read write array1165007 +Node: Extension Sample Readfile1166949 +Node: Extension Sample Time1168044 +Node: Extension Sample API Tests1169796 +Node: gawkextlib1170288 +Node: Extension summary1173206 +Node: Extension Exercises1176908 +Node: Language History1178150 +Node: V7/SVR3.11179806 +Node: SVR41181958 +Node: POSIX1183392 +Node: BTL1184773 +Node: POSIX/GNU1185502 +Node: Feature History1191280 +Node: Common Extensions1208455 +Node: Ranges and Locales1209738 +Ref: Ranges and Locales-Footnote-11214354 +Ref: Ranges and Locales-Footnote-21214381 +Ref: Ranges and Locales-Footnote-31214616 +Node: Contributors1214839 +Node: History summary1220836 +Node: Installation1222216 +Node: Gawk Distribution1223160 +Node: Getting1223644 +Node: Extracting1224607 +Node: Distribution contents1226245 +Node: Unix Installation1232725 +Node: Quick Installation1233407 +Node: Compiling with MPFR1235888 +Node: Shell Startup Files1236580 +Node: Additional Configuration Options1237669 +Node: Configuration Philosophy1239984 +Node: Non-Unix Installation1242353 +Node: PC Installation1242813 +Node: PC Binary Installation1243651 +Node: PC Compiling1244086 +Node: PC Using1245203 +Node: Cygwin1248756 +Node: MSYS1249980 +Node: VMS Installation1250582 +Node: VMS Compilation1251373 +Ref: VMS Compilation-Footnote-11252602 +Node: VMS Dynamic Extensions1252660 +Node: VMS Installation Details1254345 +Node: VMS Running1256598 +Node: VMS GNV1260877 +Node: VMS Old Gawk1261612 +Node: Bugs1262083 +Node: Bug address1262832 +Node: Usenet1265814 +Node: Performance bugs1266823 +Node: Maintainers1269680 +Node: Other Versions1270875 +Node: Installation summary1278740 +Node: Notes1279949 +Node: Compatibility Mode1280743 +Node: Additions1281525 +Node: Accessing The Source1282450 +Node: Adding Code1283887 +Node: New Ports1290106 +Node: Derived Files1294481 +Ref: Derived Files-Footnote-11300141 +Ref: Derived Files-Footnote-21300176 +Ref: Derived Files-Footnote-31300774 +Node: Future Extensions1300888 +Node: Implementation Limitations1301546 +Node: Extension Design1302756 +Node: Old Extension Problems1303900 +Ref: Old Extension Problems-Footnote-11305418 +Node: Extension New Mechanism Goals1305475 +Ref: Extension New Mechanism Goals-Footnote-11308839 +Node: Extension Other Design Decisions1309028 +Node: Extension Future Growth1311141 +Node: Notes summary1311747 +Node: Basic Concepts1312905 +Node: Basic High Level1313586 +Ref: figure-general-flow1313868 +Ref: figure-process-flow1314553 +Ref: Basic High Level-Footnote-11317854 +Node: Basic Data Typing1318039 +Node: Glossary1321367 +Node: Copying1353252 +Node: GNU Free Documentation License1390795 +Node: Index1415915 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 7c4cb23c..2478cf98 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -1027,6 +1027,7 @@ particular records in a file and perform operations upon them. * Unix Installation:: Installing @command{gawk} under various versions of Unix. * Quick Installation:: Compiling @command{gawk} under Unix. +* Compiling with MPFR:: Building with MPFR. * Shell Startup Files:: Shell convenience functions. * Additional Configuration Options:: Other compile-time options. * Configuration Philosophy:: How it's all supposed to work. @@ -1056,6 +1057,7 @@ particular records in a file and perform operations upon them. * Bugs:: Reporting Problems and Bugs. * Bug address:: Where to send reports to. * Usenet:: Where not to send reports to. +* Performance bugs:: What to do if you think there is a performance issue. * Maintainers:: Maintainers of non-*nix ports. * Other Versions:: Other freely available @command{awk} implementations. @@ -41854,6 +41856,10 @@ to configure @command{gawk} for your system yourself. @node Quick Installation @appendixsubsec Compiling @command{gawk} for Unix-Like Systems +@menu +* Compiling with MPFR:: Building with MPFR. +@end menu + The normal installation steps should work on all modern commercial Unix-derived systems, GNU/Linux, BSD-based systems, and the Cygwin environment for MS-Windows. @@ -41927,6 +41933,24 @@ is likely that you will be asked for your password, and you will have to have been set up previously as a user who is allowed to run the @command{sudo} command. + +@node Compiling with MPFR +@appendixsubsubsec Building With MPFR + +@cindex MPFR library, building with +Use of the MPFR library with @command{gawk} +is an optional feature: if you have the MPFR and GMP libraries already installed +when you configure and build @command{gawk}, +@command{gawk} automatically will be able to use them. + +You can install these libraries from source code by fetching them +from the GNU distribution site at @code{ftp.gnu.org}. + +Most modern systems provide package managers which save you the trouble +of building from source. They fetch and install the library header files +and binaries for you. You will need to research how to do this for +your particular system. + @node Shell Startup Files @appendixsubsec Shell Startup Files @@ -42723,6 +42747,7 @@ but we might well want to fix it. @menu * Bug address:: Where to send reports to. * Usenet:: Where not to send reports to. +* Performance bugs:: What to do if you think there is a performance issue. * Maintainers:: Maintainers of non-*nix ports. @end menu @@ -42832,6 +42857,88 @@ and run to another section of the playground. Then, if you like mixing metaphors, you can throw rocks from there." @end ignore +@node Performance bugs +@appendixsubsec What To Do If You Think There Is A Performance Issue + +@cindex performance, checking issues +@cindex profiling, compiling @command{gawk} for +If you think that @command{gawk} is too slow at doing a particular task, +you should investigate before sending in a bug report. Here are the steps +to follow: + +@enumerate 1 +@item +Run @command{gawk} with the @option{--profile} option (@pxref{Options}) +to see what your +program is doing. It may be that you have written it in an inefficient manner. +For example, you may be doing something for every record that could be done +just once, for every file. +(Use a @code{BEGINFILE} rule; @pxref{BEGINFILE/ENDFILE}.) +Or you may be doing something for every file that only needs to be done +once per run of the program. +(Use a @code{BEGIN} rule; @pxref{BEGIN/END}.) + +@item +If profiling at the @command{awk} level doesn't help, then you will +need to compile @command{gawk} itself for profiling at the C language level. + +To do that, start with the latest released version of +@command{gawk}. Unpack the source code in a new directory, and configure +it: + +@example +$ @kbd{tar -xpzvf gawk-X.Y.Z.tar.gz} +@print{} @dots{} @ii{Output ommited} +$ @kbd{cd gawk-X.Y.Z} +$ @kbd{./configure} +@print{} @dots{} @ii{Output ommited} +@end example + +@item +Edit the files @file{Makefile} and @file{support/Makefile}. +Change every instance of @option{-O2} or @option{-O} to @option{-pg}. +This causes @command{gawk} to be compiled for profiling. + +@item +Compile the program by running the @command{make} command: + +@example +@group +$ @kbd{make} +@print{} @dots{} @ii{Output ommited} +@end group +@end example + +@item +Run the freshly compiled @command{gawk} on a @emph{real} program, +using @emph{real} data. Using an artificial program to try to time one +particular feature of @command{gawk} is useless; real @command{awk} programs +generally spend most of their time doing I/O, not computing. If you want to prove +that something is slow, it @emph{must} be done using a real program and real data. + +Use a data file that is large enough for the statistical profiling to measure +where @command{gawk} spends its time. It should be at least 100 megabytes in size. + +@item +When done, you should have a file in the current directory named @file{gmon.out}. +Run the command @samp{gprof gawk gmon.out > gprof.out}. + +@item +Submit a bug report explaining what you think is slow. Include the @file{gprof.out} +file with it. + +Preferably, you should also submit the program and the data, or else indicate where to +get the data if the file is large. + +@item +If you have not submitted your program and data, be prepared to apply patches and +rerun the profiling in order to see if the patches were effective. + +@end enumerate + +If you are incapable or unwilling to do the steps listed above, then you will +just have to live with @command{gawk} as it is. + @node Maintainers @appendixsubsec Reporting Problems with Non-Unix Ports diff --git a/doc/gawktexi.in b/doc/gawktexi.in index 3b6a6692..37ecbc9f 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -1022,6 +1022,7 @@ particular records in a file and perform operations upon them. * Unix Installation:: Installing @command{gawk} under various versions of Unix. * Quick Installation:: Compiling @command{gawk} under Unix. +* Compiling with MPFR:: Building with MPFR. * Shell Startup Files:: Shell convenience functions. * Additional Configuration Options:: Other compile-time options. * Configuration Philosophy:: How it's all supposed to work. @@ -1051,6 +1052,7 @@ particular records in a file and perform operations upon them. * Bugs:: Reporting Problems and Bugs. * Bug address:: Where to send reports to. * Usenet:: Where not to send reports to. +* Performance bugs:: What to do if you think there is a performance issue. * Maintainers:: Maintainers of non-*nix ports. * Other Versions:: Other freely available @command{awk} implementations. @@ -40697,6 +40699,10 @@ to configure @command{gawk} for your system yourself. @node Quick Installation @appendixsubsec Compiling @command{gawk} for Unix-Like Systems +@menu +* Compiling with MPFR:: Building with MPFR. +@end menu + The normal installation steps should work on all modern commercial Unix-derived systems, GNU/Linux, BSD-based systems, and the Cygwin environment for MS-Windows. @@ -40770,6 +40776,24 @@ is likely that you will be asked for your password, and you will have to have been set up previously as a user who is allowed to run the @command{sudo} command. + +@node Compiling with MPFR +@appendixsubsubsec Building With MPFR + +@cindex MPFR library, building with +Use of the MPFR library with @command{gawk} +is an optional feature: if you have the MPFR and GMP libraries already installed +when you configure and build @command{gawk}, +@command{gawk} automatically will be able to use them. + +You can install these libraries from source code by fetching them +from the GNU distribution site at @code{ftp.gnu.org}. + +Most modern systems provide package managers which save you the trouble +of building from source. They fetch and install the library header files +and binaries for you. You will need to research how to do this for +your particular system. + @node Shell Startup Files @appendixsubsec Shell Startup Files @@ -41566,6 +41590,7 @@ but we might well want to fix it. @menu * Bug address:: Where to send reports to. * Usenet:: Where not to send reports to. +* Performance bugs:: What to do if you think there is a performance issue. * Maintainers:: Maintainers of non-*nix ports. @end menu @@ -41675,6 +41700,88 @@ and run to another section of the playground. Then, if you like mixing metaphors, you can throw rocks from there." @end ignore +@node Performance bugs +@appendixsubsec What To Do If You Think There Is A Performance Issue + +@cindex performance, checking issues +@cindex profiling, compiling @command{gawk} for +If you think that @command{gawk} is too slow at doing a particular task, +you should investigate before sending in a bug report. Here are the steps +to follow: + +@enumerate 1 +@item +Run @command{gawk} with the @option{--profile} option (@pxref{Options}) +to see what your +program is doing. It may be that you have written it in an inefficient manner. +For example, you may be doing something for every record that could be done +just once, for every file. +(Use a @code{BEGINFILE} rule; @pxref{BEGINFILE/ENDFILE}.) +Or you may be doing something for every file that only needs to be done +once per run of the program. +(Use a @code{BEGIN} rule; @pxref{BEGIN/END}.) + +@item +If profiling at the @command{awk} level doesn't help, then you will +need to compile @command{gawk} itself for profiling at the C language level. + +To do that, start with the latest released version of +@command{gawk}. Unpack the source code in a new directory, and configure +it: + +@example +$ @kbd{tar -xpzvf gawk-X.Y.Z.tar.gz} +@print{} @dots{} @ii{Output ommited} +$ @kbd{cd gawk-X.Y.Z} +$ @kbd{./configure} +@print{} @dots{} @ii{Output ommited} +@end example + +@item +Edit the files @file{Makefile} and @file{support/Makefile}. +Change every instance of @option{-O2} or @option{-O} to @option{-pg}. +This causes @command{gawk} to be compiled for profiling. + +@item +Compile the program by running the @command{make} command: + +@example +@group +$ @kbd{make} +@print{} @dots{} @ii{Output ommited} +@end group +@end example + +@item +Run the freshly compiled @command{gawk} on a @emph{real} program, +using @emph{real} data. Using an artificial program to try to time one +particular feature of @command{gawk} is useless; real @command{awk} programs +generally spend most of their time doing I/O, not computing. If you want to prove +that something is slow, it @emph{must} be done using a real program and real data. + +Use a data file that is large enough for the statistical profiling to measure +where @command{gawk} spends its time. It should be at least 100 megabytes in size. + +@item +When done, you should have a file in the current directory named @file{gmon.out}. +Run the command @samp{gprof gawk gmon.out > gprof.out}. + +@item +Submit a bug report explaining what you think is slow. Include the @file{gprof.out} +file with it. + +Preferably, you should also submit the program and the data, or else indicate where to +get the data if the file is large. + +@item +If you have not submitted your program and data, be prepared to apply patches and +rerun the profiling in order to see if the patches were effective. + +@end enumerate + +If you are incapable or unwilling to do the steps listed above, then you will +just have to live with @command{gawk} as it is. + @node Maintainers @appendixsubsec Reporting Problems with Non-Unix Ports |