diff options
| -rw-r--r-- | doc/ChangeLog | 4 | ||||
| -rw-r--r-- | doc/gawk.info | 803 | ||||
| -rw-r--r-- | doc/gawk.texi | 28 | ||||
| -rw-r--r-- | doc/gawktexi.in | 28 |
4 files changed, 439 insertions, 424 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index bfb0dbed..171de6b7 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,7 @@ +2015-02-09 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Restore a lost sentence. O'Reilly fixes. + 2015-02-08 Arnold D. Robbins <arnold@skeeve.com> * gawktexi.in: O'Reilly fixes. diff --git a/doc/gawk.info b/doc/gawk.info index a8e11ab9..d1cb9215 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -9072,9 +9072,10 @@ accepts any record with a first field that contains `li': -| 555-5553 -| 555-6699 - pattern. The expression `/li/' has the value one if `li' appears in -the current input record. Thus, as a pattern, `/li/' matches any record -containing `li'. + A regexp constant as a pattern is also a special case of an +expression pattern. The expression `/li/' has the value one if `li' +appears in the current input record. Thus, as a pattern, `/li/' matches +any record containing `li'. Boolean expressions are also commonly used as patterns. Whether the pattern matches an input record depends on whether its subexpressions @@ -22737,7 +22738,7 @@ the rest of this Info file. `gawk''s functionality. For example, they can provide access to system calls (such as `chdir()' to change directory) and to other C library routines that could be of use. As with most software, "the sky is the -limit;" if you can imagine something that you might want to do and can +limit"; if you can imagine something that you might want to do and can write in C or C++, you can write an extension to do it! Extensions are written in C or C++, using the "application @@ -22745,7 +22746,7 @@ programming interface" (API) defined for this purpose by the `gawk' developers. The rest of this major node explains the facilities that the API provides and how to use them, and presents a small example extension. In addition, it documents the sample extensions included in -the `gawk' distribution, and describes the `gawkextlib' project. *Note +the `gawk' distribution and describes the `gawkextlib' project. *Note Extension Design::, for a discussion of the extension mechanism goals and design. @@ -22863,7 +22864,7 @@ Example::) and also in the `testext.c' code for testing the APIs. Some other bits and pieces: * The API provides access to `gawk''s `do_XXX' values, reflecting - command-line options, like `do_lint', `do_profiling' and so on + command-line options, like `do_lint', `do_profiling', and so on (*note Extension API Variables::). These are informational: an extension cannot affect their values inside `gawk'. In addition, attempting to assign to them produces a compile-time error. @@ -22909,8 +22910,8 @@ File: gawk.info, Node: Extension API Functions Introduction, Next: General Dat 16.4.1 Introduction ------------------- -Access to facilities within `gawk' are made available by calling -through function pointers passed into your extension. +Access to facilities within `gawk' is achieved by calling through +function pointers passed into your extension. API function pointers are provided for the following kinds of operations: @@ -22931,7 +22932,7 @@ operations: - Two-way processors - All of these are discussed in detail, later in this major node. + All of these are discussed in detail later in this major node. * Printing fatal, warning, and "lint" warning messages. @@ -22957,7 +22958,7 @@ operations: - Clearing an array - - Flattening an array for easy C style looping over all its + - Flattening an array for easy C-style looping over all its indices and elements Some points about using the API: @@ -22966,7 +22967,7 @@ operations: `gawkapi.h'. For correct use, you must therefore include the corresponding standard header file _before_ including `gawkapi.h': - C Entity Header File + C entity Header file ------------------------------------------- `EOF' `<stdio.h>' Values for `errno' `<errno.h>' @@ -22990,13 +22991,13 @@ operations: * Although the API only uses ISO C 90 features, there is an exception; the "constructor" functions use the `inline' keyword. If your compiler does not support this keyword, you should either - place `-Dinline=''' on your command line, or use the GNU Autotools + place `-Dinline=''' on your command line or use the GNU Autotools and include a `config.h' file in your extensions. * All pointers filled in by `gawk' point to memory managed by `gawk' and should be treated by the extension as read-only. Memory for _all_ strings passed into `gawk' from the extension _must_ come - from calling one of `gawk_malloc()', `gawk_calloc()' or + from calling one of `gawk_malloc()', `gawk_calloc()', or `gawk_realloc()', and is managed by `gawk' from then on. * The API defines several simple `struct's that map values as seen @@ -23009,7 +23010,7 @@ operations: multibyte encoding (as defined by `LC_XXX' environment variables) and not using wide characters. This matches how `gawk' stores strings internally and also how characters are - likely to be input and output from files. + likely to be input into and output from files. * When retrieving a value (such as a parameter or that of a global variable or array element), the extension requests a specific type @@ -23046,6 +23047,8 @@ general-purpose use. Additional, more specialized, data structures are introduced in subsequent minor nodes, together with the functions that use them. + The general-purpose types and structures are as follows: + `typedef void *awk_ext_id_t;' A value of this type is received from `gawk' when an extension is loaded. That value must then be passed back to `gawk' as the @@ -23061,7 +23064,7 @@ use them. ` awk_false = 0,' ` awk_true' `} awk_bool_t;' - A simple boolean type. + A simple Boolean type. `typedef struct awk_string {' ` char *str; /* data */' @@ -23105,8 +23108,8 @@ use them. `#define array_cookie u.a' `#define scalar_cookie u.scl' `#define value_cookie u.vc' - These macros make accessing the fields of the `awk_value_t' more - readable. + Using these macros makes accessing the fields of the `awk_value_t' + more readable. `typedef void *awk_scalar_t;' Scalars can be represented as an opaque type. These values are @@ -32123,7 +32126,7 @@ Index * BEGIN pattern, and profiling: Profiling. (line 62) * BEGIN pattern, assert() user-defined function and: Assert Function. (line 83) -* BEGIN pattern, Boolean patterns and: Expression Patterns. (line 69) +* BEGIN pattern, Boolean patterns and: Expression Patterns. (line 70) * BEGIN pattern, exit statement and: Exit Statement. (line 12) * BEGIN pattern, getline and: Getline Notes. (line 19) * BEGIN pattern, headings, adding: Print Examples. (line 43) @@ -32140,7 +32143,7 @@ Index * BEGIN pattern, TEXTDOMAIN variable and: Programmer i18n. (line 60) * BEGINFILE pattern: BEGINFILE/ENDFILE. (line 6) * BEGINFILE pattern, Boolean patterns and: Expression Patterns. - (line 69) + (line 70) * beginfile() user-defined function: Filetrans Function. (line 62) * Bentley, Jon: Glossary. (line 207) * Benzinger, Michael: Contributors. (line 97) @@ -32166,7 +32169,7 @@ Index * body, in actions: Statements. (line 10) * body, in loops: While Statement. (line 14) * Boolean expressions: Boolean Ops. (line 6) -* Boolean expressions, as patterns: Expression Patterns. (line 38) +* Boolean expressions, as patterns: Expression Patterns. (line 39) * Boolean operators, See Boolean expressions: Boolean Ops. (line 6) * Bourne shell, quoting rules for: Quoting. (line 18) * braces ({}): Profiling. (line 142) @@ -32751,7 +32754,7 @@ Index * END pattern, and profiling: Profiling. (line 62) * END pattern, assert() user-defined function and: Assert Function. (line 75) -* END pattern, Boolean patterns and: Expression Patterns. (line 69) +* END pattern, Boolean patterns and: Expression Patterns. (line 70) * END pattern, exit statement and: Exit Statement. (line 12) * END pattern, next/nextfile statements and <1>: Next Statement. (line 44) @@ -32760,7 +32763,7 @@ Index * END pattern, operators and: Using BEGIN/END. (line 17) * END pattern, print statement and: I/O And BEGIN/END. (line 16) * ENDFILE pattern: BEGINFILE/ENDFILE. (line 6) -* ENDFILE pattern, Boolean patterns and: Expression Patterns. (line 69) +* ENDFILE pattern, Boolean patterns and: Expression Patterns. (line 70) * endfile() user-defined function: Filetrans Function. (line 62) * endgrent() function (C library): Group Functions. (line 212) * endgrent() user-defined function: Group Functions. (line 215) @@ -34828,383 +34831,383 @@ Node: Patterns and Actions384592 Node: Pattern Overview385712 Node: Regexp Patterns387391 Node: Expression Patterns387934 -Node: Ranges391643 -Node: BEGIN/END394750 -Node: Using BEGIN/END395511 -Ref: Using BEGIN/END-Footnote-1398247 -Node: I/O And BEGIN/END398353 -Node: BEGINFILE/ENDFILE400668 -Node: Empty403565 -Node: Using Shell Variables403882 -Node: Action Overview406155 -Node: Statements408481 -Node: If Statement410329 -Node: While Statement411824 -Node: Do Statement413852 -Node: For Statement415000 -Node: Switch Statement418158 -Node: Break Statement420540 -Node: Continue Statement422581 -Node: Next Statement424408 -Node: Nextfile Statement426789 -Node: Exit Statement429417 -Node: Built-in Variables431828 -Node: User-modified432961 -Ref: User-modified-Footnote-1440664 -Node: Auto-set440726 -Ref: Auto-set-Footnote-1454435 -Ref: Auto-set-Footnote-2454640 -Node: ARGC and ARGV454696 -Node: Pattern Action Summary458914 -Node: Arrays461347 -Node: Array Basics462676 -Node: Array Intro463520 -Ref: figure-array-elements465454 -Ref: Array Intro-Footnote-1468074 -Node: Reference to Elements468202 -Node: Assigning Elements470664 -Node: Array Example471155 -Node: Scanning an Array472914 -Node: Controlling Scanning475934 -Ref: Controlling Scanning-Footnote-1481328 -Node: Numeric Array Subscripts481644 -Node: Uninitialized Subscripts483829 -Node: Delete485446 -Ref: Delete-Footnote-1488195 -Node: Multidimensional488252 -Node: Multiscanning491349 -Node: Arrays of Arrays492938 -Node: Arrays Summary497692 -Node: Functions499783 -Node: Built-in500822 -Node: Calling Built-in501900 -Node: Numeric Functions503895 -Ref: Numeric Functions-Footnote-1508713 -Ref: Numeric Functions-Footnote-2509070 -Ref: Numeric Functions-Footnote-3509118 -Node: String Functions509390 -Ref: String Functions-Footnote-1532891 -Ref: String Functions-Footnote-2533020 -Ref: String Functions-Footnote-3533268 -Node: Gory Details533355 -Ref: table-sub-escapes535136 -Ref: table-sub-proposed536651 -Ref: table-posix-sub538013 -Ref: table-gensub-escapes539550 -Ref: Gory Details-Footnote-1540383 -Node: I/O Functions540534 -Ref: I/O Functions-Footnote-1547770 -Node: Time Functions547917 -Ref: Time Functions-Footnote-1558426 -Ref: Time Functions-Footnote-2558494 -Ref: Time Functions-Footnote-3558652 -Ref: Time Functions-Footnote-4558763 -Ref: Time Functions-Footnote-5558875 -Ref: Time Functions-Footnote-6559102 -Node: Bitwise Functions559368 -Ref: table-bitwise-ops559930 -Ref: Bitwise Functions-Footnote-1564258 -Node: Type Functions564430 -Node: I18N Functions565582 -Node: User-defined567229 -Node: Definition Syntax568034 -Ref: Definition Syntax-Footnote-1573693 -Node: Function Example573764 -Ref: Function Example-Footnote-1576685 -Node: Function Caveats576707 -Node: Calling A Function577225 -Node: Variable Scope578183 -Node: Pass By Value/Reference581176 -Node: Return Statement584673 -Node: Dynamic Typing587652 -Node: Indirect Calls588581 -Ref: Indirect Calls-Footnote-1599887 -Node: Functions Summary600015 -Node: Library Functions602717 -Ref: Library Functions-Footnote-1606325 -Ref: Library Functions-Footnote-2606468 -Node: Library Names606639 -Ref: Library Names-Footnote-1610097 -Ref: Library Names-Footnote-2610320 -Node: General Functions610406 -Node: Strtonum Function611509 -Node: Assert Function614531 -Node: Round Function617855 -Node: Cliff Random Function619396 -Node: Ordinal Functions620412 -Ref: Ordinal Functions-Footnote-1623475 -Ref: Ordinal Functions-Footnote-2623727 -Node: Join Function623938 -Ref: Join Function-Footnote-1625708 -Node: Getlocaltime Function625908 -Node: Readfile Function629652 -Node: Shell Quoting631624 -Node: Data File Management633025 -Node: Filetrans Function633657 -Node: Rewind Function637753 -Node: File Checking639139 -Ref: File Checking-Footnote-1640472 -Node: Empty Files640673 -Node: Ignoring Assigns642652 -Node: Getopt Function644202 -Ref: Getopt Function-Footnote-1655666 -Node: Passwd Functions655866 -Ref: Passwd Functions-Footnote-1664706 -Node: Group Functions664794 -Ref: Group Functions-Footnote-1672691 -Node: Walking Arrays672896 -Node: Library Functions Summary674496 -Node: Library Exercises675900 -Node: Sample Programs677180 -Node: Running Examples677950 -Node: Clones678678 -Node: Cut Program679902 -Node: Egrep Program689622 -Ref: Egrep Program-Footnote-1697125 -Node: Id Program697235 -Node: Split Program700911 -Ref: Split Program-Footnote-1704365 -Node: Tee Program704493 -Node: Uniq Program707282 -Node: Wc Program714701 -Ref: Wc Program-Footnote-1718951 -Node: Miscellaneous Programs719045 -Node: Dupword Program720258 -Node: Alarm Program722289 -Node: Translate Program727094 -Ref: Translate Program-Footnote-1731657 -Node: Labels Program731927 -Ref: Labels Program-Footnote-1735278 -Node: Word Sorting735362 -Node: History Sorting739432 -Node: Extract Program741267 -Node: Simple Sed748791 -Node: Igawk Program751861 -Ref: Igawk Program-Footnote-1766187 -Ref: Igawk Program-Footnote-2766388 -Ref: Igawk Program-Footnote-3766510 -Node: Anagram Program766625 -Node: Signature Program769686 -Node: Programs Summary770933 -Node: Programs Exercises772154 -Ref: Programs Exercises-Footnote-1776285 -Node: Advanced Features776376 -Node: Nondecimal Data778358 -Node: Array Sorting779948 -Node: Controlling Array Traversal780648 -Ref: Controlling Array Traversal-Footnote-1789014 -Node: Array Sorting Functions789132 -Ref: Array Sorting Functions-Footnote-1793018 -Node: Two-way I/O793214 -Ref: Two-way I/O-Footnote-1798159 -Ref: Two-way I/O-Footnote-2798345 -Node: TCP/IP Networking798427 -Node: Profiling801299 -Node: Advanced Features Summary809570 -Node: Internationalization811503 -Node: I18N and L10N812983 -Node: Explaining gettext813669 -Ref: Explaining gettext-Footnote-1818694 -Ref: Explaining gettext-Footnote-2818878 -Node: Programmer i18n819043 -Ref: Programmer i18n-Footnote-1823919 -Node: Translator i18n823968 -Node: String Extraction824762 -Ref: String Extraction-Footnote-1825893 -Node: Printf Ordering825979 -Ref: Printf Ordering-Footnote-1828765 -Node: I18N Portability828829 -Ref: I18N Portability-Footnote-1831285 -Node: I18N Example831348 -Ref: I18N Example-Footnote-1834151 -Node: Gawk I18N834223 -Node: I18N Summary834867 -Node: Debugger836207 -Node: Debugging837229 -Node: Debugging Concepts837670 -Node: Debugging Terms839480 -Node: Awk Debugging842052 -Node: Sample Debugging Session842958 -Node: Debugger Invocation843492 -Node: Finding The Bug844877 -Node: List of Debugger Commands851356 -Node: Breakpoint Control852688 -Node: Debugger Execution Control856365 -Node: Viewing And Changing Data859724 -Node: Execution Stack863100 -Node: Debugger Info864735 -Node: Miscellaneous Debugger Commands868780 -Node: Readline Support873781 -Node: Limitations874675 -Node: Debugging Summary876790 -Node: Arbitrary Precision Arithmetic877964 -Node: Computer Arithmetic879380 -Ref: table-numeric-ranges882979 -Ref: Computer Arithmetic-Footnote-1883503 -Node: Math Definitions883560 -Ref: table-ieee-formats886855 -Ref: Math Definitions-Footnote-1887459 -Node: MPFR features887564 -Node: FP Math Caution889235 -Ref: FP Math Caution-Footnote-1890285 -Node: Inexactness of computations890654 -Node: Inexact representation891613 -Node: Comparing FP Values892971 -Node: Errors accumulate894053 -Node: Getting Accuracy895485 -Node: Try To Round898189 -Node: Setting precision899088 -Ref: table-predefined-precision-strings899772 -Node: Setting the rounding mode901601 -Ref: table-gawk-rounding-modes901965 -Ref: Setting the rounding mode-Footnote-1905417 -Node: Arbitrary Precision Integers905596 -Ref: Arbitrary Precision Integers-Footnote-1910494 -Node: POSIX Floating Point Problems910643 -Ref: POSIX Floating Point Problems-Footnote-1914522 -Node: Floating point summary914560 -Node: Dynamic Extensions916756 -Node: Extension Intro918308 -Node: Plugin License919574 -Node: Extension Mechanism Outline920371 -Ref: figure-load-extension920799 -Ref: figure-register-new-function922279 -Ref: figure-call-new-function923283 -Node: Extension API Description925269 -Node: Extension API Functions Introduction926719 -Node: General Data Types931543 -Ref: General Data Types-Footnote-1937282 -Node: Memory Allocation Functions937581 -Ref: Memory Allocation Functions-Footnote-1940420 -Node: Constructor Functions940516 -Node: Registration Functions942250 -Node: Extension Functions942935 -Node: Exit Callback Functions945232 -Node: Extension Version String946480 -Node: Input Parsers947145 -Node: Output Wrappers957024 -Node: Two-way processors961539 -Node: Printing Messages963743 -Ref: Printing Messages-Footnote-1964819 -Node: Updating `ERRNO'964971 -Node: Requesting Values965711 -Ref: table-value-types-returned966439 -Node: Accessing Parameters967396 -Node: Symbol Table Access968627 -Node: Symbol table by name969141 -Node: Symbol table by cookie971122 -Ref: Symbol table by cookie-Footnote-1975266 -Node: Cached values975329 -Ref: Cached values-Footnote-1978828 -Node: Array Manipulation978919 -Ref: Array Manipulation-Footnote-1980017 -Node: Array Data Types980054 -Ref: Array Data Types-Footnote-1982709 -Node: Array Functions982801 -Node: Flattening Arrays986655 -Node: Creating Arrays993547 -Node: Extension API Variables998318 -Node: Extension Versioning998954 -Node: Extension API Informational Variables1000855 -Node: Extension API Boilerplate1001920 -Node: Finding Extensions1005729 -Node: Extension Example1006289 -Node: Internal File Description1007061 -Node: Internal File Ops1011128 -Ref: Internal File Ops-Footnote-11022798 -Node: Using Internal File Ops1022938 -Ref: Using Internal File Ops-Footnote-11025321 -Node: Extension Samples1025594 -Node: Extension Sample File Functions1027120 -Node: Extension Sample Fnmatch1034758 -Node: Extension Sample Fork1036249 -Node: Extension Sample Inplace1037464 -Node: Extension Sample Ord1039139 -Node: Extension Sample Readdir1039975 -Ref: table-readdir-file-types1040851 -Node: Extension Sample Revout1041662 -Node: Extension Sample Rev2way1042252 -Node: Extension Sample Read write array1042992 -Node: Extension Sample Readfile1044932 -Node: Extension Sample Time1046027 -Node: Extension Sample API Tests1047376 -Node: gawkextlib1047867 -Node: Extension summary1050525 -Node: Extension Exercises1054214 -Node: Language History1054936 -Node: V7/SVR3.11056592 -Node: SVR41058773 -Node: POSIX1060218 -Node: BTL1061607 -Node: POSIX/GNU1062341 -Node: Feature History1068130 -Node: Common Extensions1081856 -Node: Ranges and Locales1083180 -Ref: Ranges and Locales-Footnote-11087798 -Ref: Ranges and Locales-Footnote-21087825 -Ref: Ranges and Locales-Footnote-31088059 -Node: Contributors1088280 -Node: History summary1093821 -Node: Installation1095191 -Node: Gawk Distribution1096137 -Node: Getting1096621 -Node: Extracting1097444 -Node: Distribution contents1099079 -Node: Unix Installation1105144 -Node: Quick Installation1105827 -Node: Shell Startup Files1108238 -Node: Additional Configuration Options1109317 -Node: Configuration Philosophy1111056 -Node: Non-Unix Installation1113425 -Node: PC Installation1113883 -Node: PC Binary Installation1115202 -Node: PC Compiling1117050 -Ref: PC Compiling-Footnote-11120071 -Node: PC Testing1120180 -Node: PC Using1121356 -Node: Cygwin1125471 -Node: MSYS1126294 -Node: VMS Installation1126794 -Node: VMS Compilation1127586 -Ref: VMS Compilation-Footnote-11128808 -Node: VMS Dynamic Extensions1128866 -Node: VMS Installation Details1130550 -Node: VMS Running1132802 -Node: VMS GNV1135638 -Node: VMS Old Gawk1136372 -Node: Bugs1136842 -Node: Other Versions1140725 -Node: Installation summary1147149 -Node: Notes1148205 -Node: Compatibility Mode1149070 -Node: Additions1149852 -Node: Accessing The Source1150777 -Node: Adding Code1152212 -Node: New Ports1158369 -Node: Derived Files1162851 -Ref: Derived Files-Footnote-11168326 -Ref: Derived Files-Footnote-21168360 -Ref: Derived Files-Footnote-31168956 -Node: Future Extensions1169070 -Node: Implementation Limitations1169676 -Node: Extension Design1170924 -Node: Old Extension Problems1172078 -Ref: Old Extension Problems-Footnote-11173595 -Node: Extension New Mechanism Goals1173652 -Ref: Extension New Mechanism Goals-Footnote-11177012 -Node: Extension Other Design Decisions1177201 -Node: Extension Future Growth1179309 -Node: Old Extension Mechanism1180145 -Node: Notes summary1181907 -Node: Basic Concepts1183093 -Node: Basic High Level1183774 -Ref: figure-general-flow1184046 -Ref: figure-process-flow1184645 -Ref: Basic High Level-Footnote-11187874 -Node: Basic Data Typing1188059 -Node: Glossary1191387 -Node: Copying1223316 -Node: GNU Free Documentation License1260872 -Node: Index1286008 +Node: Ranges391714 +Node: BEGIN/END394821 +Node: Using BEGIN/END395582 +Ref: Using BEGIN/END-Footnote-1398318 +Node: I/O And BEGIN/END398424 +Node: BEGINFILE/ENDFILE400739 +Node: Empty403636 +Node: Using Shell Variables403953 +Node: Action Overview406226 +Node: Statements408552 +Node: If Statement410400 +Node: While Statement411895 +Node: Do Statement413923 +Node: For Statement415071 +Node: Switch Statement418229 +Node: Break Statement420611 +Node: Continue Statement422652 +Node: Next Statement424479 +Node: Nextfile Statement426860 +Node: Exit Statement429488 +Node: Built-in Variables431899 +Node: User-modified433032 +Ref: User-modified-Footnote-1440735 +Node: Auto-set440797 +Ref: Auto-set-Footnote-1454506 +Ref: Auto-set-Footnote-2454711 +Node: ARGC and ARGV454767 +Node: Pattern Action Summary458985 +Node: Arrays461418 +Node: Array Basics462747 +Node: Array Intro463591 +Ref: figure-array-elements465525 +Ref: Array Intro-Footnote-1468145 +Node: Reference to Elements468273 +Node: Assigning Elements470735 +Node: Array Example471226 +Node: Scanning an Array472985 +Node: Controlling Scanning476005 +Ref: Controlling Scanning-Footnote-1481399 +Node: Numeric Array Subscripts481715 +Node: Uninitialized Subscripts483900 +Node: Delete485517 +Ref: Delete-Footnote-1488266 +Node: Multidimensional488323 +Node: Multiscanning491420 +Node: Arrays of Arrays493009 +Node: Arrays Summary497763 +Node: Functions499854 +Node: Built-in500893 +Node: Calling Built-in501971 +Node: Numeric Functions503966 +Ref: Numeric Functions-Footnote-1508784 +Ref: Numeric Functions-Footnote-2509141 +Ref: Numeric Functions-Footnote-3509189 +Node: String Functions509461 +Ref: String Functions-Footnote-1532962 +Ref: String Functions-Footnote-2533091 +Ref: String Functions-Footnote-3533339 +Node: Gory Details533426 +Ref: table-sub-escapes535207 +Ref: table-sub-proposed536722 +Ref: table-posix-sub538084 +Ref: table-gensub-escapes539621 +Ref: Gory Details-Footnote-1540454 +Node: I/O Functions540605 +Ref: I/O Functions-Footnote-1547841 +Node: Time Functions547988 +Ref: Time Functions-Footnote-1558497 +Ref: Time Functions-Footnote-2558565 +Ref: Time Functions-Footnote-3558723 +Ref: Time Functions-Footnote-4558834 +Ref: Time Functions-Footnote-5558946 +Ref: Time Functions-Footnote-6559173 +Node: Bitwise Functions559439 +Ref: table-bitwise-ops560001 +Ref: Bitwise Functions-Footnote-1564329 +Node: Type Functions564501 +Node: I18N Functions565653 +Node: User-defined567300 +Node: Definition Syntax568105 +Ref: Definition Syntax-Footnote-1573764 +Node: Function Example573835 +Ref: Function Example-Footnote-1576756 +Node: Function Caveats576778 +Node: Calling A Function577296 +Node: Variable Scope578254 +Node: Pass By Value/Reference581247 +Node: Return Statement584744 +Node: Dynamic Typing587723 +Node: Indirect Calls588652 +Ref: Indirect Calls-Footnote-1599958 +Node: Functions Summary600086 +Node: Library Functions602788 +Ref: Library Functions-Footnote-1606396 +Ref: Library Functions-Footnote-2606539 +Node: Library Names606710 +Ref: Library Names-Footnote-1610168 +Ref: Library Names-Footnote-2610391 +Node: General Functions610477 +Node: Strtonum Function611580 +Node: Assert Function614602 +Node: Round Function617926 +Node: Cliff Random Function619467 +Node: Ordinal Functions620483 +Ref: Ordinal Functions-Footnote-1623546 +Ref: Ordinal Functions-Footnote-2623798 +Node: Join Function624009 +Ref: Join Function-Footnote-1625779 +Node: Getlocaltime Function625979 +Node: Readfile Function629723 +Node: Shell Quoting631695 +Node: Data File Management633096 +Node: Filetrans Function633728 +Node: Rewind Function637824 +Node: File Checking639210 +Ref: File Checking-Footnote-1640543 +Node: Empty Files640744 +Node: Ignoring Assigns642723 +Node: Getopt Function644273 +Ref: Getopt Function-Footnote-1655737 +Node: Passwd Functions655937 +Ref: Passwd Functions-Footnote-1664777 +Node: Group Functions664865 +Ref: Group Functions-Footnote-1672762 +Node: Walking Arrays672967 +Node: Library Functions Summary674567 +Node: Library Exercises675971 +Node: Sample Programs677251 +Node: Running Examples678021 +Node: Clones678749 +Node: Cut Program679973 +Node: Egrep Program689693 +Ref: Egrep Program-Footnote-1697196 +Node: Id Program697306 +Node: Split Program700982 +Ref: Split Program-Footnote-1704436 +Node: Tee Program704564 +Node: Uniq Program707353 +Node: Wc Program714772 +Ref: Wc Program-Footnote-1719022 +Node: Miscellaneous Programs719116 +Node: Dupword Program720329 +Node: Alarm Program722360 +Node: Translate Program727165 +Ref: Translate Program-Footnote-1731728 +Node: Labels Program731998 +Ref: Labels Program-Footnote-1735349 +Node: Word Sorting735433 +Node: History Sorting739503 +Node: Extract Program741338 +Node: Simple Sed748862 +Node: Igawk Program751932 +Ref: Igawk Program-Footnote-1766258 +Ref: Igawk Program-Footnote-2766459 +Ref: Igawk Program-Footnote-3766581 +Node: Anagram Program766696 +Node: Signature Program769757 +Node: Programs Summary771004 +Node: Programs Exercises772225 +Ref: Programs Exercises-Footnote-1776356 +Node: Advanced Features776447 +Node: Nondecimal Data778429 +Node: Array Sorting780019 +Node: Controlling Array Traversal780719 +Ref: Controlling Array Traversal-Footnote-1789085 +Node: Array Sorting Functions789203 +Ref: Array Sorting Functions-Footnote-1793089 +Node: Two-way I/O793285 +Ref: Two-way I/O-Footnote-1798230 +Ref: Two-way I/O-Footnote-2798416 +Node: TCP/IP Networking798498 +Node: Profiling801370 +Node: Advanced Features Summary809641 +Node: Internationalization811574 +Node: I18N and L10N813054 +Node: Explaining gettext813740 +Ref: Explaining gettext-Footnote-1818765 +Ref: Explaining gettext-Footnote-2818949 +Node: Programmer i18n819114 +Ref: Programmer i18n-Footnote-1823990 +Node: Translator i18n824039 +Node: String Extraction824833 +Ref: String Extraction-Footnote-1825964 +Node: Printf Ordering826050 +Ref: Printf Ordering-Footnote-1828836 +Node: I18N Portability828900 +Ref: I18N Portability-Footnote-1831356 +Node: I18N Example831419 +Ref: I18N Example-Footnote-1834222 +Node: Gawk I18N834294 +Node: I18N Summary834938 +Node: Debugger836278 +Node: Debugging837300 +Node: Debugging Concepts837741 +Node: Debugging Terms839551 +Node: Awk Debugging842123 +Node: Sample Debugging Session843029 +Node: Debugger Invocation843563 +Node: Finding The Bug844948 +Node: List of Debugger Commands851427 +Node: Breakpoint Control852759 +Node: Debugger Execution Control856436 +Node: Viewing And Changing Data859795 +Node: Execution Stack863171 +Node: Debugger Info864806 +Node: Miscellaneous Debugger Commands868851 +Node: Readline Support873852 +Node: Limitations874746 +Node: Debugging Summary876861 +Node: Arbitrary Precision Arithmetic878035 +Node: Computer Arithmetic879451 +Ref: table-numeric-ranges883050 +Ref: Computer Arithmetic-Footnote-1883574 +Node: Math Definitions883631 +Ref: table-ieee-formats886926 +Ref: Math Definitions-Footnote-1887530 +Node: MPFR features887635 +Node: FP Math Caution889306 +Ref: FP Math Caution-Footnote-1890356 +Node: Inexactness of computations890725 +Node: Inexact representation891684 +Node: Comparing FP Values893042 +Node: Errors accumulate894124 +Node: Getting Accuracy895556 +Node: Try To Round898260 +Node: Setting precision899159 +Ref: table-predefined-precision-strings899843 +Node: Setting the rounding mode901672 +Ref: table-gawk-rounding-modes902036 +Ref: Setting the rounding mode-Footnote-1905488 +Node: Arbitrary Precision Integers905667 +Ref: Arbitrary Precision Integers-Footnote-1910565 +Node: POSIX Floating Point Problems910714 +Ref: POSIX Floating Point Problems-Footnote-1914593 +Node: Floating point summary914631 +Node: Dynamic Extensions916827 +Node: Extension Intro918379 +Node: Plugin License919644 +Node: Extension Mechanism Outline920441 +Ref: figure-load-extension920869 +Ref: figure-register-new-function922349 +Ref: figure-call-new-function923353 +Node: Extension API Description925340 +Node: Extension API Functions Introduction926790 +Node: General Data Types931611 +Ref: General Data Types-Footnote-1937418 +Node: Memory Allocation Functions937717 +Ref: Memory Allocation Functions-Footnote-1940556 +Node: Constructor Functions940652 +Node: Registration Functions942386 +Node: Extension Functions943071 +Node: Exit Callback Functions945368 +Node: Extension Version String946616 +Node: Input Parsers947281 +Node: Output Wrappers957160 +Node: Two-way processors961675 +Node: Printing Messages963879 +Ref: Printing Messages-Footnote-1964955 +Node: Updating `ERRNO'965107 +Node: Requesting Values965847 +Ref: table-value-types-returned966575 +Node: Accessing Parameters967532 +Node: Symbol Table Access968763 +Node: Symbol table by name969277 +Node: Symbol table by cookie971258 +Ref: Symbol table by cookie-Footnote-1975402 +Node: Cached values975465 +Ref: Cached values-Footnote-1978964 +Node: Array Manipulation979055 +Ref: Array Manipulation-Footnote-1980153 +Node: Array Data Types980190 +Ref: Array Data Types-Footnote-1982845 +Node: Array Functions982937 +Node: Flattening Arrays986791 +Node: Creating Arrays993683 +Node: Extension API Variables998454 +Node: Extension Versioning999090 +Node: Extension API Informational Variables1000991 +Node: Extension API Boilerplate1002056 +Node: Finding Extensions1005865 +Node: Extension Example1006425 +Node: Internal File Description1007197 +Node: Internal File Ops1011264 +Ref: Internal File Ops-Footnote-11022934 +Node: Using Internal File Ops1023074 +Ref: Using Internal File Ops-Footnote-11025457 +Node: Extension Samples1025730 +Node: Extension Sample File Functions1027256 +Node: Extension Sample Fnmatch1034894 +Node: Extension Sample Fork1036385 +Node: Extension Sample Inplace1037600 +Node: Extension Sample Ord1039275 +Node: Extension Sample Readdir1040111 +Ref: table-readdir-file-types1040987 +Node: Extension Sample Revout1041798 +Node: Extension Sample Rev2way1042388 +Node: Extension Sample Read write array1043128 +Node: Extension Sample Readfile1045068 +Node: Extension Sample Time1046163 +Node: Extension Sample API Tests1047512 +Node: gawkextlib1048003 +Node: Extension summary1050661 +Node: Extension Exercises1054350 +Node: Language History1055072 +Node: V7/SVR3.11056728 +Node: SVR41058909 +Node: POSIX1060354 +Node: BTL1061743 +Node: POSIX/GNU1062477 +Node: Feature History1068266 +Node: Common Extensions1081992 +Node: Ranges and Locales1083316 +Ref: Ranges and Locales-Footnote-11087934 +Ref: Ranges and Locales-Footnote-21087961 +Ref: Ranges and Locales-Footnote-31088195 +Node: Contributors1088416 +Node: History summary1093957 +Node: Installation1095327 +Node: Gawk Distribution1096273 +Node: Getting1096757 +Node: Extracting1097580 +Node: Distribution contents1099215 +Node: Unix Installation1105280 +Node: Quick Installation1105963 +Node: Shell Startup Files1108374 +Node: Additional Configuration Options1109453 +Node: Configuration Philosophy1111192 +Node: Non-Unix Installation1113561 +Node: PC Installation1114019 +Node: PC Binary Installation1115338 +Node: PC Compiling1117186 +Ref: PC Compiling-Footnote-11120207 +Node: PC Testing1120316 +Node: PC Using1121492 +Node: Cygwin1125607 +Node: MSYS1126430 +Node: VMS Installation1126930 +Node: VMS Compilation1127722 +Ref: VMS Compilation-Footnote-11128944 +Node: VMS Dynamic Extensions1129002 +Node: VMS Installation Details1130686 +Node: VMS Running1132938 +Node: VMS GNV1135774 +Node: VMS Old Gawk1136508 +Node: Bugs1136978 +Node: Other Versions1140861 +Node: Installation summary1147285 +Node: Notes1148341 +Node: Compatibility Mode1149206 +Node: Additions1149988 +Node: Accessing The Source1150913 +Node: Adding Code1152348 +Node: New Ports1158505 +Node: Derived Files1162987 +Ref: Derived Files-Footnote-11168462 +Ref: Derived Files-Footnote-21168496 +Ref: Derived Files-Footnote-31169092 +Node: Future Extensions1169206 +Node: Implementation Limitations1169812 +Node: Extension Design1171060 +Node: Old Extension Problems1172214 +Ref: Old Extension Problems-Footnote-11173731 +Node: Extension New Mechanism Goals1173788 +Ref: Extension New Mechanism Goals-Footnote-11177148 +Node: Extension Other Design Decisions1177337 +Node: Extension Future Growth1179445 +Node: Old Extension Mechanism1180281 +Node: Notes summary1182043 +Node: Basic Concepts1183229 +Node: Basic High Level1183910 +Ref: figure-general-flow1184182 +Ref: figure-process-flow1184781 +Ref: Basic High Level-Footnote-11188010 +Node: Basic Data Typing1188195 +Node: Glossary1191523 +Node: Copying1223452 +Node: GNU Free Documentation License1261008 +Node: Index1286144 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 755d011e..e1464166 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -13167,6 +13167,7 @@ $ @kbd{awk '$1 ~ /li/ @{ print $2 @}' mail-list} @cindex regexp constants, as patterns @cindex patterns, regexp constants as +A regexp constant as a pattern is also a special case of an expression pattern. The expression @code{/li/} has the value one if @samp{li} appears in the current input record. Thus, as a pattern, @code{/li/} matches any record containing @samp{li}. @@ -31283,7 +31284,7 @@ Extensions are useful because they allow you (of course) to extend @command{gawk}'s functionality. For example, they can provide access to system calls (such as @code{chdir()} to change directory) and to other C library routines that could be of use. As with most software, -``the sky is the limit;'' if you can imagine something that you might +``the sky is the limit''; if you can imagine something that you might want to do and can write in C or C++, you can write an extension to do it! Extensions are written in C or C++, using the @dfn{application programming @@ -31291,7 +31292,7 @@ interface} (API) defined for this purpose by the @command{gawk} developers. The rest of this @value{CHAPTER} explains the facilities that the API provides and how to use them, and presents a small example extension. In addition, it documents -the sample extensions included in the @command{gawk} distribution, +the sample extensions included in the @command{gawk} distribution and describes the @code{gawkextlib} project. @ifclear FOR_PRINT @xref{Extension Design}, for a discussion of the extension mechanism @@ -31444,7 +31445,7 @@ Some other bits and pieces: @itemize @value{BULLET} @item The API provides access to @command{gawk}'s @code{do_@var{xxx}} values, -reflecting command-line options, like @code{do_lint}, @code{do_profiling} +reflecting command-line options, like @code{do_lint}, @code{do_profiling}, and so on (@pxref{Extension API Variables}). These are informational: an extension cannot affect their values inside @command{gawk}. In addition, attempting to assign to them @@ -31488,7 +31489,7 @@ This (rather large) @value{SECTION} describes the API in detail. @node Extension API Functions Introduction @subsection Introduction -Access to facilities within @command{gawk} are made available +Access to facilities within @command{gawk} is achieved by calling through function pointers passed into your extension. API function pointers are provided for the following kinds of operations: @@ -31516,7 +31517,7 @@ Output wrappers Two-way processors @end itemize -All of these are discussed in detail, later in this @value{CHAPTER}. +All of these are discussed in detail later in this @value{CHAPTER}. @item Printing fatal, warning, and ``lint'' warning messages. @@ -31554,7 +31555,7 @@ Creating a new array Clearing an array @item -Flattening an array for easy C style looping over all its indices and elements +Flattening an array for easy C-style looping over all its indices and elements @end itemize @end itemize @@ -31566,8 +31567,9 @@ The following types, macros, and/or functions are referenced in @file{gawkapi.h}. For correct use, you must therefore include the corresponding standard header file @emph{before} including @file{gawkapi.h}: +@c FIXME: Make this is a float at some point. @multitable {@code{memset()}, @code{memcpy()}} {@code{<sys/types.h>}} -@headitem C Entity @tab Header File +@headitem C entity @tab Header file @item @code{EOF} @tab @code{<stdio.h>} @item Values for @code{errno} @tab @code{<errno.h>} @item @code{FILE} @tab @code{<stdio.h>} @@ -31593,7 +31595,7 @@ Doing so, however, is poor coding practice. Although the API only uses ISO C 90 features, there is an exception; the ``constructor'' functions use the @code{inline} keyword. If your compiler does not support this keyword, you should either place -@samp{-Dinline=''} on your command line, or use the GNU Autotools and include a +@samp{-Dinline=''} on your command line or use the GNU Autotools and include a @file{config.h} file in your extensions. @item @@ -31601,7 +31603,7 @@ All pointers filled in by @command{gawk} point to memory managed by @command{gawk} and should be treated by the extension as read-only. Memory for @emph{all} strings passed into @command{gawk} from the extension @emph{must} come from calling one of -@code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}, +@code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()}, and is managed by @command{gawk} from then on. @item @@ -31615,7 +31617,7 @@ characters are allowed. By intent, strings are maintained using the current multibyte encoding (as defined by @env{LC_@var{xxx}} environment variables) and not using wide characters. This matches how @command{gawk} stores strings internally -and also how characters are likely to be input and output from files. +and also how characters are likely to be input into and output from files. @end quotation @item @@ -31660,6 +31662,8 @@ general-purpose use. Additional, more specialized, data structures are introduced in subsequent @value{SECTION}s, together with the functions that use them. +The general-purpose types and structures are as follows: + @table @code @item typedef void *awk_ext_id_t; A value of this type is received from @command{gawk} when an extension is loaded. @@ -31676,7 +31680,7 @@ while allowing @command{gawk} to use them as it needs to. @itemx @ @ @ @ awk_false = 0, @itemx @ @ @ @ awk_true @itemx @} awk_bool_t; -A simple boolean type. +A simple Boolean type. @item typedef struct awk_string @{ @itemx @ @ @ @ char *str;@ @ @ @ @ @ /* data */ @@ -31722,7 +31726,7 @@ The @code{val_type} member indicates what kind of value the @itemx #define array_cookie@ @ @ u.a @itemx #define scalar_cookie@ @ u.scl @itemx #define value_cookie@ @ @ u.vc -These macros make accessing the fields of the @code{awk_value_t} more +Using these macros makes accessing the fields of the @code{awk_value_t} more readable. @item typedef void *awk_scalar_t; diff --git a/doc/gawktexi.in b/doc/gawktexi.in index 14b669e5..04aa9e78 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -12495,6 +12495,7 @@ $ @kbd{awk '$1 ~ /li/ @{ print $2 @}' mail-list} @cindex regexp constants, as patterns @cindex patterns, regexp constants as +A regexp constant as a pattern is also a special case of an expression pattern. The expression @code{/li/} has the value one if @samp{li} appears in the current input record. Thus, as a pattern, @code{/li/} matches any record containing @samp{li}. @@ -30374,7 +30375,7 @@ Extensions are useful because they allow you (of course) to extend @command{gawk}'s functionality. For example, they can provide access to system calls (such as @code{chdir()} to change directory) and to other C library routines that could be of use. As with most software, -``the sky is the limit;'' if you can imagine something that you might +``the sky is the limit''; if you can imagine something that you might want to do and can write in C or C++, you can write an extension to do it! Extensions are written in C or C++, using the @dfn{application programming @@ -30382,7 +30383,7 @@ interface} (API) defined for this purpose by the @command{gawk} developers. The rest of this @value{CHAPTER} explains the facilities that the API provides and how to use them, and presents a small example extension. In addition, it documents -the sample extensions included in the @command{gawk} distribution, +the sample extensions included in the @command{gawk} distribution and describes the @code{gawkextlib} project. @ifclear FOR_PRINT @xref{Extension Design}, for a discussion of the extension mechanism @@ -30535,7 +30536,7 @@ Some other bits and pieces: @itemize @value{BULLET} @item The API provides access to @command{gawk}'s @code{do_@var{xxx}} values, -reflecting command-line options, like @code{do_lint}, @code{do_profiling} +reflecting command-line options, like @code{do_lint}, @code{do_profiling}, and so on (@pxref{Extension API Variables}). These are informational: an extension cannot affect their values inside @command{gawk}. In addition, attempting to assign to them @@ -30579,7 +30580,7 @@ This (rather large) @value{SECTION} describes the API in detail. @node Extension API Functions Introduction @subsection Introduction -Access to facilities within @command{gawk} are made available +Access to facilities within @command{gawk} is achieved by calling through function pointers passed into your extension. API function pointers are provided for the following kinds of operations: @@ -30607,7 +30608,7 @@ Output wrappers Two-way processors @end itemize -All of these are discussed in detail, later in this @value{CHAPTER}. +All of these are discussed in detail later in this @value{CHAPTER}. @item Printing fatal, warning, and ``lint'' warning messages. @@ -30645,7 +30646,7 @@ Creating a new array Clearing an array @item -Flattening an array for easy C style looping over all its indices and elements +Flattening an array for easy C-style looping over all its indices and elements @end itemize @end itemize @@ -30657,8 +30658,9 @@ The following types, macros, and/or functions are referenced in @file{gawkapi.h}. For correct use, you must therefore include the corresponding standard header file @emph{before} including @file{gawkapi.h}: +@c FIXME: Make this is a float at some point. @multitable {@code{memset()}, @code{memcpy()}} {@code{<sys/types.h>}} -@headitem C Entity @tab Header File +@headitem C entity @tab Header file @item @code{EOF} @tab @code{<stdio.h>} @item Values for @code{errno} @tab @code{<errno.h>} @item @code{FILE} @tab @code{<stdio.h>} @@ -30684,7 +30686,7 @@ Doing so, however, is poor coding practice. Although the API only uses ISO C 90 features, there is an exception; the ``constructor'' functions use the @code{inline} keyword. If your compiler does not support this keyword, you should either place -@samp{-Dinline=''} on your command line, or use the GNU Autotools and include a +@samp{-Dinline=''} on your command line or use the GNU Autotools and include a @file{config.h} file in your extensions. @item @@ -30692,7 +30694,7 @@ All pointers filled in by @command{gawk} point to memory managed by @command{gawk} and should be treated by the extension as read-only. Memory for @emph{all} strings passed into @command{gawk} from the extension @emph{must} come from calling one of -@code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}, +@code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()}, and is managed by @command{gawk} from then on. @item @@ -30706,7 +30708,7 @@ characters are allowed. By intent, strings are maintained using the current multibyte encoding (as defined by @env{LC_@var{xxx}} environment variables) and not using wide characters. This matches how @command{gawk} stores strings internally -and also how characters are likely to be input and output from files. +and also how characters are likely to be input into and output from files. @end quotation @item @@ -30751,6 +30753,8 @@ general-purpose use. Additional, more specialized, data structures are introduced in subsequent @value{SECTION}s, together with the functions that use them. +The general-purpose types and structures are as follows: + @table @code @item typedef void *awk_ext_id_t; A value of this type is received from @command{gawk} when an extension is loaded. @@ -30767,7 +30771,7 @@ while allowing @command{gawk} to use them as it needs to. @itemx @ @ @ @ awk_false = 0, @itemx @ @ @ @ awk_true @itemx @} awk_bool_t; -A simple boolean type. +A simple Boolean type. @item typedef struct awk_string @{ @itemx @ @ @ @ char *str;@ @ @ @ @ @ /* data */ @@ -30813,7 +30817,7 @@ The @code{val_type} member indicates what kind of value the @itemx #define array_cookie@ @ @ u.a @itemx #define scalar_cookie@ @ u.scl @itemx #define value_cookie@ @ @ u.vc -These macros make accessing the fields of the @code{awk_value_t} more +Using these macros makes accessing the fields of the @code{awk_value_t} more readable. @item typedef void *awk_scalar_t; |