diff options
| -rw-r--r-- | doc/ChangeLog | 4 | ||||
| -rw-r--r-- | doc/gawk.info | 801 | ||||
| -rw-r--r-- | doc/gawk.texi | 28 | ||||
| -rw-r--r-- | doc/gawktexi.in | 28 |
4 files changed, 438 insertions, 423 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index 319ecb2f..b6de5797 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 c56ac89c..bf573a8a 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -9071,9 +9071,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 @@ -22636,7 +22637,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 @@ -22644,7 +22645,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. @@ -22762,7 +22763,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. @@ -22808,8 +22809,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: @@ -22830,7 +22831,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. @@ -22856,7 +22857,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: @@ -22865,7 +22866,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>' @@ -22889,13 +22890,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 @@ -22908,7 +22909,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 @@ -22945,6 +22946,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 @@ -22960,7 +22963,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 */' @@ -23004,8 +23007,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 @@ -31951,7 +31954,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) @@ -31968,7 +31971,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) @@ -31994,7 +31997,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) @@ -32578,7 +32581,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) @@ -32587,7 +32590,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) @@ -34649,382 +34652,382 @@ Node: Patterns and Actions384448 Node: Pattern Overview385568 Node: Regexp Patterns387247 Node: Expression Patterns387790 -Node: Ranges391499 -Node: BEGIN/END394606 -Node: Using BEGIN/END395367 -Ref: Using BEGIN/END-Footnote-1398103 -Node: I/O And BEGIN/END398209 -Node: BEGINFILE/ENDFILE400524 -Node: Empty403421 -Node: Using Shell Variables403738 -Node: Action Overview406011 -Node: Statements408337 -Node: If Statement410185 -Node: While Statement411680 -Node: Do Statement413708 -Node: For Statement414856 -Node: Switch Statement418014 -Node: Break Statement420396 -Node: Continue Statement422437 -Node: Next Statement424264 -Node: Nextfile Statement426645 -Node: Exit Statement429273 -Node: Built-in Variables431684 -Node: User-modified432817 -Ref: User-modified-Footnote-1440520 -Node: Auto-set440582 -Ref: Auto-set-Footnote-1453634 -Ref: Auto-set-Footnote-2453839 -Node: ARGC and ARGV453895 -Node: Pattern Action Summary458113 -Node: Arrays460546 -Node: Array Basics461875 -Node: Array Intro462719 -Ref: figure-array-elements464653 -Ref: Array Intro-Footnote-1467273 -Node: Reference to Elements467401 -Node: Assigning Elements469863 -Node: Array Example470354 -Node: Scanning an Array472113 -Node: Controlling Scanning475133 -Ref: Controlling Scanning-Footnote-1480527 -Node: Numeric Array Subscripts480843 -Node: Uninitialized Subscripts483028 -Node: Delete484645 -Ref: Delete-Footnote-1487394 -Node: Multidimensional487451 -Node: Multiscanning490548 -Node: Arrays of Arrays492137 -Node: Arrays Summary496891 -Node: Functions498982 -Node: Built-in500021 -Node: Calling Built-in501099 -Node: Numeric Functions503094 -Ref: Numeric Functions-Footnote-1507110 -Ref: Numeric Functions-Footnote-2507467 -Ref: Numeric Functions-Footnote-3507515 -Node: String Functions507787 -Ref: String Functions-Footnote-1531288 -Ref: String Functions-Footnote-2531417 -Ref: String Functions-Footnote-3531665 -Node: Gory Details531752 -Ref: table-sub-escapes533533 -Ref: table-sub-proposed535048 -Ref: table-posix-sub536410 -Ref: table-gensub-escapes537947 -Ref: Gory Details-Footnote-1538780 -Node: I/O Functions538931 -Ref: I/O Functions-Footnote-1546167 -Node: Time Functions546314 -Ref: Time Functions-Footnote-1556823 -Ref: Time Functions-Footnote-2556891 -Ref: Time Functions-Footnote-3557049 -Ref: Time Functions-Footnote-4557160 -Ref: Time Functions-Footnote-5557272 -Ref: Time Functions-Footnote-6557499 -Node: Bitwise Functions557765 -Ref: table-bitwise-ops558327 -Ref: Bitwise Functions-Footnote-1562655 -Node: Type Functions562827 -Node: I18N Functions563979 -Node: User-defined565626 -Node: Definition Syntax566431 -Ref: Definition Syntax-Footnote-1572090 -Node: Function Example572161 -Ref: Function Example-Footnote-1575082 -Node: Function Caveats575104 -Node: Calling A Function575622 -Node: Variable Scope576580 -Node: Pass By Value/Reference579573 -Node: Return Statement583070 -Node: Dynamic Typing586049 -Node: Indirect Calls586978 -Ref: Indirect Calls-Footnote-1598284 -Node: Functions Summary598412 -Node: Library Functions601114 -Ref: Library Functions-Footnote-1604722 -Ref: Library Functions-Footnote-2604865 -Node: Library Names605036 -Ref: Library Names-Footnote-1608494 -Ref: Library Names-Footnote-2608717 -Node: General Functions608803 -Node: Strtonum Function609906 -Node: Assert Function612928 -Node: Round Function616252 -Node: Cliff Random Function617793 -Node: Ordinal Functions618809 -Ref: Ordinal Functions-Footnote-1621872 -Ref: Ordinal Functions-Footnote-2622124 -Node: Join Function622335 -Ref: Join Function-Footnote-1624105 -Node: Getlocaltime Function624305 -Node: Readfile Function628049 -Node: Shell Quoting630021 -Node: Data File Management631422 -Node: Filetrans Function632054 -Node: Rewind Function636150 -Node: File Checking637536 -Ref: File Checking-Footnote-1638869 -Node: Empty Files639070 -Node: Ignoring Assigns641049 -Node: Getopt Function642599 -Ref: Getopt Function-Footnote-1654063 -Node: Passwd Functions654263 -Ref: Passwd Functions-Footnote-1663103 -Node: Group Functions663191 -Ref: Group Functions-Footnote-1671088 -Node: Walking Arrays671293 -Node: Library Functions Summary672893 -Node: Library Exercises674297 -Node: Sample Programs675577 -Node: Running Examples676347 -Node: Clones677075 -Node: Cut Program678299 -Node: Egrep Program688019 -Ref: Egrep Program-Footnote-1695522 -Node: Id Program695632 -Node: Split Program699308 -Ref: Split Program-Footnote-1702762 -Node: Tee Program702890 -Node: Uniq Program705679 -Node: Wc Program713098 -Ref: Wc Program-Footnote-1717348 -Node: Miscellaneous Programs717442 -Node: Dupword Program718655 -Node: Alarm Program720686 -Node: Translate Program725491 -Ref: Translate Program-Footnote-1730054 -Node: Labels Program730324 -Ref: Labels Program-Footnote-1733675 -Node: Word Sorting733759 -Node: History Sorting737829 -Node: Extract Program739664 -Node: Simple Sed747188 -Node: Igawk Program750258 -Ref: Igawk Program-Footnote-1764584 -Ref: Igawk Program-Footnote-2764785 -Ref: Igawk Program-Footnote-3764907 -Node: Anagram Program765022 -Node: Signature Program768083 -Node: Programs Summary769330 -Node: Programs Exercises770551 -Ref: Programs Exercises-Footnote-1774682 -Node: Advanced Features774773 -Node: Nondecimal Data776755 -Node: Array Sorting778345 -Node: Controlling Array Traversal779045 -Ref: Controlling Array Traversal-Footnote-1787411 -Node: Array Sorting Functions787529 -Ref: Array Sorting Functions-Footnote-1791415 -Node: Two-way I/O791611 -Ref: Two-way I/O-Footnote-1796556 -Ref: Two-way I/O-Footnote-2796742 -Node: TCP/IP Networking796824 -Node: Profiling799696 -Node: Advanced Features Summary807237 -Node: Internationalization809170 -Node: I18N and L10N810650 -Node: Explaining gettext811336 -Ref: Explaining gettext-Footnote-1816361 -Ref: Explaining gettext-Footnote-2816545 -Node: Programmer i18n816710 -Ref: Programmer i18n-Footnote-1821586 -Node: Translator i18n821635 -Node: String Extraction822429 -Ref: String Extraction-Footnote-1823560 -Node: Printf Ordering823646 -Ref: Printf Ordering-Footnote-1826432 -Node: I18N Portability826496 -Ref: I18N Portability-Footnote-1828952 -Node: I18N Example829015 -Ref: I18N Example-Footnote-1831818 -Node: Gawk I18N831890 -Node: I18N Summary832534 -Node: Debugger833874 -Node: Debugging834896 -Node: Debugging Concepts835337 -Node: Debugging Terms837147 -Node: Awk Debugging839719 -Node: Sample Debugging Session840625 -Node: Debugger Invocation841159 -Node: Finding The Bug842544 -Node: List of Debugger Commands849023 -Node: Breakpoint Control850355 -Node: Debugger Execution Control854032 -Node: Viewing And Changing Data857391 -Node: Execution Stack860767 -Node: Debugger Info862402 -Node: Miscellaneous Debugger Commands866447 -Node: Readline Support871448 -Node: Limitations872342 -Node: Debugging Summary874457 -Node: Arbitrary Precision Arithmetic875631 -Node: Computer Arithmetic877047 -Ref: table-numeric-ranges880646 -Ref: Computer Arithmetic-Footnote-1881170 -Node: Math Definitions881227 -Ref: table-ieee-formats884522 -Ref: Math Definitions-Footnote-1885126 -Node: MPFR features885231 -Node: FP Math Caution886902 -Ref: FP Math Caution-Footnote-1887952 -Node: Inexactness of computations888321 -Node: Inexact representation889280 -Node: Comparing FP Values890638 -Node: Errors accumulate891720 -Node: Getting Accuracy893152 -Node: Try To Round895856 -Node: Setting precision896755 -Ref: table-predefined-precision-strings897439 -Node: Setting the rounding mode899268 -Ref: table-gawk-rounding-modes899632 -Ref: Setting the rounding mode-Footnote-1903084 -Node: Arbitrary Precision Integers903263 -Ref: Arbitrary Precision Integers-Footnote-1906247 -Node: POSIX Floating Point Problems906396 -Ref: POSIX Floating Point Problems-Footnote-1910275 -Node: Floating point summary910313 -Node: Dynamic Extensions912509 -Node: Extension Intro914061 -Node: Plugin License915327 -Node: Extension Mechanism Outline916124 -Ref: figure-load-extension916552 -Ref: figure-register-new-function918032 -Ref: figure-call-new-function919036 -Node: Extension API Description921022 -Node: Extension API Functions Introduction922472 -Node: General Data Types927296 -Ref: General Data Types-Footnote-1933035 -Node: Memory Allocation Functions933334 -Ref: Memory Allocation Functions-Footnote-1936173 -Node: Constructor Functions936269 -Node: Registration Functions938003 -Node: Extension Functions938688 -Node: Exit Callback Functions940985 -Node: Extension Version String942233 -Node: Input Parsers942898 -Node: Output Wrappers952777 -Node: Two-way processors957292 -Node: Printing Messages959496 -Ref: Printing Messages-Footnote-1960572 -Node: Updating `ERRNO'960724 -Node: Requesting Values961464 -Ref: table-value-types-returned962192 -Node: Accessing Parameters963149 -Node: Symbol Table Access964380 -Node: Symbol table by name964894 -Node: Symbol table by cookie966875 -Ref: Symbol table by cookie-Footnote-1971019 -Node: Cached values971082 -Ref: Cached values-Footnote-1974581 -Node: Array Manipulation974672 -Ref: Array Manipulation-Footnote-1975770 -Node: Array Data Types975807 -Ref: Array Data Types-Footnote-1978462 -Node: Array Functions978554 -Node: Flattening Arrays982408 -Node: Creating Arrays989300 -Node: Extension API Variables994071 -Node: Extension Versioning994707 -Node: Extension API Informational Variables996608 -Node: Extension API Boilerplate997673 -Node: Finding Extensions1001482 -Node: Extension Example1002042 -Node: Internal File Description1002814 -Node: Internal File Ops1006881 -Ref: Internal File Ops-Footnote-11018551 -Node: Using Internal File Ops1018691 -Ref: Using Internal File Ops-Footnote-11021074 -Node: Extension Samples1021347 -Node: Extension Sample File Functions1022873 -Node: Extension Sample Fnmatch1030511 -Node: Extension Sample Fork1032002 -Node: Extension Sample Inplace1033217 -Node: Extension Sample Ord1034892 -Node: Extension Sample Readdir1035728 -Ref: table-readdir-file-types1036604 -Node: Extension Sample Revout1037415 -Node: Extension Sample Rev2way1038005 -Node: Extension Sample Read write array1038745 -Node: Extension Sample Readfile1040685 -Node: Extension Sample Time1041780 -Node: Extension Sample API Tests1043129 -Node: gawkextlib1043620 -Node: Extension summary1046278 -Node: Extension Exercises1049967 -Node: Language History1050689 -Node: V7/SVR3.11052345 -Node: SVR41054526 -Node: POSIX1055971 -Node: BTL1057360 -Node: POSIX/GNU1058094 -Node: Feature History1063658 -Node: Common Extensions1076756 -Node: Ranges and Locales1078080 -Ref: Ranges and Locales-Footnote-11082698 -Ref: Ranges and Locales-Footnote-21082725 -Ref: Ranges and Locales-Footnote-31082959 -Node: Contributors1083180 -Node: History summary1088721 -Node: Installation1090091 -Node: Gawk Distribution1091037 -Node: Getting1091521 -Node: Extracting1092344 -Node: Distribution contents1093979 -Node: Unix Installation1099696 -Node: Quick Installation1100313 -Node: Additional Configuration Options1102737 -Node: Configuration Philosophy1104475 -Node: Non-Unix Installation1106844 -Node: PC Installation1107302 -Node: PC Binary Installation1108621 -Node: PC Compiling1110469 -Ref: PC Compiling-Footnote-11113490 -Node: PC Testing1113599 -Node: PC Using1114775 -Node: Cygwin1118890 -Node: MSYS1119713 -Node: VMS Installation1120213 -Node: VMS Compilation1121005 -Ref: VMS Compilation-Footnote-11122227 -Node: VMS Dynamic Extensions1122285 -Node: VMS Installation Details1123969 -Node: VMS Running1126221 -Node: VMS GNV1129057 -Node: VMS Old Gawk1129791 -Node: Bugs1130261 -Node: Other Versions1134144 -Node: Installation summary1140568 -Node: Notes1141624 -Node: Compatibility Mode1142489 -Node: Additions1143271 -Node: Accessing The Source1144196 -Node: Adding Code1145631 -Node: New Ports1151788 -Node: Derived Files1156270 -Ref: Derived Files-Footnote-11161745 -Ref: Derived Files-Footnote-21161779 -Ref: Derived Files-Footnote-31162375 -Node: Future Extensions1162489 -Node: Implementation Limitations1163095 -Node: Extension Design1164343 -Node: Old Extension Problems1165497 -Ref: Old Extension Problems-Footnote-11167014 -Node: Extension New Mechanism Goals1167071 -Ref: Extension New Mechanism Goals-Footnote-11170431 -Node: Extension Other Design Decisions1170620 -Node: Extension Future Growth1172728 -Node: Old Extension Mechanism1173564 -Node: Notes summary1175326 -Node: Basic Concepts1176512 -Node: Basic High Level1177193 -Ref: figure-general-flow1177465 -Ref: figure-process-flow1178064 -Ref: Basic High Level-Footnote-11181293 -Node: Basic Data Typing1181478 -Node: Glossary1184806 -Node: Copying1216735 -Node: GNU Free Documentation License1254291 -Node: Index1279427 +Node: Ranges391570 +Node: BEGIN/END394677 +Node: Using BEGIN/END395438 +Ref: Using BEGIN/END-Footnote-1398174 +Node: I/O And BEGIN/END398280 +Node: BEGINFILE/ENDFILE400595 +Node: Empty403492 +Node: Using Shell Variables403809 +Node: Action Overview406082 +Node: Statements408408 +Node: If Statement410256 +Node: While Statement411751 +Node: Do Statement413779 +Node: For Statement414927 +Node: Switch Statement418085 +Node: Break Statement420467 +Node: Continue Statement422508 +Node: Next Statement424335 +Node: Nextfile Statement426716 +Node: Exit Statement429344 +Node: Built-in Variables431755 +Node: User-modified432888 +Ref: User-modified-Footnote-1440591 +Node: Auto-set440653 +Ref: Auto-set-Footnote-1453705 +Ref: Auto-set-Footnote-2453910 +Node: ARGC and ARGV453966 +Node: Pattern Action Summary458184 +Node: Arrays460617 +Node: Array Basics461946 +Node: Array Intro462790 +Ref: figure-array-elements464724 +Ref: Array Intro-Footnote-1467344 +Node: Reference to Elements467472 +Node: Assigning Elements469934 +Node: Array Example470425 +Node: Scanning an Array472184 +Node: Controlling Scanning475204 +Ref: Controlling Scanning-Footnote-1480598 +Node: Numeric Array Subscripts480914 +Node: Uninitialized Subscripts483099 +Node: Delete484716 +Ref: Delete-Footnote-1487465 +Node: Multidimensional487522 +Node: Multiscanning490619 +Node: Arrays of Arrays492208 +Node: Arrays Summary496962 +Node: Functions499053 +Node: Built-in500092 +Node: Calling Built-in501170 +Node: Numeric Functions503165 +Ref: Numeric Functions-Footnote-1507181 +Ref: Numeric Functions-Footnote-2507538 +Ref: Numeric Functions-Footnote-3507586 +Node: String Functions507858 +Ref: String Functions-Footnote-1531359 +Ref: String Functions-Footnote-2531488 +Ref: String Functions-Footnote-3531736 +Node: Gory Details531823 +Ref: table-sub-escapes533604 +Ref: table-sub-proposed535119 +Ref: table-posix-sub536481 +Ref: table-gensub-escapes538018 +Ref: Gory Details-Footnote-1538851 +Node: I/O Functions539002 +Ref: I/O Functions-Footnote-1546238 +Node: Time Functions546385 +Ref: Time Functions-Footnote-1556894 +Ref: Time Functions-Footnote-2556962 +Ref: Time Functions-Footnote-3557120 +Ref: Time Functions-Footnote-4557231 +Ref: Time Functions-Footnote-5557343 +Ref: Time Functions-Footnote-6557570 +Node: Bitwise Functions557836 +Ref: table-bitwise-ops558398 +Ref: Bitwise Functions-Footnote-1562726 +Node: Type Functions562898 +Node: I18N Functions564050 +Node: User-defined565697 +Node: Definition Syntax566502 +Ref: Definition Syntax-Footnote-1572161 +Node: Function Example572232 +Ref: Function Example-Footnote-1575153 +Node: Function Caveats575175 +Node: Calling A Function575693 +Node: Variable Scope576651 +Node: Pass By Value/Reference579644 +Node: Return Statement583141 +Node: Dynamic Typing586120 +Node: Indirect Calls587049 +Ref: Indirect Calls-Footnote-1598355 +Node: Functions Summary598483 +Node: Library Functions601185 +Ref: Library Functions-Footnote-1604793 +Ref: Library Functions-Footnote-2604936 +Node: Library Names605107 +Ref: Library Names-Footnote-1608565 +Ref: Library Names-Footnote-2608788 +Node: General Functions608874 +Node: Strtonum Function609977 +Node: Assert Function612999 +Node: Round Function616323 +Node: Cliff Random Function617864 +Node: Ordinal Functions618880 +Ref: Ordinal Functions-Footnote-1621943 +Ref: Ordinal Functions-Footnote-2622195 +Node: Join Function622406 +Ref: Join Function-Footnote-1624176 +Node: Getlocaltime Function624376 +Node: Readfile Function628120 +Node: Shell Quoting630092 +Node: Data File Management631493 +Node: Filetrans Function632125 +Node: Rewind Function636221 +Node: File Checking637607 +Ref: File Checking-Footnote-1638940 +Node: Empty Files639141 +Node: Ignoring Assigns641120 +Node: Getopt Function642670 +Ref: Getopt Function-Footnote-1654134 +Node: Passwd Functions654334 +Ref: Passwd Functions-Footnote-1663174 +Node: Group Functions663262 +Ref: Group Functions-Footnote-1671159 +Node: Walking Arrays671364 +Node: Library Functions Summary672964 +Node: Library Exercises674368 +Node: Sample Programs675648 +Node: Running Examples676418 +Node: Clones677146 +Node: Cut Program678370 +Node: Egrep Program688090 +Ref: Egrep Program-Footnote-1695593 +Node: Id Program695703 +Node: Split Program699379 +Ref: Split Program-Footnote-1702833 +Node: Tee Program702961 +Node: Uniq Program705750 +Node: Wc Program713169 +Ref: Wc Program-Footnote-1717419 +Node: Miscellaneous Programs717513 +Node: Dupword Program718726 +Node: Alarm Program720757 +Node: Translate Program725562 +Ref: Translate Program-Footnote-1730125 +Node: Labels Program730395 +Ref: Labels Program-Footnote-1733746 +Node: Word Sorting733830 +Node: History Sorting737900 +Node: Extract Program739735 +Node: Simple Sed747259 +Node: Igawk Program750329 +Ref: Igawk Program-Footnote-1764655 +Ref: Igawk Program-Footnote-2764856 +Ref: Igawk Program-Footnote-3764978 +Node: Anagram Program765093 +Node: Signature Program768154 +Node: Programs Summary769401 +Node: Programs Exercises770622 +Ref: Programs Exercises-Footnote-1774753 +Node: Advanced Features774844 +Node: Nondecimal Data776826 +Node: Array Sorting778416 +Node: Controlling Array Traversal779116 +Ref: Controlling Array Traversal-Footnote-1787482 +Node: Array Sorting Functions787600 +Ref: Array Sorting Functions-Footnote-1791486 +Node: Two-way I/O791682 +Ref: Two-way I/O-Footnote-1796627 +Ref: Two-way I/O-Footnote-2796813 +Node: TCP/IP Networking796895 +Node: Profiling799767 +Node: Advanced Features Summary807308 +Node: Internationalization809241 +Node: I18N and L10N810721 +Node: Explaining gettext811407 +Ref: Explaining gettext-Footnote-1816432 +Ref: Explaining gettext-Footnote-2816616 +Node: Programmer i18n816781 +Ref: Programmer i18n-Footnote-1821657 +Node: Translator i18n821706 +Node: String Extraction822500 +Ref: String Extraction-Footnote-1823631 +Node: Printf Ordering823717 +Ref: Printf Ordering-Footnote-1826503 +Node: I18N Portability826567 +Ref: I18N Portability-Footnote-1829023 +Node: I18N Example829086 +Ref: I18N Example-Footnote-1831889 +Node: Gawk I18N831961 +Node: I18N Summary832605 +Node: Debugger833945 +Node: Debugging834967 +Node: Debugging Concepts835408 +Node: Debugging Terms837218 +Node: Awk Debugging839790 +Node: Sample Debugging Session840696 +Node: Debugger Invocation841230 +Node: Finding The Bug842615 +Node: List of Debugger Commands849094 +Node: Breakpoint Control850426 +Node: Debugger Execution Control854103 +Node: Viewing And Changing Data857462 +Node: Execution Stack860838 +Node: Debugger Info862473 +Node: Miscellaneous Debugger Commands866518 +Node: Readline Support871519 +Node: Limitations872413 +Node: Debugging Summary874528 +Node: Arbitrary Precision Arithmetic875702 +Node: Computer Arithmetic877118 +Ref: table-numeric-ranges880717 +Ref: Computer Arithmetic-Footnote-1881241 +Node: Math Definitions881298 +Ref: table-ieee-formats884593 +Ref: Math Definitions-Footnote-1885197 +Node: MPFR features885302 +Node: FP Math Caution886973 +Ref: FP Math Caution-Footnote-1888023 +Node: Inexactness of computations888392 +Node: Inexact representation889351 +Node: Comparing FP Values890709 +Node: Errors accumulate891791 +Node: Getting Accuracy893223 +Node: Try To Round895927 +Node: Setting precision896826 +Ref: table-predefined-precision-strings897510 +Node: Setting the rounding mode899339 +Ref: table-gawk-rounding-modes899703 +Ref: Setting the rounding mode-Footnote-1903155 +Node: Arbitrary Precision Integers903334 +Ref: Arbitrary Precision Integers-Footnote-1906318 +Node: POSIX Floating Point Problems906467 +Ref: POSIX Floating Point Problems-Footnote-1910346 +Node: Floating point summary910384 +Node: Dynamic Extensions912580 +Node: Extension Intro914132 +Node: Plugin License915397 +Node: Extension Mechanism Outline916194 +Ref: figure-load-extension916622 +Ref: figure-register-new-function918102 +Ref: figure-call-new-function919106 +Node: Extension API Description921093 +Node: Extension API Functions Introduction922543 +Node: General Data Types927364 +Ref: General Data Types-Footnote-1933171 +Node: Memory Allocation Functions933470 +Ref: Memory Allocation Functions-Footnote-1936309 +Node: Constructor Functions936405 +Node: Registration Functions938139 +Node: Extension Functions938824 +Node: Exit Callback Functions941121 +Node: Extension Version String942369 +Node: Input Parsers943034 +Node: Output Wrappers952913 +Node: Two-way processors957428 +Node: Printing Messages959632 +Ref: Printing Messages-Footnote-1960708 +Node: Updating `ERRNO'960860 +Node: Requesting Values961600 +Ref: table-value-types-returned962328 +Node: Accessing Parameters963285 +Node: Symbol Table Access964516 +Node: Symbol table by name965030 +Node: Symbol table by cookie967011 +Ref: Symbol table by cookie-Footnote-1971155 +Node: Cached values971218 +Ref: Cached values-Footnote-1974717 +Node: Array Manipulation974808 +Ref: Array Manipulation-Footnote-1975906 +Node: Array Data Types975943 +Ref: Array Data Types-Footnote-1978598 +Node: Array Functions978690 +Node: Flattening Arrays982544 +Node: Creating Arrays989436 +Node: Extension API Variables994207 +Node: Extension Versioning994843 +Node: Extension API Informational Variables996744 +Node: Extension API Boilerplate997809 +Node: Finding Extensions1001618 +Node: Extension Example1002178 +Node: Internal File Description1002950 +Node: Internal File Ops1007017 +Ref: Internal File Ops-Footnote-11018687 +Node: Using Internal File Ops1018827 +Ref: Using Internal File Ops-Footnote-11021210 +Node: Extension Samples1021483 +Node: Extension Sample File Functions1023009 +Node: Extension Sample Fnmatch1030647 +Node: Extension Sample Fork1032138 +Node: Extension Sample Inplace1033353 +Node: Extension Sample Ord1035028 +Node: Extension Sample Readdir1035864 +Ref: table-readdir-file-types1036740 +Node: Extension Sample Revout1037551 +Node: Extension Sample Rev2way1038141 +Node: Extension Sample Read write array1038881 +Node: Extension Sample Readfile1040821 +Node: Extension Sample Time1041916 +Node: Extension Sample API Tests1043265 +Node: gawkextlib1043756 +Node: Extension summary1046414 +Node: Extension Exercises1050103 +Node: Language History1050825 +Node: V7/SVR3.11052481 +Node: SVR41054662 +Node: POSIX1056107 +Node: BTL1057496 +Node: POSIX/GNU1058230 +Node: Feature History1063794 +Node: Common Extensions1076892 +Node: Ranges and Locales1078216 +Ref: Ranges and Locales-Footnote-11082834 +Ref: Ranges and Locales-Footnote-21082861 +Ref: Ranges and Locales-Footnote-31083095 +Node: Contributors1083316 +Node: History summary1088857 +Node: Installation1090227 +Node: Gawk Distribution1091173 +Node: Getting1091657 +Node: Extracting1092480 +Node: Distribution contents1094115 +Node: Unix Installation1099832 +Node: Quick Installation1100449 +Node: Additional Configuration Options1102873 +Node: Configuration Philosophy1104611 +Node: Non-Unix Installation1106980 +Node: PC Installation1107438 +Node: PC Binary Installation1108757 +Node: PC Compiling1110605 +Ref: PC Compiling-Footnote-11113626 +Node: PC Testing1113735 +Node: PC Using1114911 +Node: Cygwin1119026 +Node: MSYS1119849 +Node: VMS Installation1120349 +Node: VMS Compilation1121141 +Ref: VMS Compilation-Footnote-11122363 +Node: VMS Dynamic Extensions1122421 +Node: VMS Installation Details1124105 +Node: VMS Running1126357 +Node: VMS GNV1129193 +Node: VMS Old Gawk1129927 +Node: Bugs1130397 +Node: Other Versions1134280 +Node: Installation summary1140704 +Node: Notes1141760 +Node: Compatibility Mode1142625 +Node: Additions1143407 +Node: Accessing The Source1144332 +Node: Adding Code1145767 +Node: New Ports1151924 +Node: Derived Files1156406 +Ref: Derived Files-Footnote-11161881 +Ref: Derived Files-Footnote-21161915 +Ref: Derived Files-Footnote-31162511 +Node: Future Extensions1162625 +Node: Implementation Limitations1163231 +Node: Extension Design1164479 +Node: Old Extension Problems1165633 +Ref: Old Extension Problems-Footnote-11167150 +Node: Extension New Mechanism Goals1167207 +Ref: Extension New Mechanism Goals-Footnote-11170567 +Node: Extension Other Design Decisions1170756 +Node: Extension Future Growth1172864 +Node: Old Extension Mechanism1173700 +Node: Notes summary1175462 +Node: Basic Concepts1176648 +Node: Basic High Level1177329 +Ref: figure-general-flow1177601 +Ref: figure-process-flow1178200 +Ref: Basic High Level-Footnote-11181429 +Node: Basic Data Typing1181614 +Node: Glossary1184942 +Node: Copying1216871 +Node: GNU Free Documentation License1254427 +Node: Index1279563 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 8cb24eaa..3f2afed3 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -13166,6 +13166,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}. @@ -31123,7 +31124,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 @@ -31131,7 +31132,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 @@ -31284,7 +31285,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 @@ -31328,7 +31329,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: @@ -31356,7 +31357,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. @@ -31394,7 +31395,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 @@ -31406,8 +31407,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>} @@ -31433,7 +31435,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 @@ -31441,7 +31443,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 @@ -31455,7 +31457,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 @@ -31500,6 +31502,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. @@ -31516,7 +31520,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 */ @@ -31562,7 +31566,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 7c229020..3e97423a 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -12494,6 +12494,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}. @@ -30214,7 +30215,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 @@ -30222,7 +30223,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 @@ -30375,7 +30376,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 @@ -30419,7 +30420,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: @@ -30447,7 +30448,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. @@ -30485,7 +30486,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 @@ -30497,8 +30498,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>} @@ -30524,7 +30526,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 @@ -30532,7 +30534,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 @@ -30546,7 +30548,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 @@ -30591,6 +30593,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. @@ -30607,7 +30611,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 */ @@ -30653,7 +30657,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; |