diff options
| -rw-r--r-- | doc/ChangeLog | 6 | ||||
| -rw-r--r-- | doc/gawk.info | 1302 | ||||
| -rw-r--r-- | doc/gawk.texi | 107 | ||||
| -rw-r--r-- | doc/gawktexi.in | 107 |
4 files changed, 919 insertions, 603 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index 8e91b00e..f591fab2 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 0e8d2fdf..55ddd990 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -658,6 +658,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. @@ -687,6 +688,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. @@ -30762,6 +30764,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. @@ -30812,6 +30818,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 @@ -31473,6 +31497,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. @@ -31539,7 +31564,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 --------------------------------------------- @@ -31562,9 +31587,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 @@ -37010,6 +37101,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) @@ -37242,6 +37334,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) @@ -37432,6 +37525,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) @@ -38225,606 +38319,608 @@ Index Tag Table: Node: Top1200 -Node: Foreword345051 -Node: Foreword449493 -Node: Preface51025 -Ref: Preface-Footnote-153884 -Ref: Preface-Footnote-253993 -Ref: Preface-Footnote-354227 -Node: History54369 -Node: Names56721 -Ref: Names-Footnote-157825 -Node: This Manual57972 -Ref: This Manual-Footnote-164611 -Node: Conventions64711 -Node: Manual History67080 -Ref: Manual History-Footnote-170077 -Ref: Manual History-Footnote-270118 -Node: How To Contribute70192 -Node: Acknowledgments71118 -Node: Getting Started76055 -Node: Running gawk78494 -Node: One-shot79684 -Node: Read Terminal80947 -Node: Long82940 -Node: Executable Scripts84453 -Ref: Executable Scripts-Footnote-187086 -Node: Comments87189 -Node: Quoting89673 -Node: DOS Quoting95199 -Node: Sample Data Files97255 -Node: Very Simple99850 -Node: Two Rules105952 -Node: More Complex107837 -Node: Statements/Lines110169 -Ref: Statements/Lines-Footnote-1114653 -Node: Other Features114918 -Node: When115854 -Ref: When-Footnote-1117608 -Node: Intro Summary117673 -Node: Invoking Gawk118557 -Node: Command Line120071 -Node: Options120869 -Ref: Options-Footnote-1138783 -Ref: Options-Footnote-2139014 -Node: Other Arguments139039 -Node: Naming Standard Input143050 -Node: Environment Variables144260 -Node: AWKPATH Variable144818 -Ref: AWKPATH Variable-Footnote-1148230 -Ref: AWKPATH Variable-Footnote-2148264 -Node: AWKLIBPATH Variable148635 -Ref: AWKLIBPATH Variable-Footnote-1150332 -Node: Other Environment Variables150707 -Node: Exit Status154659 -Node: Include Files155336 -Node: Loading Shared Libraries159026 -Node: Obsolete160454 -Node: Undocumented161146 -Node: Invoking Summary161443 -Node: Regexp164284 -Node: Regexp Usage165738 -Node: Escape Sequences167775 -Node: Regexp Operators174016 -Node: Regexp Operator Details174501 -Ref: Regexp Operator Details-Footnote-1181865 -Node: Interval Expressions182012 -Ref: Interval Expressions-Footnote-1183433 -Node: Bracket Expressions183531 -Ref: table-char-classes186007 -Node: Leftmost Longest189333 -Node: Computed Regexps190636 -Node: GNU Regexp Operators194063 -Node: Case-sensitivity197800 -Ref: Case-sensitivity-Footnote-1200666 -Ref: Case-sensitivity-Footnote-2200901 -Node: Regexp Summary201009 -Node: Reading Files202475 -Node: Records204744 -Node: awk split records205819 -Node: gawk split records210519 -Ref: gawk split records-Footnote-1215593 -Node: Fields215630 -Node: Nonconstant Fields218371 -Ref: Nonconstant Fields-Footnote-1220607 -Node: Changing Fields220811 -Node: Field Separators226842 -Node: Default Field Splitting229540 -Node: Regexp Field Splitting230658 -Node: Single Character Fields234335 -Node: Command Line Field Separator235395 -Node: Full Line Fields238613 -Ref: Full Line Fields-Footnote-1240135 -Ref: Full Line Fields-Footnote-2240181 -Node: Field Splitting Summary240282 -Node: Constant Size242356 -Node: Fixed width data243088 -Node: Skipping intervening246555 -Node: Allowing trailing data247353 -Node: Fields with fixed data248390 -Node: Splitting By Content249908 -Ref: Splitting By Content-Footnote-1253691 -Node: More CSV253854 -Node: Testing field creation255446 -Node: Multiple Line257071 -Node: Getline263348 -Node: Plain Getline265817 -Node: Getline/Variable268390 -Node: Getline/File269541 -Node: Getline/Variable/File270929 -Ref: Getline/Variable/File-Footnote-1272534 -Node: Getline/Pipe272622 -Node: Getline/Variable/Pipe275326 -Node: Getline/Coprocess276461 -Node: Getline/Variable/Coprocess277728 -Node: Getline Notes278470 -Node: Getline Summary281267 -Ref: table-getline-variants281691 -Node: Read Timeout282439 -Ref: Read Timeout-Footnote-1286345 -Node: Retrying Input286403 -Node: Command-line directories287602 -Node: Input Summary288508 -Node: Input Exercises291680 -Node: Printing292114 -Node: Print293948 -Node: Print Examples295405 -Node: Output Separators298185 -Node: OFMT300202 -Node: Printf301558 -Node: Basic Printf302343 -Node: Control Letters303917 -Node: Format Modifiers309079 -Node: Printf Examples315094 -Node: Redirection317580 -Node: Special FD324421 -Ref: Special FD-Footnote-1327589 -Node: Special Files327663 -Node: Other Inherited Files328280 -Node: Special Network329281 -Node: Special Caveats330141 -Node: Close Files And Pipes331090 -Ref: table-close-pipe-return-values337997 -Ref: Close Files And Pipes-Footnote-1338810 -Ref: Close Files And Pipes-Footnote-2338958 -Node: Nonfatal339110 -Node: Output Summary341448 -Node: Output Exercises342670 -Node: Expressions343349 -Node: Values344537 -Node: Constants345215 -Node: Scalar Constants345906 -Ref: Scalar Constants-Footnote-1348416 -Node: Nondecimal-numbers348666 -Node: Regexp Constants351667 -Node: Using Constant Regexps352193 -Node: Standard Regexp Constants352815 -Node: Strong Regexp Constants356003 -Node: Variables359015 -Node: Using Variables359672 -Node: Assignment Options361582 -Node: Conversion364053 -Node: Strings And Numbers364577 -Ref: Strings And Numbers-Footnote-1367640 -Node: Locale influences conversions367749 -Ref: table-locale-affects370507 -Node: All Operators371125 -Node: Arithmetic Ops371754 -Node: Concatenation374470 -Ref: Concatenation-Footnote-1377317 -Node: Assignment Ops377424 -Ref: table-assign-ops382415 -Node: Increment Ops383728 -Node: Truth Values and Conditions387188 -Node: Truth Values388262 -Node: Typing and Comparison389310 -Node: Variable Typing390130 -Ref: Variable Typing-Footnote-1396593 -Ref: Variable Typing-Footnote-2396665 -Node: Comparison Operators396742 -Ref: table-relational-ops397161 -Node: POSIX String Comparison400656 -Ref: POSIX String Comparison-Footnote-1402351 -Ref: POSIX String Comparison-Footnote-2402490 -Node: Boolean Ops402574 -Ref: Boolean Ops-Footnote-1407056 -Node: Conditional Exp407148 -Node: Function Calls408884 -Node: Precedence412761 -Node: Locales416420 -Node: Expressions Summary418052 -Node: Patterns and Actions420625 -Node: Pattern Overview421745 -Node: Regexp Patterns423422 -Node: Expression Patterns423964 -Node: Ranges427745 -Node: BEGIN/END430853 -Node: Using BEGIN/END431614 -Ref: Using BEGIN/END-Footnote-1434368 -Node: I/O And BEGIN/END434474 -Node: BEGINFILE/ENDFILE436787 -Node: Empty440018 -Node: Using Shell Variables440335 -Node: Action Overview442609 -Node: Statements444934 -Node: If Statement446782 -Node: While Statement448277 -Node: Do Statement450305 -Node: For Statement451453 -Node: Switch Statement454624 -Node: Break Statement457065 -Node: Continue Statement459157 -Node: Next Statement460984 -Node: Nextfile Statement463367 -Node: Exit Statement466056 -Node: Built-in Variables468459 -Node: User-modified469592 -Node: Auto-set477359 -Ref: Auto-set-Footnote-1494166 -Ref: Auto-set-Footnote-2494372 -Node: ARGC and ARGV494428 -Node: Pattern Action Summary498641 -Node: Arrays501071 -Node: Array Basics502400 -Node: Array Intro503244 -Ref: figure-array-elements505219 -Ref: Array Intro-Footnote-1507923 -Node: Reference to Elements508051 -Node: Assigning Elements510515 -Node: Array Example511006 -Node: Scanning an Array512765 -Node: Controlling Scanning515787 -Ref: Controlling Scanning-Footnote-1522243 -Node: Numeric Array Subscripts522559 -Node: Uninitialized Subscripts524743 -Node: Delete526362 -Ref: Delete-Footnote-1529114 -Node: Multidimensional529171 -Node: Multiscanning532266 -Node: Arrays of Arrays533857 -Node: Arrays Summary538625 -Node: Functions540718 -Node: Built-in541756 -Node: Calling Built-in542909 -Node: Boolean Functions544905 -Node: Numeric Functions545459 -Ref: Numeric Functions-Footnote-1549486 -Ref: Numeric Functions-Footnote-2550134 -Ref: Numeric Functions-Footnote-3550182 -Node: String Functions550454 -Ref: String Functions-Footnote-1574595 -Ref: String Functions-Footnote-2574723 -Ref: String Functions-Footnote-3574971 -Node: Gory Details575058 -Ref: table-sub-escapes576849 -Ref: table-sub-proposed578368 -Ref: table-posix-sub579731 -Ref: table-gensub-escapes581272 -Ref: Gory Details-Footnote-1582095 -Node: I/O Functions582249 -Ref: table-system-return-values588703 -Ref: I/O Functions-Footnote-1590783 -Ref: I/O Functions-Footnote-2590931 -Node: Time Functions591051 -Ref: Time Functions-Footnote-1601722 -Ref: Time Functions-Footnote-2601790 -Ref: Time Functions-Footnote-3601948 -Ref: Time Functions-Footnote-4602059 -Ref: Time Functions-Footnote-5602171 -Ref: Time Functions-Footnote-6602398 -Node: Bitwise Functions602664 -Ref: table-bitwise-ops603258 -Ref: Bitwise Functions-Footnote-1609321 -Ref: Bitwise Functions-Footnote-2609494 -Node: Type Functions609685 -Node: I18N Functions612639 -Node: User-defined614290 -Node: Definition Syntax615102 -Ref: Definition Syntax-Footnote-1620796 -Node: Function Example620867 -Ref: Function Example-Footnote-1623789 -Node: Function Calling623811 -Node: Calling A Function624399 -Node: Variable Scope625357 -Node: Pass By Value/Reference628351 -Node: Function Caveats630995 -Ref: Function Caveats-Footnote-1633042 -Node: Return Statement633162 -Node: Dynamic Typing636141 -Node: Indirect Calls637071 -Ref: Indirect Calls-Footnote-1647326 -Node: Functions Summary647454 -Node: Library Functions650159 -Ref: Library Functions-Footnote-1653766 -Ref: Library Functions-Footnote-2653909 -Node: Library Names654080 -Ref: Library Names-Footnote-1657747 -Ref: Library Names-Footnote-2657970 -Node: General Functions658056 -Node: Strtonum Function659159 -Node: Assert Function662181 -Node: Round Function665507 -Node: Cliff Random Function667047 -Node: Ordinal Functions668063 -Ref: Ordinal Functions-Footnote-1671126 -Ref: Ordinal Functions-Footnote-2671378 -Node: Join Function671588 -Ref: Join Function-Footnote-1673358 -Node: Getlocaltime Function673558 -Node: Readfile Function677300 -Node: Shell Quoting679277 -Node: Data File Management680678 -Node: Filetrans Function681310 -Node: Rewind Function685406 -Node: File Checking687315 -Ref: File Checking-Footnote-1688649 -Node: Empty Files688850 -Node: Ignoring Assigns690829 -Node: Getopt Function692379 -Ref: Getopt Function-Footnote-1707590 -Node: Passwd Functions707790 -Ref: Passwd Functions-Footnote-1716629 -Node: Group Functions716717 -Ref: Group Functions-Footnote-1724615 -Node: Walking Arrays724822 -Node: Library Functions Summary727830 -Node: Library Exercises729236 -Node: Sample Programs729701 -Node: Running Examples730471 -Node: Clones731199 -Node: Cut Program732423 -Node: Egrep Program742563 -Node: Id Program751564 -Node: Split Program761511 -Ref: Split Program-Footnote-1771401 -Node: Tee Program771574 -Node: Uniq Program774364 -Node: Wc Program781952 -Node: Bytes vs. Characters782339 -Node: Using extensions783887 -Node: wc program784641 -Node: Miscellaneous Programs789506 -Node: Dupword Program790719 -Node: Alarm Program792749 -Node: Translate Program797604 -Ref: Translate Program-Footnote-1802169 -Node: Labels Program802439 -Ref: Labels Program-Footnote-1805790 -Node: Word Sorting805874 -Node: History Sorting809946 -Node: Extract Program812171 -Node: Simple Sed820225 -Node: Igawk Program823299 -Ref: Igawk Program-Footnote-1837630 -Ref: Igawk Program-Footnote-2837832 -Ref: Igawk Program-Footnote-3837954 -Node: Anagram Program838069 -Node: Signature Program841131 -Node: Programs Summary842378 -Node: Programs Exercises843592 -Ref: Programs Exercises-Footnote-1847722 -Node: Advanced Features847808 -Node: Nondecimal Data849939 -Node: Boolean Typed Values851537 -Node: Array Sorting853418 -Node: Controlling Array Traversal854123 -Ref: Controlling Array Traversal-Footnote-1862491 -Node: Array Sorting Functions862609 -Ref: Array Sorting Functions-Footnote-1867700 -Node: Two-way I/O867896 -Ref: Two-way I/O-Footnote-1875617 -Ref: Two-way I/O-Footnote-2875804 -Node: TCP/IP Networking875886 -Node: Profiling879004 -Node: Extension Philosophy888313 -Node: Advanced Features Summary889792 -Node: Internationalization891807 -Node: I18N and L10N893481 -Node: Explaining gettext894168 -Ref: Explaining gettext-Footnote-1900060 -Ref: Explaining gettext-Footnote-2900245 -Node: Programmer i18n900410 -Ref: Programmer i18n-Footnote-1905359 -Node: Translator i18n905408 -Node: String Extraction906202 -Ref: String Extraction-Footnote-1907334 -Node: Printf Ordering907420 -Ref: Printf Ordering-Footnote-1910206 -Node: I18N Portability910270 -Ref: I18N Portability-Footnote-1912726 -Node: I18N Example912789 -Ref: I18N Example-Footnote-1916064 -Ref: I18N Example-Footnote-2916137 -Node: Gawk I18N916246 -Node: I18N Summary916895 -Node: Debugger918236 -Node: Debugging919236 -Node: Debugging Concepts919677 -Node: Debugging Terms921486 -Node: Awk Debugging924061 -Ref: Awk Debugging-Footnote-1925006 -Node: Sample Debugging Session925138 -Node: Debugger Invocation925672 -Node: Finding The Bug927058 -Node: List of Debugger Commands933532 -Node: Breakpoint Control934865 -Node: Debugger Execution Control938559 -Node: Viewing And Changing Data941921 -Node: Execution Stack945462 -Node: Debugger Info947099 -Node: Miscellaneous Debugger Commands951170 -Node: Readline Support956232 -Node: Limitations957128 -Node: Debugging Summary959682 -Node: Namespaces960961 -Node: Global Namespace962072 -Node: Qualified Names963470 -Node: Default Namespace964469 -Node: Changing The Namespace965210 -Node: Naming Rules966824 -Node: Internal Name Management968672 -Node: Namespace Example969714 -Node: Namespace And Features972276 -Node: Namespace Summary973711 -Node: Arbitrary Precision Arithmetic975188 -Node: Computer Arithmetic976675 -Ref: table-numeric-ranges980441 -Ref: table-floating-point-ranges980934 -Ref: Computer Arithmetic-Footnote-1981592 -Node: Math Definitions981649 -Ref: table-ieee-formats984625 -Node: MPFR features985192 -Node: FP Math Caution986910 -Ref: FP Math Caution-Footnote-1987982 -Node: Inexactness of computations988351 -Node: Inexact representation989382 -Node: Comparing FP Values990742 -Node: Errors accumulate991983 -Node: Strange values993439 -Ref: Strange values-Footnote-1996027 -Node: Getting Accuracy996132 -Node: Try To Round998842 -Node: Setting precision999741 -Ref: table-predefined-precision-strings1000438 -Node: Setting the rounding mode1002268 -Ref: table-gawk-rounding-modes1002642 -Ref: Setting the rounding mode-Footnote-11006573 -Node: Arbitrary Precision Integers1006752 -Ref: Arbitrary Precision Integers-Footnote-11009927 -Node: Checking for MPFR1010076 -Node: POSIX Floating Point Problems1011550 -Ref: POSIX Floating Point Problems-Footnote-11015835 -Node: Floating point summary1015873 -Node: Dynamic Extensions1018063 -Node: Extension Intro1019616 -Node: Plugin License1020882 -Node: Extension Mechanism Outline1021679 -Ref: figure-load-extension1022118 -Ref: figure-register-new-function1023683 -Ref: figure-call-new-function1024775 -Node: Extension API Description1026837 -Node: Extension API Functions Introduction1028550 -Ref: table-api-std-headers1030386 -Node: General Data Types1034635 -Ref: General Data Types-Footnote-11043341 -Node: Memory Allocation Functions1043640 -Ref: Memory Allocation Functions-Footnote-11048141 -Node: Constructor Functions1048240 -Node: API Ownership of MPFR and GMP Values1051893 -Node: Registration Functions1053206 -Node: Extension Functions1053906 -Node: Exit Callback Functions1059228 -Node: Extension Version String1060478 -Node: Input Parsers1061141 -Node: Output Wrappers1073862 -Node: Two-way processors1078374 -Node: Printing Messages1080639 -Ref: Printing Messages-Footnote-11081810 -Node: Updating ERRNO1081963 -Node: Requesting Values1082702 -Ref: table-value-types-returned1083439 -Node: Accessing Parameters1084547 -Node: Symbol Table Access1085784 -Node: Symbol table by name1086296 -Ref: Symbol table by name-Footnote-11089320 -Node: Symbol table by cookie1089448 -Ref: Symbol table by cookie-Footnote-11093633 -Node: Cached values1093697 -Ref: Cached values-Footnote-11097233 -Node: Array Manipulation1097386 -Ref: Array Manipulation-Footnote-11098477 -Node: Array Data Types1098514 -Ref: Array Data Types-Footnote-11101172 -Node: Array Functions1101264 -Node: Flattening Arrays1105762 -Node: Creating Arrays1112738 -Node: Redirection API1117505 -Node: Extension API Variables1120338 -Node: Extension Versioning1121049 -Ref: gawk-api-version1121478 -Node: Extension GMP/MPFR Versioning1123209 -Node: Extension API Informational Variables1124837 -Node: Extension API Boilerplate1125910 -Node: Changes from API V11129884 -Node: Finding Extensions1131456 -Node: Extension Example1132015 -Node: Internal File Description1132813 -Node: Internal File Ops1136893 -Ref: Internal File Ops-Footnote-11148243 -Node: Using Internal File Ops1148383 -Ref: Using Internal File Ops-Footnote-11150766 -Node: Extension Samples1151040 -Node: Extension Sample File Functions1152569 -Node: Extension Sample Fnmatch1160218 -Node: Extension Sample Fork1161705 -Node: Extension Sample Inplace1162923 -Node: Extension Sample Ord1166549 -Node: Extension Sample Readdir1167385 -Ref: table-readdir-file-types1168274 -Node: Extension Sample Revout1169341 -Node: Extension Sample Rev2way1169930 -Node: Extension Sample Read write array1170670 -Node: Extension Sample Readfile1172612 -Node: Extension Sample Time1173707 -Node: Extension Sample API Tests1175459 -Node: gawkextlib1175951 -Node: Extension summary1178869 -Node: Extension Exercises1182571 -Node: Language History1183813 -Node: V7/SVR3.11185469 -Node: SVR41187621 -Node: POSIX1189055 -Node: BTL1190436 -Node: POSIX/GNU1191165 -Node: Feature History1196943 -Node: Common Extensions1214118 -Node: Ranges and Locales1215401 -Ref: Ranges and Locales-Footnote-11220017 -Ref: Ranges and Locales-Footnote-21220044 -Ref: Ranges and Locales-Footnote-31220279 -Node: Contributors1220502 -Node: History summary1226499 -Node: Installation1227879 -Node: Gawk Distribution1228823 -Node: Getting1229307 -Node: Extracting1230270 -Node: Distribution contents1231908 -Node: Unix Installation1238388 -Node: Quick Installation1239070 -Node: Shell Startup Files1241484 -Node: Additional Configuration Options1242573 -Node: Configuration Philosophy1244888 -Node: Non-Unix Installation1247257 -Node: PC Installation1247717 -Node: PC Binary Installation1248555 -Node: PC Compiling1248990 -Node: PC Using1250107 -Node: Cygwin1253660 -Node: MSYS1254884 -Node: VMS Installation1255486 -Node: VMS Compilation1256277 -Ref: VMS Compilation-Footnote-11257506 -Node: VMS Dynamic Extensions1257564 -Node: VMS Installation Details1259249 -Node: VMS Running1261502 -Node: VMS GNV1265781 -Node: VMS Old Gawk1266516 -Node: Bugs1266987 -Node: Bug address1267650 -Node: Usenet1270632 -Node: Maintainers1271636 -Node: Other Versions1272821 -Node: Installation summary1280686 -Node: Notes1281895 -Node: Compatibility Mode1282689 -Node: Additions1283471 -Node: Accessing The Source1284396 -Node: Adding Code1285833 -Node: New Ports1292052 -Node: Derived Files1296427 -Ref: Derived Files-Footnote-11302087 -Ref: Derived Files-Footnote-21302122 -Ref: Derived Files-Footnote-31302720 -Node: Future Extensions1302834 -Node: Implementation Limitations1303492 -Node: Extension Design1304702 -Node: Old Extension Problems1305846 -Ref: Old Extension Problems-Footnote-11307364 -Node: Extension New Mechanism Goals1307421 -Ref: Extension New Mechanism Goals-Footnote-11310785 -Node: Extension Other Design Decisions1310974 -Node: Extension Future Growth1313087 -Node: Notes summary1313693 -Node: Basic Concepts1314851 -Node: Basic High Level1315532 -Ref: figure-general-flow1315814 -Ref: figure-process-flow1316499 -Ref: Basic High Level-Footnote-11319800 -Node: Basic Data Typing1319985 -Node: Glossary1323313 -Node: Copying1355200 -Node: GNU Free Documentation License1392743 -Node: Index1417863 +Node: Foreword345205 +Node: Foreword449647 +Node: Preface51179 +Ref: Preface-Footnote-154038 +Ref: Preface-Footnote-254147 +Ref: Preface-Footnote-354381 +Node: History54523 +Node: Names56875 +Ref: Names-Footnote-157979 +Node: This Manual58126 +Ref: This Manual-Footnote-164765 +Node: Conventions64865 +Node: Manual History67234 +Ref: Manual History-Footnote-170231 +Ref: Manual History-Footnote-270272 +Node: How To Contribute70346 +Node: Acknowledgments71272 +Node: Getting Started76209 +Node: Running gawk78648 +Node: One-shot79838 +Node: Read Terminal81101 +Node: Long83094 +Node: Executable Scripts84607 +Ref: Executable Scripts-Footnote-187240 +Node: Comments87343 +Node: Quoting89827 +Node: DOS Quoting95353 +Node: Sample Data Files97409 +Node: Very Simple100004 +Node: Two Rules106106 +Node: More Complex107991 +Node: Statements/Lines110323 +Ref: Statements/Lines-Footnote-1114807 +Node: Other Features115072 +Node: When116008 +Ref: When-Footnote-1117762 +Node: Intro Summary117827 +Node: Invoking Gawk118711 +Node: Command Line120225 +Node: Options121023 +Ref: Options-Footnote-1138937 +Ref: Options-Footnote-2139168 +Node: Other Arguments139193 +Node: Naming Standard Input143204 +Node: Environment Variables144414 +Node: AWKPATH Variable144972 +Ref: AWKPATH Variable-Footnote-1148384 +Ref: AWKPATH Variable-Footnote-2148418 +Node: AWKLIBPATH Variable148789 +Ref: AWKLIBPATH Variable-Footnote-1150486 +Node: Other Environment Variables150861 +Node: Exit Status154813 +Node: Include Files155490 +Node: Loading Shared Libraries159180 +Node: Obsolete160608 +Node: Undocumented161300 +Node: Invoking Summary161597 +Node: Regexp164438 +Node: Regexp Usage165892 +Node: Escape Sequences167929 +Node: Regexp Operators174170 +Node: Regexp Operator Details174655 +Ref: Regexp Operator Details-Footnote-1182019 +Node: Interval Expressions182166 +Ref: Interval Expressions-Footnote-1183587 +Node: Bracket Expressions183685 +Ref: table-char-classes186161 +Node: Leftmost Longest189487 +Node: Computed Regexps190790 +Node: GNU Regexp Operators194217 +Node: Case-sensitivity197954 +Ref: Case-sensitivity-Footnote-1200820 +Ref: Case-sensitivity-Footnote-2201055 +Node: Regexp Summary201163 +Node: Reading Files202629 +Node: Records204898 +Node: awk split records205973 +Node: gawk split records210673 +Ref: gawk split records-Footnote-1215747 +Node: Fields215784 +Node: Nonconstant Fields218525 +Ref: Nonconstant Fields-Footnote-1220761 +Node: Changing Fields220965 +Node: Field Separators226996 +Node: Default Field Splitting229694 +Node: Regexp Field Splitting230812 +Node: Single Character Fields234489 +Node: Command Line Field Separator235549 +Node: Full Line Fields238767 +Ref: Full Line Fields-Footnote-1240289 +Ref: Full Line Fields-Footnote-2240335 +Node: Field Splitting Summary240436 +Node: Constant Size242510 +Node: Fixed width data243242 +Node: Skipping intervening246709 +Node: Allowing trailing data247507 +Node: Fields with fixed data248544 +Node: Splitting By Content250062 +Ref: Splitting By Content-Footnote-1253845 +Node: More CSV254008 +Node: Testing field creation255600 +Node: Multiple Line257225 +Node: Getline263502 +Node: Plain Getline265971 +Node: Getline/Variable268544 +Node: Getline/File269695 +Node: Getline/Variable/File271083 +Ref: Getline/Variable/File-Footnote-1272688 +Node: Getline/Pipe272776 +Node: Getline/Variable/Pipe275480 +Node: Getline/Coprocess276615 +Node: Getline/Variable/Coprocess277882 +Node: Getline Notes278624 +Node: Getline Summary281421 +Ref: table-getline-variants281845 +Node: Read Timeout282593 +Ref: Read Timeout-Footnote-1286499 +Node: Retrying Input286557 +Node: Command-line directories287756 +Node: Input Summary288662 +Node: Input Exercises291834 +Node: Printing292268 +Node: Print294102 +Node: Print Examples295559 +Node: Output Separators298339 +Node: OFMT300356 +Node: Printf301712 +Node: Basic Printf302497 +Node: Control Letters304071 +Node: Format Modifiers309233 +Node: Printf Examples315248 +Node: Redirection317734 +Node: Special FD324575 +Ref: Special FD-Footnote-1327743 +Node: Special Files327817 +Node: Other Inherited Files328434 +Node: Special Network329435 +Node: Special Caveats330295 +Node: Close Files And Pipes331244 +Ref: table-close-pipe-return-values338151 +Ref: Close Files And Pipes-Footnote-1338964 +Ref: Close Files And Pipes-Footnote-2339112 +Node: Nonfatal339264 +Node: Output Summary341602 +Node: Output Exercises342824 +Node: Expressions343503 +Node: Values344691 +Node: Constants345369 +Node: Scalar Constants346060 +Ref: Scalar Constants-Footnote-1348570 +Node: Nondecimal-numbers348820 +Node: Regexp Constants351821 +Node: Using Constant Regexps352347 +Node: Standard Regexp Constants352969 +Node: Strong Regexp Constants356157 +Node: Variables359169 +Node: Using Variables359826 +Node: Assignment Options361736 +Node: Conversion364207 +Node: Strings And Numbers364731 +Ref: Strings And Numbers-Footnote-1367794 +Node: Locale influences conversions367903 +Ref: table-locale-affects370661 +Node: All Operators371279 +Node: Arithmetic Ops371908 +Node: Concatenation374624 +Ref: Concatenation-Footnote-1377471 +Node: Assignment Ops377578 +Ref: table-assign-ops382569 +Node: Increment Ops383882 +Node: Truth Values and Conditions387342 +Node: Truth Values388416 +Node: Typing and Comparison389464 +Node: Variable Typing390284 +Ref: Variable Typing-Footnote-1396747 +Ref: Variable Typing-Footnote-2396819 +Node: Comparison Operators396896 +Ref: table-relational-ops397315 +Node: POSIX String Comparison400810 +Ref: POSIX String Comparison-Footnote-1402505 +Ref: POSIX String Comparison-Footnote-2402644 +Node: Boolean Ops402728 +Ref: Boolean Ops-Footnote-1407210 +Node: Conditional Exp407302 +Node: Function Calls409038 +Node: Precedence412915 +Node: Locales416574 +Node: Expressions Summary418206 +Node: Patterns and Actions420779 +Node: Pattern Overview421899 +Node: Regexp Patterns423576 +Node: Expression Patterns424118 +Node: Ranges427899 +Node: BEGIN/END431007 +Node: Using BEGIN/END431768 +Ref: Using BEGIN/END-Footnote-1434522 +Node: I/O And BEGIN/END434628 +Node: BEGINFILE/ENDFILE436941 +Node: Empty440172 +Node: Using Shell Variables440489 +Node: Action Overview442763 +Node: Statements445088 +Node: If Statement446936 +Node: While Statement448431 +Node: Do Statement450459 +Node: For Statement451607 +Node: Switch Statement454778 +Node: Break Statement457219 +Node: Continue Statement459311 +Node: Next Statement461138 +Node: Nextfile Statement463521 +Node: Exit Statement466210 +Node: Built-in Variables468613 +Node: User-modified469746 +Node: Auto-set477513 +Ref: Auto-set-Footnote-1494320 +Ref: Auto-set-Footnote-2494526 +Node: ARGC and ARGV494582 +Node: Pattern Action Summary498795 +Node: Arrays501225 +Node: Array Basics502554 +Node: Array Intro503398 +Ref: figure-array-elements505373 +Ref: Array Intro-Footnote-1508077 +Node: Reference to Elements508205 +Node: Assigning Elements510669 +Node: Array Example511160 +Node: Scanning an Array512919 +Node: Controlling Scanning515941 +Ref: Controlling Scanning-Footnote-1522397 +Node: Numeric Array Subscripts522713 +Node: Uninitialized Subscripts524897 +Node: Delete526516 +Ref: Delete-Footnote-1529268 +Node: Multidimensional529325 +Node: Multiscanning532420 +Node: Arrays of Arrays534011 +Node: Arrays Summary538779 +Node: Functions540872 +Node: Built-in541910 +Node: Calling Built-in543063 +Node: Boolean Functions545059 +Node: Numeric Functions545613 +Ref: Numeric Functions-Footnote-1549640 +Ref: Numeric Functions-Footnote-2550288 +Ref: Numeric Functions-Footnote-3550336 +Node: String Functions550608 +Ref: String Functions-Footnote-1574749 +Ref: String Functions-Footnote-2574877 +Ref: String Functions-Footnote-3575125 +Node: Gory Details575212 +Ref: table-sub-escapes577003 +Ref: table-sub-proposed578522 +Ref: table-posix-sub579885 +Ref: table-gensub-escapes581426 +Ref: Gory Details-Footnote-1582249 +Node: I/O Functions582403 +Ref: table-system-return-values588857 +Ref: I/O Functions-Footnote-1590937 +Ref: I/O Functions-Footnote-2591085 +Node: Time Functions591205 +Ref: Time Functions-Footnote-1601876 +Ref: Time Functions-Footnote-2601944 +Ref: Time Functions-Footnote-3602102 +Ref: Time Functions-Footnote-4602213 +Ref: Time Functions-Footnote-5602325 +Ref: Time Functions-Footnote-6602552 +Node: Bitwise Functions602818 +Ref: table-bitwise-ops603412 +Ref: Bitwise Functions-Footnote-1609475 +Ref: Bitwise Functions-Footnote-2609648 +Node: Type Functions609839 +Node: I18N Functions612793 +Node: User-defined614444 +Node: Definition Syntax615256 +Ref: Definition Syntax-Footnote-1620950 +Node: Function Example621021 +Ref: Function Example-Footnote-1623943 +Node: Function Calling623965 +Node: Calling A Function624553 +Node: Variable Scope625511 +Node: Pass By Value/Reference628505 +Node: Function Caveats631149 +Ref: Function Caveats-Footnote-1633196 +Node: Return Statement633316 +Node: Dynamic Typing636295 +Node: Indirect Calls637225 +Ref: Indirect Calls-Footnote-1647480 +Node: Functions Summary647608 +Node: Library Functions650313 +Ref: Library Functions-Footnote-1653920 +Ref: Library Functions-Footnote-2654063 +Node: Library Names654234 +Ref: Library Names-Footnote-1657901 +Ref: Library Names-Footnote-2658124 +Node: General Functions658210 +Node: Strtonum Function659313 +Node: Assert Function662335 +Node: Round Function665661 +Node: Cliff Random Function667201 +Node: Ordinal Functions668217 +Ref: Ordinal Functions-Footnote-1671280 +Ref: Ordinal Functions-Footnote-2671532 +Node: Join Function671742 +Ref: Join Function-Footnote-1673512 +Node: Getlocaltime Function673712 +Node: Readfile Function677454 +Node: Shell Quoting679431 +Node: Data File Management680832 +Node: Filetrans Function681464 +Node: Rewind Function685560 +Node: File Checking687469 +Ref: File Checking-Footnote-1688803 +Node: Empty Files689004 +Node: Ignoring Assigns690983 +Node: Getopt Function692533 +Ref: Getopt Function-Footnote-1707744 +Node: Passwd Functions707944 +Ref: Passwd Functions-Footnote-1716783 +Node: Group Functions716871 +Ref: Group Functions-Footnote-1724769 +Node: Walking Arrays724976 +Node: Library Functions Summary727984 +Node: Library Exercises729390 +Node: Sample Programs729855 +Node: Running Examples730625 +Node: Clones731353 +Node: Cut Program732577 +Node: Egrep Program742717 +Node: Id Program751718 +Node: Split Program761665 +Ref: Split Program-Footnote-1771555 +Node: Tee Program771728 +Node: Uniq Program774518 +Node: Wc Program782106 +Node: Bytes vs. Characters782493 +Node: Using extensions784041 +Node: wc program784795 +Node: Miscellaneous Programs789660 +Node: Dupword Program790873 +Node: Alarm Program792903 +Node: Translate Program797758 +Ref: Translate Program-Footnote-1802323 +Node: Labels Program802593 +Ref: Labels Program-Footnote-1805944 +Node: Word Sorting806028 +Node: History Sorting810100 +Node: Extract Program812325 +Node: Simple Sed820379 +Node: Igawk Program823453 +Ref: Igawk Program-Footnote-1837784 +Ref: Igawk Program-Footnote-2837986 +Ref: Igawk Program-Footnote-3838108 +Node: Anagram Program838223 +Node: Signature Program841285 +Node: Programs Summary842532 +Node: Programs Exercises843746 +Ref: Programs Exercises-Footnote-1847876 +Node: Advanced Features847962 +Node: Nondecimal Data850093 +Node: Boolean Typed Values851691 +Node: Array Sorting853572 +Node: Controlling Array Traversal854277 +Ref: Controlling Array Traversal-Footnote-1862645 +Node: Array Sorting Functions862763 +Ref: Array Sorting Functions-Footnote-1867854 +Node: Two-way I/O868050 +Ref: Two-way I/O-Footnote-1875771 +Ref: Two-way I/O-Footnote-2875958 +Node: TCP/IP Networking876040 +Node: Profiling879158 +Node: Extension Philosophy888467 +Node: Advanced Features Summary889946 +Node: Internationalization891961 +Node: I18N and L10N893635 +Node: Explaining gettext894322 +Ref: Explaining gettext-Footnote-1900214 +Ref: Explaining gettext-Footnote-2900399 +Node: Programmer i18n900564 +Ref: Programmer i18n-Footnote-1905513 +Node: Translator i18n905562 +Node: String Extraction906356 +Ref: String Extraction-Footnote-1907488 +Node: Printf Ordering907574 +Ref: Printf Ordering-Footnote-1910360 +Node: I18N Portability910424 +Ref: I18N Portability-Footnote-1912880 +Node: I18N Example912943 +Ref: I18N Example-Footnote-1916218 +Ref: I18N Example-Footnote-2916291 +Node: Gawk I18N916400 +Node: I18N Summary917049 +Node: Debugger918390 +Node: Debugging919390 +Node: Debugging Concepts919831 +Node: Debugging Terms921640 +Node: Awk Debugging924215 +Ref: Awk Debugging-Footnote-1925160 +Node: Sample Debugging Session925292 +Node: Debugger Invocation925826 +Node: Finding The Bug927212 +Node: List of Debugger Commands933686 +Node: Breakpoint Control935019 +Node: Debugger Execution Control938713 +Node: Viewing And Changing Data942075 +Node: Execution Stack945616 +Node: Debugger Info947253 +Node: Miscellaneous Debugger Commands951324 +Node: Readline Support956386 +Node: Limitations957282 +Node: Debugging Summary959836 +Node: Namespaces961115 +Node: Global Namespace962226 +Node: Qualified Names963624 +Node: Default Namespace964623 +Node: Changing The Namespace965364 +Node: Naming Rules966978 +Node: Internal Name Management968826 +Node: Namespace Example969868 +Node: Namespace And Features972430 +Node: Namespace Summary973865 +Node: Arbitrary Precision Arithmetic975342 +Node: Computer Arithmetic976829 +Ref: table-numeric-ranges980595 +Ref: table-floating-point-ranges981088 +Ref: Computer Arithmetic-Footnote-1981746 +Node: Math Definitions981803 +Ref: table-ieee-formats984779 +Node: MPFR features985346 +Node: FP Math Caution987064 +Ref: FP Math Caution-Footnote-1988136 +Node: Inexactness of computations988505 +Node: Inexact representation989536 +Node: Comparing FP Values990896 +Node: Errors accumulate992137 +Node: Strange values993593 +Ref: Strange values-Footnote-1996181 +Node: Getting Accuracy996286 +Node: Try To Round998996 +Node: Setting precision999895 +Ref: table-predefined-precision-strings1000592 +Node: Setting the rounding mode1002422 +Ref: table-gawk-rounding-modes1002796 +Ref: Setting the rounding mode-Footnote-11006727 +Node: Arbitrary Precision Integers1006906 +Ref: Arbitrary Precision Integers-Footnote-11010081 +Node: Checking for MPFR1010230 +Node: POSIX Floating Point Problems1011704 +Ref: POSIX Floating Point Problems-Footnote-11015989 +Node: Floating point summary1016027 +Node: Dynamic Extensions1018217 +Node: Extension Intro1019770 +Node: Plugin License1021036 +Node: Extension Mechanism Outline1021833 +Ref: figure-load-extension1022272 +Ref: figure-register-new-function1023837 +Ref: figure-call-new-function1024929 +Node: Extension API Description1026991 +Node: Extension API Functions Introduction1028704 +Ref: table-api-std-headers1030540 +Node: General Data Types1034789 +Ref: General Data Types-Footnote-11043495 +Node: Memory Allocation Functions1043794 +Ref: Memory Allocation Functions-Footnote-11048295 +Node: Constructor Functions1048394 +Node: API Ownership of MPFR and GMP Values1052047 +Node: Registration Functions1053360 +Node: Extension Functions1054060 +Node: Exit Callback Functions1059382 +Node: Extension Version String1060632 +Node: Input Parsers1061295 +Node: Output Wrappers1074016 +Node: Two-way processors1078528 +Node: Printing Messages1080793 +Ref: Printing Messages-Footnote-11081964 +Node: Updating ERRNO1082117 +Node: Requesting Values1082856 +Ref: table-value-types-returned1083593 +Node: Accessing Parameters1084701 +Node: Symbol Table Access1085938 +Node: Symbol table by name1086450 +Ref: Symbol table by name-Footnote-11089474 +Node: Symbol table by cookie1089602 +Ref: Symbol table by cookie-Footnote-11093787 +Node: Cached values1093851 +Ref: Cached values-Footnote-11097387 +Node: Array Manipulation1097540 +Ref: Array Manipulation-Footnote-11098631 +Node: Array Data Types1098668 +Ref: Array Data Types-Footnote-11101326 +Node: Array Functions1101418 +Node: Flattening Arrays1105916 +Node: Creating Arrays1112892 +Node: Redirection API1117659 +Node: Extension API Variables1120492 +Node: Extension Versioning1121203 +Ref: gawk-api-version1121632 +Node: Extension GMP/MPFR Versioning1123363 +Node: Extension API Informational Variables1124991 +Node: Extension API Boilerplate1126064 +Node: Changes from API V11130038 +Node: Finding Extensions1131610 +Node: Extension Example1132169 +Node: Internal File Description1132967 +Node: Internal File Ops1137047 +Ref: Internal File Ops-Footnote-11148397 +Node: Using Internal File Ops1148537 +Ref: Using Internal File Ops-Footnote-11150920 +Node: Extension Samples1151194 +Node: Extension Sample File Functions1152723 +Node: Extension Sample Fnmatch1160372 +Node: Extension Sample Fork1161859 +Node: Extension Sample Inplace1163077 +Node: Extension Sample Ord1166703 +Node: Extension Sample Readdir1167539 +Ref: table-readdir-file-types1168428 +Node: Extension Sample Revout1169495 +Node: Extension Sample Rev2way1170084 +Node: Extension Sample Read write array1170824 +Node: Extension Sample Readfile1172766 +Node: Extension Sample Time1173861 +Node: Extension Sample API Tests1175613 +Node: gawkextlib1176105 +Node: Extension summary1179023 +Node: Extension Exercises1182725 +Node: Language History1183967 +Node: V7/SVR3.11185623 +Node: SVR41187775 +Node: POSIX1189209 +Node: BTL1190590 +Node: POSIX/GNU1191319 +Node: Feature History1197097 +Node: Common Extensions1214272 +Node: Ranges and Locales1215555 +Ref: Ranges and Locales-Footnote-11220171 +Ref: Ranges and Locales-Footnote-21220198 +Ref: Ranges and Locales-Footnote-31220433 +Node: Contributors1220656 +Node: History summary1226653 +Node: Installation1228033 +Node: Gawk Distribution1228977 +Node: Getting1229461 +Node: Extracting1230424 +Node: Distribution contents1232062 +Node: Unix Installation1238542 +Node: Quick Installation1239224 +Node: Compiling with MPFR1241705 +Node: Shell Startup Files1242397 +Node: Additional Configuration Options1243486 +Node: Configuration Philosophy1245801 +Node: Non-Unix Installation1248170 +Node: PC Installation1248630 +Node: PC Binary Installation1249468 +Node: PC Compiling1249903 +Node: PC Using1251020 +Node: Cygwin1254573 +Node: MSYS1255797 +Node: VMS Installation1256399 +Node: VMS Compilation1257190 +Ref: VMS Compilation-Footnote-11258419 +Node: VMS Dynamic Extensions1258477 +Node: VMS Installation Details1260162 +Node: VMS Running1262415 +Node: VMS GNV1266694 +Node: VMS Old Gawk1267429 +Node: Bugs1267900 +Node: Bug address1268649 +Node: Usenet1271631 +Node: Performance bugs1272640 +Node: Maintainers1275497 +Node: Other Versions1276692 +Node: Installation summary1284557 +Node: Notes1285766 +Node: Compatibility Mode1286560 +Node: Additions1287342 +Node: Accessing The Source1288267 +Node: Adding Code1289704 +Node: New Ports1295923 +Node: Derived Files1300298 +Ref: Derived Files-Footnote-11305958 +Ref: Derived Files-Footnote-21305993 +Ref: Derived Files-Footnote-31306591 +Node: Future Extensions1306705 +Node: Implementation Limitations1307363 +Node: Extension Design1308573 +Node: Old Extension Problems1309717 +Ref: Old Extension Problems-Footnote-11311235 +Node: Extension New Mechanism Goals1311292 +Ref: Extension New Mechanism Goals-Footnote-11314656 +Node: Extension Other Design Decisions1314845 +Node: Extension Future Growth1316958 +Node: Notes summary1317564 +Node: Basic Concepts1318722 +Node: Basic High Level1319403 +Ref: figure-general-flow1319685 +Ref: figure-process-flow1320370 +Ref: Basic High Level-Footnote-11323671 +Node: Basic Data Typing1323856 +Node: Glossary1327184 +Node: Copying1359071 +Node: GNU Free Documentation License1396614 +Node: Index1421734 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 476c3717..d0832b5c 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -1031,6 +1031,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. @@ -1060,6 +1061,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. @@ -42186,6 +42188,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. @@ -42259,6 +42265,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 @@ -43055,6 +43079,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 @@ -43164,6 +43189,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 8a6587c3..24a04336 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -1026,6 +1026,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. @@ -1055,6 +1056,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. @@ -41029,6 +41031,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. @@ -41102,6 +41108,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 @@ -41898,6 +41922,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 @@ -42007,6 +42032,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 |