summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorArnold D. Robbins <arnold@skeeve.com>2016-12-17 20:43:40 +0200
committerArnold D. Robbins <arnold@skeeve.com>2016-12-17 20:43:40 +0200
commitb76409d4d7fe75c018a80c685668cb65769a613c (patch)
treefdea7f02dd5bc7a7a4de8fb8d544b5be9eaed291
parent570758ee453fb42451f52a451e75d0a51c732cde (diff)
downloadgawk-b76409d4d7fe75c018a80c685668cb65769a613c.tar.gz
Further api doc updates. Simplify lint checking for max args.
-rw-r--r--ChangeLog7
-rw-r--r--doc/ChangeLog5
-rw-r--r--doc/gawk.info1240
-rw-r--r--doc/gawk.texi111
-rw-r--r--doc/gawktexi.in111
-rw-r--r--gawkapi.h7
-rw-r--r--interpret.h2
7 files changed, 790 insertions, 693 deletions
diff --git a/ChangeLog b/ChangeLog
index 436bf592..dfedd36b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2016-12-17 Arnold D. Robbins <arnold@skeeve.com>
+
+ * gawkapi.h (api_add_ext_func): Add comment about point to
+ awk_ext_func_t not being const but gawk doesn't use it.
+ * * interpret.h (Op_ext_builtin): Simplify code, check only
+ if do_lint and ! f->suppress_lint and num_args > max_expected.
+
2016-12-16 Arnold D. Robbins <arnold@skeeve.com>
* gawkapi.h (awk_ext_func_t): Put max back before min. Restores
diff --git a/doc/ChangeLog b/doc/ChangeLog
index f68e4ce0..c9c618d2 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,8 @@
+2016-12-17 Arnold D. Robbins <arnold@skeeve.com>
+
+ * gawktexi.in: Further API clarifications and edits, add a
+ section on backwards compatibility.
+
2016-12-16 Arnold D. Robbins <arnold@skeeve.com>
* gawktexi.in: Update description of awk_ext_func_t structure,
diff --git a/doc/gawk.info b/doc/gawk.info
index 2269c821..9033acab 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -569,6 +569,7 @@ in (a) below. A copy of the license is included in the section entitled
* Extension API Informational Variables:: Variables providing information about
'gawk''s invocation.
* Extension API Boilerplate:: Boilerplate code for using the API.
+* Changes from API V1:: Changes from V1 of the API.
* Finding Extensions:: How 'gawk' finds compiled
extensions.
* Extension Example:: Example C code for an extension.
@@ -23439,6 +23440,7 @@ API in detail.
redirections.
* Extension API Variables:: Variables provided by the API.
* Extension API Boilerplate:: Boilerplate code for using the API.
+* Changes from API V1:: Changes from V1 of the API.

File: gawk.info, Node: Extension API Functions Introduction, Next: General Data Types, Up: Extension API Description
@@ -23879,7 +23881,9 @@ Extension functions are described by the following record:
which may be followed by any number of letters, digits, and
underscores. Letter case in function names is significant.
-'awk_value_t *(*const function)(int num_actual_args, awk_value_t *result, struct awk_ext_func *finfo);'
+'awk_value_t *(*const function)(int num_actual_args,'
+' awk_value_t *result,'
+' struct awk_ext_func *finfo);'
This is a pointer to the C function that provides the extension's
functionality. The function must fill in '*result' with either a
number or a string. 'gawk' takes ownership of any string memory.
@@ -23920,19 +23924,46 @@ Extension functions are described by the following record:
'void *data;'
This is an opaque pointer to any data that an extension function
may wish to have available when called. Passing the
- 'awk_ext_funct_t' structure to the extension function, and having
- this pointer available in it enables writing a single C or C++
+ 'awk_ext_func_t' structure to the extension function, and having
+ this pointer available in it enable writing a single C or C++
function that implements multiple 'awk'-level extension functions.
Once you have a record representing your extension function, you
register it with 'gawk' using this API function:
-'awk_bool_t add_ext_func(const char *namespace, const awk_ext_func_t *func);'
+'awk_bool_t add_ext_func(const char *namespace, awk_ext_func_t *func);'
This function returns true upon success, false otherwise. The
'namespace' parameter is currently not used; you should pass in an
empty string ('""'). The 'func' pointer is the address of a
'struct' representing your function, as just described.
+ 'gawk' does not modify what 'func' points to, but the extension
+ function itself receives this pointer and can modify what it points
+ to, thus it is purposely not declared to be 'const'.
+
+ The combination of 'min_required_args', 'max_expected_args', and
+'suppress_lint' may be confusing. Here is how you should set things up.
+
+Any number of arguments is valid
+ Set 'min_required_args' and 'max_expected_args' to zero and set
+ 'suppress_lint' to 'awk_true'.
+
+A minimum number of arguments is required, no limit on maximum number of arguments
+ Set 'min_required_args' to the minimum required. Set
+ 'max_expected_args' to zero and set 'suppress_lint' to 'awk_true'.
+
+A minium number of arguments is required, a maximum number is expected
+ Set 'min_required_args' to the minimum required. Set
+ 'max_expected_args' to the maximum expected. Set 'suppress_lint'
+ to 'awk_false'.
+
+A minum number of arguments is required, and no more than a maximum is allowed
+ Set 'min_required_args' to the minimum required. Set
+ 'max_expected_args' to the maximum expected. Set 'suppress_lint'
+ to 'awk_false'. In your extension function, check that
+ 'num_actual_args' does not exceed 'f->max_expected_args'. If it
+ does, issue a fatal error message.
+

File: gawk.info, Node: Exit Callback Functions, Next: Extension Version String, Prev: Extension Functions, Up: Registration Functions
@@ -24526,11 +24557,6 @@ termed a "symbol table". The functions are as follows:
However, with the exception of the 'PROCINFO' array, an extension cannot
change any of those variables.
- CAUTION: It is possible for the lookup of 'PROCINFO' to fail. This
- happens if the 'awk' program being run does not reference
- 'PROCINFO'; in this case, 'gawk' doesn't bother to create the array
- and populate it.
-

File: gawk.info, Node: Symbol table by cookie, Next: Cached values, Prev: Symbol table by name, Up: Symbol Table Access
@@ -25322,10 +25348,10 @@ versions are available at compile time as C preprocessor defines to
support conditional compilation, and as enum constants to facilitate
debugging:
-API Version C preprocessor define enum constant
----------------------------------------------------------------------------
-Major gawk_api_major_version GAWK_API_MAJOR_VERSION
-Minor gawk_api_minor_version GAWK_API_MINOR_VERSION
+API Version C preprocessor define enum constant
+--------------------------------------------------------------------
+Major 'gawk_api_major_version' 'GAWK_API_MAJOR_VERSION'
+Minor 'gawk_api_minor_version' 'GAWK_API_MINOR_VERSION'
Table 16.2: gawk API version constants
@@ -25342,10 +25368,10 @@ For this reason, the major and minor API versions of the running 'gawk'
are included in the API 'struct' as read-only constant integers:
'api->major_version'
- The major version of the running 'gawk'
+ The major version of the running 'gawk'.
'api->minor_version'
- The minor version of the running 'gawk'
+ The minor version of the running 'gawk'.
It is up to the extension to decide if there are API
incompatibilities. Typically, a check like this is enough:
@@ -25399,7 +25425,7 @@ predefined variable (*note Built-in Variables::). The others should not
change during execution.

-File: gawk.info, Node: Extension API Boilerplate, Prev: Extension API Variables, Up: Extension API Description
+File: gawk.info, Node: Extension API Boilerplate, Next: Changes from API V1, Prev: Extension API Variables, Up: Extension API Description
16.4.14 Boilerplate Code
------------------------
@@ -25419,7 +25445,7 @@ the 'gawkapi.h' header file:
static const char *ext_version = NULL; /* or ... = "some string" */
static awk_ext_func_t func_table[] = {
- { "name", do_name, 1 },
+ { "name", do_name, 1, 0, awk_false, NULL },
/* ... */
};
@@ -25500,6 +25526,22 @@ does the following:
'gawk'.

+File: gawk.info, Node: Changes from API V1, Prev: Extension API Boilerplate, Up: Extension API Description
+
+16.4.15 Changes From Version 1 of the API
+-----------------------------------------
+
+The current API is _not_ binary compatible with version 1 of the API.
+You will have to recompile your extensions in order to use them with the
+current version of 'gawk'.
+
+ Fortunately, at the possible expense of some compile-time warnings,
+the API remains source-code-compatible with the previous API. The major
+differences are the additional members in the 'awk_ext_func_t'
+structure, and the addition of the third argument to the C
+implementation function.
+
+
File: gawk.info, Node: Finding Extensions, Next: Extension Example, Prev: Extension API Description, Up: Dynamic Extensions
16.5 How 'gawk' Finds Extensions
@@ -25716,24 +25758,20 @@ is a pointer to an 'awk_value_t' structure, usually named 'result':
/* do_chdir --- provide dynamically loaded chdir() function for gawk */
static awk_value_t *
- do_chdir(int nargs, awk_value_t *result)
+ do_chdir(int nargs, awk_value_t *result, struct awk_ext_func *unused)
{
awk_value_t newdir;
int ret = -1;
assert(result != NULL);
- if (do_lint && nargs != 1)
- lintwarn(ext_id,
- _("chdir: called with incorrect number of arguments, "
- "expecting 1"));
-
The 'newdir' variable represents the new directory to change to,
which is retrieved with 'get_argument()'. Note that the first argument
is numbered zero.
If the argument is retrieved successfully, the function calls the
-'chdir()' system call. If the 'chdir()' fails, 'ERRNO' is updated:
+'chdir()' system call. Otherwise, if the 'chdir()' fails, it updates
+'ERRNO':
if (get_argument(0, AWK_STRING, & newdir)) {
ret = chdir(newdir.str_value.str);
@@ -25920,7 +25958,7 @@ declarations and argument checking:
/* do_stat --- provide a stat() function for gawk */
static awk_value_t *
- do_stat(int nargs, awk_value_t *result)
+ do_stat(int nargs, awk_value_t *result, struct awk_ext_func *unused)
{
awk_value_t file_param, array_param;
char *name;
@@ -25932,13 +25970,6 @@ declarations and argument checking:
assert(result != NULL);
- if (nargs != 2 && nargs != 3) {
- if (do_lint)
- lintwarn(ext_id,
- _("stat: called with wrong number of arguments"));
- return make_number(-1, result);
- }
-
Then comes the actual work. First, the function gets the arguments.
Next, it gets the information for the file. If the called function
('lstat()' or 'stat()') returns an error, the code sets 'ERRNO' and
@@ -25995,11 +26026,9 @@ there is an initialization function:
for loading each function into 'gawk':
static awk_ext_func_t func_table[] = {
- { "chdir", do_chdir, 1 },
- { "stat", do_stat, 2 },
- #ifndef __MINGW32__
- { "fts", do_fts, 3 },
- #endif
+ { "chdir", do_chdir, 1, 1, awk_false, NULL },
+ { "stat", do_stat, 3, 2, awk_false, NULL },
+ ...
};
Each extension must have a routine named 'dl_load()' to load
@@ -35345,573 +35374,574 @@ Index

Tag Table:
Node: Top1200
-Node: Foreword342726
-Node: Foreword447168
-Node: Preface48700
-Ref: Preface-Footnote-151559
-Ref: Preface-Footnote-251666
-Ref: Preface-Footnote-351900
-Node: History52042
-Node: Names54394
-Ref: Names-Footnote-155488
-Node: This Manual55635
-Ref: This Manual-Footnote-162120
-Node: Conventions62220
-Node: Manual History64574
-Ref: Manual History-Footnote-167569
-Ref: Manual History-Footnote-267610
-Node: How To Contribute67684
-Node: Acknowledgments68813
-Node: Getting Started73699
-Node: Running gawk76138
-Node: One-shot77328
-Node: Read Terminal78591
-Node: Long80584
-Node: Executable Scripts82097
-Ref: Executable Scripts-Footnote-184892
-Node: Comments84995
-Node: Quoting87479
-Node: DOS Quoting92996
-Node: Sample Data Files93671
-Node: Very Simple96266
-Node: Two Rules101168
-Node: More Complex103053
-Node: Statements/Lines105919
-Ref: Statements/Lines-Footnote-1110378
-Node: Other Features110643
-Node: When111579
-Ref: When-Footnote-1113333
-Node: Intro Summary113398
-Node: Invoking Gawk114282
-Node: Command Line115796
-Node: Options116594
-Ref: Options-Footnote-1132693
-Ref: Options-Footnote-2132923
-Node: Other Arguments132948
-Node: Naming Standard Input135895
-Node: Environment Variables136988
-Node: AWKPATH Variable137546
-Ref: AWKPATH Variable-Footnote-1140957
-Ref: AWKPATH Variable-Footnote-2140991
-Node: AWKLIBPATH Variable141252
-Node: Other Environment Variables142509
-Node: Exit Status146330
-Node: Include Files147007
-Node: Loading Shared Libraries150602
-Node: Obsolete152030
-Node: Undocumented152722
-Node: Invoking Summary153019
-Node: Regexp154679
-Node: Regexp Usage156133
-Node: Escape Sequences158170
-Node: Regexp Operators164402
-Ref: Regexp Operators-Footnote-1171818
-Ref: Regexp Operators-Footnote-2171965
-Node: Bracket Expressions172063
-Ref: table-char-classes174539
-Node: Leftmost Longest177676
-Node: Computed Regexps178979
-Node: GNU Regexp Operators182406
-Node: Case-sensitivity186085
-Ref: Case-sensitivity-Footnote-1188972
-Ref: Case-sensitivity-Footnote-2189207
-Node: Regexp Summary189315
-Node: Reading Files190781
-Node: Records192944
-Node: awk split records193677
-Node: gawk split records198608
-Ref: gawk split records-Footnote-1203148
-Node: Fields203185
-Node: Nonconstant Fields205926
-Ref: Nonconstant Fields-Footnote-1208162
-Node: Changing Fields208366
-Node: Field Separators214294
-Node: Default Field Splitting216992
-Node: Regexp Field Splitting218110
-Node: Single Character Fields221463
-Node: Command Line Field Separator222523
-Node: Full Line Fields225741
-Ref: Full Line Fields-Footnote-1227263
-Ref: Full Line Fields-Footnote-2227309
-Node: Field Splitting Summary227410
-Node: Constant Size229484
-Node: Splitting By Content234062
-Ref: Splitting By Content-Footnote-1238033
-Node: Multiple Line238196
-Ref: Multiple Line-Footnote-1244078
-Node: Getline244257
-Node: Plain Getline246724
-Node: Getline/Variable249363
-Node: Getline/File250512
-Node: Getline/Variable/File251898
-Ref: Getline/Variable/File-Footnote-1253501
-Node: Getline/Pipe253589
-Node: Getline/Variable/Pipe256294
-Node: Getline/Coprocess257427
-Node: Getline/Variable/Coprocess258692
-Node: Getline Notes259432
-Node: Getline Summary262227
-Ref: table-getline-variants262649
-Node: Read Timeout263397
-Ref: Read Timeout-Footnote-1267303
-Node: Retrying Input267361
-Node: Command-line directories268560
-Node: Input Summary269466
-Node: Input Exercises272638
-Node: Printing273366
-Node: Print275200
-Node: Print Examples276657
-Node: Output Separators279437
-Node: OFMT281454
-Node: Printf282810
-Node: Basic Printf283595
-Node: Control Letters285169
-Node: Format Modifiers289157
-Node: Printf Examples295172
-Node: Redirection297658
-Node: Special FD304499
-Ref: Special FD-Footnote-1307667
-Node: Special Files307741
-Node: Other Inherited Files308358
-Node: Special Network309359
-Node: Special Caveats310219
-Node: Close Files And Pipes311168
-Ref: table-close-pipe-return-values318075
-Ref: Close Files And Pipes-Footnote-1318858
-Ref: Close Files And Pipes-Footnote-2319006
-Node: Nonfatal319158
-Node: Output Summary321483
-Node: Output Exercises322705
-Node: Expressions323384
-Node: Values324572
-Node: Constants325250
-Node: Scalar Constants325941
-Ref: Scalar Constants-Footnote-1326805
-Node: Nondecimal-numbers327055
-Node: Regexp Constants330056
-Node: Using Constant Regexps330582
-Node: Standard Regexp Constants331204
-Node: Strong Regexp Constants334392
-Node: Variables337350
-Node: Using Variables338007
-Node: Assignment Options339917
-Node: Conversion341790
-Node: Strings And Numbers342314
-Ref: Strings And Numbers-Footnote-1345377
-Node: Locale influences conversions345486
-Ref: table-locale-affects348244
-Node: All Operators348862
-Node: Arithmetic Ops349491
-Node: Concatenation351997
-Ref: Concatenation-Footnote-1354844
-Node: Assignment Ops354951
-Ref: table-assign-ops359942
-Node: Increment Ops361255
-Node: Truth Values and Conditions364715
-Node: Truth Values365789
-Node: Typing and Comparison366837
-Node: Variable Typing367657
-Ref: Variable Typing-Footnote-1374120
-Ref: Variable Typing-Footnote-2374192
-Node: Comparison Operators374269
-Ref: table-relational-ops374688
-Node: POSIX String Comparison378183
-Ref: POSIX String Comparison-Footnote-1379878
-Ref: POSIX String Comparison-Footnote-2380017
-Node: Boolean Ops380101
-Ref: Boolean Ops-Footnote-1384583
-Node: Conditional Exp384675
-Node: Function Calls386411
-Node: Precedence390288
-Node: Locales393947
-Node: Expressions Summary395579
-Node: Patterns and Actions398152
-Node: Pattern Overview399272
-Node: Regexp Patterns400949
-Node: Expression Patterns401491
-Node: Ranges405272
-Node: BEGIN/END408380
-Node: Using BEGIN/END409141
-Ref: Using BEGIN/END-Footnote-1411877
-Node: I/O And BEGIN/END411983
-Node: BEGINFILE/ENDFILE414297
-Node: Empty417204
-Node: Using Shell Variables417521
-Node: Action Overview419795
-Node: Statements422120
-Node: If Statement423968
-Node: While Statement425463
-Node: Do Statement427491
-Node: For Statement428639
-Node: Switch Statement431797
-Node: Break Statement434183
-Node: Continue Statement436275
-Node: Next Statement438102
-Node: Nextfile Statement440485
-Node: Exit Statement443137
-Node: Built-in Variables445540
-Node: User-modified446673
-Node: Auto-set454259
-Ref: Auto-set-Footnote-1468912
-Ref: Auto-set-Footnote-2469118
-Node: ARGC and ARGV469174
-Node: Pattern Action Summary473387
-Node: Arrays475817
-Node: Array Basics477146
-Node: Array Intro477990
-Ref: figure-array-elements479965
-Ref: Array Intro-Footnote-1482669
-Node: Reference to Elements482797
-Node: Assigning Elements485261
-Node: Array Example485752
-Node: Scanning an Array487511
-Node: Controlling Scanning490533
-Ref: Controlling Scanning-Footnote-1495932
-Node: Numeric Array Subscripts496248
-Node: Uninitialized Subscripts498432
-Node: Delete500051
-Ref: Delete-Footnote-1502803
-Node: Multidimensional502860
-Node: Multiscanning505955
-Node: Arrays of Arrays507546
-Node: Arrays Summary512313
-Node: Functions514406
-Node: Built-in515444
-Node: Calling Built-in516525
-Node: Numeric Functions518521
-Ref: Numeric Functions-Footnote-1523354
-Ref: Numeric Functions-Footnote-2523711
-Ref: Numeric Functions-Footnote-3523759
-Node: String Functions524031
-Ref: String Functions-Footnote-1547535
-Ref: String Functions-Footnote-2547663
-Ref: String Functions-Footnote-3547911
-Node: Gory Details547998
-Ref: table-sub-escapes549789
-Ref: table-sub-proposed551308
-Ref: table-posix-sub552671
-Ref: table-gensub-escapes554212
-Ref: Gory Details-Footnote-1555035
-Node: I/O Functions555189
-Ref: table-system-return-values561771
-Ref: I/O Functions-Footnote-1563751
-Ref: I/O Functions-Footnote-2563899
-Node: Time Functions564019
-Ref: Time Functions-Footnote-1574541
-Ref: Time Functions-Footnote-2574609
-Ref: Time Functions-Footnote-3574767
-Ref: Time Functions-Footnote-4574878
-Ref: Time Functions-Footnote-5574990
-Ref: Time Functions-Footnote-6575217
-Node: Bitwise Functions575483
-Ref: table-bitwise-ops576077
-Ref: Bitwise Functions-Footnote-1582103
-Ref: Bitwise Functions-Footnote-2582276
-Node: Type Functions582467
-Node: I18N Functions585143
-Node: User-defined586794
-Node: Definition Syntax587599
-Ref: Definition Syntax-Footnote-1593286
-Node: Function Example593357
-Ref: Function Example-Footnote-1596279
-Node: Function Caveats596301
-Node: Calling A Function596819
-Node: Variable Scope597777
-Node: Pass By Value/Reference600771
-Node: Return Statement604270
-Node: Dynamic Typing607249
-Node: Indirect Calls608179
-Ref: Indirect Calls-Footnote-1618430
-Node: Functions Summary618558
-Node: Library Functions621263
-Ref: Library Functions-Footnote-1624870
-Ref: Library Functions-Footnote-2625013
-Node: Library Names625184
-Ref: Library Names-Footnote-1628644
-Ref: Library Names-Footnote-2628867
-Node: General Functions628953
-Node: Strtonum Function630056
-Node: Assert Function633078
-Node: Round Function636404
-Node: Cliff Random Function637945
-Node: Ordinal Functions638961
-Ref: Ordinal Functions-Footnote-1642024
-Ref: Ordinal Functions-Footnote-2642276
-Node: Join Function642486
-Ref: Join Function-Footnote-1644256
-Node: Getlocaltime Function644456
-Node: Readfile Function648198
-Node: Shell Quoting650170
-Node: Data File Management651571
-Node: Filetrans Function652203
-Node: Rewind Function656299
-Node: File Checking658205
-Ref: File Checking-Footnote-1659539
-Node: Empty Files659740
-Node: Ignoring Assigns661719
-Node: Getopt Function663269
-Ref: Getopt Function-Footnote-1674738
-Node: Passwd Functions674938
-Ref: Passwd Functions-Footnote-1683777
-Node: Group Functions683865
-Ref: Group Functions-Footnote-1691763
-Node: Walking Arrays691970
-Node: Library Functions Summary694978
-Node: Library Exercises696384
-Node: Sample Programs696849
-Node: Running Examples697619
-Node: Clones698347
-Node: Cut Program699571
-Node: Egrep Program709500
-Ref: Egrep Program-Footnote-1717012
-Node: Id Program717122
-Node: Split Program720802
-Ref: Split Program-Footnote-1724261
-Node: Tee Program724390
-Node: Uniq Program727180
-Node: Wc Program734606
-Ref: Wc Program-Footnote-1738861
-Node: Miscellaneous Programs738955
-Node: Dupword Program740168
-Node: Alarm Program742198
-Node: Translate Program747053
-Ref: Translate Program-Footnote-1751618
-Node: Labels Program751888
-Ref: Labels Program-Footnote-1755239
-Node: Word Sorting755323
-Node: History Sorting759395
-Node: Extract Program761230
-Node: Simple Sed768759
-Node: Igawk Program771833
-Ref: Igawk Program-Footnote-1786164
-Ref: Igawk Program-Footnote-2786366
-Ref: Igawk Program-Footnote-3786488
-Node: Anagram Program786603
-Node: Signature Program789665
-Node: Programs Summary790912
-Node: Programs Exercises792126
-Ref: Programs Exercises-Footnote-1796255
-Node: Advanced Features796346
-Node: Nondecimal Data798336
-Node: Array Sorting799927
-Node: Controlling Array Traversal800627
-Ref: Controlling Array Traversal-Footnote-1808994
-Node: Array Sorting Functions809112
-Ref: Array Sorting Functions-Footnote-1814203
-Node: Two-way I/O814399
-Ref: Two-way I/O-Footnote-1820949
-Ref: Two-way I/O-Footnote-2821136
-Node: TCP/IP Networking821218
-Node: Profiling824336
-Ref: Profiling-Footnote-1832829
-Node: Advanced Features Summary833152
-Node: Internationalization834996
-Node: I18N and L10N836476
-Node: Explaining gettext837163
-Ref: Explaining gettext-Footnote-1843055
-Ref: Explaining gettext-Footnote-2843240
-Node: Programmer i18n843405
-Ref: Programmer i18n-Footnote-1848354
-Node: Translator i18n848403
-Node: String Extraction849197
-Ref: String Extraction-Footnote-1850329
-Node: Printf Ordering850415
-Ref: Printf Ordering-Footnote-1853201
-Node: I18N Portability853265
-Ref: I18N Portability-Footnote-1855721
-Node: I18N Example855784
-Ref: I18N Example-Footnote-1858590
-Node: Gawk I18N858663
-Node: I18N Summary859308
-Node: Debugger860649
-Node: Debugging861671
-Node: Debugging Concepts862112
-Node: Debugging Terms863921
-Node: Awk Debugging866496
-Node: Sample Debugging Session867402
-Node: Debugger Invocation867936
-Node: Finding The Bug869322
-Node: List of Debugger Commands875800
-Node: Breakpoint Control877133
-Node: Debugger Execution Control880827
-Node: Viewing And Changing Data884189
-Node: Execution Stack887563
-Node: Debugger Info889200
-Node: Miscellaneous Debugger Commands893271
-Node: Readline Support898359
-Node: Limitations899255
-Node: Debugging Summary901364
-Node: Arbitrary Precision Arithmetic902643
-Node: Computer Arithmetic904059
-Ref: table-numeric-ranges907650
-Ref: Computer Arithmetic-Footnote-1908372
-Node: Math Definitions908429
-Ref: table-ieee-formats911743
-Ref: Math Definitions-Footnote-1912346
-Node: MPFR features912451
-Node: FP Math Caution914168
-Ref: FP Math Caution-Footnote-1915240
-Node: Inexactness of computations915609
-Node: Inexact representation916569
-Node: Comparing FP Values917929
-Node: Errors accumulate919011
-Node: Getting Accuracy920444
-Node: Try To Round923154
-Node: Setting precision924053
-Ref: table-predefined-precision-strings924750
-Node: Setting the rounding mode926580
-Ref: table-gawk-rounding-modes926954
-Ref: Setting the rounding mode-Footnote-1930362
-Node: Arbitrary Precision Integers930541
-Ref: Arbitrary Precision Integers-Footnote-1935458
-Node: POSIX Floating Point Problems935607
-Ref: POSIX Floating Point Problems-Footnote-1939489
-Node: Floating point summary939527
-Node: Dynamic Extensions941717
-Node: Extension Intro943270
-Node: Plugin License944536
-Node: Extension Mechanism Outline945333
-Ref: figure-load-extension945772
-Ref: figure-register-new-function947337
-Ref: figure-call-new-function948429
-Node: Extension API Description950491
-Node: Extension API Functions Introduction952064
-Node: General Data Types957375
-Ref: General Data Types-Footnote-1963330
-Node: Memory Allocation Functions963629
-Ref: Memory Allocation Functions-Footnote-1966474
-Node: Constructor Functions966573
-Node: Registration Functions968318
-Node: Extension Functions969003
-Node: Exit Callback Functions972844
-Node: Extension Version String974094
-Node: Input Parsers974757
-Node: Output Wrappers984639
-Node: Two-way processors989151
-Node: Printing Messages991416
-Ref: Printing Messages-Footnote-1992587
-Node: Updating ERRNO992740
-Node: Requesting Values993479
-Ref: table-value-types-returned994216
-Node: Accessing Parameters995099
-Node: Symbol Table Access996334
-Node: Symbol table by name996846
-Node: Symbol table by cookie998867
-Ref: Symbol table by cookie-Footnote-11003019
-Node: Cached values1003083
-Ref: Cached values-Footnote-11006590
-Node: Array Manipulation1006681
-Ref: Array Manipulation-Footnote-11007772
-Node: Array Data Types1007809
-Ref: Array Data Types-Footnote-11010467
-Node: Array Functions1010559
-Node: Flattening Arrays1014417
-Node: Creating Arrays1021325
-Node: Redirection API1026094
-Node: Extension API Variables1028925
-Node: Extension Versioning1029558
-Ref: gawk-api-version1029995
-Node: Extension API Informational Variables1031751
-Node: Extension API Boilerplate1032815
-Node: Finding Extensions1036629
-Node: Extension Example1037188
-Node: Internal File Description1037986
-Node: Internal File Ops1042066
-Ref: Internal File Ops-Footnote-11053828
-Node: Using Internal File Ops1053968
-Ref: Using Internal File Ops-Footnote-11056351
-Node: Extension Samples1056625
-Node: Extension Sample File Functions1058154
-Node: Extension Sample Fnmatch1065803
-Node: Extension Sample Fork1067290
-Node: Extension Sample Inplace1068508
-Node: Extension Sample Ord1071718
-Node: Extension Sample Readdir1072554
-Ref: table-readdir-file-types1073443
-Node: Extension Sample Revout1074248
-Node: Extension Sample Rev2way1074837
-Node: Extension Sample Read write array1075577
-Node: Extension Sample Readfile1077519
-Node: Extension Sample Time1078614
-Node: Extension Sample API Tests1079962
-Node: gawkextlib1080454
-Node: Extension summary1082901
-Node: Extension Exercises1086603
-Node: Language History1088101
-Node: V7/SVR3.11089757
-Node: SVR41091909
-Node: POSIX1093343
-Node: BTL1094722
-Node: POSIX/GNU1095451
-Node: Feature History1101313
-Node: Common Extensions1115683
-Node: Ranges and Locales1116966
-Ref: Ranges and Locales-Footnote-11121582
-Ref: Ranges and Locales-Footnote-21121609
-Ref: Ranges and Locales-Footnote-31121844
-Node: Contributors1122065
-Node: History summary1127625
-Node: Installation1129005
-Node: Gawk Distribution1129949
-Node: Getting1130433
-Node: Extracting1131394
-Node: Distribution contents1133032
-Node: Unix Installation1139117
-Node: Quick Installation1139799
-Node: Shell Startup Files1142213
-Node: Additional Configuration Options1143291
-Node: Configuration Philosophy1145096
-Node: Non-Unix Installation1147465
-Node: PC Installation1147925
-Node: PC Binary Installation1148763
-Node: PC Compiling1149198
-Node: PC Using1150315
-Node: Cygwin1153360
-Node: MSYS1154130
-Node: VMS Installation1154631
-Node: VMS Compilation1155422
-Ref: VMS Compilation-Footnote-11156651
-Node: VMS Dynamic Extensions1156709
-Node: VMS Installation Details1158394
-Node: VMS Running1160647
-Node: VMS GNV1164926
-Node: VMS Old Gawk1165661
-Node: Bugs1166132
-Node: Bug address1166795
-Node: Usenet1169192
-Node: Maintainers1169967
-Node: Other Versions1171343
-Node: Installation summary1177927
-Node: Notes1178962
-Node: Compatibility Mode1179827
-Node: Additions1180609
-Node: Accessing The Source1181534
-Node: Adding Code1182969
-Node: New Ports1189188
-Node: Derived Files1193676
-Ref: Derived Files-Footnote-11199161
-Ref: Derived Files-Footnote-21199196
-Ref: Derived Files-Footnote-31199794
-Node: Future Extensions1199908
-Node: Implementation Limitations1200566
-Node: Extension Design1201749
-Node: Old Extension Problems1202903
-Ref: Old Extension Problems-Footnote-11204421
-Node: Extension New Mechanism Goals1204478
-Ref: Extension New Mechanism Goals-Footnote-11207842
-Node: Extension Other Design Decisions1208031
-Node: Extension Future Growth1210144
-Node: Old Extension Mechanism1210980
-Node: Notes summary1212743
-Node: Basic Concepts1213925
-Node: Basic High Level1214606
-Ref: figure-general-flow1214888
-Ref: figure-process-flow1215573
-Ref: Basic High Level-Footnote-11218874
-Node: Basic Data Typing1219059
-Node: Glossary1222387
-Node: Copying1254334
-Node: GNU Free Documentation License1291873
-Node: Index1316991
+Node: Foreword342794
+Node: Foreword447236
+Node: Preface48768
+Ref: Preface-Footnote-151627
+Ref: Preface-Footnote-251734
+Ref: Preface-Footnote-351968
+Node: History52110
+Node: Names54462
+Ref: Names-Footnote-155556
+Node: This Manual55703
+Ref: This Manual-Footnote-162188
+Node: Conventions62288
+Node: Manual History64642
+Ref: Manual History-Footnote-167637
+Ref: Manual History-Footnote-267678
+Node: How To Contribute67752
+Node: Acknowledgments68881
+Node: Getting Started73767
+Node: Running gawk76206
+Node: One-shot77396
+Node: Read Terminal78659
+Node: Long80652
+Node: Executable Scripts82165
+Ref: Executable Scripts-Footnote-184960
+Node: Comments85063
+Node: Quoting87547
+Node: DOS Quoting93064
+Node: Sample Data Files93739
+Node: Very Simple96334
+Node: Two Rules101236
+Node: More Complex103121
+Node: Statements/Lines105987
+Ref: Statements/Lines-Footnote-1110446
+Node: Other Features110711
+Node: When111647
+Ref: When-Footnote-1113401
+Node: Intro Summary113466
+Node: Invoking Gawk114350
+Node: Command Line115864
+Node: Options116662
+Ref: Options-Footnote-1132761
+Ref: Options-Footnote-2132991
+Node: Other Arguments133016
+Node: Naming Standard Input135963
+Node: Environment Variables137056
+Node: AWKPATH Variable137614
+Ref: AWKPATH Variable-Footnote-1141025
+Ref: AWKPATH Variable-Footnote-2141059
+Node: AWKLIBPATH Variable141320
+Node: Other Environment Variables142577
+Node: Exit Status146398
+Node: Include Files147075
+Node: Loading Shared Libraries150670
+Node: Obsolete152098
+Node: Undocumented152790
+Node: Invoking Summary153087
+Node: Regexp154747
+Node: Regexp Usage156201
+Node: Escape Sequences158238
+Node: Regexp Operators164470
+Ref: Regexp Operators-Footnote-1171886
+Ref: Regexp Operators-Footnote-2172033
+Node: Bracket Expressions172131
+Ref: table-char-classes174607
+Node: Leftmost Longest177744
+Node: Computed Regexps179047
+Node: GNU Regexp Operators182474
+Node: Case-sensitivity186153
+Ref: Case-sensitivity-Footnote-1189040
+Ref: Case-sensitivity-Footnote-2189275
+Node: Regexp Summary189383
+Node: Reading Files190849
+Node: Records193012
+Node: awk split records193745
+Node: gawk split records198676
+Ref: gawk split records-Footnote-1203216
+Node: Fields203253
+Node: Nonconstant Fields205994
+Ref: Nonconstant Fields-Footnote-1208230
+Node: Changing Fields208434
+Node: Field Separators214362
+Node: Default Field Splitting217060
+Node: Regexp Field Splitting218178
+Node: Single Character Fields221531
+Node: Command Line Field Separator222591
+Node: Full Line Fields225809
+Ref: Full Line Fields-Footnote-1227331
+Ref: Full Line Fields-Footnote-2227377
+Node: Field Splitting Summary227478
+Node: Constant Size229552
+Node: Splitting By Content234130
+Ref: Splitting By Content-Footnote-1238101
+Node: Multiple Line238264
+Ref: Multiple Line-Footnote-1244146
+Node: Getline244325
+Node: Plain Getline246792
+Node: Getline/Variable249431
+Node: Getline/File250580
+Node: Getline/Variable/File251966
+Ref: Getline/Variable/File-Footnote-1253569
+Node: Getline/Pipe253657
+Node: Getline/Variable/Pipe256362
+Node: Getline/Coprocess257495
+Node: Getline/Variable/Coprocess258760
+Node: Getline Notes259500
+Node: Getline Summary262295
+Ref: table-getline-variants262717
+Node: Read Timeout263465
+Ref: Read Timeout-Footnote-1267371
+Node: Retrying Input267429
+Node: Command-line directories268628
+Node: Input Summary269534
+Node: Input Exercises272706
+Node: Printing273434
+Node: Print275268
+Node: Print Examples276725
+Node: Output Separators279505
+Node: OFMT281522
+Node: Printf282878
+Node: Basic Printf283663
+Node: Control Letters285237
+Node: Format Modifiers289225
+Node: Printf Examples295240
+Node: Redirection297726
+Node: Special FD304567
+Ref: Special FD-Footnote-1307735
+Node: Special Files307809
+Node: Other Inherited Files308426
+Node: Special Network309427
+Node: Special Caveats310287
+Node: Close Files And Pipes311236
+Ref: table-close-pipe-return-values318143
+Ref: Close Files And Pipes-Footnote-1318926
+Ref: Close Files And Pipes-Footnote-2319074
+Node: Nonfatal319226
+Node: Output Summary321551
+Node: Output Exercises322773
+Node: Expressions323452
+Node: Values324640
+Node: Constants325318
+Node: Scalar Constants326009
+Ref: Scalar Constants-Footnote-1326873
+Node: Nondecimal-numbers327123
+Node: Regexp Constants330124
+Node: Using Constant Regexps330650
+Node: Standard Regexp Constants331272
+Node: Strong Regexp Constants334460
+Node: Variables337418
+Node: Using Variables338075
+Node: Assignment Options339985
+Node: Conversion341858
+Node: Strings And Numbers342382
+Ref: Strings And Numbers-Footnote-1345445
+Node: Locale influences conversions345554
+Ref: table-locale-affects348312
+Node: All Operators348930
+Node: Arithmetic Ops349559
+Node: Concatenation352065
+Ref: Concatenation-Footnote-1354912
+Node: Assignment Ops355019
+Ref: table-assign-ops360010
+Node: Increment Ops361323
+Node: Truth Values and Conditions364783
+Node: Truth Values365857
+Node: Typing and Comparison366905
+Node: Variable Typing367725
+Ref: Variable Typing-Footnote-1374188
+Ref: Variable Typing-Footnote-2374260
+Node: Comparison Operators374337
+Ref: table-relational-ops374756
+Node: POSIX String Comparison378251
+Ref: POSIX String Comparison-Footnote-1379946
+Ref: POSIX String Comparison-Footnote-2380085
+Node: Boolean Ops380169
+Ref: Boolean Ops-Footnote-1384651
+Node: Conditional Exp384743
+Node: Function Calls386479
+Node: Precedence390356
+Node: Locales394015
+Node: Expressions Summary395647
+Node: Patterns and Actions398220
+Node: Pattern Overview399340
+Node: Regexp Patterns401017
+Node: Expression Patterns401559
+Node: Ranges405340
+Node: BEGIN/END408448
+Node: Using BEGIN/END409209
+Ref: Using BEGIN/END-Footnote-1411945
+Node: I/O And BEGIN/END412051
+Node: BEGINFILE/ENDFILE414365
+Node: Empty417272
+Node: Using Shell Variables417589
+Node: Action Overview419863
+Node: Statements422188
+Node: If Statement424036
+Node: While Statement425531
+Node: Do Statement427559
+Node: For Statement428707
+Node: Switch Statement431865
+Node: Break Statement434251
+Node: Continue Statement436343
+Node: Next Statement438170
+Node: Nextfile Statement440553
+Node: Exit Statement443205
+Node: Built-in Variables445608
+Node: User-modified446741
+Node: Auto-set454327
+Ref: Auto-set-Footnote-1468980
+Ref: Auto-set-Footnote-2469186
+Node: ARGC and ARGV469242
+Node: Pattern Action Summary473455
+Node: Arrays475885
+Node: Array Basics477214
+Node: Array Intro478058
+Ref: figure-array-elements480033
+Ref: Array Intro-Footnote-1482737
+Node: Reference to Elements482865
+Node: Assigning Elements485329
+Node: Array Example485820
+Node: Scanning an Array487579
+Node: Controlling Scanning490601
+Ref: Controlling Scanning-Footnote-1496000
+Node: Numeric Array Subscripts496316
+Node: Uninitialized Subscripts498500
+Node: Delete500119
+Ref: Delete-Footnote-1502871
+Node: Multidimensional502928
+Node: Multiscanning506023
+Node: Arrays of Arrays507614
+Node: Arrays Summary512381
+Node: Functions514474
+Node: Built-in515512
+Node: Calling Built-in516593
+Node: Numeric Functions518589
+Ref: Numeric Functions-Footnote-1523422
+Ref: Numeric Functions-Footnote-2523779
+Ref: Numeric Functions-Footnote-3523827
+Node: String Functions524099
+Ref: String Functions-Footnote-1547603
+Ref: String Functions-Footnote-2547731
+Ref: String Functions-Footnote-3547979
+Node: Gory Details548066
+Ref: table-sub-escapes549857
+Ref: table-sub-proposed551376
+Ref: table-posix-sub552739
+Ref: table-gensub-escapes554280
+Ref: Gory Details-Footnote-1555103
+Node: I/O Functions555257
+Ref: table-system-return-values561839
+Ref: I/O Functions-Footnote-1563819
+Ref: I/O Functions-Footnote-2563967
+Node: Time Functions564087
+Ref: Time Functions-Footnote-1574609
+Ref: Time Functions-Footnote-2574677
+Ref: Time Functions-Footnote-3574835
+Ref: Time Functions-Footnote-4574946
+Ref: Time Functions-Footnote-5575058
+Ref: Time Functions-Footnote-6575285
+Node: Bitwise Functions575551
+Ref: table-bitwise-ops576145
+Ref: Bitwise Functions-Footnote-1582171
+Ref: Bitwise Functions-Footnote-2582344
+Node: Type Functions582535
+Node: I18N Functions585211
+Node: User-defined586862
+Node: Definition Syntax587667
+Ref: Definition Syntax-Footnote-1593354
+Node: Function Example593425
+Ref: Function Example-Footnote-1596347
+Node: Function Caveats596369
+Node: Calling A Function596887
+Node: Variable Scope597845
+Node: Pass By Value/Reference600839
+Node: Return Statement604338
+Node: Dynamic Typing607317
+Node: Indirect Calls608247
+Ref: Indirect Calls-Footnote-1618498
+Node: Functions Summary618626
+Node: Library Functions621331
+Ref: Library Functions-Footnote-1624938
+Ref: Library Functions-Footnote-2625081
+Node: Library Names625252
+Ref: Library Names-Footnote-1628712
+Ref: Library Names-Footnote-2628935
+Node: General Functions629021
+Node: Strtonum Function630124
+Node: Assert Function633146
+Node: Round Function636472
+Node: Cliff Random Function638013
+Node: Ordinal Functions639029
+Ref: Ordinal Functions-Footnote-1642092
+Ref: Ordinal Functions-Footnote-2642344
+Node: Join Function642554
+Ref: Join Function-Footnote-1644324
+Node: Getlocaltime Function644524
+Node: Readfile Function648266
+Node: Shell Quoting650238
+Node: Data File Management651639
+Node: Filetrans Function652271
+Node: Rewind Function656367
+Node: File Checking658273
+Ref: File Checking-Footnote-1659607
+Node: Empty Files659808
+Node: Ignoring Assigns661787
+Node: Getopt Function663337
+Ref: Getopt Function-Footnote-1674806
+Node: Passwd Functions675006
+Ref: Passwd Functions-Footnote-1683845
+Node: Group Functions683933
+Ref: Group Functions-Footnote-1691831
+Node: Walking Arrays692038
+Node: Library Functions Summary695046
+Node: Library Exercises696452
+Node: Sample Programs696917
+Node: Running Examples697687
+Node: Clones698415
+Node: Cut Program699639
+Node: Egrep Program709568
+Ref: Egrep Program-Footnote-1717080
+Node: Id Program717190
+Node: Split Program720870
+Ref: Split Program-Footnote-1724329
+Node: Tee Program724458
+Node: Uniq Program727248
+Node: Wc Program734674
+Ref: Wc Program-Footnote-1738929
+Node: Miscellaneous Programs739023
+Node: Dupword Program740236
+Node: Alarm Program742266
+Node: Translate Program747121
+Ref: Translate Program-Footnote-1751686
+Node: Labels Program751956
+Ref: Labels Program-Footnote-1755307
+Node: Word Sorting755391
+Node: History Sorting759463
+Node: Extract Program761298
+Node: Simple Sed768827
+Node: Igawk Program771901
+Ref: Igawk Program-Footnote-1786232
+Ref: Igawk Program-Footnote-2786434
+Ref: Igawk Program-Footnote-3786556
+Node: Anagram Program786671
+Node: Signature Program789733
+Node: Programs Summary790980
+Node: Programs Exercises792194
+Ref: Programs Exercises-Footnote-1796323
+Node: Advanced Features796414
+Node: Nondecimal Data798404
+Node: Array Sorting799995
+Node: Controlling Array Traversal800695
+Ref: Controlling Array Traversal-Footnote-1809062
+Node: Array Sorting Functions809180
+Ref: Array Sorting Functions-Footnote-1814271
+Node: Two-way I/O814467
+Ref: Two-way I/O-Footnote-1821017
+Ref: Two-way I/O-Footnote-2821204
+Node: TCP/IP Networking821286
+Node: Profiling824404
+Ref: Profiling-Footnote-1832897
+Node: Advanced Features Summary833220
+Node: Internationalization835064
+Node: I18N and L10N836544
+Node: Explaining gettext837231
+Ref: Explaining gettext-Footnote-1843123
+Ref: Explaining gettext-Footnote-2843308
+Node: Programmer i18n843473
+Ref: Programmer i18n-Footnote-1848422
+Node: Translator i18n848471
+Node: String Extraction849265
+Ref: String Extraction-Footnote-1850397
+Node: Printf Ordering850483
+Ref: Printf Ordering-Footnote-1853269
+Node: I18N Portability853333
+Ref: I18N Portability-Footnote-1855789
+Node: I18N Example855852
+Ref: I18N Example-Footnote-1858658
+Node: Gawk I18N858731
+Node: I18N Summary859376
+Node: Debugger860717
+Node: Debugging861739
+Node: Debugging Concepts862180
+Node: Debugging Terms863989
+Node: Awk Debugging866564
+Node: Sample Debugging Session867470
+Node: Debugger Invocation868004
+Node: Finding The Bug869390
+Node: List of Debugger Commands875868
+Node: Breakpoint Control877201
+Node: Debugger Execution Control880895
+Node: Viewing And Changing Data884257
+Node: Execution Stack887631
+Node: Debugger Info889268
+Node: Miscellaneous Debugger Commands893339
+Node: Readline Support898427
+Node: Limitations899323
+Node: Debugging Summary901432
+Node: Arbitrary Precision Arithmetic902711
+Node: Computer Arithmetic904127
+Ref: table-numeric-ranges907718
+Ref: Computer Arithmetic-Footnote-1908440
+Node: Math Definitions908497
+Ref: table-ieee-formats911811
+Ref: Math Definitions-Footnote-1912414
+Node: MPFR features912519
+Node: FP Math Caution914236
+Ref: FP Math Caution-Footnote-1915308
+Node: Inexactness of computations915677
+Node: Inexact representation916637
+Node: Comparing FP Values917997
+Node: Errors accumulate919079
+Node: Getting Accuracy920512
+Node: Try To Round923222
+Node: Setting precision924121
+Ref: table-predefined-precision-strings924818
+Node: Setting the rounding mode926648
+Ref: table-gawk-rounding-modes927022
+Ref: Setting the rounding mode-Footnote-1930430
+Node: Arbitrary Precision Integers930609
+Ref: Arbitrary Precision Integers-Footnote-1935526
+Node: POSIX Floating Point Problems935675
+Ref: POSIX Floating Point Problems-Footnote-1939557
+Node: Floating point summary939595
+Node: Dynamic Extensions941785
+Node: Extension Intro943338
+Node: Plugin License944604
+Node: Extension Mechanism Outline945401
+Ref: figure-load-extension945840
+Ref: figure-register-new-function947405
+Ref: figure-call-new-function948497
+Node: Extension API Description950559
+Node: Extension API Functions Introduction952201
+Node: General Data Types957512
+Ref: General Data Types-Footnote-1963467
+Node: Memory Allocation Functions963766
+Ref: Memory Allocation Functions-Footnote-1966611
+Node: Constructor Functions966710
+Node: Registration Functions968455
+Node: Extension Functions969140
+Node: Exit Callback Functions974338
+Node: Extension Version String975588
+Node: Input Parsers976251
+Node: Output Wrappers986133
+Node: Two-way processors990645
+Node: Printing Messages992910
+Ref: Printing Messages-Footnote-1994081
+Node: Updating ERRNO994234
+Node: Requesting Values994973
+Ref: table-value-types-returned995710
+Node: Accessing Parameters996593
+Node: Symbol Table Access997828
+Node: Symbol table by name998340
+Node: Symbol table by cookie1000129
+Ref: Symbol table by cookie-Footnote-11004281
+Node: Cached values1004345
+Ref: Cached values-Footnote-11007852
+Node: Array Manipulation1007943
+Ref: Array Manipulation-Footnote-11009034
+Node: Array Data Types1009071
+Ref: Array Data Types-Footnote-11011729
+Node: Array Functions1011821
+Node: Flattening Arrays1015679
+Node: Creating Arrays1022587
+Node: Redirection API1027356
+Node: Extension API Variables1030187
+Node: Extension Versioning1030820
+Ref: gawk-api-version1031257
+Node: Extension API Informational Variables1032985
+Node: Extension API Boilerplate1034049
+Node: Changes from API V11037911
+Node: Finding Extensions1038571
+Node: Extension Example1039130
+Node: Internal File Description1039928
+Node: Internal File Ops1044008
+Ref: Internal File Ops-Footnote-11055408
+Node: Using Internal File Ops1055548
+Ref: Using Internal File Ops-Footnote-11057931
+Node: Extension Samples1058205
+Node: Extension Sample File Functions1059734
+Node: Extension Sample Fnmatch1067383
+Node: Extension Sample Fork1068870
+Node: Extension Sample Inplace1070088
+Node: Extension Sample Ord1073298
+Node: Extension Sample Readdir1074134
+Ref: table-readdir-file-types1075023
+Node: Extension Sample Revout1075828
+Node: Extension Sample Rev2way1076417
+Node: Extension Sample Read write array1077157
+Node: Extension Sample Readfile1079099
+Node: Extension Sample Time1080194
+Node: Extension Sample API Tests1081542
+Node: gawkextlib1082034
+Node: Extension summary1084481
+Node: Extension Exercises1088183
+Node: Language History1089681
+Node: V7/SVR3.11091337
+Node: SVR41093489
+Node: POSIX1094923
+Node: BTL1096302
+Node: POSIX/GNU1097031
+Node: Feature History1102893
+Node: Common Extensions1117263
+Node: Ranges and Locales1118546
+Ref: Ranges and Locales-Footnote-11123162
+Ref: Ranges and Locales-Footnote-21123189
+Ref: Ranges and Locales-Footnote-31123424
+Node: Contributors1123645
+Node: History summary1129205
+Node: Installation1130585
+Node: Gawk Distribution1131529
+Node: Getting1132013
+Node: Extracting1132974
+Node: Distribution contents1134612
+Node: Unix Installation1140697
+Node: Quick Installation1141379
+Node: Shell Startup Files1143793
+Node: Additional Configuration Options1144871
+Node: Configuration Philosophy1146676
+Node: Non-Unix Installation1149045
+Node: PC Installation1149505
+Node: PC Binary Installation1150343
+Node: PC Compiling1150778
+Node: PC Using1151895
+Node: Cygwin1154940
+Node: MSYS1155710
+Node: VMS Installation1156211
+Node: VMS Compilation1157002
+Ref: VMS Compilation-Footnote-11158231
+Node: VMS Dynamic Extensions1158289
+Node: VMS Installation Details1159974
+Node: VMS Running1162227
+Node: VMS GNV1166506
+Node: VMS Old Gawk1167241
+Node: Bugs1167712
+Node: Bug address1168375
+Node: Usenet1170772
+Node: Maintainers1171547
+Node: Other Versions1172923
+Node: Installation summary1179507
+Node: Notes1180542
+Node: Compatibility Mode1181407
+Node: Additions1182189
+Node: Accessing The Source1183114
+Node: Adding Code1184549
+Node: New Ports1190768
+Node: Derived Files1195256
+Ref: Derived Files-Footnote-11200741
+Ref: Derived Files-Footnote-21200776
+Ref: Derived Files-Footnote-31201374
+Node: Future Extensions1201488
+Node: Implementation Limitations1202146
+Node: Extension Design1203329
+Node: Old Extension Problems1204483
+Ref: Old Extension Problems-Footnote-11206001
+Node: Extension New Mechanism Goals1206058
+Ref: Extension New Mechanism Goals-Footnote-11209422
+Node: Extension Other Design Decisions1209611
+Node: Extension Future Growth1211724
+Node: Old Extension Mechanism1212560
+Node: Notes summary1214323
+Node: Basic Concepts1215505
+Node: Basic High Level1216186
+Ref: figure-general-flow1216468
+Ref: figure-process-flow1217153
+Ref: Basic High Level-Footnote-11220454
+Node: Basic Data Typing1220639
+Node: Glossary1223967
+Node: Copying1255914
+Node: GNU Free Documentation License1293453
+Node: Index1318571

End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index a419a668..4998f81e 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -933,6 +933,7 @@ particular records in a file and perform operations upon them.
* Extension API Informational Variables:: Variables providing information about
@command{gawk}'s invocation.
* Extension API Boilerplate:: Boilerplate code for using the API.
+* Changes from API V1:: Changes from V1 of the API.
* Finding Extensions:: How @command{gawk} finds compiled
extensions.
* Extension Example:: Example C code for an extension.
@@ -32323,6 +32324,7 @@ This (rather large) @value{SECTION} describes the API in detail.
redirections.
* Extension API Variables:: Variables provided by the API.
* Extension API Boilerplate:: Boilerplate code for using the API.
+* Changes from API V1:: Changes from V1 of the API.
@end menu
@node Extension API Functions Introduction
@@ -32823,11 +32825,15 @@ or an underscore, which may be followed by any number of
letters, digits, and underscores.
Letter case in function names is significant.
-@item awk_value_t *(*const function)(int num_actual_args, awk_value_t *result, struct awk_ext_func *finfo);
+@item awk_value_t *(*const function)(int num_actual_args,
+@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_value_t *result,
+@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ struct awk_ext_func *finfo);
This is a pointer to the C function that provides the extension's
functionality.
The function must fill in @code{*result} with either a number
-or a string. @command{gawk} takes ownership of any string memory.
+or a string.
+@c FIXME: Change to a scalar - number, string or regex once regex api stuff is merged.
+@command{gawk} takes ownership of any string memory.
As mentioned earlier, string memory @emph{must} come from one of
@code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()}.
@@ -32862,9 +32868,9 @@ to @code{awk_true}.
@item void *data;
This is an opaque pointer to any data that an extension function may
-wish to have available when called. Passing the @code{awk_ext_funct_t}
+wish to have available when called. Passing the @code{awk_ext_func_t}
structure to the extension function, and having this pointer available
-in it enables writing a single C or C++ function that implements multiple
+in it enable writing a single C or C++ function that implements multiple
@command{awk}-level extension functions.
@end table
@@ -32872,11 +32878,42 @@ Once you have a record representing your extension function, you register
it with @command{gawk} using this API function:
@table @code
-@item awk_bool_t add_ext_func(const char *namespace, const awk_ext_func_t *func);
+@item awk_bool_t add_ext_func(const char *namespace, awk_ext_func_t *func);
This function returns true upon success, false otherwise.
The @code{namespace} parameter is currently not used; you should pass in an
empty string (@code{""}). The @code{func} pointer is the address of a
@code{struct} representing your function, as just described.
+
+@command{gawk} does not modify what @code{func} points to, but the
+extension function itself receives this pointer and can modify what it
+points to, thus it is purposely not declared to be @code{const}.
+@end table
+
+The combination of @code{min_required_args}, @code{max_expected_args},
+and @code{suppress_lint} may be confusing. Here is how you should
+set things up.
+
+@table @asis
+@item Any number of arguments is valid
+Set @code{min_required_args} and @code{max_expected_args} to zero and
+set @code{suppress_lint} to @code{awk_true}.
+
+@item A minimum number of arguments is required, no limit on maximum number of arguments
+Set @code{min_required_args} to the minimum required. Set
+@code{max_expected_args} to zero and
+set @code{suppress_lint} to @code{awk_true}.
+
+@item A minium number of arguments is required, a maximum number is expected
+Set @code{min_required_args} to the minimum required. Set
+@code{max_expected_args} to the maximum expected.
+Set @code{suppress_lint} to @code{awk_false}.
+
+@item A minum number of arguments is required, and no more than a maximum is allowed
+Set @code{min_required_args} to the minimum required. Set
+@code{max_expected_args} to the maximum expected.
+Set @code{suppress_lint} to @code{awk_false}.
+In your extension function, check that @code{num_actual_args} does not
+exceed @code{f->max_expected_args}. If it does, issue a fatal error message.
@end table
@node Exit Callback Functions
@@ -33617,13 +33654,6 @@ An extension can look up the value of @command{gawk}'s special variables.
However, with the exception of the @code{PROCINFO} array, an extension
cannot change any of those variables.
-@quotation CAUTION
-It is possible for the lookup of @code{PROCINFO} to fail. This happens if
-the @command{awk} program being run does not reference @code{PROCINFO};
-in this case, @command{gawk} doesn't bother to create the array and
-populate it.
-@end quotation
-
@node Symbol table by cookie
@subsubsection Variable Access and Update by Cookie
@@ -34509,10 +34539,10 @@ debugging:
@float Table,gawk-api-version
@caption{gawk API version constants}
-@multitable @columnfractions .33 .33 .33
+@multitable {@b{API Version}} {@code{gawk_api_major_version}} {@code{GAWK_API_MAJOR_VERSION}}
@headitem API Version @tab C preprocessor define @tab enum constant
-@item Major @tab gawk_api_major_version @tab GAWK_API_MAJOR_VERSION
-@item Minor @tab gawk_api_minor_version @tab GAWK_API_MINOR_VERSION
+@item Major @tab @code{gawk_api_major_version} @tab @code{GAWK_API_MAJOR_VERSION}
+@item Minor @tab @code{gawk_api_minor_version} @tab @code{GAWK_API_MINOR_VERSION}
@end multitable
@end float
@@ -34531,10 +34561,10 @@ constant integers:
@table @code
@item api->major_version
-The major version of the running @command{gawk}
+The major version of the running @command{gawk}.
@item api->minor_version
-The minor version of the running @command{gawk}
+The minor version of the running @command{gawk}.
@end table
It is up to the extension to decide if there are API incompatibilities.
@@ -34607,7 +34637,7 @@ static awk_ext_id_t ext_id;
static const char *ext_version = NULL; /* or @dots{} = "some string" */
static awk_ext_func_t func_table[] = @{
- @{ "name", do_name, 1 @},
+ @{ "name", do_name, 1, 0, awk_false, NULL @},
/* @dots{} */
@};
@@ -34708,6 +34738,19 @@ If @code{ext_version} is not @code{NULL}, register
the version string with @command{gawk}.
@end enumerate
+
+@node Changes from API V1
+@subsection Changes From Version 1 of the API
+
+The current API is @emph{not} binary compatible with version 1 of the API.
+You will have to recompile your extensions in order to use them with
+the current version of @command{gawk}.
+
+Fortunately, at the possible expense of some compile-time warnings, the API remains
+source-code--compatible with the previous API. The major differences are
+the additional members in the @code{awk_ext_func_t} structure, and the
+addition of the third argument to the C implementation function.
+
@node Finding Extensions
@section How @command{gawk} Finds Extensions
@cindex extension search path
@@ -34948,17 +34991,12 @@ The second is a pointer to an @code{awk_value_t} structure, usually named
/* do_chdir --- provide dynamically loaded chdir() function for gawk */
static awk_value_t *
-do_chdir(int nargs, awk_value_t *result)
+do_chdir(int nargs, awk_value_t *result, struct awk_ext_func *unused)
@{
awk_value_t newdir;
int ret = -1;
assert(result != NULL);
-
- if (do_lint && nargs != 1)
- lintwarn(ext_id,
- _("chdir: called with incorrect number of arguments, "
- "expecting 1"));
@end example
The @code{newdir}
@@ -34967,8 +35005,8 @@ with @code{get_argument()}. Note that the first argument is
numbered zero.
If the argument is retrieved successfully, the function calls the
-@code{chdir()} system call. If the @code{chdir()} fails, @code{ERRNO}
-is updated:
+@code{chdir()} system call. Otherwise, if the @code{chdir()} fails,
+it updates @code{ERRNO}:
@example
if (get_argument(0, AWK_STRING, & newdir)) @{
@@ -35172,15 +35210,11 @@ is set to point to @code{stat()}, instead.
Here is the @code{do_stat()} function, which starts with
variable declarations and argument checking:
-@ignore
-Changed message for page breaking. Used to be:
- "stat: called with incorrect number of arguments (%d), should be 2",
-@end ignore
@example
/* do_stat --- provide a stat() function for gawk */
static awk_value_t *
-do_stat(int nargs, awk_value_t *result)
+do_stat(int nargs, awk_value_t *result, struct awk_ext_func *unused)
@{
awk_value_t file_param, array_param;
char *name;
@@ -35191,13 +35225,6 @@ do_stat(int nargs, awk_value_t *result)
int (*statfunc)(const char *path, struct stat *sbuf) = lstat;
assert(result != NULL);
-
- if (nargs != 2 && nargs != 3) @{
- if (do_lint)
- lintwarn(ext_id,
- _("stat: called with wrong number of arguments"));
- return make_number(-1, result);
- @}
@end example
Then comes the actual work. First, the function gets the arguments.
@@ -35265,11 +35292,9 @@ structures for loading each function into @command{gawk}:
@example
static awk_ext_func_t func_table[] = @{
- @{ "chdir", do_chdir, 1 @},
- @{ "stat", do_stat, 2 @},
-#ifndef __MINGW32__
- @{ "fts", do_fts, 3 @},
-#endif
+ @{ "chdir", do_chdir, 1, 1, awk_false, NULL @},
+ @{ "stat", do_stat, 3, 2, awk_false, NULL @},
+ @dots{}
@};
@end example
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index 987c541d..ca571514 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -928,6 +928,7 @@ particular records in a file and perform operations upon them.
* Extension API Informational Variables:: Variables providing information about
@command{gawk}'s invocation.
* Extension API Boilerplate:: Boilerplate code for using the API.
+* Changes from API V1:: Changes from V1 of the API.
* Finding Extensions:: How @command{gawk} finds compiled
extensions.
* Extension Example:: Example C code for an extension.
@@ -31337,6 +31338,7 @@ This (rather large) @value{SECTION} describes the API in detail.
redirections.
* Extension API Variables:: Variables provided by the API.
* Extension API Boilerplate:: Boilerplate code for using the API.
+* Changes from API V1:: Changes from V1 of the API.
@end menu
@node Extension API Functions Introduction
@@ -31837,11 +31839,15 @@ or an underscore, which may be followed by any number of
letters, digits, and underscores.
Letter case in function names is significant.
-@item awk_value_t *(*const function)(int num_actual_args, awk_value_t *result, struct awk_ext_func *finfo);
+@item awk_value_t *(*const function)(int num_actual_args,
+@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_value_t *result,
+@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ struct awk_ext_func *finfo);
This is a pointer to the C function that provides the extension's
functionality.
The function must fill in @code{*result} with either a number
-or a string. @command{gawk} takes ownership of any string memory.
+or a string.
+@c FIXME: Change to a scalar - number, string or regex once regex api stuff is merged.
+@command{gawk} takes ownership of any string memory.
As mentioned earlier, string memory @emph{must} come from one of
@code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()}.
@@ -31876,9 +31882,9 @@ to @code{awk_true}.
@item void *data;
This is an opaque pointer to any data that an extension function may
-wish to have available when called. Passing the @code{awk_ext_funct_t}
+wish to have available when called. Passing the @code{awk_ext_func_t}
structure to the extension function, and having this pointer available
-in it enables writing a single C or C++ function that implements multiple
+in it enable writing a single C or C++ function that implements multiple
@command{awk}-level extension functions.
@end table
@@ -31886,11 +31892,42 @@ Once you have a record representing your extension function, you register
it with @command{gawk} using this API function:
@table @code
-@item awk_bool_t add_ext_func(const char *namespace, const awk_ext_func_t *func);
+@item awk_bool_t add_ext_func(const char *namespace, awk_ext_func_t *func);
This function returns true upon success, false otherwise.
The @code{namespace} parameter is currently not used; you should pass in an
empty string (@code{""}). The @code{func} pointer is the address of a
@code{struct} representing your function, as just described.
+
+@command{gawk} does not modify what @code{func} points to, but the
+extension function itself receives this pointer and can modify what it
+points to, thus it is purposely not declared to be @code{const}.
+@end table
+
+The combination of @code{min_required_args}, @code{max_expected_args},
+and @code{suppress_lint} may be confusing. Here is how you should
+set things up.
+
+@table @asis
+@item Any number of arguments is valid
+Set @code{min_required_args} and @code{max_expected_args} to zero and
+set @code{suppress_lint} to @code{awk_true}.
+
+@item A minimum number of arguments is required, no limit on maximum number of arguments
+Set @code{min_required_args} to the minimum required. Set
+@code{max_expected_args} to zero and
+set @code{suppress_lint} to @code{awk_true}.
+
+@item A minium number of arguments is required, a maximum number is expected
+Set @code{min_required_args} to the minimum required. Set
+@code{max_expected_args} to the maximum expected.
+Set @code{suppress_lint} to @code{awk_false}.
+
+@item A minum number of arguments is required, and no more than a maximum is allowed
+Set @code{min_required_args} to the minimum required. Set
+@code{max_expected_args} to the maximum expected.
+Set @code{suppress_lint} to @code{awk_false}.
+In your extension function, check that @code{num_actual_args} does not
+exceed @code{f->max_expected_args}. If it does, issue a fatal error message.
@end table
@node Exit Callback Functions
@@ -32631,13 +32668,6 @@ An extension can look up the value of @command{gawk}'s special variables.
However, with the exception of the @code{PROCINFO} array, an extension
cannot change any of those variables.
-@quotation CAUTION
-It is possible for the lookup of @code{PROCINFO} to fail. This happens if
-the @command{awk} program being run does not reference @code{PROCINFO};
-in this case, @command{gawk} doesn't bother to create the array and
-populate it.
-@end quotation
-
@node Symbol table by cookie
@subsubsection Variable Access and Update by Cookie
@@ -33523,10 +33553,10 @@ debugging:
@float Table,gawk-api-version
@caption{gawk API version constants}
-@multitable @columnfractions .33 .33 .33
+@multitable {@b{API Version}} {@code{gawk_api_major_version}} {@code{GAWK_API_MAJOR_VERSION}}
@headitem API Version @tab C preprocessor define @tab enum constant
-@item Major @tab gawk_api_major_version @tab GAWK_API_MAJOR_VERSION
-@item Minor @tab gawk_api_minor_version @tab GAWK_API_MINOR_VERSION
+@item Major @tab @code{gawk_api_major_version} @tab @code{GAWK_API_MAJOR_VERSION}
+@item Minor @tab @code{gawk_api_minor_version} @tab @code{GAWK_API_MINOR_VERSION}
@end multitable
@end float
@@ -33545,10 +33575,10 @@ constant integers:
@table @code
@item api->major_version
-The major version of the running @command{gawk}
+The major version of the running @command{gawk}.
@item api->minor_version
-The minor version of the running @command{gawk}
+The minor version of the running @command{gawk}.
@end table
It is up to the extension to decide if there are API incompatibilities.
@@ -33621,7 +33651,7 @@ static awk_ext_id_t ext_id;
static const char *ext_version = NULL; /* or @dots{} = "some string" */
static awk_ext_func_t func_table[] = @{
- @{ "name", do_name, 1 @},
+ @{ "name", do_name, 1, 0, awk_false, NULL @},
/* @dots{} */
@};
@@ -33722,6 +33752,19 @@ If @code{ext_version} is not @code{NULL}, register
the version string with @command{gawk}.
@end enumerate
+
+@node Changes from API V1
+@subsection Changes From Version 1 of the API
+
+The current API is @emph{not} binary compatible with version 1 of the API.
+You will have to recompile your extensions in order to use them with
+the current version of @command{gawk}.
+
+Fortunately, at the possible expense of some compile-time warnings, the API remains
+source-code--compatible with the previous API. The major differences are
+the additional members in the @code{awk_ext_func_t} structure, and the
+addition of the third argument to the C implementation function.
+
@node Finding Extensions
@section How @command{gawk} Finds Extensions
@cindex extension search path
@@ -33962,17 +34005,12 @@ The second is a pointer to an @code{awk_value_t} structure, usually named
/* do_chdir --- provide dynamically loaded chdir() function for gawk */
static awk_value_t *
-do_chdir(int nargs, awk_value_t *result)
+do_chdir(int nargs, awk_value_t *result, struct awk_ext_func *unused)
@{
awk_value_t newdir;
int ret = -1;
assert(result != NULL);
-
- if (do_lint && nargs != 1)
- lintwarn(ext_id,
- _("chdir: called with incorrect number of arguments, "
- "expecting 1"));
@end example
The @code{newdir}
@@ -33981,8 +34019,8 @@ with @code{get_argument()}. Note that the first argument is
numbered zero.
If the argument is retrieved successfully, the function calls the
-@code{chdir()} system call. If the @code{chdir()} fails, @code{ERRNO}
-is updated:
+@code{chdir()} system call. Otherwise, if the @code{chdir()} fails,
+it updates @code{ERRNO}:
@example
if (get_argument(0, AWK_STRING, & newdir)) @{
@@ -34186,15 +34224,11 @@ is set to point to @code{stat()}, instead.
Here is the @code{do_stat()} function, which starts with
variable declarations and argument checking:
-@ignore
-Changed message for page breaking. Used to be:
- "stat: called with incorrect number of arguments (%d), should be 2",
-@end ignore
@example
/* do_stat --- provide a stat() function for gawk */
static awk_value_t *
-do_stat(int nargs, awk_value_t *result)
+do_stat(int nargs, awk_value_t *result, struct awk_ext_func *unused)
@{
awk_value_t file_param, array_param;
char *name;
@@ -34205,13 +34239,6 @@ do_stat(int nargs, awk_value_t *result)
int (*statfunc)(const char *path, struct stat *sbuf) = lstat;
assert(result != NULL);
-
- if (nargs != 2 && nargs != 3) @{
- if (do_lint)
- lintwarn(ext_id,
- _("stat: called with wrong number of arguments"));
- return make_number(-1, result);
- @}
@end example
Then comes the actual work. First, the function gets the arguments.
@@ -34279,11 +34306,9 @@ structures for loading each function into @command{gawk}:
@example
static awk_ext_func_t func_table[] = @{
- @{ "chdir", do_chdir, 1 @},
- @{ "stat", do_stat, 2 @},
-#ifndef __MINGW32__
- @{ "fts", do_fts, 3 @},
-#endif
+ @{ "chdir", do_chdir, 1, 1, awk_false, NULL @},
+ @{ "stat", do_stat, 3, 2, awk_false, NULL @},
+ @dots{}
@};
@end example
diff --git a/gawkapi.h b/gawkapi.h
index 337fef8a..aae3ac0a 100644
--- a/gawkapi.h
+++ b/gawkapi.h
@@ -428,7 +428,12 @@ typedef struct gawk_api {
/* Next, registration functions: */
- /* Add a function to the interpreter, returns true upon success */
+ /*
+ * Add a function to the interpreter, returns true upon success.
+ * Gawk does not modify what func points to, but the extension
+ * function itself receives this pointer and can modify what it
+ * points to, thus it's not const.
+ */
awk_bool_t (*api_add_ext_func)(awk_ext_id_t id, const char *namespace,
awk_ext_func_t *func);
diff --git a/interpret.h b/interpret.h
index 7a8db88d..1399e720 100644
--- a/interpret.h
+++ b/interpret.h
@@ -965,7 +965,7 @@ arrayfor:
fatal(_("%s: called with %lu arguments, expecting at least %lu"),
pc[1].func_name, arg_count, min_req);
- if (do_lint && max_expect > 0 && arg_count > max_expect && ! f->suppress_lint)
+ if (do_lint && ! f->suppress_lint && arg_count > max_expect)
lintwarn(_("%s: called with %lu arguments, expecting no more than %lu"),
pc[1].func_name, arg_count, max_expect);