diff options
| -rw-r--r-- | ChangeLog | 5 | ||||
| -rw-r--r-- | doc/ChangeLog | 4 | ||||
| -rw-r--r-- | doc/gawk.info | 497 | ||||
| -rw-r--r-- | doc/gawk.texi | 391 | ||||
| -rw-r--r-- | doc/gawktexi.in | 391 | ||||
| -rw-r--r-- | extension/ChangeLog | 5 | ||||
| -rw-r--r-- | extension/filefuncs.c | 4 | ||||
| -rw-r--r-- | extension/testext.c | 6 | ||||
| -rw-r--r-- | gawkapi.h | 12 | ||||
| -rw-r--r-- | test/ChangeLog | 4 | ||||
| -rw-r--r-- | test/testext.ok | 1 |
11 files changed, 674 insertions, 646 deletions
@@ -1,3 +1,8 @@ +2014-09-29 Arnold D. Robbins <arnold@skeeve.com> + + * gawkapi.h: Minor edits to sync with documentation. Does not + influence the behavior of the API. + 2014-09-28 Arnold D. Robbins <arnold@skeeve.com> * command.y (cmdtab): Add "where" as an alias for "backtrace". diff --git a/doc/ChangeLog b/doc/ChangeLog index e7faba83..5004b645 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,7 @@ +2014-09-29 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: More fixes after reading through the MS. + 2014-09-28 Arnold D. Robbins <arnold@skeeve.com> * gawktexi.in: More fixes after reading through the MS. diff --git a/doc/gawk.info b/doc/gawk.info index a227afd6..eeca9a77 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -22722,9 +22722,8 @@ operations: * All pointers filled in by `gawk' point to memory managed by `gawk' and should be treated by the extension as read-only. Memory for _all_ strings passed into `gawk' from the extension _must_ come - from calling the API-provided function pointers `api_malloc()', - `api_calloc()' or `api_realloc()', and is managed by `gawk' from - then on. + from calling one of `gawk_malloc()', `gawk_calloc()' or + `gawk_realloc()', and is managed by `gawk' from then on. * The API defines several simple `struct's that map values as seen from `awk'. A value can be a `double', a string, or an array (as @@ -22796,9 +22795,8 @@ 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 calling the - API-provided function pointers `api_malloc()', `api_calloc()', or - `api_realloc()'!* + memory pointed to. *Such memory must come from calling one of the + `gawk_malloc()', `gawk_calloc()', or `gawk_realloc()' functions!* As mentioned earlier, strings are maintained using the current multibyte encoding. @@ -22903,62 +22901,30 @@ the value. See also the entry for "Cookie" in the *note Glossary::. -File: gawk.info, Node: Requesting Values, Next: Memory Allocation Functions, Prev: General Data Types, Up: Extension API Description - -16.4.3 Requesting Values ------------------------- - -All of the functions that return values from `gawk' work in the same -way. You pass in an `awk_valtype_t' value to indicate what kind of -value you expect. If the actual value matches what you requested, the -function returns true and fills in the `awk_value_t' result. -Otherwise, the function returns false, and the `val_type' member -indicates the type of the actual value. You may then print an error -message, or reissue the request for the actual value type, as -appropriate. This behavior is summarized in *note -table-value-types-returned::. - - Type of Actual Value: --------------------------------------------------------------------------- - - String Number Array Undefined ------------------------------------------------------------------------------- - String String String false false - Number Number if can Number false false - be converted, - else false -Type Array false false Array false -Requested: Scalar Scalar Scalar false false - Undefined String Number Array Undefined - Value false false false false - Cookie - -Table 16.1: API Value Types Returned - - File: gawk.info, Node: Memory Allocation Functions, Next: Constructor Functions, Prev: Requesting Values, Up: Extension API Description -16.4.4 Memory Allocation Functions and Convenience Macros +16.4.3 Memory Allocation Functions and Convenience Macros --------------------------------------------------------- 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. +convenience macros. This node presents them all as function +prototypes, in the way that extension code would use them. `void *gawk_malloc(size_t size);' - Call `gawk'-provided `api_malloc()' to allocate storage that may + Call the correct version of `malloc()' to allocate storage that may be passed to `gawk'. `void *gawk_calloc(size_t nmemb, size_t size);' - Call `gawk'-provided `api_calloc()' to allocate storage that may + Call the correct version of `calloc()' to allocate storage that may be passed to `gawk'. `void *gawk_realloc(void *ptr, size_t size);' - Call `gawk'-provided `api_realloc()' to allocate storage that may - be passed to `gawk'. + Call the correct version of `realloc()' to allocate storage that + may be passed to `gawk'. `void gawk_free(void *ptr);' - Call `gawk'-provided `api_free()' to release storage that was + Call the correct version of `free()' to release storage that was allocated with `gawk_malloc()', `gawk_calloc()' or `gawk_realloc()'. @@ -22968,11 +22934,10 @@ C library than was used for the `gawk' executable.(1) If `gawk' were to use its version of `free()' when the memory came from an unrelated version of `malloc()', unexpected behavior would likely result. - 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. + Two convenience macros may be used for allocating storage from +`gawk_malloc()' and `gawk_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: @@ -22982,7 +22947,7 @@ not return a value. `type' The type of the pointer variable, used to create a cast for - the call to `api_malloc()'. + the call to `gawk_malloc()'. `size' The total number of bytes to be allocated. @@ -23002,9 +22967,9 @@ not return a value. make_malloced_string(message, strlen(message), & result); `#define erealloc(pointer, type, size, message) ...' - This is like `emalloc()', but it calls `api_realloc()', instead of - `api_malloc()'. The arguments are the same as for the `emalloc()' - macro. + This is like `emalloc()', but it calls `gawk_realloc()', instead + of `gawk_malloc()'. The arguments are the same as for the + `emalloc()' macro. ---------- Footnotes ---------- @@ -23014,7 +22979,7 @@ Unix-like systems as well. File: gawk.info, Node: Constructor Functions, Next: Registration Functions, Prev: Memory Allocation Functions, Up: Extension API Description -16.4.5 Constructor Functions +16.4.4 Constructor Functions ---------------------------- The API provides a number of "constructor" functions for creating @@ -23033,10 +22998,10 @@ extension code would use them. `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'. + pointing to data previously obtained from `gawk_malloc()', + `gawk_calloc()' or `gawk_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)' @@ -23052,7 +23017,7 @@ extension code would use them. File: gawk.info, Node: Registration Functions, Next: Printing Messages, Prev: Constructor Functions, Up: Extension API Description -16.4.6 Registration Functions +16.4.5 Registration Functions ----------------------------- This minor node describes the API functions for registering parts of @@ -23070,7 +23035,7 @@ your extension with `gawk'. File: gawk.info, Node: Extension Functions, Next: Exit Callback Functions, Up: Registration Functions -16.4.6.1 Registering An Extension Function +16.4.5.1 Registering An Extension Function .......................................... Extension functions are described by the following record: @@ -23088,17 +23053,16 @@ Extension functions are described by the following record: by this name. This is a regular C string. Function names must obey the rules for `awk' identifiers. That is, - they must begin with either a letter or an underscore, which may - be followed by any number of letters, digits, and underscores. - Letter case in function names is significant. + they must begin with either an English letter or an underscore, + which may be followed by any number of letters, digits, and + underscores. Letter case in function names is significant. `awk_value_t *(*function)(int num_actual_args, awk_value_t *result);' - This is a pointer to the C function that provides the desired - functionality. The function must fill in the result with either a + 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. - As mentioned earlier, string memory *must* come from the - api-provided functions `api_malloc()', `api_calloc()' or - `api_realloc()'. + As mentioned earlier, string memory *must* come from one of + `gawk_malloc()', `gawk_calloc()' or `gawk_realloc()'. The `num_actual_args' argument tells the C function how many actual parameters were passed from the calling `awk' code. @@ -23109,7 +23073,7 @@ Extension functions are described by the following record: `size_t num_expected_args;' This is the number of arguments the function expects to receive. Each extension function may decide what to do if the number of - arguments isn't what it expected. Following `awk' functions, it + arguments isn't what it expected. As with real `awk' functions, it is likely OK to ignore extra arguments. Once you have a record representing your extension function, you @@ -23124,7 +23088,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.6.2 Registering An Exit Callback Function +16.4.5.2 Registering An Exit Callback Function .............................................. An "exit callback" function is a function that `gawk' calls before it @@ -23154,7 +23118,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.6.3 Registering An Extension Version String +16.4.5.3 Registering An Extension Version String ................................................ You can register a version string which indicates the name and version @@ -23170,7 +23134,7 @@ invoked with the `--version' option. File: gawk.info, Node: Input Parsers, Next: Output Wrappers, Prev: Extension Version String, Up: Registration Functions -16.4.6.4 Customized Input Parsers +16.4.5.4 Customized Input Parsers ................................. By default, `gawk' reads text files as its input. It uses the value of @@ -23339,7 +23303,7 @@ records. The parameters are as follows: `*rt_start' should be set to point to the data to be used for `RT', and `*rt_len' should be set to the length of the data. Otherwise, `*rt_len' should be set to zero. `gawk' makes its own - copy of this data, so the extension must manage the storage. + copy of this data, so the extension must manage this storage. The return value is the length of the buffer pointed to by `*out', or `EOF' if end-of-file was reached or an error occurred. @@ -23393,7 +23357,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.6.5 Customized Output Wrappers +16.4.5.5 Customized Output Wrappers ................................... An "output wrapper" is the mirror image of an input parser. It allows @@ -23500,7 +23464,7 @@ just use normally. File: gawk.info, Node: Two-way processors, Prev: Output Wrappers, Up: Registration Functions -16.4.6.6 Customized Two-way Processors +16.4.5.6 Customized Two-way Processors ...................................... A "two-way processor" combines an input parser and an output wrapper for @@ -23553,7 +23517,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.7 Printing Messages +16.4.6 Printing Messages ------------------------ You can print different kinds of warning messages from your extension, @@ -23584,7 +23548,7 @@ the pity. File: gawk.info, Node: Updating `ERRNO', Next: Accessing Parameters, Prev: Printing Messages, Up: Extension API Description -16.4.8 Updating `ERRNO' +16.4.7 Updating `ERRNO' ----------------------- The following functions allow you to update the `ERRNO' variable: @@ -23599,10 +23563,43 @@ The following functions allow you to update the `ERRNO' variable: Set `ERRNO' directly to the string value of `ERRNO'. `gawk' makes a copy of the value of `string'. -`void unset_ERRNO();' +`void unset_ERRNO(void);' Unset `ERRNO'. +File: gawk.info, Node: Requesting Values, Next: Memory Allocation Functions, Prev: General Data Types, Up: Extension API Description + +16.4.8 Requesting Values +------------------------ + +All of the functions that return values from `gawk' work in the same +way. You pass in an `awk_valtype_t' value to indicate what kind of +value you expect. If the actual value matches what you requested, the +function returns true and fills in the `awk_value_t' result. +Otherwise, the function returns false, and the `val_type' member +indicates the type of the actual value. You may then print an error +message, or reissue the request for the actual value type, as +appropriate. This behavior is summarized in *note +table-value-types-returned::. + + Type of Actual Value: +-------------------------------------------------------------------------- + + String Number Array Undefined +------------------------------------------------------------------------------ + String String String false false + Number Number if can Number false false + be converted, + else false +Type Array false false Array false +Requested: Scalar Scalar Scalar false false + Undefined String Number Array Undefined + Value false false false false + Cookie + +Table 16.1: API Value Types Returned + + File: gawk.info, Node: Accessing Parameters, Next: Symbol Table Access, Prev: Updating `ERRNO', Up: Extension API Description 16.4.9 Accessing and Updating Parameters @@ -23661,7 +23658,7 @@ termed a "symbol table". Fill in the `awk_value_t' structure pointed to by `result' with the value of the variable named by the string `name', which is a regular C string. `wanted' indicates the type of value expected. - Return true if the actual type matches `wanted', false otherwise + Return true if the actual type matches `wanted', false otherwise. In the latter case, `result->val_type' indicates the actual type (*note Table 16.1: table-value-types-returned.). @@ -23679,7 +23676,7 @@ termed a "symbol table". However, with the exception of the `PROCINFO' array, an extension cannot change any of those variables. - NOTE: It is possible for the lookup of `PROCINFO' to fail. This + 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. @@ -23701,7 +23698,7 @@ was discussed earlier, in *note General Data Types::. ` awk_valtype_t wanted,' ` awk_value_t *result);' Retrieve the current value of a scalar cookie. Once you have - obtained a scalar_cookie using `sym_lookup()', you can use this + obtained a scalar cookie using `sym_lookup()', you can use this function to get its value more efficiently. Return false if the value cannot be retrieved. @@ -23760,7 +23757,7 @@ usual. Then get a scalar cookie for the variable using `sym_lookup()': /* install initial value */ sym_update("MAGIC_VAR", make_number(42.0, & value)); - /* get cookie */ + /* get the cookie */ sym_lookup("MAGIC_VAR", AWK_SCALAR, & value); /* save the cookie */ @@ -23811,7 +23808,7 @@ 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 -`api_malloc()', `api_calloc()' or `api_realloc()'. If you have 20 +`gawk_malloc()', `gawk_calloc()' or `gawk_realloc()'. If you have 20 variables, all of which have the same string value, you must create 20 identical copies of the string.(1) @@ -23875,8 +23872,8 @@ Using value cookies in this way saves considerable storage, since all of `VAR1' through `VAR100' share the same value. You might be wondering, "Is this sharing problematic? What happens -if `awk' code assigns a new value to `VAR1', are all the others be -changed too?" +if `awk' code assigns a new value to `VAR1', are all the others changed +too?" That's a great question. The answer is that no, it's not a problem. Internally, `gawk' uses "reference-counted strings". This means that @@ -23942,7 +23939,7 @@ The data types associated with arrays are listed below. ` struct awk_element *next;' ` enum {' ` AWK_ELEMENT_DEFAULT = 0, /* set by gawk */' -` AWK_ELEMENT_DELETE = 1 /* set by extension if should be deleted */' +` AWK_ELEMENT_DELETE = 1 /* set by extension */' ` } flags;' ` awk_value_t index;' ` awk_value_t value;' @@ -23960,8 +23957,8 @@ The data types associated with arrays are listed below. the list. `enum { ... } flags;' - A set of flag values that convey information between `gawk' - and the extension. Currently there is only one: + A set of flag values that convey information between the + extension and `gawk'. Currently there is only one: `AWK_ELEMENT_DELETE'. Setting it causes `gawk' to delete the element from the original array upon release of the flattened array. @@ -23972,8 +23969,8 @@ The data types associated with arrays are listed below. memory pointed to by `index' and `value' belongs to `gawk'. `typedef struct awk_flat_array {' -` awk_const void *awk_const opaque1; /* private data for use by gawk */' -` awk_const void *awk_const opaque2; /* private data for use by gawk */' +` awk_const void *awk_const opaque1; /* for use by gawk */' +` awk_const void *awk_const opaque2; /* for use by gawk */' ` awk_const size_t count; /* how many elements */' ` awk_element_t elements[1]; /* will be extended */' `} awk_flat_array_t;' @@ -23997,7 +23994,7 @@ File: gawk.info, Node: Array Functions, Next: Flattening Arrays, Prev: Array The following functions relate to individual array elements. `awk_bool_t get_element_count(awk_array_t a_cookie, size_t *count);' - For the array represented by `a_cookie', return in `*count' the + For the array represented by `a_cookie', place in `*count' the number of elements it contains. A subarray counts as a single element. Return false if there is an error. @@ -24017,9 +24014,9 @@ 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 the API-provided functions - `api_malloc()', `api_calloc()' or `api_realloc()' and `gawk' - releases the storage. + string value of `index' must come from `gawk_malloc()', + `gawk_calloc()' or `gawk_realloc()', and `gawk' releases the + storage. `awk_bool_t set_array_element(awk_array_t a_cookie,' ` const awk_value_t *const index,' @@ -24041,7 +24038,7 @@ The following functions relate to individual array elements. The following functions relate to arrays as a whole: -`awk_array_t create_array();' +`awk_array_t create_array(void);' Create a new array to which elements may be added. *Note Creating Arrays::, for a discussion of how to create a new array and add elements to it. @@ -24077,7 +24074,8 @@ array in a fashion that makes it easy for C code to traverse the entire array. Test code in `extension/testext.c' does this, and also serves as a nice example showing how to use the APIs. - First, the `gawk' script that drives the test extension: + We walk through that part of the code one step at a time. First, +the `gawk' script that drives the test extension: @load "testext" BEGIN { @@ -24198,8 +24196,7 @@ flag bit set: valrep2str(& flat_array->elements[i].value)); if (strcmp(value3.str_value.str, - flat_array->elements[i].index.str_value.str) - == 0) { + flat_array->elements[i].index.str_value.str) == 0) { flat_array->elements[i].flags |= AWK_ELEMENT_DELETE; printf("dump_array_and_delete: marking element \"%s\" " "for deletion\n", @@ -24289,9 +24286,9 @@ code: The following C code is a simple test extension to create an array with two regular elements and with a subarray. The leading `#include' -directives and boilerplate variable declarations are omitted for -brevity. The first step is to create a new array and then install it -in the symbol table: +directives and boilerplate variable declarations (*note Extension API +Boilerplate::) are omitted for brevity. The first step is to create a +new array and then install it in the symbol table: /* create_new_array --- create a named array */ @@ -24513,12 +24510,12 @@ in the `gawkapi.h' header file: /* OR: */ static awk_bool_t - init_my_module(void) + init_my_extension(void) { ... } - static awk_bool_t (*init_func)(void) = init_my_module; + static awk_bool_t (*init_func)(void) = init_my_extension; dl_load_func(func_table, some_name, "name_space_in_quotes") @@ -24550,8 +24547,8 @@ in the `gawkapi.h' header file: `static awk_bool_t (*init_func)(void) = NULL;' ` OR' -`static awk_bool_t init_my_module(void) { ... }' -`static awk_bool_t (*init_func)(void) = init_my_module;' +`static awk_bool_t init_my_extension(void) { ... }' +`static awk_bool_t (*init_func)(void) = init_my_extension;' If you need to do some initialization work, you should define a function that does it (creates variables, opens files, etc.) and then define the `init_func' pointer to point to your function. @@ -24605,8 +24602,9 @@ File: gawk.info, Node: Extension Example, Next: Extension Samples, Prev: Find Two useful functions that are not in `awk' are `chdir()' (so that an `awk' program can change its directory) and `stat()' (so that an `awk' -program can gather information about a file). This minor node -implements these functions for `gawk' in an extension. +program can gather information about a file). In order to illustrate +the API in action, this minor node implements these functions for +`gawk' in an extension. * Menu: @@ -24630,8 +24628,7 @@ directory to change to: newdir = "/home/arnold/funstuff" ret = chdir(newdir) if (ret < 0) { - printf("could not change to %s: %s\n", - newdir, ERRNO) > "/dev/stderr" + printf("could not change to %s: %s\n", newdir, ERRNO) > "/dev/stderr" exit 1 } ... @@ -24796,7 +24793,7 @@ arguments: the first is an `int' usually called `nargs', that represents the number of actual arguments for the function. The second is a pointer to an `awk_value_t', usually named `result'. - /* do_chdir --- provide dynamically loaded chdir() builtin for gawk */ + /* do_chdir --- provide dynamically loaded chdir() function for gawk */ static awk_value_t * do_chdir(int nargs, awk_value_t *result) @@ -24984,7 +24981,7 @@ and/or the type of the file. It then returns zero, for success: } } - array_set(array, "type", make_const_string(type, strlen(type), &tmp)); + array_set(array, "type", make_const_string(type, strlen(type), & tmp)); return 0; } @@ -26889,7 +26886,7 @@ Info file, in approximate chronological order: various PC platforms. * Christos Zoulas provided the `extension()' built-in function for - dynamically adding new modules. (This was obsoleted at `gawk' + dynamically adding new functions. (This was obsoleted at `gawk' 4.1.) * Ju"rgen Kahrs contributed the initial version of the TCP/IP @@ -28386,9 +28383,9 @@ there are several steps that you need to take in order to make it possible to include them: 1. Before building the new feature into `gawk' itself, consider - writing it as an extension module (*note Dynamic Extensions::). - If that's not possible, continue with the rest of the steps in - this list. + writing it as an extension (*note Dynamic Extensions::). If + that's not possible, continue with the rest of the steps in this + list. 2. Be prepared to sign the appropriate paperwork. In order for the FSF to distribute your changes, you must either place those @@ -34573,138 +34570,138 @@ Ref: figure-register-new-function911987 Ref: figure-call-new-function912991 Node: Extension API Description914977 Node: Extension API Functions Introduction916427 -Node: General Data Types921293 -Ref: General Data Types-Footnote-1926986 -Node: Requesting Values927285 -Ref: table-value-types-returned928022 -Node: Memory Allocation Functions928980 -Ref: Memory Allocation Functions-Footnote-1931727 -Node: Constructor Functions931823 -Node: Registration Functions933581 -Node: Extension Functions934266 -Node: Exit Callback Functions936568 -Node: Extension Version String937816 -Node: Input Parsers938466 -Node: Output Wrappers948280 -Node: Two-way processors952796 -Node: Printing Messages955000 -Ref: Printing Messages-Footnote-1956077 -Node: Updating `ERRNO'956229 -Node: Accessing Parameters956968 -Node: Symbol Table Access958198 -Node: Symbol table by name958712 -Node: Symbol table by cookie960688 -Ref: Symbol table by cookie-Footnote-1964821 -Node: Cached values964884 -Ref: Cached values-Footnote-1968388 -Node: Array Manipulation968479 -Ref: Array Manipulation-Footnote-1969577 -Node: Array Data Types969616 -Ref: Array Data Types-Footnote-1972319 -Node: Array Functions972411 -Node: Flattening Arrays976285 -Node: Creating Arrays983137 -Node: Extension API Variables987868 -Node: Extension Versioning988504 -Node: Extension API Informational Variables990405 -Node: Extension API Boilerplate991491 -Node: Finding Extensions995295 -Node: Extension Example995855 -Node: Internal File Description996585 -Node: Internal File Ops1000676 -Ref: Internal File Ops-Footnote-11012108 -Node: Using Internal File Ops1012248 -Ref: Using Internal File Ops-Footnote-11014595 -Node: Extension Samples1014863 -Node: Extension Sample File Functions1016387 -Node: Extension Sample Fnmatch1023955 -Node: Extension Sample Fork1025437 -Node: Extension Sample Inplace1026650 -Node: Extension Sample Ord1028325 -Node: Extension Sample Readdir1029161 -Ref: table-readdir-file-types1030017 -Node: Extension Sample Revout1030816 -Node: Extension Sample Rev2way1031407 -Node: Extension Sample Read write array1032148 -Node: Extension Sample Readfile1034027 -Node: Extension Sample API Tests1035127 -Node: Extension Sample Time1035652 -Node: gawkextlib1036967 -Node: Extension summary1039780 -Node: Extension Exercises1043473 -Node: Language History1044195 -Node: V7/SVR3.11045838 -Node: SVR41048158 -Node: POSIX1049600 -Node: BTL1050986 -Node: POSIX/GNU1051720 -Node: Feature History1057496 -Node: Common Extensions1070587 -Node: Ranges and Locales1071899 -Ref: Ranges and Locales-Footnote-11076516 -Ref: Ranges and Locales-Footnote-21076543 -Ref: Ranges and Locales-Footnote-31076777 -Node: Contributors1076998 -Node: History summary1082423 -Node: Installation1083792 -Node: Gawk Distribution1084743 -Node: Getting1085227 -Node: Extracting1086051 -Node: Distribution contents1087693 -Node: Unix Installation1093463 -Node: Quick Installation1094080 -Node: Additional Configuration Options1096522 -Node: Configuration Philosophy1098260 -Node: Non-Unix Installation1100611 -Node: PC Installation1101069 -Node: PC Binary Installation1102380 -Node: PC Compiling1104228 -Ref: PC Compiling-Footnote-11107227 -Node: PC Testing1107332 -Node: PC Using1108508 -Node: Cygwin1112660 -Node: MSYS1113469 -Node: VMS Installation1113967 -Node: VMS Compilation1114763 -Ref: VMS Compilation-Footnote-11115985 -Node: VMS Dynamic Extensions1116043 -Node: VMS Installation Details1117416 -Node: VMS Running1119668 -Node: VMS GNV1122502 -Node: VMS Old Gawk1123225 -Node: Bugs1123695 -Node: Other Versions1127699 -Node: Installation summary1133923 -Node: Notes1134979 -Node: Compatibility Mode1135844 -Node: Additions1136626 -Node: Accessing The Source1137551 -Node: Adding Code1138987 -Node: New Ports1145165 -Node: Derived Files1149646 -Ref: Derived Files-Footnote-11155121 -Ref: Derived Files-Footnote-21155155 -Ref: Derived Files-Footnote-31155751 -Node: Future Extensions1155865 -Node: Implementation Limitations1156471 -Node: Extension Design1157719 -Node: Old Extension Problems1158873 -Ref: Old Extension Problems-Footnote-11160390 -Node: Extension New Mechanism Goals1160447 -Ref: Extension New Mechanism Goals-Footnote-11163807 -Node: Extension Other Design Decisions1163996 -Node: Extension Future Growth1166102 -Node: Old Extension Mechanism1166938 -Node: Notes summary1168700 -Node: Basic Concepts1169886 -Node: Basic High Level1170567 -Ref: figure-general-flow1170839 -Ref: figure-process-flow1171438 -Ref: Basic High Level-Footnote-11174667 -Node: Basic Data Typing1174852 -Node: Glossary1178180 -Node: Copying1203332 -Node: GNU Free Documentation License1240888 -Node: Index1266024 +Node: General Data Types921263 +Ref: General Data Types-Footnote-1926940 +Node: Memory Allocation Functions927239 +Ref: Memory Allocation Functions-Footnote-1930068 +Node: Constructor Functions930164 +Node: Registration Functions931898 +Node: Extension Functions932583 +Node: Exit Callback Functions934879 +Node: Extension Version String936127 +Node: Input Parsers936777 +Node: Output Wrappers946592 +Node: Two-way processors951108 +Node: Printing Messages953312 +Ref: Printing Messages-Footnote-1954389 +Node: Updating `ERRNO'954541 +Node: Requesting Values955284 +Ref: table-value-types-returned956021 +Node: Accessing Parameters956979 +Node: Symbol Table Access958209 +Node: Symbol table by name958723 +Node: Symbol table by cookie960703 +Ref: Symbol table by cookie-Footnote-1964840 +Node: Cached values964903 +Ref: Cached values-Footnote-1968407 +Node: Array Manipulation968498 +Ref: Array Manipulation-Footnote-1969596 +Node: Array Data Types969635 +Ref: Array Data Types-Footnote-1972292 +Node: Array Functions972384 +Node: Flattening Arrays976238 +Node: Creating Arrays983125 +Node: Extension API Variables987892 +Node: Extension Versioning988528 +Node: Extension API Informational Variables990429 +Node: Extension API Boilerplate991515 +Node: Finding Extensions995331 +Node: Extension Example995891 +Node: Internal File Description996663 +Node: Internal File Ops1000730 +Ref: Internal File Ops-Footnote-11012164 +Node: Using Internal File Ops1012304 +Ref: Using Internal File Ops-Footnote-11014651 +Node: Extension Samples1014919 +Node: Extension Sample File Functions1016443 +Node: Extension Sample Fnmatch1024011 +Node: Extension Sample Fork1025493 +Node: Extension Sample Inplace1026706 +Node: Extension Sample Ord1028381 +Node: Extension Sample Readdir1029217 +Ref: table-readdir-file-types1030073 +Node: Extension Sample Revout1030872 +Node: Extension Sample Rev2way1031463 +Node: Extension Sample Read write array1032204 +Node: Extension Sample Readfile1034083 +Node: Extension Sample API Tests1035183 +Node: Extension Sample Time1035708 +Node: gawkextlib1037023 +Node: Extension summary1039836 +Node: Extension Exercises1043529 +Node: Language History1044251 +Node: V7/SVR3.11045894 +Node: SVR41048214 +Node: POSIX1049656 +Node: BTL1051042 +Node: POSIX/GNU1051776 +Node: Feature History1057552 +Node: Common Extensions1070643 +Node: Ranges and Locales1071955 +Ref: Ranges and Locales-Footnote-11076572 +Ref: Ranges and Locales-Footnote-21076599 +Ref: Ranges and Locales-Footnote-31076833 +Node: Contributors1077054 +Node: History summary1082481 +Node: Installation1083850 +Node: Gawk Distribution1084801 +Node: Getting1085285 +Node: Extracting1086109 +Node: Distribution contents1087751 +Node: Unix Installation1093521 +Node: Quick Installation1094138 +Node: Additional Configuration Options1096580 +Node: Configuration Philosophy1098318 +Node: Non-Unix Installation1100669 +Node: PC Installation1101127 +Node: PC Binary Installation1102438 +Node: PC Compiling1104286 +Ref: PC Compiling-Footnote-11107285 +Node: PC Testing1107390 +Node: PC Using1108566 +Node: Cygwin1112718 +Node: MSYS1113527 +Node: VMS Installation1114025 +Node: VMS Compilation1114821 +Ref: VMS Compilation-Footnote-11116043 +Node: VMS Dynamic Extensions1116101 +Node: VMS Installation Details1117474 +Node: VMS Running1119726 +Node: VMS GNV1122560 +Node: VMS Old Gawk1123283 +Node: Bugs1123753 +Node: Other Versions1127757 +Node: Installation summary1133981 +Node: Notes1135037 +Node: Compatibility Mode1135902 +Node: Additions1136684 +Node: Accessing The Source1137609 +Node: Adding Code1139045 +Node: New Ports1145217 +Node: Derived Files1149698 +Ref: Derived Files-Footnote-11155173 +Ref: Derived Files-Footnote-21155207 +Ref: Derived Files-Footnote-31155803 +Node: Future Extensions1155917 +Node: Implementation Limitations1156523 +Node: Extension Design1157771 +Node: Old Extension Problems1158925 +Ref: Old Extension Problems-Footnote-11160442 +Node: Extension New Mechanism Goals1160499 +Ref: Extension New Mechanism Goals-Footnote-11163859 +Node: Extension Other Design Decisions1164048 +Node: Extension Future Growth1166154 +Node: Old Extension Mechanism1166990 +Node: Notes summary1168752 +Node: Basic Concepts1169938 +Node: Basic High Level1170619 +Ref: figure-general-flow1170891 +Ref: figure-process-flow1171490 +Ref: Basic High Level-Footnote-11174719 +Node: Basic Data Typing1174904 +Node: Glossary1178232 +Node: Copying1203384 +Node: GNU Free Documentation License1240940 +Node: Index1266076 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 00a5a436..f7b04d7d 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -31391,8 +31391,8 @@ does not support this keyword, you should either place All pointers filled in by @command{gawk} point to memory managed by @command{gawk} and should be treated by the extension as read-only. Memory for @emph{all} strings passed into @command{gawk} -from the extension @emph{must} come from calling the API-provided function -pointers @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()}, +from the extension @emph{must} come from calling one of +@code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}, and is managed by @command{gawk} from then on. @item @@ -31475,8 +31475,8 @@ 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 calling the API-provided function -pointers @code{api_malloc()}, @code{api_calloc()}, or @code{api_realloc()}!} +@strong{Such memory must come from calling one of the +@code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()} functions!} As mentioned earlier, strings are maintained using the current multibyte encoding. @@ -31581,149 +31581,6 @@ and then pass in that value cookie whenever you wish to set the value of a variable. This saves both storage space within the running @command{gawk} process as well as the time needed to create the value. -@node Requesting Values -@subsection Requesting Values - -All of the functions that return values from @command{gawk} -work in the same way. You pass in an @code{awk_valtype_t} value -to indicate what kind of value you expect. If the actual value -matches what you requested, the function returns true and fills -in the @code{awk_value_t} result. -Otherwise, the function returns false, and the @code{val_type} -member indicates the type of the actual value. You may then -print an error message, or reissue the request for the actual -value type, as appropriate. This behavior is summarized in -@ref{table-value-types-returned}. - -@c FIXME: Try to do this with spans... - -@float Table,table-value-types-returned -@caption{API Value Types Returned} -@docbook -<informaltable> -<tgroup cols="2"> - <colspec colwidth="50*"/><colspec colwidth="50*"/> - <thead> - <row><entry></entry><entry><para>Type of Actual Value:</para></entry></row> - </thead> - <tbody> - <row><entry></entry><entry></entry></row> - </tbody> -</tgroup> -<tgroup cols="6"> - <colspec colwidth="16.6*"/> - <colspec colwidth="16.6*"/> - <colspec colwidth="19.8*"/> - <colspec colwidth="15*"/> - <colspec colwidth="15*"/> - <colspec colwidth="16.6*"/> - <thead> - <row> - <entry></entry> - <entry></entry> - <entry><para>String</para></entry> - <entry><para>Number</para></entry> - <entry><para>Array</para></entry> - <entry><para>Undefined</para></entry> - </row> - </thead> - <tbody> - <row> - <entry></entry> - <entry><para><emphasis role="bold">String</emphasis></para></entry> - <entry><para>String</para></entry> - <entry><para>String</para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> - </row> - <row> - <entry></entry> - <entry><para><emphasis role="bold">Number</emphasis></para></entry> - <entry><para>Number if can be converted, else false</para></entry> - <entry><para>Number</para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> - </row> - <row> - <entry><para><emphasis role="bold">Type</emphasis></para></entry> - <entry><para><emphasis role="bold">Array</emphasis></para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> - <entry><para>Array</para></entry> - <entry><para>false</para></entry> - </row> - <row> - <entry><para><emphasis role="bold">Requested:</emphasis></para></entry> - <entry><para><emphasis role="bold">Scalar</emphasis></para></entry> - <entry><para>Scalar</para></entry> - <entry><para>Scalar</para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> - </row> - <row> - <entry></entry> - <entry><para><emphasis role="bold">Undefined</emphasis></para></entry> - <entry><para>String</para></entry> - <entry><para>Number</para></entry> - <entry><para>Array</para></entry> - <entry><para>Undefined</para></entry> - </row> - <row> - <entry></entry> - <entry><para><emphasis role="bold">Value Cookie</emphasis></para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> - <entry><para>false</para> - </entry><entry><para>false</para></entry> - </row> - </tbody> -</tgroup> -</informaltable> -@end docbook - -@ifnotplaintext -@ifnotdocbook -@multitable @columnfractions .50 .50 -@headitem @tab Type of Actual Value: -@end multitable -@multitable @columnfractions .166 .166 .198 .15 .15 .166 -@headitem @tab @tab String @tab Number @tab Array @tab Undefined -@item @tab @b{String} @tab String @tab String @tab false @tab false -@item @tab @b{Number} @tab Number if can be converted, else false @tab Number @tab false @tab false -@item @b{Type} @tab @b{Array} @tab false @tab false @tab Array @tab false -@item @b{Requested:} @tab @b{Scalar} @tab Scalar @tab Scalar @tab false @tab false -@item @tab @b{Undefined} @tab String @tab Number @tab Array @tab Undefined -@item @tab @b{Value Cookie} @tab false @tab false @tab false @tab false -@end multitable -@end ifnotdocbook -@end ifnotplaintext -@ifplaintext -@example - +-------------------------------------------------+ - | Type of Actual Value: | - +------------+------------+-----------+-----------+ - | String | Number | Array | Undefined | -+-----------+-----------+------------+------------+-----------+-----------+ -| | String | String | String | false | false | -| |-----------+------------+------------+-----------+-----------+ -| | Number | Number if | Number | false | false | -| | | can be | | | | -| | | converted, | | | | -| | | else false | | | | -| |-----------+------------+------------+-----------+-----------+ -| Type | Array | false | false | Array | false | -| Requested |-----------+------------+------------+-----------+-----------+ -| | Scalar | Scalar | Scalar | false | false | -| |-----------+------------+------------+-----------+-----------+ -| | Undefined | String | Number | Array | Undefined | -| |-----------+------------+------------+-----------+-----------+ -| | Value | false | false | false | false | -| | Cookie | | | | | -+-----------+-----------+------------+------------+-----------+-----------+ -@end example -@end ifplaintext -@end float - @node Memory Allocation Functions @subsection Memory Allocation Functions and Convenience Macros @cindex allocating memory for extensions @@ -31732,22 +31589,24 @@ value type, as appropriate. This behavior is summarized in The API provides a number of @dfn{memory allocation} functions for allocating memory that can be passed to @command{gawk}, 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 void *gawk_malloc(size_t size); -Call @command{gawk}-provided @code{api_malloc()} to allocate storage that may +Call the correct version of @code{malloc()} to allocate storage that may be passed to @command{gawk}. @item void *gawk_calloc(size_t nmemb, size_t size); -Call @command{gawk}-provided @code{api_calloc()} to allocate storage that may +Call the correct version of @code{calloc()} to allocate storage that may be passed to @command{gawk}. @item void *gawk_realloc(void *ptr, size_t size); -Call @command{gawk}-provided @code{api_realloc()} to allocate storage that may +Call the correct version of @code{realloc()} to allocate storage that may be passed to @command{gawk}. @item void gawk_free(void *ptr); -Call @command{gawk}-provided @code{api_free()} to release storage that was +Call the correct version of @code{free()} to release storage that was allocated with @code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}. @end table @@ -31761,8 +31620,8 @@ unrelated version of @code{malloc()}, unexpected behavior would likely result. 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} +from @code{gawk_malloc()} and +@code{gawk_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. @@ -31776,7 +31635,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{api_malloc()}. +The type of the pointer variable, used to create a cast for the call to @code{gawk_malloc()}. @item size The total number of bytes to be allocated. @@ -31800,8 +31659,8 @@ 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{api_realloc()}, -instead of @code{api_malloc()}. +This is like @code{emalloc()}, but it calls @code{gawk_realloc()}, +instead of @code{gawk_malloc()}. The arguments are the same as for the @code{emalloc()} macro. @end table @@ -31825,7 +31684,7 @@ for storage in @code{result}. It returns @code{result}. @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 +value pointing to data previously obtained from @code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}. The idea here is that the data is passed directly to @command{gawk}, which assumes responsibility for it. It returns @code{result}. @@ -31880,17 +31739,18 @@ The name of the new function. This is a regular C string. Function names must obey the rules for @command{awk} -identifiers. That is, they must begin with either a letter +identifiers. That is, they must begin with either an English letter 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 *(*function)(int num_actual_args, awk_value_t *result); -This is a pointer to the C function that provides the desired +This is a pointer to the C function that provides the extension's functionality. -The function must fill in the result with either a number +The function must fill in @code{*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 the api-provided functions @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()}. +As mentioned earlier, string memory @strong{must} come from one of @code{gawk_malloc()}, +@code{gawk_calloc()} or @code{gawk_realloc()}. The @code{num_actual_args} argument tells the C function how many actual parameters were passed from the calling @command{awk} code. @@ -31901,7 +31761,7 @@ This is for the convenience of the calling code inside @command{gawk}. @item size_t num_expected_args; This is the number of arguments the function expects to receive. Each extension function may decide what to do if the number of -arguments isn't what it expected. Following @command{awk} functions, it +arguments isn't what it expected. As with real @command{awk} functions, it is likely OK to ignore extra arguments. @end table @@ -32155,7 +32015,7 @@ If the concept of a ``record terminator'' makes sense, then @code{RT}, and @code{*rt_len} should be set to the length of the data. Otherwise, @code{*rt_len} should be set to zero. @code{gawk} makes its own copy of this data, so the -extension must manage the storage. +extension must manage this storage. @end table The return value is the length of the buffer pointed to by @@ -32434,10 +32294,144 @@ into a (possibly translated) string using the C @code{strerror()} function. Set @code{ERRNO} directly to the string value of @code{ERRNO}. @command{gawk} makes a copy of the value of @code{string}. -@item void unset_ERRNO(); +@item void unset_ERRNO(void); Unset @code{ERRNO}. @end table +@node Requesting Values +@subsection Requesting Values + +All of the functions that return values from @command{gawk} +work in the same way. You pass in an @code{awk_valtype_t} value +to indicate what kind of value you expect. If the actual value +matches what you requested, the function returns true and fills +in the @code{awk_value_t} result. +Otherwise, the function returns false, and the @code{val_type} +member indicates the type of the actual value. You may then +print an error message, or reissue the request for the actual +value type, as appropriate. This behavior is summarized in +@ref{table-value-types-returned}. + +@float Table,table-value-types-returned +@caption{API Value Types Returned} +@docbook +<informaltable> +<tgroup cols="6"> + <colspec colwidth="16.6*"/> + <colspec colwidth="16.6*"/> + <colspec colwidth="19.8*" colname="c3"/> + <colspec colwidth="15*" colname="c4"/> + <colspec colwidth="15*" colname="c5"/> + <colspec colwidth="16.6*" colname="c6"/> + <spanspec spanname="hspan" namest="c3" nameend="c6" align="center"/> + <thead> + <row><entry></entry><entry spanname="hspan"><para>Type of Actual Value:</para></entry></row> + <row> + <entry></entry> + <entry></entry> + <entry><para>String</para></entry> + <entry><para>Number</para></entry> + <entry><para>Array</para></entry> + <entry><para>Undefined</para></entry> + </row> + </thead> + <tbody> + <row> + <entry></entry> + <entry><para><emphasis role="bold">String</emphasis></para></entry> + <entry><para>String</para></entry> + <entry><para>String</para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + </row> + <row> + <entry></entry> + <entry><para><emphasis role="bold">Number</emphasis></para></entry> + <entry><para>Number if can be converted, else false</para></entry> + <entry><para>Number</para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + </row> + <row> + <entry><para><emphasis role="bold">Type</emphasis></para></entry> + <entry><para><emphasis role="bold">Array</emphasis></para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + <entry><para>Array</para></entry> + <entry><para>false</para></entry> + </row> + <row> + <entry><para><emphasis role="bold">Requested:</emphasis></para></entry> + <entry><para><emphasis role="bold">Scalar</emphasis></para></entry> + <entry><para>Scalar</para></entry> + <entry><para>Scalar</para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + </row> + <row> + <entry></entry> + <entry><para><emphasis role="bold">Undefined</emphasis></para></entry> + <entry><para>String</para></entry> + <entry><para>Number</para></entry> + <entry><para>Array</para></entry> + <entry><para>Undefined</para></entry> + </row> + <row> + <entry></entry> + <entry><para><emphasis role="bold">Value Cookie</emphasis></para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + <entry><para>false</para> + </entry><entry><para>false</para></entry> + </row> + </tbody> +</tgroup> +</informaltable> +@end docbook + +@ifnotplaintext +@ifnotdocbook +@multitable @columnfractions .50 .50 +@headitem @tab Type of Actual Value: +@end multitable +@multitable @columnfractions .166 .166 .198 .15 .15 .166 +@headitem @tab @tab String @tab Number @tab Array @tab Undefined +@item @tab @b{String} @tab String @tab String @tab false @tab false +@item @tab @b{Number} @tab Number if can be converted, else false @tab Number @tab false @tab false +@item @b{Type} @tab @b{Array} @tab false @tab false @tab Array @tab false +@item @b{Requested:} @tab @b{Scalar} @tab Scalar @tab Scalar @tab false @tab false +@item @tab @b{Undefined} @tab String @tab Number @tab Array @tab Undefined +@item @tab @b{Value Cookie} @tab false @tab false @tab false @tab false +@end multitable +@end ifnotdocbook +@end ifnotplaintext +@ifplaintext +@example + +-------------------------------------------------+ + | Type of Actual Value: | + +------------+------------+-----------+-----------+ + | String | Number | Array | Undefined | ++-----------+-----------+------------+------------+-----------+-----------+ +| | String | String | String | false | false | +| |-----------+------------+------------+-----------+-----------+ +| | Number | Number if | Number | false | false | +| | | can be | | | | +| | | converted, | | | | +| | | else false | | | | +| |-----------+------------+------------+-----------+-----------+ +| Type | Array | false | false | Array | false | +| Requested |-----------+------------+------------+-----------+-----------+ +| | Scalar | Scalar | Scalar | false | false | +| |-----------+------------+------------+-----------+-----------+ +| | Undefined | String | Number | Array | Undefined | +| |-----------+------------+------------+-----------+-----------+ +| | Value | false | false | false | false | +| | Cookie | | | | | ++-----------+-----------+------------+------------+-----------+-----------+ +@end example +@end ifplaintext +@end float + @node Accessing Parameters @subsection Accessing and Updating Parameters @@ -32492,7 +32486,7 @@ about symbols is termed a @dfn{symbol table}. Fill in the @code{awk_value_t} structure pointed to by @code{result} with the value of the variable named by the string @code{name}, which is a regular C string. @code{wanted} indicates the type of value expected. -Return true if the actual type matches @code{wanted}, false otherwise +Return true if the actual type matches @code{wanted}, false otherwise. In the latter case, @code{result->val_type} indicates the actual type (@pxref{table-value-types-returned}). @@ -32511,7 +32505,7 @@ 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 NOTE +@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 @@ -32533,7 +32527,7 @@ The following functions let you work with scalar cookies. @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_valtype_t wanted, @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_value_t *result); Retrieve the current value of a scalar cookie. -Once you have obtained a scalar_cookie using @code{sym_lookup()}, you can +Once you have obtained a scalar cookie using @code{sym_lookup()}, you can use this function to get its value more efficiently. Return false if the value cannot be retrieved. @@ -32595,7 +32589,7 @@ my_extension_init() /* install initial value */ sym_update("MAGIC_VAR", make_number(42.0, & value)); - /* get cookie */ + /* get the cookie */ sym_lookup("MAGIC_VAR", AWK_SCALAR, & value); /* save the cookie */ @@ -32644,7 +32638,8 @@ 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{api_malloc()}, @code{api_calloc()} or @code{api_realloc()}. +@emph{every} string value's storage @emph{must} come from @code{gawk_malloc()}, +@code{gawk_calloc()} or @code{gawk_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.} @@ -32715,7 +32710,7 @@ Using value cookies in this way saves considerable storage, since all of You might be wondering, ``Is this sharing problematic? What happens if @command{awk} code assigns a new value to @code{VAR1}, -are all the others be changed too?'' +are all the others changed too?'' That's a great question. The answer is that no, it's not a problem. Internally, @command{gawk} uses @dfn{reference-counted strings}. This means @@ -32770,7 +32765,7 @@ with the @code{<stdio.h>} library routines. @itemx @ @ @ @ struct awk_element *next; @itemx @ @ @ @ enum @{ @itemx @ @ @ @ @ @ @ @ AWK_ELEMENT_DEFAULT = 0,@ @ /* set by gawk */ -@itemx @ @ @ @ @ @ @ @ AWK_ELEMENT_DELETE = 1@ @ @ @ /* set by extension if should be deleted */ +@itemx @ @ @ @ @ @ @ @ AWK_ELEMENT_DELETE = 1@ @ @ @ /* set by extension */ @itemx @ @ @ @ @} flags; @itemx @ @ @ @ awk_value_t index; @itemx @ @ @ @ awk_value_t value; @@ -32790,8 +32785,8 @@ an extension to create a linked list of new elements that can then be added to an array in a loop that traverses the list. @item enum @{ @dots{} @} flags; -A set of flag values that convey information between @command{gawk} -and the extension. Currently there is only one: @code{AWK_ELEMENT_DELETE}. +A set of flag values that convey information between the extension +and @command{gawk}. Currently there is only one: @code{AWK_ELEMENT_DELETE}. Setting it causes @command{gawk} to delete the element from the original array upon release of the flattened array. @@ -32802,8 +32797,8 @@ The index and value of the element, respectively. @end table @item typedef struct awk_flat_array @{ -@itemx @ @ @ @ awk_const void *awk_const opaque1;@ @ @ @ /* private data for use by gawk */ -@itemx @ @ @ @ awk_const void *awk_const opaque2;@ @ @ @ /* private data for use by gawk */ +@itemx @ @ @ @ awk_const void *awk_const opaque1;@ @ @ @ /* for use by gawk */ +@itemx @ @ @ @ awk_const void *awk_const opaque2;@ @ @ @ /* for use by gawk */ @itemx @ @ @ @ awk_const size_t count;@ @ @ @ @ /* how many elements */ @itemx @ @ @ @ awk_element_t elements[1];@ @ /* will be extended */ @itemx @} awk_flat_array_t; @@ -32822,7 +32817,7 @@ The following functions relate to individual array elements. @table @code @item awk_bool_t get_element_count(awk_array_t a_cookie, size_t *count); -For the array represented by @code{a_cookie}, return in @code{*count} +For the array represented by @code{a_cookie}, place in @code{*count} the number of elements it contains. A subarray counts as a single element. Return false if there is an error. @@ -32842,7 +32837,8 @@ 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 the API-provided functions @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()} and +the string value of @code{index} must come from @code{gawk_malloc()}, +@code{gawk_calloc()} or @code{gawk_realloc()}, and @command{gawk} releases the storage. @item awk_bool_t set_array_element(awk_array_t a_cookie, @@ -32869,7 +32865,7 @@ not exist in the array. The following functions relate to arrays as a whole: @table @code -@item awk_array_t create_array(); +@item awk_array_t create_array(void); Create a new array to which elements may be added. @xref{Creating Arrays}, for a discussion of how to create a new array and add elements to it. @@ -32886,7 +32882,13 @@ For the array represented by @code{a_cookie}, create an @code{awk_flat_array_t} structure and fill it in. Set the pointer whose address is passed as @code{data} to point to this structure. Return true upon success, or false otherwise. -@xref{Flattening Arrays}, for a discussion of how to +@ifset FOR_PRINT +See the next section +@end ifset +@ifclear FOR_PRINT +@xref{Flattening Arrays}, +@end ifclear +for a discussion of how to flatten an array and work with it. @item awk_bool_t release_flattened_array(awk_array_t a_cookie, @@ -32906,6 +32908,7 @@ for C code to traverse the entire array. Test code in @file{extension/testext.c} does this, and also serves as a nice example showing how to use the APIs. +We walk through that part of the code one step at a time. First, the @command{gawk} script that drives the test extension: @example @@ -33044,8 +33047,7 @@ have this flag bit set: valrep2str(& flat_array->elements[i].value)); if (strcmp(value3.str_value.str, - flat_array->elements[i].index.str_value.str) - == 0) @{ + flat_array->elements[i].index.str_value.str) == 0) @{ flat_array->elements[i].flags |= AWK_ELEMENT_DELETE; printf("dump_array_and_delete: marking element \"%s\" " "for deletion\n", @@ -33149,7 +33151,9 @@ of the array cookie after the call to @code{set_element()}. The following C code is a simple test extension to create an array with two regular elements and with a subarray. The leading @code{#include} -directives and boilerplate variable declarations are omitted for brevity. +directives and boilerplate variable declarations +(@pxref{Extension API Boilerplate}) +are omitted for brevity. The first step is to create a new array and then install it in the symbol table: @@ -33428,12 +33432,12 @@ static awk_bool_t (*init_func)(void) = NULL; /* OR: */ static awk_bool_t -init_my_module(void) +init_my_extension(void) @{ @dots{} @} -static awk_bool_t (*init_func)(void) = init_my_module; +static awk_bool_t (*init_func)(void) = init_my_extension; dl_load_func(func_table, some_name, "name_space_in_quotes") @end example @@ -33476,8 +33480,8 @@ It can then be looped over for multiple calls to @c Use @var{OR} for docbook @item static awk_bool_t (*init_func)(void) = NULL; @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @var{OR} -@itemx static awk_bool_t init_my_module(void) @{ @dots{} @} -@itemx static awk_bool_t (*init_func)(void) = init_my_module; +@itemx static awk_bool_t init_my_extension(void) @{ @dots{} @} +@itemx static awk_bool_t (*init_func)(void) = init_my_extension; If you need to do some initialization work, you should define a function that does it (creates variables, opens files, etc.) and then define the @code{init_func} pointer to point to your @@ -33544,8 +33548,8 @@ path with a list of directories to search for compiled extensions. Two useful functions that are not in @command{awk} are @code{chdir()} (so that an @command{awk} program can change its directory) and @code{stat()} (so that an @command{awk} program can gather information about a file). -This @value{SECTION} implements these functions for @command{gawk} -in an extension. +In order to illustrate the API in action, this @value{SECTION} implements +these functions for @command{gawk} in an extension. @menu * Internal File Description:: What the new functions will do. @@ -33567,8 +33571,7 @@ straightforward. It takes one argument, the new directory to change to: newdir = "/home/arnold/funstuff" ret = chdir(newdir) if (ret < 0) @{ - printf("could not change to %s: %s\n", - newdir, ERRNO) > "/dev/stderr" + printf("could not change to %s: %s\n", newdir, ERRNO) > "/dev/stderr" exit 1 @} @dots{} @@ -33756,7 +33759,7 @@ The second is a pointer to an @code{awk_value_t}, usually named @code{result}. @example -/* do_chdir --- provide dynamically loaded chdir() builtin for gawk */ +/* do_chdir --- provide dynamically loaded chdir() function for gawk */ static awk_value_t * do_chdir(int nargs, awk_value_t *result) @@ -33965,7 +33968,7 @@ for success: @} @} - array_set(array, "type", make_const_string(type, strlen(type), &tmp)); + array_set(array, "type", make_const_string(type, strlen(type), & tmp)); return 0; @} @@ -36573,7 +36576,7 @@ the various PC platforms. @cindex Zoulas, Christos Christos Zoulas provided the @code{extension()} -built-in function for dynamically adding new modules. +built-in function for dynamically adding new functions. (This was obsoleted at @command{gawk} 4.1.) @item @@ -38481,7 +38484,7 @@ make it possible to include them: @enumerate 1 @item Before building the new feature into @command{gawk} itself, -consider writing it as an extension module +consider writing it as an extension (@pxref{Dynamic Extensions}). If that's not possible, continue with the rest of the steps in this list. diff --git a/doc/gawktexi.in b/doc/gawktexi.in index a0677a7c..b42d7f7b 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -30488,8 +30488,8 @@ does not support this keyword, you should either place All pointers filled in by @command{gawk} point to memory managed by @command{gawk} and should be treated by the extension as read-only. Memory for @emph{all} strings passed into @command{gawk} -from the extension @emph{must} come from calling the API-provided function -pointers @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()}, +from the extension @emph{must} come from calling one of +@code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}, and is managed by @command{gawk} from then on. @item @@ -30572,8 +30572,8 @@ 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 calling the API-provided function -pointers @code{api_malloc()}, @code{api_calloc()}, or @code{api_realloc()}!} +@strong{Such memory must come from calling one of the +@code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()} functions!} As mentioned earlier, strings are maintained using the current multibyte encoding. @@ -30678,149 +30678,6 @@ and then pass in that value cookie whenever you wish to set the value of a variable. This saves both storage space within the running @command{gawk} process as well as the time needed to create the value. -@node Requesting Values -@subsection Requesting Values - -All of the functions that return values from @command{gawk} -work in the same way. You pass in an @code{awk_valtype_t} value -to indicate what kind of value you expect. If the actual value -matches what you requested, the function returns true and fills -in the @code{awk_value_t} result. -Otherwise, the function returns false, and the @code{val_type} -member indicates the type of the actual value. You may then -print an error message, or reissue the request for the actual -value type, as appropriate. This behavior is summarized in -@ref{table-value-types-returned}. - -@c FIXME: Try to do this with spans... - -@float Table,table-value-types-returned -@caption{API Value Types Returned} -@docbook -<informaltable> -<tgroup cols="2"> - <colspec colwidth="50*"/><colspec colwidth="50*"/> - <thead> - <row><entry></entry><entry><para>Type of Actual Value:</para></entry></row> - </thead> - <tbody> - <row><entry></entry><entry></entry></row> - </tbody> -</tgroup> -<tgroup cols="6"> - <colspec colwidth="16.6*"/> - <colspec colwidth="16.6*"/> - <colspec colwidth="19.8*"/> - <colspec colwidth="15*"/> - <colspec colwidth="15*"/> - <colspec colwidth="16.6*"/> - <thead> - <row> - <entry></entry> - <entry></entry> - <entry><para>String</para></entry> - <entry><para>Number</para></entry> - <entry><para>Array</para></entry> - <entry><para>Undefined</para></entry> - </row> - </thead> - <tbody> - <row> - <entry></entry> - <entry><para><emphasis role="bold">String</emphasis></para></entry> - <entry><para>String</para></entry> - <entry><para>String</para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> - </row> - <row> - <entry></entry> - <entry><para><emphasis role="bold">Number</emphasis></para></entry> - <entry><para>Number if can be converted, else false</para></entry> - <entry><para>Number</para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> - </row> - <row> - <entry><para><emphasis role="bold">Type</emphasis></para></entry> - <entry><para><emphasis role="bold">Array</emphasis></para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> - <entry><para>Array</para></entry> - <entry><para>false</para></entry> - </row> - <row> - <entry><para><emphasis role="bold">Requested:</emphasis></para></entry> - <entry><para><emphasis role="bold">Scalar</emphasis></para></entry> - <entry><para>Scalar</para></entry> - <entry><para>Scalar</para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> - </row> - <row> - <entry></entry> - <entry><para><emphasis role="bold">Undefined</emphasis></para></entry> - <entry><para>String</para></entry> - <entry><para>Number</para></entry> - <entry><para>Array</para></entry> - <entry><para>Undefined</para></entry> - </row> - <row> - <entry></entry> - <entry><para><emphasis role="bold">Value Cookie</emphasis></para></entry> - <entry><para>false</para></entry> - <entry><para>false</para></entry> - <entry><para>false</para> - </entry><entry><para>false</para></entry> - </row> - </tbody> -</tgroup> -</informaltable> -@end docbook - -@ifnotplaintext -@ifnotdocbook -@multitable @columnfractions .50 .50 -@headitem @tab Type of Actual Value: -@end multitable -@multitable @columnfractions .166 .166 .198 .15 .15 .166 -@headitem @tab @tab String @tab Number @tab Array @tab Undefined -@item @tab @b{String} @tab String @tab String @tab false @tab false -@item @tab @b{Number} @tab Number if can be converted, else false @tab Number @tab false @tab false -@item @b{Type} @tab @b{Array} @tab false @tab false @tab Array @tab false -@item @b{Requested:} @tab @b{Scalar} @tab Scalar @tab Scalar @tab false @tab false -@item @tab @b{Undefined} @tab String @tab Number @tab Array @tab Undefined -@item @tab @b{Value Cookie} @tab false @tab false @tab false @tab false -@end multitable -@end ifnotdocbook -@end ifnotplaintext -@ifplaintext -@example - +-------------------------------------------------+ - | Type of Actual Value: | - +------------+------------+-----------+-----------+ - | String | Number | Array | Undefined | -+-----------+-----------+------------+------------+-----------+-----------+ -| | String | String | String | false | false | -| |-----------+------------+------------+-----------+-----------+ -| | Number | Number if | Number | false | false | -| | | can be | | | | -| | | converted, | | | | -| | | else false | | | | -| |-----------+------------+------------+-----------+-----------+ -| Type | Array | false | false | Array | false | -| Requested |-----------+------------+------------+-----------+-----------+ -| | Scalar | Scalar | Scalar | false | false | -| |-----------+------------+------------+-----------+-----------+ -| | Undefined | String | Number | Array | Undefined | -| |-----------+------------+------------+-----------+-----------+ -| | Value | false | false | false | false | -| | Cookie | | | | | -+-----------+-----------+------------+------------+-----------+-----------+ -@end example -@end ifplaintext -@end float - @node Memory Allocation Functions @subsection Memory Allocation Functions and Convenience Macros @cindex allocating memory for extensions @@ -30829,22 +30686,24 @@ value type, as appropriate. This behavior is summarized in The API provides a number of @dfn{memory allocation} functions for allocating memory that can be passed to @command{gawk}, 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 void *gawk_malloc(size_t size); -Call @command{gawk}-provided @code{api_malloc()} to allocate storage that may +Call the correct version of @code{malloc()} to allocate storage that may be passed to @command{gawk}. @item void *gawk_calloc(size_t nmemb, size_t size); -Call @command{gawk}-provided @code{api_calloc()} to allocate storage that may +Call the correct version of @code{calloc()} to allocate storage that may be passed to @command{gawk}. @item void *gawk_realloc(void *ptr, size_t size); -Call @command{gawk}-provided @code{api_realloc()} to allocate storage that may +Call the correct version of @code{realloc()} to allocate storage that may be passed to @command{gawk}. @item void gawk_free(void *ptr); -Call @command{gawk}-provided @code{api_free()} to release storage that was +Call the correct version of @code{free()} to release storage that was allocated with @code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}. @end table @@ -30858,8 +30717,8 @@ unrelated version of @code{malloc()}, unexpected behavior would likely result. 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} +from @code{gawk_malloc()} and +@code{gawk_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. @@ -30873,7 +30732,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{api_malloc()}. +The type of the pointer variable, used to create a cast for the call to @code{gawk_malloc()}. @item size The total number of bytes to be allocated. @@ -30897,8 +30756,8 @@ 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{api_realloc()}, -instead of @code{api_malloc()}. +This is like @code{emalloc()}, but it calls @code{gawk_realloc()}, +instead of @code{gawk_malloc()}. The arguments are the same as for the @code{emalloc()} macro. @end table @@ -30922,7 +30781,7 @@ for storage in @code{result}. It returns @code{result}. @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 +value pointing to data previously obtained from @code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}. The idea here is that the data is passed directly to @command{gawk}, which assumes responsibility for it. It returns @code{result}. @@ -30977,17 +30836,18 @@ The name of the new function. This is a regular C string. Function names must obey the rules for @command{awk} -identifiers. That is, they must begin with either a letter +identifiers. That is, they must begin with either an English letter 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 *(*function)(int num_actual_args, awk_value_t *result); -This is a pointer to the C function that provides the desired +This is a pointer to the C function that provides the extension's functionality. -The function must fill in the result with either a number +The function must fill in @code{*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 the api-provided functions @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()}. +As mentioned earlier, string memory @strong{must} come from one of @code{gawk_malloc()}, +@code{gawk_calloc()} or @code{gawk_realloc()}. The @code{num_actual_args} argument tells the C function how many actual parameters were passed from the calling @command{awk} code. @@ -30998,7 +30858,7 @@ This is for the convenience of the calling code inside @command{gawk}. @item size_t num_expected_args; This is the number of arguments the function expects to receive. Each extension function may decide what to do if the number of -arguments isn't what it expected. Following @command{awk} functions, it +arguments isn't what it expected. As with real @command{awk} functions, it is likely OK to ignore extra arguments. @end table @@ -31252,7 +31112,7 @@ If the concept of a ``record terminator'' makes sense, then @code{RT}, and @code{*rt_len} should be set to the length of the data. Otherwise, @code{*rt_len} should be set to zero. @code{gawk} makes its own copy of this data, so the -extension must manage the storage. +extension must manage this storage. @end table The return value is the length of the buffer pointed to by @@ -31531,10 +31391,144 @@ into a (possibly translated) string using the C @code{strerror()} function. Set @code{ERRNO} directly to the string value of @code{ERRNO}. @command{gawk} makes a copy of the value of @code{string}. -@item void unset_ERRNO(); +@item void unset_ERRNO(void); Unset @code{ERRNO}. @end table +@node Requesting Values +@subsection Requesting Values + +All of the functions that return values from @command{gawk} +work in the same way. You pass in an @code{awk_valtype_t} value +to indicate what kind of value you expect. If the actual value +matches what you requested, the function returns true and fills +in the @code{awk_value_t} result. +Otherwise, the function returns false, and the @code{val_type} +member indicates the type of the actual value. You may then +print an error message, or reissue the request for the actual +value type, as appropriate. This behavior is summarized in +@ref{table-value-types-returned}. + +@float Table,table-value-types-returned +@caption{API Value Types Returned} +@docbook +<informaltable> +<tgroup cols="6"> + <colspec colwidth="16.6*"/> + <colspec colwidth="16.6*"/> + <colspec colwidth="19.8*" colname="c3"/> + <colspec colwidth="15*" colname="c4"/> + <colspec colwidth="15*" colname="c5"/> + <colspec colwidth="16.6*" colname="c6"/> + <spanspec spanname="hspan" namest="c3" nameend="c6" align="center"/> + <thead> + <row><entry></entry><entry spanname="hspan"><para>Type of Actual Value:</para></entry></row> + <row> + <entry></entry> + <entry></entry> + <entry><para>String</para></entry> + <entry><para>Number</para></entry> + <entry><para>Array</para></entry> + <entry><para>Undefined</para></entry> + </row> + </thead> + <tbody> + <row> + <entry></entry> + <entry><para><emphasis role="bold">String</emphasis></para></entry> + <entry><para>String</para></entry> + <entry><para>String</para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + </row> + <row> + <entry></entry> + <entry><para><emphasis role="bold">Number</emphasis></para></entry> + <entry><para>Number if can be converted, else false</para></entry> + <entry><para>Number</para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + </row> + <row> + <entry><para><emphasis role="bold">Type</emphasis></para></entry> + <entry><para><emphasis role="bold">Array</emphasis></para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + <entry><para>Array</para></entry> + <entry><para>false</para></entry> + </row> + <row> + <entry><para><emphasis role="bold">Requested:</emphasis></para></entry> + <entry><para><emphasis role="bold">Scalar</emphasis></para></entry> + <entry><para>Scalar</para></entry> + <entry><para>Scalar</para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + </row> + <row> + <entry></entry> + <entry><para><emphasis role="bold">Undefined</emphasis></para></entry> + <entry><para>String</para></entry> + <entry><para>Number</para></entry> + <entry><para>Array</para></entry> + <entry><para>Undefined</para></entry> + </row> + <row> + <entry></entry> + <entry><para><emphasis role="bold">Value Cookie</emphasis></para></entry> + <entry><para>false</para></entry> + <entry><para>false</para></entry> + <entry><para>false</para> + </entry><entry><para>false</para></entry> + </row> + </tbody> +</tgroup> +</informaltable> +@end docbook + +@ifnotplaintext +@ifnotdocbook +@multitable @columnfractions .50 .50 +@headitem @tab Type of Actual Value: +@end multitable +@multitable @columnfractions .166 .166 .198 .15 .15 .166 +@headitem @tab @tab String @tab Number @tab Array @tab Undefined +@item @tab @b{String} @tab String @tab String @tab false @tab false +@item @tab @b{Number} @tab Number if can be converted, else false @tab Number @tab false @tab false +@item @b{Type} @tab @b{Array} @tab false @tab false @tab Array @tab false +@item @b{Requested:} @tab @b{Scalar} @tab Scalar @tab Scalar @tab false @tab false +@item @tab @b{Undefined} @tab String @tab Number @tab Array @tab Undefined +@item @tab @b{Value Cookie} @tab false @tab false @tab false @tab false +@end multitable +@end ifnotdocbook +@end ifnotplaintext +@ifplaintext +@example + +-------------------------------------------------+ + | Type of Actual Value: | + +------------+------------+-----------+-----------+ + | String | Number | Array | Undefined | ++-----------+-----------+------------+------------+-----------+-----------+ +| | String | String | String | false | false | +| |-----------+------------+------------+-----------+-----------+ +| | Number | Number if | Number | false | false | +| | | can be | | | | +| | | converted, | | | | +| | | else false | | | | +| |-----------+------------+------------+-----------+-----------+ +| Type | Array | false | false | Array | false | +| Requested |-----------+------------+------------+-----------+-----------+ +| | Scalar | Scalar | Scalar | false | false | +| |-----------+------------+------------+-----------+-----------+ +| | Undefined | String | Number | Array | Undefined | +| |-----------+------------+------------+-----------+-----------+ +| | Value | false | false | false | false | +| | Cookie | | | | | ++-----------+-----------+------------+------------+-----------+-----------+ +@end example +@end ifplaintext +@end float + @node Accessing Parameters @subsection Accessing and Updating Parameters @@ -31589,7 +31583,7 @@ about symbols is termed a @dfn{symbol table}. Fill in the @code{awk_value_t} structure pointed to by @code{result} with the value of the variable named by the string @code{name}, which is a regular C string. @code{wanted} indicates the type of value expected. -Return true if the actual type matches @code{wanted}, false otherwise +Return true if the actual type matches @code{wanted}, false otherwise. In the latter case, @code{result->val_type} indicates the actual type (@pxref{table-value-types-returned}). @@ -31608,7 +31602,7 @@ 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 NOTE +@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 @@ -31630,7 +31624,7 @@ The following functions let you work with scalar cookies. @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_valtype_t wanted, @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_value_t *result); Retrieve the current value of a scalar cookie. -Once you have obtained a scalar_cookie using @code{sym_lookup()}, you can +Once you have obtained a scalar cookie using @code{sym_lookup()}, you can use this function to get its value more efficiently. Return false if the value cannot be retrieved. @@ -31692,7 +31686,7 @@ my_extension_init() /* install initial value */ sym_update("MAGIC_VAR", make_number(42.0, & value)); - /* get cookie */ + /* get the cookie */ sym_lookup("MAGIC_VAR", AWK_SCALAR, & value); /* save the cookie */ @@ -31741,7 +31735,8 @@ 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{api_malloc()}, @code{api_calloc()} or @code{api_realloc()}. +@emph{every} string value's storage @emph{must} come from @code{gawk_malloc()}, +@code{gawk_calloc()} or @code{gawk_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.} @@ -31812,7 +31807,7 @@ Using value cookies in this way saves considerable storage, since all of You might be wondering, ``Is this sharing problematic? What happens if @command{awk} code assigns a new value to @code{VAR1}, -are all the others be changed too?'' +are all the others changed too?'' That's a great question. The answer is that no, it's not a problem. Internally, @command{gawk} uses @dfn{reference-counted strings}. This means @@ -31867,7 +31862,7 @@ with the @code{<stdio.h>} library routines. @itemx @ @ @ @ struct awk_element *next; @itemx @ @ @ @ enum @{ @itemx @ @ @ @ @ @ @ @ AWK_ELEMENT_DEFAULT = 0,@ @ /* set by gawk */ -@itemx @ @ @ @ @ @ @ @ AWK_ELEMENT_DELETE = 1@ @ @ @ /* set by extension if should be deleted */ +@itemx @ @ @ @ @ @ @ @ AWK_ELEMENT_DELETE = 1@ @ @ @ /* set by extension */ @itemx @ @ @ @ @} flags; @itemx @ @ @ @ awk_value_t index; @itemx @ @ @ @ awk_value_t value; @@ -31887,8 +31882,8 @@ an extension to create a linked list of new elements that can then be added to an array in a loop that traverses the list. @item enum @{ @dots{} @} flags; -A set of flag values that convey information between @command{gawk} -and the extension. Currently there is only one: @code{AWK_ELEMENT_DELETE}. +A set of flag values that convey information between the extension +and @command{gawk}. Currently there is only one: @code{AWK_ELEMENT_DELETE}. Setting it causes @command{gawk} to delete the element from the original array upon release of the flattened array. @@ -31899,8 +31894,8 @@ The index and value of the element, respectively. @end table @item typedef struct awk_flat_array @{ -@itemx @ @ @ @ awk_const void *awk_const opaque1;@ @ @ @ /* private data for use by gawk */ -@itemx @ @ @ @ awk_const void *awk_const opaque2;@ @ @ @ /* private data for use by gawk */ +@itemx @ @ @ @ awk_const void *awk_const opaque1;@ @ @ @ /* for use by gawk */ +@itemx @ @ @ @ awk_const void *awk_const opaque2;@ @ @ @ /* for use by gawk */ @itemx @ @ @ @ awk_const size_t count;@ @ @ @ @ /* how many elements */ @itemx @ @ @ @ awk_element_t elements[1];@ @ /* will be extended */ @itemx @} awk_flat_array_t; @@ -31919,7 +31914,7 @@ The following functions relate to individual array elements. @table @code @item awk_bool_t get_element_count(awk_array_t a_cookie, size_t *count); -For the array represented by @code{a_cookie}, return in @code{*count} +For the array represented by @code{a_cookie}, place in @code{*count} the number of elements it contains. A subarray counts as a single element. Return false if there is an error. @@ -31939,7 +31934,8 @@ 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 the API-provided functions @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()} and +the string value of @code{index} must come from @code{gawk_malloc()}, +@code{gawk_calloc()} or @code{gawk_realloc()}, and @command{gawk} releases the storage. @item awk_bool_t set_array_element(awk_array_t a_cookie, @@ -31966,7 +31962,7 @@ not exist in the array. The following functions relate to arrays as a whole: @table @code -@item awk_array_t create_array(); +@item awk_array_t create_array(void); Create a new array to which elements may be added. @xref{Creating Arrays}, for a discussion of how to create a new array and add elements to it. @@ -31983,7 +31979,13 @@ For the array represented by @code{a_cookie}, create an @code{awk_flat_array_t} structure and fill it in. Set the pointer whose address is passed as @code{data} to point to this structure. Return true upon success, or false otherwise. -@xref{Flattening Arrays}, for a discussion of how to +@ifset FOR_PRINT +See the next section +@end ifset +@ifclear FOR_PRINT +@xref{Flattening Arrays}, +@end ifclear +for a discussion of how to flatten an array and work with it. @item awk_bool_t release_flattened_array(awk_array_t a_cookie, @@ -32003,6 +32005,7 @@ for C code to traverse the entire array. Test code in @file{extension/testext.c} does this, and also serves as a nice example showing how to use the APIs. +We walk through that part of the code one step at a time. First, the @command{gawk} script that drives the test extension: @example @@ -32141,8 +32144,7 @@ have this flag bit set: valrep2str(& flat_array->elements[i].value)); if (strcmp(value3.str_value.str, - flat_array->elements[i].index.str_value.str) - == 0) @{ + flat_array->elements[i].index.str_value.str) == 0) @{ flat_array->elements[i].flags |= AWK_ELEMENT_DELETE; printf("dump_array_and_delete: marking element \"%s\" " "for deletion\n", @@ -32246,7 +32248,9 @@ of the array cookie after the call to @code{set_element()}. The following C code is a simple test extension to create an array with two regular elements and with a subarray. The leading @code{#include} -directives and boilerplate variable declarations are omitted for brevity. +directives and boilerplate variable declarations +(@pxref{Extension API Boilerplate}) +are omitted for brevity. The first step is to create a new array and then install it in the symbol table: @@ -32525,12 +32529,12 @@ static awk_bool_t (*init_func)(void) = NULL; /* OR: */ static awk_bool_t -init_my_module(void) +init_my_extension(void) @{ @dots{} @} -static awk_bool_t (*init_func)(void) = init_my_module; +static awk_bool_t (*init_func)(void) = init_my_extension; dl_load_func(func_table, some_name, "name_space_in_quotes") @end example @@ -32573,8 +32577,8 @@ It can then be looped over for multiple calls to @c Use @var{OR} for docbook @item static awk_bool_t (*init_func)(void) = NULL; @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @var{OR} -@itemx static awk_bool_t init_my_module(void) @{ @dots{} @} -@itemx static awk_bool_t (*init_func)(void) = init_my_module; +@itemx static awk_bool_t init_my_extension(void) @{ @dots{} @} +@itemx static awk_bool_t (*init_func)(void) = init_my_extension; If you need to do some initialization work, you should define a function that does it (creates variables, opens files, etc.) and then define the @code{init_func} pointer to point to your @@ -32641,8 +32645,8 @@ path with a list of directories to search for compiled extensions. Two useful functions that are not in @command{awk} are @code{chdir()} (so that an @command{awk} program can change its directory) and @code{stat()} (so that an @command{awk} program can gather information about a file). -This @value{SECTION} implements these functions for @command{gawk} -in an extension. +In order to illustrate the API in action, this @value{SECTION} implements +these functions for @command{gawk} in an extension. @menu * Internal File Description:: What the new functions will do. @@ -32664,8 +32668,7 @@ straightforward. It takes one argument, the new directory to change to: newdir = "/home/arnold/funstuff" ret = chdir(newdir) if (ret < 0) @{ - printf("could not change to %s: %s\n", - newdir, ERRNO) > "/dev/stderr" + printf("could not change to %s: %s\n", newdir, ERRNO) > "/dev/stderr" exit 1 @} @dots{} @@ -32853,7 +32856,7 @@ The second is a pointer to an @code{awk_value_t}, usually named @code{result}. @example -/* do_chdir --- provide dynamically loaded chdir() builtin for gawk */ +/* do_chdir --- provide dynamically loaded chdir() function for gawk */ static awk_value_t * do_chdir(int nargs, awk_value_t *result) @@ -33062,7 +33065,7 @@ for success: @} @} - array_set(array, "type", make_const_string(type, strlen(type), &tmp)); + array_set(array, "type", make_const_string(type, strlen(type), & tmp)); return 0; @} @@ -35670,7 +35673,7 @@ the various PC platforms. @cindex Zoulas, Christos Christos Zoulas provided the @code{extension()} -built-in function for dynamically adding new modules. +built-in function for dynamically adding new functions. (This was obsoleted at @command{gawk} 4.1.) @item @@ -37578,7 +37581,7 @@ make it possible to include them: @enumerate 1 @item Before building the new feature into @command{gawk} itself, -consider writing it as an extension module +consider writing it as an extension (@pxref{Dynamic Extensions}). If that's not possible, continue with the rest of the steps in this list. diff --git a/extension/ChangeLog b/extension/ChangeLog index f324bdeb..c54d3b25 100644 --- a/extension/ChangeLog +++ b/extension/ChangeLog @@ -1,3 +1,8 @@ +2014-09-29 Arnold D. Robbins <arnold@skeeve.com> + + * filefuncs.c: Minor edits to sync with documentation. + * testext.c: Add test to get PROCINFO, expected to fail. + 2014-08-12 Arnold D. Robbins <arnold@skeeve.com> * Makefile.am (RM): Define for makes that don't have it, diff --git a/extension/filefuncs.c b/extension/filefuncs.c index d5249a4e..a20e9ff7 100644 --- a/extension/filefuncs.c +++ b/extension/filefuncs.c @@ -145,7 +145,7 @@ static const char *ext_version = "filefuncs extension: version 1.0"; int plugin_is_GPL_compatible; -/* do_chdir --- provide dynamically loaded chdir() builtin for gawk */ +/* do_chdir --- provide dynamically loaded chdir() function for gawk */ static awk_value_t * do_chdir(int nargs, awk_value_t *result) @@ -448,7 +448,7 @@ fill_stat_array(const char *name, awk_array_t array, struct stat *sbuf) } } - array_set(array, "type", make_const_string(type, strlen(type), &tmp)); + array_set(array, "type", make_const_string(type, strlen(type), & tmp)); return 0; } diff --git a/extension/testext.c b/extension/testext.c index 2dda339f..7462265b 100644 --- a/extension/testext.c +++ b/extension/testext.c @@ -302,6 +302,12 @@ var_test(int nargs, awk_value_t *result) goto out; } + /* look up PROCINFO - should fail */ + if (sym_lookup("PROCINFO", AWK_ARRAY, & value)) + printf("var_test: sym_lookup of PROCINFO failed - got a value!\n"); + else + printf("var_test: sym_lookup of PROCINFO passed - did not get a value\n"); + /* look up a reserved variable - should pass */ if (sym_lookup("ARGC", AWK_NUMBER, & value)) printf("var_test: sym_lookup of ARGC passed - got a value!\n"); @@ -865,17 +865,17 @@ static awk_bool_t (*init_func)(void) = NULL; /* OR: */ static awk_bool_t -init_my_module(void) +init_my_extension(void) { ... } -static awk_bool_t (*init_func)(void) = init_my_module; +static awk_bool_t (*init_func)(void) = init_my_extension; dl_load_func(func_table, some_name, "name_space_in_quotes") #endif -#define dl_load_func(func_table, module, name_space) \ +#define dl_load_func(func_table, extension, name_space) \ int dl_load(const gawk_api_t *const api_p, awk_ext_id_t id) \ { \ size_t i, j; \ @@ -886,7 +886,7 @@ int dl_load(const gawk_api_t *const api_p, awk_ext_id_t id) \ \ if (api->major_version != GAWK_API_MAJOR_VERSION \ || api->minor_version < GAWK_API_MINOR_VERSION) { \ - fprintf(stderr, #module ": version mismatch with gawk!\n"); \ + fprintf(stderr, #extension ": version mismatch with gawk!\n"); \ fprintf(stderr, "\tmy version (%d, %d), gawk version (%d, %d)\n", \ GAWK_API_MAJOR_VERSION, GAWK_API_MINOR_VERSION, \ api->major_version, api->minor_version); \ @@ -898,7 +898,7 @@ int dl_load(const gawk_api_t *const api_p, awk_ext_id_t id) \ if (func_table[i].name == NULL) \ break; \ if (! add_ext_func(name_space, & func_table[i])) { \ - warning(ext_id, #module ": could not add %s\n", \ + warning(ext_id, #extension ": could not add %s\n", \ func_table[i].name); \ errors++; \ } \ @@ -906,7 +906,7 @@ int dl_load(const gawk_api_t *const api_p, awk_ext_id_t id) \ \ if (init_func != NULL) { \ if (! init_func()) { \ - warning(ext_id, #module ": initialization function failed\n"); \ + warning(ext_id, #extension ": initialization function failed\n"); \ errors++; \ } \ } \ diff --git a/test/ChangeLog b/test/ChangeLog index fda75ee8..b221bf2f 100644 --- a/test/ChangeLog +++ b/test/ChangeLog @@ -1,3 +1,7 @@ +2014-09-29 Arnold D. Robbins <arnold@skeeve.com> + + * testext.ok: Adjusted after minor code change. + 2014-09-27 Arnold D. Robbins <arnold@skeeve.com> * profile2.ok, profile3.ok, profile4.ok, profile5.ok: diff --git a/test/testext.ok b/test/testext.ok index 5612e92c..9b36bf72 100644 --- a/test/testext.ok +++ b/test/testext.ok @@ -15,6 +15,7 @@ try_modify_environ: set_array_element of ENVIRON failed try_modify_environ: marking element "testext" for deletion try_del_environ() could not delete element - pass try_del_environ() could not add an element - pass +var_test: sym_lookup of PROCINFO passed - did not get a value var_test: sym_lookup of ARGC passed - got a value! var_test: sym_update of ARGC failed - correctly var_test: sym_update("testvar") succeeded |