From b4343b17479151d438d32530cdd2541262e3088e Mon Sep 17 00:00:00 2001 From: "Andrew J. Schorr" Date: Sat, 8 Mar 2014 14:41:00 -0500 Subject: Add memory allocation functions to gawk API. --- ChangeLog | 10 + doc/ChangeLog | 5 + doc/gawk.info | 1224 +++++++++++++++++++++++++------------------------ doc/gawk.texi | 105 +++-- doc/gawktexi.in | 105 +++-- extension/ChangeLog | 11 + extension/filefuncs.c | 6 +- extension/inplace.c | 6 +- extension/readdir.c | 4 +- extension/readfile.c | 2 +- extension/revtwoway.c | 4 +- extension/rwarray.c | 6 +- extension/testext.c | 4 +- gawkapi.c | 6 + gawkapi.h | 24 +- 15 files changed, 828 insertions(+), 694 deletions(-) diff --git a/ChangeLog b/ChangeLog index 887d026c..31d1d616 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,13 @@ +2014-03-08 Andrew J. Schorr + + * gawkapi.c (api_impl): Add memory allocation function pointers. + * gawkapi.h (GAWK_API_MINOR_VERSION): Bump. + (gawk_api_t): Add memory allocation function pointers api_malloc, + api_calloc, api_realloc, and api_free. + (gawk_malloc, gawk_calloc, gawk_realloc, gawk_free): New macros. + (emalloc): Replace malloc with gawk_malloc. + (erealloc): Replace erealloc with gawk_erealloc. + 2014-03-05 Arnold D. Robbins Straighten out enumerated types some more. diff --git a/doc/ChangeLog b/doc/ChangeLog index cf61ad19..085ba317 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,8 @@ +2014-03-08 Andrew J. Schorr + + * gawktexi.in: Document new extension API functions api_malloc, + api_calloc, api_realloc, and api_free. + 2014-03-07 Arnold D. Robbins * gawktexi.in: Indexing improvements. diff --git a/doc/gawk.info b/doc/gawk.info index 6fb7ee3e..799d1c11 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -522,6 +522,7 @@ texts being (a) (see below), and with the Back-Cover Texts being (b) * Extension API Functions Introduction:: Introduction to the API functions. * General Data Types:: The data types. * Requesting Values:: How to get a value. +* Memory Allocation Functions:: Functions for allocating memory. * Constructor Functions:: Functions for creating values. * Registration Functions:: Functions to register things with `gawk'. @@ -21733,6 +21734,7 @@ This (rather large) minor node describes the API in detail. * Extension API Functions Introduction:: Introduction to the API functions. * General Data Types:: The data types. * Requesting Values:: How to get a value. +* Memory Allocation Functions:: Functions for allocating memory. * Constructor Functions:: Functions for creating values. * Registration Functions:: Functions to register things with `gawk'. @@ -21809,10 +21811,8 @@ operations: `EOF' `' `FILE' `' `NULL' `' - `malloc()' `' `memcpy()' `' `memset()' `' - `realloc()' `' `size_t' `' `struct stat' `' @@ -21838,7 +21838,9 @@ operations: * All pointers filled in by `gawk' are 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 `malloc()' and is managed by `gawk' from then on. + from calling the api-provided function pointers `api_malloc()', + `api_calloc()' or `api_realloc()' and is managed by `gawk' from + then on. * The API defines several simple `struct's that map values as seen from `awk'. A value can be a `double', a string, or an array (as @@ -21910,7 +21912,9 @@ that use them. `} awk_string_t;' This represents a mutable string. `gawk' owns the memory pointed to if it supplied the value. Otherwise, it takes ownership of the - memory pointed to. *Such memory must come from `malloc()'!* + memory pointed to. *Such memory must come from calling the + api-provided function pointers `api_malloc()', `api_calloc()', or + `api_realloc()'!* As mentioned earlier, strings are maintained using the current multibyte encoding. @@ -22015,7 +22019,7 @@ the value. See also the entry for "Cookie" in the *note Glossary::.  -File: gawk.info, Node: Requesting Values, Next: Constructor Functions, Prev: General Data Types, Up: Extension API Description +File: gawk.info, Node: Requesting Values, Next: Memory Allocation Functions, Prev: General Data Types, Up: Extension API Description 16.4.3 Requesting Values ------------------------ @@ -22048,46 +22052,37 @@ Requested: Scalar Scalar Scalar false false Table 16.1: Value Types Returned  -File: gawk.info, Node: Constructor Functions, Next: Registration Functions, Prev: Requesting Values, Up: Extension API Description +File: gawk.info, Node: Memory Allocation Functions, Next: Constructor Functions, Prev: Requesting Values, Up: Extension API Description -16.4.4 Constructor Functions and Convenience Macros ---------------------------------------------------- +16.4.4 Memory Allocation Functions and Convenience Macros +--------------------------------------------------------- -The API provides a number of "constructor" functions for creating -string and numeric values, as well as a number of convenience macros. -This node presents them all as function prototypes, in the way that -extension code would use them. +The API provides a number of "memory allocation" functions for +allocating memory that can be passed to gawk, as well as a number of +convenience macros. -`static inline awk_value_t *' -`make_const_string(const char *string, size_t length, awk_value_t *result)' - This function creates a string value in the `awk_value_t' variable - pointed to by `result'. It expects `string' to be a C string - constant (or other string data), and automatically creates a - _copy_ of the data for storage in `result'. It returns `result'. +`void *gawk_malloc(size_t size);' + Call `gawk'-provided `api_malloc()' to allocate storage that may + be passed to `gawk'. -`static inline awk_value_t *' -`make_malloced_string(const char *string, size_t length, awk_value_t *result)' - This function creates a string value in the `awk_value_t' variable - pointed to by `result'. It expects `string' to be a `char *' value - pointing to data previously obtained from `malloc()'. The idea here - is that the data is passed directly to `gawk', which assumes - responsibility for it. It returns `result'. +`void *gawk_calloc(size_t nmemb, size_t size);' + Call `gawk'-provided `api_calloc()' to allocate storage that may + be passed to `gawk'. -`static inline awk_value_t *' -`make_null_string(awk_value_t *result)' - This specialized function creates a null string (the "undefined" - value) in the `awk_value_t' variable pointed to by `result'. It - returns `result'. +`void *gawk_realloc(void *ptr, size_t size);' + Call `gawk'-provided `api_realloc()' to allocate storage that may + be passed to `gawk'. -`static inline awk_value_t *' -`make_number(double num, awk_value_t *result)' - This function simply creates a numeric value in the `awk_value_t' - variable pointed to by `result'. +`void gawk_free(void *ptr);' + Call `gawk'-provided `api_free()' to release storage that was + allocated with `gawk_malloc()', `gawk_calloc()' or + `gawk_realloc()'. - Two convenience macros may be used for allocating storage from -`malloc()' and `realloc()'. If the allocation fails, they cause `gawk' -to exit with a fatal error message. They should be used as if they were -procedure calls that do not return a value. + Two convenience macros may be used for allocating storage from the +api-provided function pointers `api_malloc()' and `api_realloc()'. If +the allocation fails, they cause `gawk' to exit with a fatal error +message. They should be used as if they were procedure calls that do +not return a value. `#define emalloc(pointer, type, size, message) ...' The arguments to this macro are as follows: @@ -22096,7 +22091,7 @@ procedure calls that do not return a value. `type' The type of the pointer variable, used to create a cast for - the call to `malloc()'. + the call to `api_malloc()'. `size' The total number of bytes to be allocated. @@ -22116,14 +22111,52 @@ procedure calls that do not return a value. make_malloced_string(message, strlen(message), & result); `#define erealloc(pointer, type, size, message) ...' - This is like `emalloc()', but it calls `realloc()', instead of - `malloc()'. The arguments are the same as for the `emalloc()' + This is like `emalloc()', but it calls `api_realloc()', instead of + `api_malloc()'. The arguments are the same as for the `emalloc()' macro. + +File: gawk.info, Node: Constructor Functions, Next: Registration Functions, Prev: Memory Allocation Functions, Up: Extension API Description + +16.4.5 Constructor Functions +---------------------------- + +The API provides a number of "constructor" functions for creating +string and numeric values, as well as a number of convenience macros. +This node presents them all as function prototypes, in the way that +extension code would use them. + +`static inline awk_value_t *' +`make_const_string(const char *string, size_t length, awk_value_t *result)' + This function creates a string value in the `awk_value_t' variable + pointed to by `result'. It expects `string' to be a C string + constant (or other string data), and automatically creates a + _copy_ of the data for storage in `result'. It returns `result'. + +`static inline awk_value_t *' +`make_malloced_string(const char *string, size_t length, awk_value_t *result)' + This function creates a string value in the `awk_value_t' variable + pointed to by `result'. It expects `string' to be a `char *' value + pointing to data previously obtained from the api-provided + functions `api_malloc()', `api_calloc()' or `api_realloc()'. The + idea here is that the data is passed directly to `gawk', which + assumes responsibility for it. It returns `result'. + +`static inline awk_value_t *' +`make_null_string(awk_value_t *result)' + This specialized function creates a null string (the "undefined" + value) in the `awk_value_t' variable pointed to by `result'. It + returns `result'. + +`static inline awk_value_t *' +`make_number(double num, awk_value_t *result)' + This function simply creates a numeric value in the `awk_value_t' + variable pointed to by `result'. +  File: gawk.info, Node: Registration Functions, Next: Printing Messages, Prev: Constructor Functions, Up: Extension API Description -16.4.5 Registration Functions +16.4.6 Registration Functions ----------------------------- This minor node describes the API functions for registering parts of @@ -22141,7 +22174,7 @@ your extension with `gawk'.  File: gawk.info, Node: Extension Functions, Next: Exit Callback Functions, Up: Registration Functions -16.4.5.1 Registering An Extension Function +16.4.6.1 Registering An Extension Function .......................................... Extension functions are described by the following record: @@ -22167,7 +22200,9 @@ Extension functions are described by the following record: This is a pointer to the C function that provides the desired functionality. The function must fill in the result with either a number or a string. `gawk' takes ownership of any string memory. - As mentioned earlier, string memory *must* come from `malloc()'. + As mentioned earlier, string memory *must* come from the + api-provided functions `api_malloc()', `api_calloc()' or + `api_realloc()'. The `num_actual_args' argument tells the C function how many actual parameters were passed from the calling `awk' code. @@ -22193,7 +22228,7 @@ register it with `gawk' using this API function:  File: gawk.info, Node: Exit Callback Functions, Next: Extension Version String, Prev: Extension Functions, Up: Registration Functions -16.4.5.2 Registering An Exit Callback Function +16.4.6.2 Registering An Exit Callback Function .............................................. An "exit callback" function is a function that `gawk' calls before it @@ -22222,7 +22257,7 @@ order--that is, in the reverse order in which they are registered with  File: gawk.info, Node: Extension Version String, Next: Input Parsers, Prev: Exit Callback Functions, Up: Registration Functions -16.4.5.3 Registering An Extension Version String +16.4.6.3 Registering An Extension Version String ................................................ You can register a version string which indicates the name and version @@ -22238,7 +22273,7 @@ invoked with the `--version' option.  File: gawk.info, Node: Input Parsers, Next: Output Wrappers, Prev: Extension Version String, Up: Registration Functions -16.4.5.4 Customized Input Parsers +16.4.6.4 Customized Input Parsers ................................. By default, `gawk' reads text files as its input. It uses the value of @@ -22460,7 +22495,7 @@ whether or not to activate an input parser (*note BEGINFILE/ENDFILE::).  File: gawk.info, Node: Output Wrappers, Next: Two-way processors, Prev: Input Parsers, Up: Registration Functions -16.4.5.5 Customized Output Wrappers +16.4.6.5 Customized Output Wrappers ................................... An "output wrapper" is the mirror image of an input parser. It allows @@ -22567,7 +22602,7 @@ normally.  File: gawk.info, Node: Two-way processors, Prev: Output Wrappers, Up: Registration Functions -16.4.5.6 Customized Two-way Processors +16.4.6.6 Customized Two-way Processors ...................................... A "two-way processor" combines an input parser and an output wrapper for @@ -22620,7 +22655,7 @@ can take this" and "take over for this" functions,  File: gawk.info, Node: Printing Messages, Next: Updating `ERRNO', Prev: Registration Functions, Up: Extension API Description -16.4.6 Printing Messages +16.4.7 Printing Messages ------------------------ You can print different kinds of warning messages from your extension, @@ -22651,7 +22686,7 @@ the pity.  File: gawk.info, Node: Updating `ERRNO', Next: Accessing Parameters, Prev: Printing Messages, Up: Extension API Description -16.4.7 Updating `ERRNO' +16.4.8 Updating `ERRNO' ----------------------- The following functions allow you to update the `ERRNO' variable: @@ -22672,7 +22707,7 @@ The following functions allow you to update the `ERRNO' variable:  File: gawk.info, Node: Accessing Parameters, Next: Symbol Table Access, Prev: Updating `ERRNO', Up: Extension API Description -16.4.8 Accessing and Updating Parameters +16.4.9 Accessing and Updating Parameters ---------------------------------------- Two functions give you access to the arguments (parameters) passed to @@ -22698,8 +22733,8 @@ your extension function. They are:  File: gawk.info, Node: Symbol Table Access, Next: Array Manipulation, Prev: Accessing Parameters, Up: Extension API Description -16.4.9 Symbol Table Access --------------------------- +16.4.10 Symbol Table Access +--------------------------- Two sets of routines provide access to global variables, and one set allows you to create and release cached values. @@ -22713,8 +22748,8 @@ allows you to create and release cached values.  File: gawk.info, Node: Symbol table by name, Next: Symbol table by cookie, Up: Symbol Table Access -16.4.9.1 Variable Access and Update by Name -........................................... +16.4.10.1 Variable Access and Update by Name +............................................ The following routines provide the ability to access and update global `awk'-level variables by name. In compiler terminology, identifiers of @@ -22749,8 +22784,8 @@ cannot change any of those variables.  File: gawk.info, Node: Symbol table by cookie, Next: Cached values, Prev: Symbol table by name, Up: Symbol Table Access -16.4.9.2 Variable Access and Update by Cookie -............................................. +16.4.10.2 Variable Access and Update by Cookie +.............................................. A "scalar cookie" is an opaque handle that provides access to a global variable or array. It is an optimization that avoids looking up @@ -22862,8 +22897,8 @@ like this:  File: gawk.info, Node: Cached values, Prev: Symbol table by cookie, Up: Symbol Table Access -16.4.9.3 Creating and Using Cached Values -......................................... +16.4.10.3 Creating and Using Cached Values +.......................................... The routines in this section allow you to create and release cached values. As with scalar cookies, in theory, cached values are not @@ -22873,8 +22908,9 @@ variables using `sym_update()' or `sym_update_scalar()', as you like. However, you can understand the point of cached values if you remember that _every_ string value's storage _must_ come from -`malloc()'. If you have 20 variables, all of which have the same -string value, you must create 20 identical copies of the string.(1) +`api_malloc()', `api_calloc()' or `api_realloc()'. If you have 20 +variables, all of which have the same string value, you must create 20 +identical copies of the string.(1) It is clearly more efficient, if possible, to create a value once, and then tell `gawk' to reuse the value for multiple variables. That is @@ -22957,7 +22993,7 @@ using `release_value()'.  File: gawk.info, Node: Array Manipulation, Next: Extension API Variables, Prev: Symbol Table Access, Up: Extension API Description -16.4.10 Array Manipulation +16.4.11 Array Manipulation -------------------------- The primary data structure(1) in `awk' is the associative array (*note @@ -22984,7 +23020,7 @@ arrays of arrays (*note General Data Types::).  File: gawk.info, Node: Array Data Types, Next: Array Functions, Up: Array Manipulation -16.4.10.1 Array Data Types +16.4.11.1 Array Data Types .......................... The data types associated with arrays are listed below. @@ -23051,7 +23087,7 @@ overuse this term.  File: gawk.info, Node: Array Functions, Next: Flattening Arrays, Prev: Array Data Types, Up: Array Manipulation -16.4.10.2 Array Functions +16.4.11.2 Array Functions ......................... The following functions relate to individual array elements. @@ -23077,7 +23113,8 @@ The following functions relate to individual array elements. strings (*note Conversion::); thus using integral values is safest. As with _all_ strings passed into `gawk' from an extension, the - string value of `index' must come from `malloc()', and `gawk' + string value of `index' must come from the api-provided functions + `api_malloc()', `api_calloc()' or `api_realloc()' and `gawk' releases the storage. `awk_bool_t set_array_element(awk_array_t a_cookie,' @@ -23128,7 +23165,7 @@ The following functions relate to individual array elements.  File: gawk.info, Node: Flattening Arrays, Next: Creating Arrays, Prev: Array Functions, Up: Array Manipulation -16.4.10.3 Working With All The Elements of an Array +16.4.11.3 Working With All The Elements of an Array ................................................... To "flatten" an array is create a structure that represents the full @@ -23302,7 +23339,7 @@ return value to success, and returns:  File: gawk.info, Node: Creating Arrays, Prev: Flattening Arrays, Up: Array Manipulation -16.4.10.4 How To Create and Populate Arrays +16.4.11.4 How To Create and Populate Arrays ........................................... Besides working with arrays created by `awk' code, you can create @@ -23441,7 +23478,7 @@ environment variable.)  File: gawk.info, Node: Extension API Variables, Next: Extension API Boilerplate, Prev: Array Manipulation, Up: Extension API Description -16.4.11 API Variables +16.4.12 API Variables --------------------- The API provides two sets of variables. The first provides information @@ -23458,7 +23495,7 @@ information about how `gawk' was invoked.  File: gawk.info, Node: Extension Versioning, Next: Extension API Informational Variables, Up: Extension API Variables -16.4.11.1 API Version Constants and Variables +16.4.12.1 API Version Constants and Variables ............................................. The API provides both a "major" and a "minor" version number. The API @@ -23507,7 +23544,7 @@ Boilerplate::).  File: gawk.info, Node: Extension API Informational Variables, Prev: Extension Versioning, Up: Extension API Variables -16.4.11.2 Informational Variables +16.4.12.2 Informational Variables ................................. The API provides access to several variables that describe whether the @@ -23543,7 +23580,7 @@ change during execution.  File: gawk.info, Node: Extension API Boilerplate, Prev: Extension API Variables, Up: Extension API Description -16.4.12 Boilerplate Code +16.4.13 Boilerplate Code ------------------------ As mentioned earlier (*note Extension Mechanism Outline::), the function @@ -32792,526 +32829,527 @@ Index  Tag Table: Node: Top1366 -Node: Foreword40856 -Node: Preface45201 -Ref: Preface-Footnote-148254 -Ref: Preface-Footnote-248350 -Node: History48582 -Node: Names50956 -Ref: Names-Footnote-152433 -Node: This Manual52505 -Ref: This Manual-Footnote-158279 -Node: Conventions58379 -Node: Manual History60535 -Ref: Manual History-Footnote-163983 -Ref: Manual History-Footnote-264024 -Node: How To Contribute64098 -Node: Acknowledgments65242 -Node: Getting Started69436 -Node: Running gawk71815 -Node: One-shot73001 -Node: Read Terminal74226 -Ref: Read Terminal-Footnote-175876 -Ref: Read Terminal-Footnote-276152 -Node: Long76323 -Node: Executable Scripts77699 -Ref: Executable Scripts-Footnote-179532 -Ref: Executable Scripts-Footnote-279634 -Node: Comments80181 -Node: Quoting82648 -Node: DOS Quoting87271 -Node: Sample Data Files87946 -Node: Very Simple90332 -Node: Two Rules94931 -Node: More Complex97078 -Ref: More Complex-Footnote-1100008 -Node: Statements/Lines100093 -Ref: Statements/Lines-Footnote-1104555 -Node: Other Features104820 -Node: When105748 -Node: Invoking Gawk107895 -Node: Command Line109358 -Node: Options110141 -Ref: Options-Footnote-1125536 -Node: Other Arguments125561 -Node: Naming Standard Input128219 -Node: Environment Variables129313 -Node: AWKPATH Variable129871 -Ref: AWKPATH Variable-Footnote-1132629 -Node: AWKLIBPATH Variable132889 -Node: Other Environment Variables133607 -Node: Exit Status136570 -Node: Include Files137245 -Node: Loading Shared Libraries140814 -Node: Obsolete142178 -Node: Undocumented142875 -Node: Regexp143117 -Node: Regexp Usage144506 -Node: Escape Sequences146532 -Node: Regexp Operators152201 -Ref: Regexp Operators-Footnote-1159581 -Ref: Regexp Operators-Footnote-2159728 -Node: Bracket Expressions159826 -Ref: table-char-classes161716 -Node: GNU Regexp Operators164239 -Node: Case-sensitivity167962 -Ref: Case-sensitivity-Footnote-1170930 -Ref: Case-sensitivity-Footnote-2171165 -Node: Leftmost Longest171273 -Node: Computed Regexps172474 -Node: Reading Files175811 -Node: Records177813 -Ref: Records-Footnote-1186901 -Node: Fields186938 -Ref: Fields-Footnote-1189971 -Node: Nonconstant Fields190057 -Node: Changing Fields192259 -Node: Field Separators198218 -Node: Default Field Splitting200920 -Node: Regexp Field Splitting202037 -Node: Single Character Fields205379 -Node: Command Line Field Separator206438 -Node: Full Line Fields209872 -Ref: Full Line Fields-Footnote-1210380 -Node: Field Splitting Summary210426 -Ref: Field Splitting Summary-Footnote-1213525 -Node: Constant Size213626 -Node: Splitting By Content218233 -Ref: Splitting By Content-Footnote-1221982 -Node: Multiple Line222022 -Ref: Multiple Line-Footnote-1227869 -Node: Getline228048 -Node: Plain Getline230264 -Node: Getline/Variable232359 -Node: Getline/File233506 -Node: Getline/Variable/File234847 -Ref: Getline/Variable/File-Footnote-1236446 -Node: Getline/Pipe236533 -Node: Getline/Variable/Pipe239232 -Node: Getline/Coprocess240339 -Node: Getline/Variable/Coprocess241591 -Node: Getline Notes242328 -Node: Getline Summary245115 -Ref: table-getline-variants245523 -Node: Read Timeout246435 -Ref: Read Timeout-Footnote-1250176 -Node: Command line directories250233 -Node: Printing250863 -Node: Print252494 -Node: Print Examples253831 -Node: Output Separators256615 -Node: OFMT258375 -Node: Printf259733 -Node: Basic Printf260639 -Node: Control Letters262178 -Node: Format Modifiers265990 -Node: Printf Examples271999 -Node: Redirection274714 -Node: Special Files281679 -Node: Special FD282212 -Ref: Special FD-Footnote-1285837 -Node: Special Network285911 -Node: Special Caveats286761 -Node: Close Files And Pipes287557 -Ref: Close Files And Pipes-Footnote-1294540 -Ref: Close Files And Pipes-Footnote-2294688 -Node: Expressions294838 -Node: Values295970 -Node: Constants296646 -Node: Scalar Constants297326 -Ref: Scalar Constants-Footnote-1298185 -Node: Nondecimal-numbers298367 -Node: Regexp Constants301367 -Node: Using Constant Regexps301842 -Node: Variables304897 -Node: Using Variables305552 -Node: Assignment Options307276 -Node: Conversion309148 -Ref: table-locale-affects314648 -Ref: Conversion-Footnote-1315272 -Node: All Operators315381 -Node: Arithmetic Ops316011 -Node: Concatenation318516 -Ref: Concatenation-Footnote-1321308 -Node: Assignment Ops321428 -Ref: table-assign-ops326416 -Node: Increment Ops327747 -Node: Truth Values and Conditions331181 -Node: Truth Values332264 -Node: Typing and Comparison333313 -Node: Variable Typing334106 -Ref: Variable Typing-Footnote-1338003 -Node: Comparison Operators338125 -Ref: table-relational-ops338535 -Node: POSIX String Comparison342083 -Ref: POSIX String Comparison-Footnote-1343039 -Node: Boolean Ops343177 -Ref: Boolean Ops-Footnote-1347255 -Node: Conditional Exp347346 -Node: Function Calls349078 -Node: Precedence352672 -Node: Locales356341 -Node: Patterns and Actions357430 -Node: Pattern Overview358484 -Node: Regexp Patterns360153 -Node: Expression Patterns360696 -Node: Ranges364381 -Node: BEGIN/END367485 -Node: Using BEGIN/END368247 -Ref: Using BEGIN/END-Footnote-1370978 -Node: I/O And BEGIN/END371084 -Node: BEGINFILE/ENDFILE373366 -Node: Empty376280 -Node: Using Shell Variables376596 -Node: Action Overview378881 -Node: Statements381238 -Node: If Statement383092 -Node: While Statement384591 -Node: Do Statement386635 -Node: For Statement387791 -Node: Switch Statement390943 -Node: Break Statement393097 -Node: Continue Statement395087 -Node: Next Statement396880 -Node: Nextfile Statement399270 -Node: Exit Statement401925 -Node: Built-in Variables404341 -Node: User-modified405436 -Ref: User-modified-Footnote-1413794 -Node: Auto-set413856 -Ref: Auto-set-Footnote-1426934 -Ref: Auto-set-Footnote-2427139 -Node: ARGC and ARGV427195 -Node: Arrays431046 -Node: Array Basics432551 -Node: Array Intro433377 -Node: Reference to Elements437694 -Node: Assigning Elements439964 -Node: Array Example440455 -Node: Scanning an Array442187 -Node: Controlling Scanning444501 -Ref: Controlling Scanning-Footnote-1449588 -Node: Delete449904 -Ref: Delete-Footnote-1452669 -Node: Numeric Array Subscripts452726 -Node: Uninitialized Subscripts454909 -Node: Multidimensional456536 -Node: Multiscanning459629 -Node: Arrays of Arrays461218 -Node: Functions465858 -Node: Built-in466677 -Node: Calling Built-in467755 -Node: Numeric Functions469743 -Ref: Numeric Functions-Footnote-1473575 -Ref: Numeric Functions-Footnote-2473932 -Ref: Numeric Functions-Footnote-3473980 -Node: String Functions474249 -Ref: String Functions-Footnote-1497169 -Ref: String Functions-Footnote-2497298 -Ref: String Functions-Footnote-3497546 -Node: Gory Details497633 -Ref: table-sub-escapes499312 -Ref: table-sub-posix-92500666 -Ref: table-sub-proposed502017 -Ref: table-posix-sub503371 -Ref: table-gensub-escapes504916 -Ref: Gory Details-Footnote-1506092 -Ref: Gory Details-Footnote-2506143 -Node: I/O Functions506294 -Ref: I/O Functions-Footnote-1513284 -Node: Time Functions513431 -Ref: Time Functions-Footnote-1524364 -Ref: Time Functions-Footnote-2524432 -Ref: Time Functions-Footnote-3524590 -Ref: Time Functions-Footnote-4524701 -Ref: Time Functions-Footnote-5524813 -Ref: Time Functions-Footnote-6525040 -Node: Bitwise Functions525306 -Ref: table-bitwise-ops525868 -Ref: Bitwise Functions-Footnote-1530089 -Node: Type Functions530273 -Node: I18N Functions531424 -Node: User-defined533051 -Node: Definition Syntax533855 -Ref: Definition Syntax-Footnote-1538769 -Node: Function Example538838 -Ref: Function Example-Footnote-1541487 -Node: Function Caveats541509 -Node: Calling A Function542027 -Node: Variable Scope542982 -Node: Pass By Value/Reference545945 -Node: Return Statement549453 -Node: Dynamic Typing552434 -Node: Indirect Calls553365 -Node: Library Functions563052 -Ref: Library Functions-Footnote-1566565 -Ref: Library Functions-Footnote-2566708 -Node: Library Names566879 -Ref: Library Names-Footnote-1570352 -Ref: Library Names-Footnote-2570572 -Node: General Functions570658 -Node: Strtonum Function571686 -Node: Assert Function574616 -Node: Round Function577942 -Node: Cliff Random Function579483 -Node: Ordinal Functions580499 -Ref: Ordinal Functions-Footnote-1583576 -Ref: Ordinal Functions-Footnote-2583828 -Node: Join Function584039 -Ref: Join Function-Footnote-1585810 -Node: Getlocaltime Function586010 -Node: Readfile Function589751 -Node: Data File Management591590 -Node: Filetrans Function592222 -Node: Rewind Function596291 -Node: File Checking597678 -Node: Empty Files598772 -Node: Ignoring Assigns601002 -Node: Getopt Function602556 -Ref: Getopt Function-Footnote-1613859 -Node: Passwd Functions614062 -Ref: Passwd Functions-Footnote-1623040 -Node: Group Functions623128 -Node: Walking Arrays631212 -Node: Sample Programs633348 -Node: Running Examples634022 -Node: Clones634750 -Node: Cut Program635974 -Node: Egrep Program645825 -Ref: Egrep Program-Footnote-1653598 -Node: Id Program653708 -Node: Split Program657324 -Ref: Split Program-Footnote-1660843 -Node: Tee Program660971 -Node: Uniq Program663774 -Node: Wc Program671203 -Ref: Wc Program-Footnote-1675469 -Ref: Wc Program-Footnote-2675669 -Node: Miscellaneous Programs675761 -Node: Dupword Program676949 -Node: Alarm Program678980 -Node: Translate Program683787 -Ref: Translate Program-Footnote-1688174 -Ref: Translate Program-Footnote-2688422 -Node: Labels Program688556 -Ref: Labels Program-Footnote-1691927 -Node: Word Sorting692011 -Node: History Sorting695895 -Node: Extract Program697734 -Ref: Extract Program-Footnote-1705237 -Node: Simple Sed705365 -Node: Igawk Program708427 -Ref: Igawk Program-Footnote-1723584 -Ref: Igawk Program-Footnote-2723785 -Node: Anagram Program723923 -Node: Signature Program726991 -Node: Advanced Features728091 -Node: Nondecimal Data729977 -Node: Array Sorting731560 -Node: Controlling Array Traversal732257 -Node: Array Sorting Functions740541 -Ref: Array Sorting Functions-Footnote-1744410 -Node: Two-way I/O744604 -Ref: Two-way I/O-Footnote-1750036 -Node: TCP/IP Networking750118 -Node: Profiling752962 -Node: Internationalization760465 -Node: I18N and L10N761890 -Node: Explaining gettext762576 -Ref: Explaining gettext-Footnote-1767644 -Ref: Explaining gettext-Footnote-2767828 -Node: Programmer i18n767993 -Node: Translator i18n772195 -Node: String Extraction772989 -Ref: String Extraction-Footnote-1773950 -Node: Printf Ordering774036 -Ref: Printf Ordering-Footnote-1776818 -Node: I18N Portability776882 -Ref: I18N Portability-Footnote-1779331 -Node: I18N Example779394 -Ref: I18N Example-Footnote-1782032 -Node: Gawk I18N782104 -Node: Debugger782725 -Node: Debugging783696 -Node: Debugging Concepts784129 -Node: Debugging Terms785985 -Node: Awk Debugging788582 -Node: Sample Debugging Session789474 -Node: Debugger Invocation789994 -Node: Finding The Bug791327 -Node: List of Debugger Commands797814 -Node: Breakpoint Control799148 -Node: Debugger Execution Control802812 -Node: Viewing And Changing Data806172 -Node: Execution Stack809528 -Node: Debugger Info810995 -Node: Miscellaneous Debugger Commands814977 -Node: Readline Support820153 -Node: Limitations820984 -Node: Arbitrary Precision Arithmetic823236 -Ref: Arbitrary Precision Arithmetic-Footnote-1824885 -Node: General Arithmetic825033 -Node: Floating Point Issues826753 -Node: String Conversion Precision827634 -Ref: String Conversion Precision-Footnote-1829339 -Node: Unexpected Results829448 -Node: POSIX Floating Point Problems831601 -Ref: POSIX Floating Point Problems-Footnote-1835426 -Node: Integer Programming835464 -Node: Floating-point Programming837203 -Ref: Floating-point Programming-Footnote-1843534 -Ref: Floating-point Programming-Footnote-2843804 -Node: Floating-point Representation844068 -Node: Floating-point Context845233 -Ref: table-ieee-formats846072 -Node: Rounding Mode847456 -Ref: table-rounding-modes847935 -Ref: Rounding Mode-Footnote-1850950 -Node: Gawk and MPFR851129 -Node: Arbitrary Precision Floats852384 -Ref: Arbitrary Precision Floats-Footnote-1854827 -Node: Setting Precision855143 -Ref: table-predefined-precision-strings855829 -Node: Setting Rounding Mode857974 -Ref: table-gawk-rounding-modes858378 -Node: Floating-point Constants859565 -Node: Changing Precision860994 -Ref: Changing Precision-Footnote-1862391 -Node: Exact Arithmetic862565 -Node: Arbitrary Precision Integers865703 -Ref: Arbitrary Precision Integers-Footnote-1868718 -Node: Dynamic Extensions868865 -Node: Extension Intro870323 -Node: Plugin License871588 -Node: Extension Mechanism Outline872273 -Ref: load-extension872690 -Ref: load-new-function874168 -Ref: call-new-function875163 -Node: Extension API Description877178 -Node: Extension API Functions Introduction878391 -Node: General Data Types883257 -Ref: General Data Types-Footnote-1888859 -Node: Requesting Values889158 -Ref: table-value-types-returned889889 -Node: Constructor Functions890843 -Node: Registration Functions893863 -Node: Extension Functions894548 -Node: Exit Callback Functions896774 -Node: Extension Version String898023 -Node: Input Parsers898673 -Node: Output Wrappers908430 -Node: Two-way processors912940 -Node: Printing Messages915148 -Ref: Printing Messages-Footnote-1916225 -Node: Updating `ERRNO'916377 -Node: Accessing Parameters917116 -Node: Symbol Table Access918346 -Node: Symbol table by name918858 -Node: Symbol table by cookie920605 -Ref: Symbol table by cookie-Footnote-1924735 -Node: Cached values924798 -Ref: Cached values-Footnote-1928247 -Node: Array Manipulation928338 -Ref: Array Manipulation-Footnote-1929436 -Node: Array Data Types929475 -Ref: Array Data Types-Footnote-1932178 -Node: Array Functions932270 -Node: Flattening Arrays936036 -Node: Creating Arrays942888 -Node: Extension API Variables947613 -Node: Extension Versioning948249 -Node: Extension API Informational Variables950150 -Node: Extension API Boilerplate951236 -Node: Finding Extensions955040 -Node: Extension Example955600 -Node: Internal File Description956330 -Node: Internal File Ops960421 -Ref: Internal File Ops-Footnote-1971930 -Node: Using Internal File Ops972070 -Ref: Using Internal File Ops-Footnote-1974423 -Node: Extension Samples974689 -Node: Extension Sample File Functions976213 -Node: Extension Sample Fnmatch984698 -Node: Extension Sample Fork986467 -Node: Extension Sample Inplace987680 -Node: Extension Sample Ord989458 -Node: Extension Sample Readdir990294 -Node: Extension Sample Revout991826 -Node: Extension Sample Rev2way992419 -Node: Extension Sample Read write array993109 -Node: Extension Sample Readfile994992 -Node: Extension Sample API Tests995810 -Node: Extension Sample Time996335 -Node: gawkextlib997699 -Node: Language History1000480 -Node: V7/SVR3.11002073 -Node: SVR41004393 -Node: POSIX1005835 -Node: BTL1007221 -Node: POSIX/GNU1007955 -Node: Feature History1013554 -Node: Common Extensions1026530 -Node: Ranges and Locales1027842 -Ref: Ranges and Locales-Footnote-11032459 -Ref: Ranges and Locales-Footnote-21032486 -Ref: Ranges and Locales-Footnote-31032720 -Node: Contributors1032941 -Node: Installation1038086 -Node: Gawk Distribution1038980 -Node: Getting1039464 -Node: Extracting1040290 -Node: Distribution contents1041982 -Node: Unix Installation1047687 -Node: Quick Installation1048304 -Node: Additional Configuration Options1050750 -Node: Configuration Philosophy1052486 -Node: Non-Unix Installation1054840 -Node: PC Installation1055298 -Node: PC Binary Installation1056597 -Node: PC Compiling1058445 -Node: PC Testing1061389 -Node: PC Using1062565 -Node: Cygwin1066733 -Node: MSYS1067542 -Node: VMS Installation1068056 -Node: VMS Compilation1068820 -Ref: VMS Compilation-Footnote-11070072 -Node: VMS Dynamic Extensions1070130 -Node: VMS Installation Details1071503 -Node: VMS Running1073754 -Node: VMS GNV1076588 -Node: VMS Old Gawk1077311 -Node: Bugs1077781 -Node: Other Versions1081699 -Node: Notes1087783 -Node: Compatibility Mode1088583 -Node: Additions1089366 -Node: Accessing The Source1090293 -Node: Adding Code1091733 -Node: New Ports1097778 -Node: Derived Files1101913 -Ref: Derived Files-Footnote-11107234 -Ref: Derived Files-Footnote-21107268 -Ref: Derived Files-Footnote-31107868 -Node: Future Extensions1107966 -Node: Implementation Limitations1108549 -Node: Extension Design1109801 -Node: Old Extension Problems1110955 -Ref: Old Extension Problems-Footnote-11112463 -Node: Extension New Mechanism Goals1112520 -Ref: Extension New Mechanism Goals-Footnote-11115885 -Node: Extension Other Design Decisions1116071 -Node: Extension Future Growth1118177 -Node: Old Extension Mechanism1119013 -Node: Basic Concepts1120753 -Node: Basic High Level1121434 -Ref: figure-general-flow1121705 -Ref: figure-process-flow1122304 -Ref: Basic High Level-Footnote-11125533 -Node: Basic Data Typing1125718 -Node: Glossary1129073 -Node: Copying1154535 -Node: GNU Free Documentation License1192092 -Node: Index1217229 +Node: Foreword40929 +Node: Preface45274 +Ref: Preface-Footnote-148327 +Ref: Preface-Footnote-248423 +Node: History48655 +Node: Names51029 +Ref: Names-Footnote-152506 +Node: This Manual52578 +Ref: This Manual-Footnote-158352 +Node: Conventions58452 +Node: Manual History60608 +Ref: Manual History-Footnote-164056 +Ref: Manual History-Footnote-264097 +Node: How To Contribute64171 +Node: Acknowledgments65315 +Node: Getting Started69509 +Node: Running gawk71888 +Node: One-shot73074 +Node: Read Terminal74299 +Ref: Read Terminal-Footnote-175949 +Ref: Read Terminal-Footnote-276225 +Node: Long76396 +Node: Executable Scripts77772 +Ref: Executable Scripts-Footnote-179605 +Ref: Executable Scripts-Footnote-279707 +Node: Comments80254 +Node: Quoting82721 +Node: DOS Quoting87344 +Node: Sample Data Files88019 +Node: Very Simple90405 +Node: Two Rules95004 +Node: More Complex97151 +Ref: More Complex-Footnote-1100081 +Node: Statements/Lines100166 +Ref: Statements/Lines-Footnote-1104628 +Node: Other Features104893 +Node: When105821 +Node: Invoking Gawk107968 +Node: Command Line109431 +Node: Options110214 +Ref: Options-Footnote-1125609 +Node: Other Arguments125634 +Node: Naming Standard Input128292 +Node: Environment Variables129386 +Node: AWKPATH Variable129944 +Ref: AWKPATH Variable-Footnote-1132702 +Node: AWKLIBPATH Variable132962 +Node: Other Environment Variables133680 +Node: Exit Status136643 +Node: Include Files137318 +Node: Loading Shared Libraries140887 +Node: Obsolete142251 +Node: Undocumented142948 +Node: Regexp143190 +Node: Regexp Usage144579 +Node: Escape Sequences146605 +Node: Regexp Operators152274 +Ref: Regexp Operators-Footnote-1159654 +Ref: Regexp Operators-Footnote-2159801 +Node: Bracket Expressions159899 +Ref: table-char-classes161789 +Node: GNU Regexp Operators164312 +Node: Case-sensitivity168035 +Ref: Case-sensitivity-Footnote-1171003 +Ref: Case-sensitivity-Footnote-2171238 +Node: Leftmost Longest171346 +Node: Computed Regexps172547 +Node: Reading Files175884 +Node: Records177886 +Ref: Records-Footnote-1186974 +Node: Fields187011 +Ref: Fields-Footnote-1190044 +Node: Nonconstant Fields190130 +Node: Changing Fields192332 +Node: Field Separators198291 +Node: Default Field Splitting200993 +Node: Regexp Field Splitting202110 +Node: Single Character Fields205452 +Node: Command Line Field Separator206511 +Node: Full Line Fields209945 +Ref: Full Line Fields-Footnote-1210453 +Node: Field Splitting Summary210499 +Ref: Field Splitting Summary-Footnote-1213598 +Node: Constant Size213699 +Node: Splitting By Content218306 +Ref: Splitting By Content-Footnote-1222055 +Node: Multiple Line222095 +Ref: Multiple Line-Footnote-1227942 +Node: Getline228121 +Node: Plain Getline230337 +Node: Getline/Variable232432 +Node: Getline/File233579 +Node: Getline/Variable/File234920 +Ref: Getline/Variable/File-Footnote-1236519 +Node: Getline/Pipe236606 +Node: Getline/Variable/Pipe239305 +Node: Getline/Coprocess240412 +Node: Getline/Variable/Coprocess241664 +Node: Getline Notes242401 +Node: Getline Summary245188 +Ref: table-getline-variants245596 +Node: Read Timeout246508 +Ref: Read Timeout-Footnote-1250249 +Node: Command line directories250306 +Node: Printing250936 +Node: Print252567 +Node: Print Examples253904 +Node: Output Separators256688 +Node: OFMT258448 +Node: Printf259806 +Node: Basic Printf260712 +Node: Control Letters262251 +Node: Format Modifiers266063 +Node: Printf Examples272072 +Node: Redirection274787 +Node: Special Files281752 +Node: Special FD282285 +Ref: Special FD-Footnote-1285910 +Node: Special Network285984 +Node: Special Caveats286834 +Node: Close Files And Pipes287630 +Ref: Close Files And Pipes-Footnote-1294613 +Ref: Close Files And Pipes-Footnote-2294761 +Node: Expressions294911 +Node: Values296043 +Node: Constants296719 +Node: Scalar Constants297399 +Ref: Scalar Constants-Footnote-1298258 +Node: Nondecimal-numbers298440 +Node: Regexp Constants301440 +Node: Using Constant Regexps301915 +Node: Variables304970 +Node: Using Variables305625 +Node: Assignment Options307349 +Node: Conversion309221 +Ref: table-locale-affects314721 +Ref: Conversion-Footnote-1315345 +Node: All Operators315454 +Node: Arithmetic Ops316084 +Node: Concatenation318589 +Ref: Concatenation-Footnote-1321381 +Node: Assignment Ops321501 +Ref: table-assign-ops326489 +Node: Increment Ops327820 +Node: Truth Values and Conditions331254 +Node: Truth Values332337 +Node: Typing and Comparison333386 +Node: Variable Typing334179 +Ref: Variable Typing-Footnote-1338076 +Node: Comparison Operators338198 +Ref: table-relational-ops338608 +Node: POSIX String Comparison342156 +Ref: POSIX String Comparison-Footnote-1343112 +Node: Boolean Ops343250 +Ref: Boolean Ops-Footnote-1347328 +Node: Conditional Exp347419 +Node: Function Calls349151 +Node: Precedence352745 +Node: Locales356414 +Node: Patterns and Actions357503 +Node: Pattern Overview358557 +Node: Regexp Patterns360226 +Node: Expression Patterns360769 +Node: Ranges364454 +Node: BEGIN/END367558 +Node: Using BEGIN/END368320 +Ref: Using BEGIN/END-Footnote-1371051 +Node: I/O And BEGIN/END371157 +Node: BEGINFILE/ENDFILE373439 +Node: Empty376353 +Node: Using Shell Variables376669 +Node: Action Overview378954 +Node: Statements381311 +Node: If Statement383165 +Node: While Statement384664 +Node: Do Statement386708 +Node: For Statement387864 +Node: Switch Statement391016 +Node: Break Statement393170 +Node: Continue Statement395160 +Node: Next Statement396953 +Node: Nextfile Statement399343 +Node: Exit Statement401998 +Node: Built-in Variables404414 +Node: User-modified405509 +Ref: User-modified-Footnote-1413867 +Node: Auto-set413929 +Ref: Auto-set-Footnote-1427007 +Ref: Auto-set-Footnote-2427212 +Node: ARGC and ARGV427268 +Node: Arrays431119 +Node: Array Basics432624 +Node: Array Intro433450 +Node: Reference to Elements437767 +Node: Assigning Elements440037 +Node: Array Example440528 +Node: Scanning an Array442260 +Node: Controlling Scanning444574 +Ref: Controlling Scanning-Footnote-1449661 +Node: Delete449977 +Ref: Delete-Footnote-1452742 +Node: Numeric Array Subscripts452799 +Node: Uninitialized Subscripts454982 +Node: Multidimensional456609 +Node: Multiscanning459702 +Node: Arrays of Arrays461291 +Node: Functions465931 +Node: Built-in466750 +Node: Calling Built-in467828 +Node: Numeric Functions469816 +Ref: Numeric Functions-Footnote-1473648 +Ref: Numeric Functions-Footnote-2474005 +Ref: Numeric Functions-Footnote-3474053 +Node: String Functions474322 +Ref: String Functions-Footnote-1497242 +Ref: String Functions-Footnote-2497371 +Ref: String Functions-Footnote-3497619 +Node: Gory Details497706 +Ref: table-sub-escapes499385 +Ref: table-sub-posix-92500739 +Ref: table-sub-proposed502090 +Ref: table-posix-sub503444 +Ref: table-gensub-escapes504989 +Ref: Gory Details-Footnote-1506165 +Ref: Gory Details-Footnote-2506216 +Node: I/O Functions506367 +Ref: I/O Functions-Footnote-1513357 +Node: Time Functions513504 +Ref: Time Functions-Footnote-1524437 +Ref: Time Functions-Footnote-2524505 +Ref: Time Functions-Footnote-3524663 +Ref: Time Functions-Footnote-4524774 +Ref: Time Functions-Footnote-5524886 +Ref: Time Functions-Footnote-6525113 +Node: Bitwise Functions525379 +Ref: table-bitwise-ops525941 +Ref: Bitwise Functions-Footnote-1530162 +Node: Type Functions530346 +Node: I18N Functions531497 +Node: User-defined533124 +Node: Definition Syntax533928 +Ref: Definition Syntax-Footnote-1538842 +Node: Function Example538911 +Ref: Function Example-Footnote-1541560 +Node: Function Caveats541582 +Node: Calling A Function542100 +Node: Variable Scope543055 +Node: Pass By Value/Reference546018 +Node: Return Statement549526 +Node: Dynamic Typing552507 +Node: Indirect Calls553438 +Node: Library Functions563125 +Ref: Library Functions-Footnote-1566638 +Ref: Library Functions-Footnote-2566781 +Node: Library Names566952 +Ref: Library Names-Footnote-1570425 +Ref: Library Names-Footnote-2570645 +Node: General Functions570731 +Node: Strtonum Function571759 +Node: Assert Function574689 +Node: Round Function578015 +Node: Cliff Random Function579556 +Node: Ordinal Functions580572 +Ref: Ordinal Functions-Footnote-1583649 +Ref: Ordinal Functions-Footnote-2583901 +Node: Join Function584112 +Ref: Join Function-Footnote-1585883 +Node: Getlocaltime Function586083 +Node: Readfile Function589824 +Node: Data File Management591663 +Node: Filetrans Function592295 +Node: Rewind Function596364 +Node: File Checking597751 +Node: Empty Files598845 +Node: Ignoring Assigns601075 +Node: Getopt Function602629 +Ref: Getopt Function-Footnote-1613932 +Node: Passwd Functions614135 +Ref: Passwd Functions-Footnote-1623113 +Node: Group Functions623201 +Node: Walking Arrays631285 +Node: Sample Programs633421 +Node: Running Examples634095 +Node: Clones634823 +Node: Cut Program636047 +Node: Egrep Program645898 +Ref: Egrep Program-Footnote-1653671 +Node: Id Program653781 +Node: Split Program657397 +Ref: Split Program-Footnote-1660916 +Node: Tee Program661044 +Node: Uniq Program663847 +Node: Wc Program671276 +Ref: Wc Program-Footnote-1675542 +Ref: Wc Program-Footnote-2675742 +Node: Miscellaneous Programs675834 +Node: Dupword Program677022 +Node: Alarm Program679053 +Node: Translate Program683860 +Ref: Translate Program-Footnote-1688247 +Ref: Translate Program-Footnote-2688495 +Node: Labels Program688629 +Ref: Labels Program-Footnote-1692000 +Node: Word Sorting692084 +Node: History Sorting695968 +Node: Extract Program697807 +Ref: Extract Program-Footnote-1705310 +Node: Simple Sed705438 +Node: Igawk Program708500 +Ref: Igawk Program-Footnote-1723657 +Ref: Igawk Program-Footnote-2723858 +Node: Anagram Program723996 +Node: Signature Program727064 +Node: Advanced Features728164 +Node: Nondecimal Data730050 +Node: Array Sorting731633 +Node: Controlling Array Traversal732330 +Node: Array Sorting Functions740614 +Ref: Array Sorting Functions-Footnote-1744483 +Node: Two-way I/O744677 +Ref: Two-way I/O-Footnote-1750109 +Node: TCP/IP Networking750191 +Node: Profiling753035 +Node: Internationalization760538 +Node: I18N and L10N761963 +Node: Explaining gettext762649 +Ref: Explaining gettext-Footnote-1767717 +Ref: Explaining gettext-Footnote-2767901 +Node: Programmer i18n768066 +Node: Translator i18n772268 +Node: String Extraction773062 +Ref: String Extraction-Footnote-1774023 +Node: Printf Ordering774109 +Ref: Printf Ordering-Footnote-1776891 +Node: I18N Portability776955 +Ref: I18N Portability-Footnote-1779404 +Node: I18N Example779467 +Ref: I18N Example-Footnote-1782105 +Node: Gawk I18N782177 +Node: Debugger782798 +Node: Debugging783769 +Node: Debugging Concepts784202 +Node: Debugging Terms786058 +Node: Awk Debugging788655 +Node: Sample Debugging Session789547 +Node: Debugger Invocation790067 +Node: Finding The Bug791400 +Node: List of Debugger Commands797887 +Node: Breakpoint Control799221 +Node: Debugger Execution Control802885 +Node: Viewing And Changing Data806245 +Node: Execution Stack809601 +Node: Debugger Info811068 +Node: Miscellaneous Debugger Commands815050 +Node: Readline Support820226 +Node: Limitations821057 +Node: Arbitrary Precision Arithmetic823309 +Ref: Arbitrary Precision Arithmetic-Footnote-1824958 +Node: General Arithmetic825106 +Node: Floating Point Issues826826 +Node: String Conversion Precision827707 +Ref: String Conversion Precision-Footnote-1829412 +Node: Unexpected Results829521 +Node: POSIX Floating Point Problems831674 +Ref: POSIX Floating Point Problems-Footnote-1835499 +Node: Integer Programming835537 +Node: Floating-point Programming837276 +Ref: Floating-point Programming-Footnote-1843607 +Ref: Floating-point Programming-Footnote-2843877 +Node: Floating-point Representation844141 +Node: Floating-point Context845306 +Ref: table-ieee-formats846145 +Node: Rounding Mode847529 +Ref: table-rounding-modes848008 +Ref: Rounding Mode-Footnote-1851023 +Node: Gawk and MPFR851202 +Node: Arbitrary Precision Floats852457 +Ref: Arbitrary Precision Floats-Footnote-1854900 +Node: Setting Precision855216 +Ref: table-predefined-precision-strings855902 +Node: Setting Rounding Mode858047 +Ref: table-gawk-rounding-modes858451 +Node: Floating-point Constants859638 +Node: Changing Precision861067 +Ref: Changing Precision-Footnote-1862464 +Node: Exact Arithmetic862638 +Node: Arbitrary Precision Integers865776 +Ref: Arbitrary Precision Integers-Footnote-1868791 +Node: Dynamic Extensions868938 +Node: Extension Intro870396 +Node: Plugin License871661 +Node: Extension Mechanism Outline872346 +Ref: load-extension872763 +Ref: load-new-function874241 +Ref: call-new-function875236 +Node: Extension API Description877251 +Node: Extension API Functions Introduction878538 +Node: General Data Types883410 +Ref: General Data Types-Footnote-1889105 +Node: Requesting Values889404 +Ref: table-value-types-returned890141 +Node: Memory Allocation Functions891095 +Node: Constructor Functions893456 +Node: Registration Functions895214 +Node: Extension Functions895899 +Node: Exit Callback Functions898201 +Node: Extension Version String899450 +Node: Input Parsers900100 +Node: Output Wrappers909857 +Node: Two-way processors914367 +Node: Printing Messages916575 +Ref: Printing Messages-Footnote-1917652 +Node: Updating `ERRNO'917804 +Node: Accessing Parameters918543 +Node: Symbol Table Access919773 +Node: Symbol table by name920287 +Node: Symbol table by cookie922036 +Ref: Symbol table by cookie-Footnote-1926168 +Node: Cached values926231 +Ref: Cached values-Footnote-1929721 +Node: Array Manipulation929812 +Ref: Array Manipulation-Footnote-1930910 +Node: Array Data Types930949 +Ref: Array Data Types-Footnote-1933652 +Node: Array Functions933744 +Node: Flattening Arrays937580 +Node: Creating Arrays944432 +Node: Extension API Variables949157 +Node: Extension Versioning949793 +Node: Extension API Informational Variables951694 +Node: Extension API Boilerplate952780 +Node: Finding Extensions956584 +Node: Extension Example957144 +Node: Internal File Description957874 +Node: Internal File Ops961965 +Ref: Internal File Ops-Footnote-1973474 +Node: Using Internal File Ops973614 +Ref: Using Internal File Ops-Footnote-1975967 +Node: Extension Samples976233 +Node: Extension Sample File Functions977757 +Node: Extension Sample Fnmatch986242 +Node: Extension Sample Fork988011 +Node: Extension Sample Inplace989224 +Node: Extension Sample Ord991002 +Node: Extension Sample Readdir991838 +Node: Extension Sample Revout993370 +Node: Extension Sample Rev2way993963 +Node: Extension Sample Read write array994653 +Node: Extension Sample Readfile996536 +Node: Extension Sample API Tests997354 +Node: Extension Sample Time997879 +Node: gawkextlib999243 +Node: Language History1002024 +Node: V7/SVR3.11003617 +Node: SVR41005937 +Node: POSIX1007379 +Node: BTL1008765 +Node: POSIX/GNU1009499 +Node: Feature History1015098 +Node: Common Extensions1028074 +Node: Ranges and Locales1029386 +Ref: Ranges and Locales-Footnote-11034003 +Ref: Ranges and Locales-Footnote-21034030 +Ref: Ranges and Locales-Footnote-31034264 +Node: Contributors1034485 +Node: Installation1039630 +Node: Gawk Distribution1040524 +Node: Getting1041008 +Node: Extracting1041834 +Node: Distribution contents1043526 +Node: Unix Installation1049231 +Node: Quick Installation1049848 +Node: Additional Configuration Options1052294 +Node: Configuration Philosophy1054030 +Node: Non-Unix Installation1056384 +Node: PC Installation1056842 +Node: PC Binary Installation1058141 +Node: PC Compiling1059989 +Node: PC Testing1062933 +Node: PC Using1064109 +Node: Cygwin1068277 +Node: MSYS1069086 +Node: VMS Installation1069600 +Node: VMS Compilation1070364 +Ref: VMS Compilation-Footnote-11071616 +Node: VMS Dynamic Extensions1071674 +Node: VMS Installation Details1073047 +Node: VMS Running1075298 +Node: VMS GNV1078132 +Node: VMS Old Gawk1078855 +Node: Bugs1079325 +Node: Other Versions1083243 +Node: Notes1089327 +Node: Compatibility Mode1090127 +Node: Additions1090910 +Node: Accessing The Source1091837 +Node: Adding Code1093277 +Node: New Ports1099322 +Node: Derived Files1103457 +Ref: Derived Files-Footnote-11108778 +Ref: Derived Files-Footnote-21108812 +Ref: Derived Files-Footnote-31109412 +Node: Future Extensions1109510 +Node: Implementation Limitations1110093 +Node: Extension Design1111345 +Node: Old Extension Problems1112499 +Ref: Old Extension Problems-Footnote-11114007 +Node: Extension New Mechanism Goals1114064 +Ref: Extension New Mechanism Goals-Footnote-11117429 +Node: Extension Other Design Decisions1117615 +Node: Extension Future Growth1119721 +Node: Old Extension Mechanism1120557 +Node: Basic Concepts1122297 +Node: Basic High Level1122978 +Ref: figure-general-flow1123249 +Ref: figure-process-flow1123848 +Ref: Basic High Level-Footnote-11127077 +Node: Basic Data Typing1127262 +Node: Glossary1130617 +Node: Copying1156079 +Node: GNU Free Documentation License1193636 +Node: Index1218773  End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 713f5a46..f0c7d6e6 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -742,6 +742,7 @@ particular records in a file and perform operations upon them. * Extension API Functions Introduction:: Introduction to the API functions. * General Data Types:: The data types. * Requesting Values:: How to get a value. +* Memory Allocation Functions:: Functions for allocating memory. * Constructor Functions:: Functions for creating values. * Registration Functions:: Functions to register things with @command{gawk}. @@ -29575,6 +29576,7 @@ This (rather large) @value{SECTION} describes the API in detail. * Extension API Functions Introduction:: Introduction to the API functions. * General Data Types:: The data types. * Requesting Values:: How to get a value. +* Memory Allocation Functions:: Functions for allocating memory. * Constructor Functions:: Functions for creating values. * Registration Functions:: Functions to register things with @command{gawk}. @@ -29668,10 +29670,8 @@ corresponding standard header file @emph{before} including @file{gawkapi.h}: @item @code{EOF} @tab @code{} @item @code{FILE} @tab @code{} @item @code{NULL} @tab @code{} -@item @code{malloc()} @tab @code{} @item @code{memcpy()} @tab @code{} @item @code{memset()} @tab @code{} -@item @code{realloc()} @tab @code{} @item @code{size_t} @tab @code{} @item @code{struct stat} @tab @code{} @end multitable @@ -29701,7 +29701,7 @@ does not support this keyword, you should either place All pointers filled in by @command{gawk} are 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 @code{malloc()} and is managed +from the extension @emph{must} come from calling the api-provided function pointers @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()} and is managed by @command{gawk} from then on. @item @@ -29784,7 +29784,7 @@ A simple boolean type. This represents a mutable string. @command{gawk} owns the memory pointed to if it supplied the value. Otherwise, it takes ownership of the memory pointed to. -@strong{Such memory must come from @code{malloc()}!} +@strong{Such memory must come from calling the api-provided function pointers @code{api_malloc()}, @code{api_calloc()}, or @code{api_realloc()}!} As mentioned earlier, strings are maintained using the current multibyte encoding. @@ -29946,44 +29946,33 @@ value type, as appropriate. This behavior is summarized in @end float @end ifplaintext -@node Constructor Functions -@subsection Constructor Functions and Convenience Macros +@node Memory Allocation Functions +@subsection Memory Allocation Functions and Convenience Macros -The API provides a number of @dfn{constructor} functions for creating -string and numeric values, as well as a number of convenience macros. -This @value{SUBSECTION} presents them all as function prototypes, in -the way that extension code would use them. +The API provides a number of @dfn{memory allocation} functions for +allocating memory that can be passed to gawk, as well as a number of convenience macros. @table @code -@item static inline awk_value_t * -@itemx make_const_string(const char *string, size_t length, awk_value_t *result) -This function creates a string value in the @code{awk_value_t} variable -pointed to by @code{result}. It expects @code{string} to be a C string constant -(or other string data), and automatically creates a @emph{copy} of the data -for storage in @code{result}. It returns @code{result}. +@item void *gawk_malloc(size_t size); +Call @command{gawk}-provided @code{api_malloc()} to allocate storage that may +be passed to @command{gawk}. -@item static inline awk_value_t * -@itemx make_malloced_string(const char *string, size_t length, awk_value_t *result) -This function creates a string value in the @code{awk_value_t} variable -pointed to by @code{result}. It expects @code{string} to be a @samp{char *} -value pointing to data previously obtained from @code{malloc()}. The idea here -is that the data is passed directly to @command{gawk}, which assumes -responsibility for it. It returns @code{result}. +@item void *gawk_calloc(size_t nmemb, size_t size); +Call @command{gawk}-provided @code{api_calloc()} to allocate storage that may +be passed to @command{gawk}. -@item static inline awk_value_t * -@itemx make_null_string(awk_value_t *result) -This specialized function creates a null string (the ``undefined'' value) -in the @code{awk_value_t} variable pointed to by @code{result}. -It returns @code{result}. +@item void *gawk_realloc(void *ptr, size_t size); +Call @command{gawk}-provided @code{api_realloc()} to allocate storage that may +be passed to @command{gawk}. -@item static inline awk_value_t * -@itemx make_number(double num, awk_value_t *result) -This function simply creates a numeric value in the @code{awk_value_t} variable -pointed to by @code{result}. +@item void gawk_free(void *ptr); +Call @command{gawk}-provided @code{api_free()} to release storage that was +allocated with @code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}. @end table -Two convenience macros may be used for allocating storage from @code{malloc()} -and @code{realloc()}. If the allocation fails, they cause @command{gawk} to + +Two convenience macros may be used for allocating storage from the api-provided function pointers @code{api_malloc()} +and @code{api_realloc()}. If the allocation fails, they cause @command{gawk} to exit with a fatal error message. They should be used as if they were procedure calls that do not return a value. @@ -29996,7 +29985,7 @@ The arguments to this macro are as follows: The pointer variable to point at the allocated storage. @item type -The type of the pointer variable, used to create a cast for the call to @code{malloc()}. +The type of the pointer variable, used to create a cast for the call to @code{api_malloc()}. @item size The total number of bytes to be allocated. @@ -30020,11 +30009,47 @@ make_malloced_string(message, strlen(message), & result); @end example @item #define erealloc(pointer, type, size, message) @dots{} -This is like @code{emalloc()}, but it calls @code{realloc()}, -instead of @code{malloc()}. +This is like @code{emalloc()}, but it calls @code{api_realloc()}, +instead of @code{api_malloc()}. The arguments are the same as for the @code{emalloc()} macro. @end table +@node Constructor Functions +@subsection Constructor Functions + +The API provides a number of @dfn{constructor} functions for creating +string and numeric values, as well as a number of convenience macros. +This @value{SUBSECTION} presents them all as function prototypes, in +the way that extension code would use them. + +@table @code +@item static inline awk_value_t * +@itemx make_const_string(const char *string, size_t length, awk_value_t *result) +This function creates a string value in the @code{awk_value_t} variable +pointed to by @code{result}. It expects @code{string} to be a C string constant +(or other string data), and automatically creates a @emph{copy} of the data +for storage in @code{result}. It returns @code{result}. + +@item static inline awk_value_t * +@itemx make_malloced_string(const char *string, size_t length, awk_value_t *result) +This function creates a string value in the @code{awk_value_t} variable +pointed to by @code{result}. It expects @code{string} to be a @samp{char *} +value pointing to data previously obtained from the api-provided functions @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()}. The idea here +is that the data is passed directly to @command{gawk}, which assumes +responsibility for it. It returns @code{result}. + +@item static inline awk_value_t * +@itemx make_null_string(awk_value_t *result) +This specialized function creates a null string (the ``undefined'' value) +in the @code{awk_value_t} variable pointed to by @code{result}. +It returns @code{result}. + +@item static inline awk_value_t * +@itemx make_number(double num, awk_value_t *result) +This function simply creates a numeric value in the @code{awk_value_t} variable +pointed to by @code{result}. +@end table + @node Registration Functions @subsection Registration Functions @@ -30072,7 +30097,7 @@ This is a pointer to the C function that provides the desired functionality. The function must fill in the result with either a number or a string. @command{gawk} takes ownership of any string memory. -As mentioned earlier, string memory @strong{must} come from @code{malloc()}. +As mentioned earlier, string memory @strong{must} come from the api-provided functions @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()}. The @code{num_actual_args} argument tells the C function how many actual parameters were passed from the calling @command{awk} code. @@ -30810,7 +30835,7 @@ assign those values to variables using @code{sym_update()} or @code{sym_update_scalar()}, as you like. However, you can understand the point of cached values if you remember that -@emph{every} string value's storage @emph{must} come from @code{malloc()}. +@emph{every} string value's storage @emph{must} come from @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()}. If you have 20 variables, all of which have the same string value, you must create 20 identical copies of the string.@footnote{Numeric values are clearly less problematic, requiring only a C @code{double} to store.} @@ -31007,7 +31032,7 @@ requires that you understand how such values are converted to strings (@pxref{Conversion}); thus using integral values is safest. As with @emph{all} strings passed into @code{gawk} from an extension, -the string value of @code{index} must come from @code{malloc()}, and +the string value of @code{index} must come from the api-provided functions @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()} and @command{gawk} releases the storage. @item awk_bool_t set_array_element(awk_array_t a_cookie, diff --git a/doc/gawktexi.in b/doc/gawktexi.in index dd3d1409..3720a0dc 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -737,6 +737,7 @@ particular records in a file and perform operations upon them. * Extension API Functions Introduction:: Introduction to the API functions. * General Data Types:: The data types. * Requesting Values:: How to get a value. +* Memory Allocation Functions:: Functions for allocating memory. * Constructor Functions:: Functions for creating values. * Registration Functions:: Functions to register things with @command{gawk}. @@ -28716,6 +28717,7 @@ This (rather large) @value{SECTION} describes the API in detail. * Extension API Functions Introduction:: Introduction to the API functions. * General Data Types:: The data types. * Requesting Values:: How to get a value. +* Memory Allocation Functions:: Functions for allocating memory. * Constructor Functions:: Functions for creating values. * Registration Functions:: Functions to register things with @command{gawk}. @@ -28809,10 +28811,8 @@ corresponding standard header file @emph{before} including @file{gawkapi.h}: @item @code{EOF} @tab @code{} @item @code{FILE} @tab @code{} @item @code{NULL} @tab @code{} -@item @code{malloc()} @tab @code{} @item @code{memcpy()} @tab @code{} @item @code{memset()} @tab @code{} -@item @code{realloc()} @tab @code{} @item @code{size_t} @tab @code{} @item @code{struct stat} @tab @code{} @end multitable @@ -28842,7 +28842,7 @@ does not support this keyword, you should either place All pointers filled in by @command{gawk} are 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 @code{malloc()} and is managed +from the extension @emph{must} come from calling the api-provided function pointers @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()} and is managed by @command{gawk} from then on. @item @@ -28925,7 +28925,7 @@ A simple boolean type. This represents a mutable string. @command{gawk} owns the memory pointed to if it supplied the value. Otherwise, it takes ownership of the memory pointed to. -@strong{Such memory must come from @code{malloc()}!} +@strong{Such memory must come from calling the api-provided function pointers @code{api_malloc()}, @code{api_calloc()}, or @code{api_realloc()}!} As mentioned earlier, strings are maintained using the current multibyte encoding. @@ -29087,44 +29087,33 @@ value type, as appropriate. This behavior is summarized in @end float @end ifplaintext -@node Constructor Functions -@subsection Constructor Functions and Convenience Macros +@node Memory Allocation Functions +@subsection Memory Allocation Functions and Convenience Macros -The API provides a number of @dfn{constructor} functions for creating -string and numeric values, as well as a number of convenience macros. -This @value{SUBSECTION} presents them all as function prototypes, in -the way that extension code would use them. +The API provides a number of @dfn{memory allocation} functions for +allocating memory that can be passed to gawk, as well as a number of convenience macros. @table @code -@item static inline awk_value_t * -@itemx make_const_string(const char *string, size_t length, awk_value_t *result) -This function creates a string value in the @code{awk_value_t} variable -pointed to by @code{result}. It expects @code{string} to be a C string constant -(or other string data), and automatically creates a @emph{copy} of the data -for storage in @code{result}. It returns @code{result}. +@item void *gawk_malloc(size_t size); +Call @command{gawk}-provided @code{api_malloc()} to allocate storage that may +be passed to @command{gawk}. -@item static inline awk_value_t * -@itemx make_malloced_string(const char *string, size_t length, awk_value_t *result) -This function creates a string value in the @code{awk_value_t} variable -pointed to by @code{result}. It expects @code{string} to be a @samp{char *} -value pointing to data previously obtained from @code{malloc()}. The idea here -is that the data is passed directly to @command{gawk}, which assumes -responsibility for it. It returns @code{result}. +@item void *gawk_calloc(size_t nmemb, size_t size); +Call @command{gawk}-provided @code{api_calloc()} to allocate storage that may +be passed to @command{gawk}. -@item static inline awk_value_t * -@itemx make_null_string(awk_value_t *result) -This specialized function creates a null string (the ``undefined'' value) -in the @code{awk_value_t} variable pointed to by @code{result}. -It returns @code{result}. +@item void *gawk_realloc(void *ptr, size_t size); +Call @command{gawk}-provided @code{api_realloc()} to allocate storage that may +be passed to @command{gawk}. -@item static inline awk_value_t * -@itemx make_number(double num, awk_value_t *result) -This function simply creates a numeric value in the @code{awk_value_t} variable -pointed to by @code{result}. +@item void gawk_free(void *ptr); +Call @command{gawk}-provided @code{api_free()} to release storage that was +allocated with @code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}. @end table -Two convenience macros may be used for allocating storage from @code{malloc()} -and @code{realloc()}. If the allocation fails, they cause @command{gawk} to + +Two convenience macros may be used for allocating storage from the api-provided function pointers @code{api_malloc()} +and @code{api_realloc()}. If the allocation fails, they cause @command{gawk} to exit with a fatal error message. They should be used as if they were procedure calls that do not return a value. @@ -29137,7 +29126,7 @@ The arguments to this macro are as follows: The pointer variable to point at the allocated storage. @item type -The type of the pointer variable, used to create a cast for the call to @code{malloc()}. +The type of the pointer variable, used to create a cast for the call to @code{api_malloc()}. @item size The total number of bytes to be allocated. @@ -29161,11 +29150,47 @@ make_malloced_string(message, strlen(message), & result); @end example @item #define erealloc(pointer, type, size, message) @dots{} -This is like @code{emalloc()}, but it calls @code{realloc()}, -instead of @code{malloc()}. +This is like @code{emalloc()}, but it calls @code{api_realloc()}, +instead of @code{api_malloc()}. The arguments are the same as for the @code{emalloc()} macro. @end table +@node Constructor Functions +@subsection Constructor Functions + +The API provides a number of @dfn{constructor} functions for creating +string and numeric values, as well as a number of convenience macros. +This @value{SUBSECTION} presents them all as function prototypes, in +the way that extension code would use them. + +@table @code +@item static inline awk_value_t * +@itemx make_const_string(const char *string, size_t length, awk_value_t *result) +This function creates a string value in the @code{awk_value_t} variable +pointed to by @code{result}. It expects @code{string} to be a C string constant +(or other string data), and automatically creates a @emph{copy} of the data +for storage in @code{result}. It returns @code{result}. + +@item static inline awk_value_t * +@itemx make_malloced_string(const char *string, size_t length, awk_value_t *result) +This function creates a string value in the @code{awk_value_t} variable +pointed to by @code{result}. It expects @code{string} to be a @samp{char *} +value pointing to data previously obtained from the api-provided functions @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()}. The idea here +is that the data is passed directly to @command{gawk}, which assumes +responsibility for it. It returns @code{result}. + +@item static inline awk_value_t * +@itemx make_null_string(awk_value_t *result) +This specialized function creates a null string (the ``undefined'' value) +in the @code{awk_value_t} variable pointed to by @code{result}. +It returns @code{result}. + +@item static inline awk_value_t * +@itemx make_number(double num, awk_value_t *result) +This function simply creates a numeric value in the @code{awk_value_t} variable +pointed to by @code{result}. +@end table + @node Registration Functions @subsection Registration Functions @@ -29213,7 +29238,7 @@ This is a pointer to the C function that provides the desired functionality. The function must fill in the result with either a number or a string. @command{gawk} takes ownership of any string memory. -As mentioned earlier, string memory @strong{must} come from @code{malloc()}. +As mentioned earlier, string memory @strong{must} come from the api-provided functions @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()}. The @code{num_actual_args} argument tells the C function how many actual parameters were passed from the calling @command{awk} code. @@ -29951,7 +29976,7 @@ assign those values to variables using @code{sym_update()} or @code{sym_update_scalar()}, as you like. However, you can understand the point of cached values if you remember that -@emph{every} string value's storage @emph{must} come from @code{malloc()}. +@emph{every} string value's storage @emph{must} come from @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()}. If you have 20 variables, all of which have the same string value, you must create 20 identical copies of the string.@footnote{Numeric values are clearly less problematic, requiring only a C @code{double} to store.} @@ -30148,7 +30173,7 @@ requires that you understand how such values are converted to strings (@pxref{Conversion}); thus using integral values is safest. As with @emph{all} strings passed into @code{gawk} from an extension, -the string value of @code{index} must come from @code{malloc()}, and +the string value of @code{index} must come from the api-provided functions @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()} and @command{gawk} releases the storage. @item awk_bool_t set_array_element(awk_array_t a_cookie, diff --git a/extension/ChangeLog b/extension/ChangeLog index bde626de..4a1fe2ed 100644 --- a/extension/ChangeLog +++ b/extension/ChangeLog @@ -1,3 +1,14 @@ +2014-03-08 Andrew J. Schorr + + * filefuncs.c (read_symlink, do_fts): Replace free with gawk_free. + * inplace.c (at_exit, do_inplace_end): Ditto. + * readdir.c (dir_close): Ditto. + * readfile.c (do_readfile): Ditto. + * revtwoway.c (close_two_proc_data): Ditto. + * rwarray (read_elem): Replace realloc with gawk_realloc. + (read_value): Replace malloc and free with gawk_malloc and gawk_free. + * testext.c (try_modify_environ): Replace free with gawk_free. + 2014-02-12 John E. Malmberg * time.c: Better hack for nanosleep bug based on feedback from HP. diff --git a/extension/filefuncs.c b/extension/filefuncs.c index 3eb2a6b5..58acab4d 100644 --- a/extension/filefuncs.c +++ b/extension/filefuncs.c @@ -284,7 +284,7 @@ read_symlink(const char *fname, size_t bufsize, ssize_t *linksize) returns -1 with errno == ERANGE if the buffer is too small. */ if (errno != ERANGE) { - free(buf); + gawk_free(buf); return NULL; } } @@ -293,7 +293,7 @@ read_symlink(const char *fname, size_t bufsize, ssize_t *linksize) buf[*linksize] = '\0'; return buf; } - free(buf); + gawk_free(buf); if (bufsize <= MAXSIZE/2) bufsize *= 2; else if (bufsize < MAXSIZE) @@ -854,7 +854,7 @@ do_fts(int nargs, awk_value_t *result) out: if (pathvector != NULL) - free(pathvector); + gawk_free(pathvector); if (path_array != NULL) (void) release_flattened_array(pathlist.array_cookie, path_array); diff --git a/extension/inplace.c b/extension/inplace.c index 91b1a229..b6228a5b 100644 --- a/extension/inplace.c +++ b/extension/inplace.c @@ -96,7 +96,7 @@ at_exit(void *data, int exit_status) (void) exit_status; /* silence warnings */ if (state.tname) { unlink(state.tname); - free(state.tname); + gawk_free(state.tname); state.tname = NULL; } } @@ -242,7 +242,7 @@ do_inplace_end(int nargs, awk_value_t *result) if (link(filename.str_value.str, bakname) < 0) fatal(ext_id, _("inplace_end: link(`%s', `%s') failed (%s)"), filename.str_value.str, bakname, strerror(errno)); - free(bakname); + gawk_free(bakname); } #ifdef __MINGW32__ @@ -252,7 +252,7 @@ do_inplace_end(int nargs, awk_value_t *result) if (rename(state.tname, filename.str_value.str) < 0) fatal(ext_id, _("inplace_end: rename(`%s', `%s') failed (%s)"), state.tname, filename.str_value.str, strerror(errno)); - free(state.tname); + gawk_free(state.tname); state.tname = NULL; return make_number(0, result); } diff --git a/extension/readdir.c b/extension/readdir.c index 91296801..5b9a7913 100644 --- a/extension/readdir.c +++ b/extension/readdir.c @@ -235,8 +235,8 @@ dir_close(awk_input_buf_t *iobuf) the_dir = (open_directory_t *) iobuf->opaque; closedir(the_dir->dp); - free(the_dir->buf); - free(the_dir); + gawk_free(the_dir->buf); + gawk_free(the_dir); iobuf->fd = -1; } diff --git a/extension/readfile.c b/extension/readfile.c index 06889c3d..71d67ee6 100644 --- a/extension/readfile.c +++ b/extension/readfile.c @@ -107,7 +107,7 @@ do_readfile(int nargs, awk_value_t *result) if ((ret = read(fd, text, sbuf.st_size)) != sbuf.st_size) { (void) close(fd); update_ERRNO_int(errno); - free(text); + gawk_free(text); goto done; } diff --git a/extension/revtwoway.c b/extension/revtwoway.c index 5f490825..675e0efa 100644 --- a/extension/revtwoway.c +++ b/extension/revtwoway.c @@ -119,8 +119,8 @@ close_two_proc_data(two_way_proc_data_t *proc_data) return; } - free(proc_data->data); - free(proc_data); + gawk_free(proc_data->data); + gawk_free(proc_data); } /* diff --git a/extension/rwarray.c b/extension/rwarray.c index 6185000b..940acd62 100644 --- a/extension/rwarray.c +++ b/extension/rwarray.c @@ -408,7 +408,7 @@ read_elem(FILE *fp, awk_element_t *element) buflen = index_len; } else if (buflen < index_len) { /* reallocate buffer */ - char *cp = realloc(buffer, index_len); + char *cp = gawk_realloc(buffer, index_len); if (cp == NULL) return awk_false; @@ -468,11 +468,11 @@ read_value(FILE *fp, awk_value_t *value) len = ntohl(len); value->val_type = AWK_STRING; value->str_value.len = len; - value->str_value.str = malloc(len + 2); + value->str_value.str = gawk_malloc(len + 2); memset(value->str_value.str, '\0', len + 2); if (fread(value->str_value.str, 1, len, fp) != (ssize_t) len) { - free(value->str_value.str); + gawk_free(value->str_value.str); return awk_false; } } diff --git a/extension/testext.c b/extension/testext.c index d11272b8..22f2eb84 100644 --- a/extension/testext.c +++ b/extension/testext.c @@ -237,8 +237,8 @@ try_modify_environ(int nargs, awk_value_t *result) printf("try_modify_environ: set_array_element of ENVIRON passed\n"); } else { printf("try_modify_environ: set_array_element of ENVIRON failed\n"); - free(index.str_value.str); - free(value.str_value.str); + gawk_free(index.str_value.str); + gawk_free(value.str_value.str); } if (! flatten_array(environ_array, & flat_array)) { diff --git a/gawkapi.c b/gawkapi.c index fb456ce7..782cee48 100644 --- a/gawkapi.c +++ b/gawkapi.c @@ -1111,6 +1111,12 @@ gawk_api_t api_impl = { api_clear_array, api_flatten_array, api_release_flattened_array, + + /* Memory allocation */ + malloc, + calloc, + realloc, + free, }; /* init_ext_api --- init the extension API */ diff --git a/gawkapi.h b/gawkapi.h index b26ee24c..e84f2dea 100644 --- a/gawkapi.h +++ b/gawkapi.h @@ -30,7 +30,6 @@ * * FILE - * NULL - - * malloc() - * memset(), memcpy() - * size_t - * struct stat - @@ -62,7 +61,7 @@ * * Additional important information: * - * 1. ALL string values in awk_value_t objects need to come from malloc(). + * 1. ALL string values in awk_value_t objects need to come from api_malloc(). * Gawk will handle releasing the storage if necessary. This is slightly * awkward, in that you can't take an awk_value_t that you got from gawk * and reuse it directly, even for something that is conceptually pass @@ -264,7 +263,7 @@ typedef struct awk_two_way_processor { /* Current version of the API. */ enum { GAWK_API_MAJOR_VERSION = 1, - GAWK_API_MINOR_VERSION = 0 + GAWK_API_MINOR_VERSION = 1 }; /* A number of typedefs related to different types of values. */ @@ -665,6 +664,16 @@ typedef struct gawk_api { awk_bool_t (*api_release_flattened_array)(awk_ext_id_t id, awk_array_t a_cookie, awk_flat_array_t *data); + + /* + * Hooks to provide access to gawk's memory allocation functions. + * This ensures that memory passed between gawk and the extension + * is allocated and released by the same library. + */ + void *(*api_malloc)(size_t size); + void *(*api_calloc)(size_t nmemb, size_t size); + void *(*api_realloc)(void *ptr, size_t size); + void (*api_free)(void *ptr); } gawk_api_t; #ifndef GAWK /* these are not for the gawk code itself! */ @@ -736,6 +745,11 @@ typedef struct gawk_api { #define release_flattened_array(array, data) \ (api->api_release_flattened_array(ext_id, array, data)) +#define gawk_malloc(size) (api->api_malloc(size)) +#define gawk_calloc(nmemb, size) (api->api_calloc(nmemb, size)) +#define gawk_realloc(ptr, size) (api->api_realloc(ptr, size)) +#define gawk_free(ptr) (api->api_free(ptr)) + #define create_value(value, result) \ (api->api_create_value(ext_id, value,result)) @@ -747,13 +761,13 @@ typedef struct gawk_api { #define emalloc(pointer, type, size, message) \ do { \ - if ((pointer = (type) malloc(size)) == 0) \ + if ((pointer = (type) gawk_malloc(size)) == 0) \ fatal(ext_id, "%s: malloc of %d bytes failed\n", message, size); \ } while(0) #define erealloc(pointer, type, size, message) \ do { \ - if ((pointer = (type) realloc(pointer, size)) == 0) \ + if ((pointer = (type) gawk_realloc(pointer, size)) == 0) \ fatal(ext_id, "%s: realloc of %d bytes failed\n", message, size); \ } while(0) -- cgit v1.2.1