[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[gawk-diffs] [SCM] gawk branch, gawk-4.1-stable, updated. gawk-4.1.0-586
|
From: |
Arnold Robbins |
|
Subject: |
[gawk-diffs] [SCM] gawk branch, gawk-4.1-stable, updated. gawk-4.1.0-586-g2f49027 |
|
Date: |
Wed, 11 Feb 2015 21:21:48 +0000 |
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "gawk".
The branch, gawk-4.1-stable has been updated
via 2f49027b6d6b1f03ae07c5cd9625b072465079bd (commit)
from 9478ffc5b7ae6988bb109a7be9189ed02f3720e8 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
http://git.sv.gnu.org/cgit/gawk.git/commit/?id=2f49027b6d6b1f03ae07c5cd9625b072465079bd
commit 2f49027b6d6b1f03ae07c5cd9625b072465079bd
Author: Arnold D. Robbins <address@hidden>
Date: Wed Feb 11 23:21:28 2015 +0200
O'Reilly edits, through Chapter 16.
diff --git a/ChangeLog b/ChangeLog
index 9d17537..773afd3 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2015-02-11 Arnold D. Robbins <address@hidden>
+
+ * gawkapi.h: Fix spelling error in comment.
+
2015-02-07 Arnold D. Robbins <address@hidden>
* regcomp.c, regex.c, regex.h, regex_internal.c, regex_internal.h,
diff --git a/doc/ChangeLog b/doc/ChangeLog
index c62d302..9af9ef0 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,7 @@
+2015-02-11 Arnold D. Robbins <address@hidden>
+
+ * gawktexi.in: O'Reilly fixes.
+
2015-02-10 Arnold D. Robbins <address@hidden>
* gawktexi.in: Minor fixes, O'Reilly fixes.
diff --git a/doc/gawk.info b/doc/gawk.info
index eb8d07b..8061bbd 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -23071,7 +23071,7 @@ first.
If you know that you wish to use the same numeric or string _value_ for
one or more variables, you can create the value once, retaining a
"value cookie" for it, and then pass in that value cookie whenever you
-wish to set the value of a variable. This both storage space within
+wish to set the value of a variable. This saves storage space within
the running `gawk' process and reduces the time needed to create the
value.
@@ -23108,7 +23108,7 @@ prototypes, in the way that extension code would use
them:
`void gawk_free(void *ptr);'
Call the correct version of `free()' to release storage that was
- allocated with `gawk_malloc()', `gawk_calloc()' or
+ allocated with `gawk_malloc()', `gawk_calloc()', or
`gawk_realloc()'.
The API has to provide these functions because it is possible for an
@@ -23120,7 +23120,7 @@ version of `malloc()', unexpected behavior would likely
result.
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.
+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:
@@ -23150,13 +23150,13 @@ as if they were procedure calls that do not return a
value.
make_malloced_string(message, strlen(message), & result);
`#define erealloc(pointer, type, size, message) ...'
- This is like `emalloc()', but it calls `gawk_realloc()', instead
- of `gawk_malloc()'. The arguments are the same as for the
+ This is like `emalloc()', but it calls `gawk_realloc()' instead of
+ `gawk_malloc()'. The arguments are the same as for the
`emalloc()' macro.
---------- Footnotes ----------
- (1) This is more common on MS-Windows systems, but can happen on
+ (1) This is more common on MS-Windows systems, but it can happen on
Unix-like systems as well.
@@ -23182,7 +23182,7 @@ extension code would use them:
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 `gawk_malloc()',
- `gawk_calloc()' or `gawk_realloc()'. The idea here is that the
+ `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'.
@@ -23232,7 +23232,7 @@ Extension functions are described by the following
record:
The fields are:
`const char *name;'
- The name of the new function. `awk' level code calls the function
+ The name of the new function. `awk'-level code calls the function
by this name. This is a regular C string.
Function names must obey the rules for `awk' identifiers. That is,
@@ -23244,7 +23244,7 @@ Extension functions are described by the following
record:
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 one of
+ 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
@@ -23291,10 +23291,10 @@ function with `gawk' using the following function:
`gawk' intends to pass to the `exit()' system call.
`arg0'
- A pointer to private data which `gawk' saves in order to pass
+ A pointer to private data that `gawk' saves in order to pass
to the function pointed to by `funcp'.
- Exit callback functions are called in last-in-first-out (LIFO)
+ Exit callback functions are called in last-in, first-out (LIFO)
order--that is, in the reverse order in which they are registered with
`gawk'.
@@ -23304,8 +23304,8 @@ File: gawk.info, Node: Extension Version String,
Next: Input Parsers, Prev: E
16.4.5.3 Registering An Extension Version String
................................................
-You can register a version string which indicates the name and version
-of your extension, with `gawk', as follows:
+You can register a version string that indicates the name and version
+of your extension with `gawk', as follows:
`void register_ext_version(const char *version);'
Register the string pointed to by `version' with `gawk'. Note
@@ -23328,7 +23328,7 @@ Files::). Additionally, it sets the value of `RT'
(*note Built-in
Variables::).
If you want, you can provide your own custom input parser. An input
-parser's job is to return a record to the `gawk' record processing
+parser's job is to return a record to the `gawk' record-processing
code, along with indicators for the value and length of the data to be
used for `RT', if any.
@@ -23345,10 +23345,10 @@ used for `RT', if any.
`awk_bool_t XXX_take_control_of(awk_input_buf_t *iobuf);'
When `gawk' decides to hand control of the file over to the input
parser, it calls this function. This function in turn must fill
- in certain fields in the `awk_input_buf_t' structure, and ensure
+ in certain fields in the `awk_input_buf_t' structure and ensure
that certain conditions are true. It should then return true. If
- an error of some kind occurs, it should not fill in any fields,
- and should return false; then `gawk' will not use the input parser.
+ an error of some kind occurs, it should not fill in any fields and
+ should return false; then `gawk' will not use the input parser.
The details are presented shortly.
Your extension should package these functions inside an
@@ -23425,10 +23425,10 @@ the `struct stat', or any combination of these
factors.
Once `XXX_can_take_file()' has returned true, and `gawk' has decided
to use your input parser, it calls `XXX_take_control_of()'. That
-function then fills one of either the `get_record' field or the
-`read_func' field in the `awk_input_buf_t'. It must also ensure that
-`fd' is _not_ set to `INVALID_HANDLE'. The following list describes
-the fields that may be filled by `XXX_take_control_of()':
+function then fills either the `get_record' field or the `read_func'
+field in the `awk_input_buf_t'. It must also ensure that `fd' is _not_
+set to `INVALID_HANDLE'. The following list describes the fields that
+may be filled by `XXX_take_control_of()':
`void *opaque;'
This is used to hold any state information needed by the input
@@ -23445,22 +23445,22 @@ the fields that may be filled by
`XXX_take_control_of()':
Its behavior is described in the text following this list.
`ssize_t (*read_func)();'
- This function pointer should point to function that has the same
+ This function pointer should point to a function that has the same
behavior as the standard POSIX `read()' system call. It is an
alternative to the `get_record' pointer. Its behavior is also
described in the text following this list.
`void (*close_func)(struct awk_input *iobuf);'
This function pointer should point to a function that does the
- "tear down." It should release any resources allocated by
+ "teardown." It should release any resources allocated by
`XXX_take_control_of()'. It may also close the file. If it does
so, it should set the `fd' field to `INVALID_HANDLE'.
If `fd' is still not `INVALID_HANDLE' after the call to this
function, `gawk' calls the regular `close()' system call.
- Having a "tear down" function is optional. If your input parser
- does not need it, do not set this field. Then, `gawk' calls the
+ Having a "teardown" function is optional. If your input parser does
+ not need it, do not set this field. Then, `gawk' calls the
regular `close()' system call on the file descriptor, so it should
be valid.
@@ -23468,7 +23468,7 @@ the fields that may be filled by
`XXX_take_control_of()':
records. The parameters are as follows:
`char **out'
- This is a pointer to a `char *' variable which is set to point to
+ This is a pointer to a `char *' variable that is set to point to
the record. `gawk' makes its own copy of the data, so the
extension must manage this storage.
@@ -23517,16 +23517,16 @@ explicitly.
NOTE: You must choose one method or the other: either a function
that returns a record, or one that returns raw data. In
particular, if you supply a function to get a record, `gawk' will
- call it, and never call the raw read function.
+ call it, and will never call the raw read function.
`gawk' ships with a sample extension that reads directories,
-returning records for each entry in the directory (*note Extension
-Sample Readdir::). You may wish to use that code as a guide for writing
-your own input parser.
+returning records for each entry in a directory (*note Extension Sample
+Readdir::). You may wish to use that code as a guide for writing your
+own input parser.
When writing an input parser, you should think about (and document)
how it is expected to interact with `awk' code. You may want it to
-always be called, and take effect as appropriate (as the `readdir'
+always be called, and to take effect as appropriate (as the `readdir'
extension does). Or you may want it to take effect based upon the
value of an `awk' variable, as the XML extension from the `gawkextlib'
project does (*note gawkextlib::). In the latter case, code in a
@@ -23626,17 +23626,17 @@ in the `awk_output_buf_t'. The data members are as
follows:
These pointers should be set to point to functions that perform
the equivalent function as the `<stdio.h>' functions do, if
appropriate. `gawk' uses these function pointers for all output.
- `gawk' initializes the pointers to point to internal, "pass
- through" functions that just call the regular `<stdio.h>'
- functions, so an extension only needs to redefine those functions
- that are appropriate for what it does.
+ `gawk' initializes the pointers to point to internal "pass-through"
+ functions that just call the regular `<stdio.h>' functions, so an
+ extension only needs to redefine those functions that are
+ appropriate for what it does.
The `XXX_can_take_file()' function should make a decision based upon
the `name' and `mode' fields, and any additional state (such as `awk'
variable values) that is appropriate.
When `gawk' calls `XXX_take_control_of()', that function should fill
-in the other fields, as appropriate, except for `fp', which it should
+in the other fields as appropriate, except for `fp', which it should
just use normally.
You register your output wrapper with the following function:
@@ -23673,16 +23673,17 @@ structures as described earlier.
The name of the two-way processor.
`awk_bool_t (*can_take_two_way)(const char *name);'
- This function returns true if it wants to take over two-way I/O
- for this file name. It should not change any state (variable
- values, etc.) within `gawk'.
+ The function pointed to by this field should return true if it
+ wants to take over two-way I/O for this file name. It should not
+ change any state (variable values, etc.) within `gawk'.
`awk_bool_t (*take_control_of)(const char *name,'
` awk_input_buf_t *inbuf,'
` awk_output_buf_t *outbuf);'
- This function should fill in the `awk_input_buf_t' and
- `awk_outut_buf_t' structures pointed to by `inbuf' and `outbuf',
- respectively. These structures were described earlier.
+ The function pointed to by this field should fill in the
+ `awk_input_buf_t' and `awk_outut_buf_t' structures pointed to by
+ `inbuf' and `outbuf', respectively. These structures were
+ described earlier.
`awk_const struct two_way_processor *awk_const next;'
This is for use by `gawk'; therefore it is marked `awk_const' so
@@ -23706,7 +23707,7 @@ File: gawk.info, Node: Printing Messages, Next:
Updating `ERRNO', Prev: Regis
You can print different kinds of warning messages from your extension,
as described here. Note that for these functions, you must pass in the
-extension id received from `gawk' when the extension was loaded:(1)
+extension ID received from `gawk' when the extension was loaded:(1)
`void fatal(awk_ext_id_t id, const char *format, ...);'
Print a message and then cause `gawk' to exit immediately.
@@ -23762,7 +23763,7 @@ 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
+message or reissue the request for the actual value type, as
appropriate. This behavior is summarized in *note
table-value-types-returned::.
@@ -23771,15 +23772,15 @@ table-value-types-returned::.
String Number Array Undefined
------------------------------------------------------------------------------
- String String String false false
- Number Number if can Number false false
+ 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
+Type Array False False Array False
+Requested Scalar Scalar Scalar False False
Undefined String Number Array Undefined
- Value false false false false
- Cookie
+ Value False False False False
+ cookie
Table 16.1: API value types returned
@@ -23796,16 +23797,16 @@ your extension function. They are:
` awk_valtype_t wanted,'
` awk_value_t *result);'
Fill in the `awk_value_t' structure pointed to by `result' with
- the `count''th argument. 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.). Counts are zero based--the first
+ the `count'th argument. Return true if the actual type matches
+ `wanted', and false otherwise. In the latter case,
+ `result->val_type' indicates the actual type (*note Table 16.1:
+ table-value-types-returned.). Counts are zero-based--the first
argument is numbered zero, the second one, and so on. `wanted'
indicates the type of value expected.
`awk_bool_t set_argument(size_t count, awk_array_t array);'
Convert a parameter that was undefined into an array; this provides
- call-by-reference for arrays. Return false if `count' is too big,
+ call by reference for arrays. Return false if `count' is too big,
or if the argument's type is not undefined. *Note Array
Manipulation::, for more information on creating arrays.
@@ -23833,8 +23834,8 @@ File: gawk.info, Node: Symbol table by name, Next:
Symbol table by cookie, Up
The following routines provide the ability to access and update global
`awk'-level variables by name. In compiler terminology, identifiers of
different kinds are termed "symbols", thus the "sym" in the routines'
-names. The data structure which stores information about symbols is
-termed a "symbol table".
+names. The data structure that stores information about symbols is
+termed a "symbol table". The functions are as follows:
`awk_bool_t sym_lookup(const char *name,'
` awk_valtype_t wanted,'
@@ -23842,14 +23843,14 @@ 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.
- In the latter case, `result->val_type' indicates the actual type
- (*note Table 16.1: table-value-types-returned.).
+ Return true if the actual type matches `wanted', and false
+ otherwise. In the latter case, `result->val_type' indicates the
+ actual type (*note Table 16.1: table-value-types-returned.).
`awk_bool_t sym_update(const char *name, awk_value_t *value);'
Update the variable named by the string `name', which is a regular
C string. The variable is added to `gawk''s symbol table if it is
- not there. Return true if everything worked, false otherwise.
+ not there. Return true if everything worked, and false otherwise.
Changing types (scalar to array or vice versa) of an existing
variable is _not_ allowed, nor may this routine be used to update
@@ -23874,7 +23875,7 @@ File: gawk.info, Node: Symbol table by cookie, Next:
Cached values, Prev: Sym
A "scalar cookie" is an opaque handle that provides access to a global
variable or array. It is an optimization that avoids looking up
variables in `gawk''s symbol table every time access is needed. This
-was discussed earlier in *note General Data Types::.
+was discussed earlier, in *note General Data Types::.
The following functions let you work with scalar cookies:
@@ -23985,7 +23986,7 @@ File: gawk.info, Node: Cached values, Prev: Symbol
table by cookie, Up: Symbo
..........................................
The routines in this section allow you to create and release cached
-values. As with scalar cookies, in theory, cached values are not
+values. Like scalar cookies, in theory, cached values are not
necessary. You can create numbers and strings using the functions in
*note Constructor Functions::. You can then assign those values to
variables using `sym_update()' or `sym_update_scalar()', as you like.
@@ -24056,7 +24057,7 @@ Using value cookies in this way saves considerable
storage, as 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 changed
+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.
@@ -24175,7 +24176,7 @@ File: gawk.info, Node: Array Functions, Next:
Flattening Arrays, Prev: Array
16.4.11.2 Array Functions
.........................
-The following functions relate to individual array elements.
+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', place in `*count' the
@@ -24193,13 +24194,14 @@ The following functions relate to individual array
elements.
(*note Table 16.1: table-value-types-returned.).
The value for `index' can be numeric, in which case `gawk'
- converts it to a string. Using non-integral values is possible, but
+ converts it to a string. Using nonintegral values is possible, but
requires that you understand how such values are converted to
- strings (*note Conversion::); thus using integral values is safest.
+ 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 `gawk_malloc()',
- `gawk_calloc()' or `gawk_realloc()', and `gawk' releases the
+ `gawk_calloc()', or `gawk_realloc()', and `gawk' releases the
storage.
`awk_bool_t set_array_element(awk_array_t a_cookie,'
@@ -24243,9 +24245,9 @@ The following functions relate to individual array
elements.
`awk_bool_t release_flattened_array(awk_array_t a_cookie,'
` awk_flat_array_t *data);'
When done with a flattened array, release the storage using this
- function. You must pass in both the original array cookie, and
- the address of the created `awk_flat_array_t' structure. The
- function returns true upon success, false otherwise.
+ function. You must pass in both the original array cookie and the
+ address of the created `awk_flat_array_t' structure. The function
+ returns true upon success, false otherwise.
File: gawk.info, Node: Flattening Arrays, Next: Creating Arrays, Prev:
Array Functions, Up: Array Manipulation
@@ -24255,8 +24257,8 @@ File: gawk.info, Node: Flattening Arrays, Next:
Creating Arrays, Prev: Array
To "flatten" an array is to create a structure that represents the full
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.
+array. Some of the code in `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 `gawk' script that drives the test extension:
@@ -24305,9 +24307,8 @@ number of arguments:
}
The function then proceeds in steps, as follows. First, retrieve the
-name of the array, passed as the first argument. Then retrieve the
-array itself. If either operation fails, print error messages and
-return:
+name of the array, passed as the first argument, followed by the array
+itself. If either operation fails, print an error message and return:
/* get argument named array as flat array and print it */
if (get_argument(0, AWK_STRING, & value)) {
@@ -24337,9 +24338,9 @@ count of elements in the array and print it:
printf("dump_array_and_delete: incoming size is %lu\n",
(unsigned long) count);
- The third step is to actually flatten the array, and then to double
-check that the count in the `awk_flat_array_t' is the same as the count
-just retrieved:
+ The third step is to actually flatten the array, and then to
+double-check that the count in the `awk_flat_array_t' is the same as
+the count just retrieved:
if (! flatten_array(value2.array_cookie, & flat_array)) {
printf("dump_array_and_delete: could not flatten array\n");
@@ -24356,7 +24357,7 @@ just retrieved:
The fourth step is to retrieve the index of the element to be
deleted, which was passed as the second argument. Remember that
-argument counts passed to `get_argument()' are zero-based, thus the
+argument counts passed to `get_argument()' are zero-based, and thus the
second argument is numbered one:
if (! get_argument(1, AWK_STRING, & value3)) {
@@ -24369,7 +24370,7 @@ over every element in the array, printing the index and
element values.
In addition, upon finding the element with the index that is supposed
to be deleted, the function sets the `AWK_ELEMENT_DELETE' bit in the
`flags' field of the element. When the array is released, `gawk'
-traverses the flattened array, and deletes any elements which have this
+traverses the flattened array, and deletes any elements that have this
flag bit set:
for (i = 0; i < flat_array->count; i++) {
@@ -24587,10 +24588,10 @@ The API provides both a "major" and a "minor" version
number. The API
versions are available at compile time as constants:
`GAWK_API_MAJOR_VERSION'
- The major version of the API.
+ The major version of the API
`GAWK_API_MINOR_VERSION'
- The minor version of the API.
+ The minor version of the API
The minor version increases when new functions are added to the API.
Such new functions are always added to the end of the API `struct'.
@@ -24605,13 +24606,13 @@ For this reason, the major and minor API versions of
the running `gawk'
are included in the API `struct' as read-only constant integers:
`api->major_version'
- The major version of the running `gawk'.
+ The major version of the running `gawk'
`api->minor_version'
- The minor version of the running `gawk'.
+ The minor version of the running `gawk'
It is up to the extension to decide if there are API
-incompatibilities. Typically a check like this is enough:
+incompatibilities. Typically, a check like this is enough:
if (api->major_version != GAWK_API_MAJOR_VERSION
|| api->minor_version < GAWK_API_MINOR_VERSION) {
@@ -24623,7 +24624,7 @@ incompatibilities. Typically a check like this is
enough:
}
Such code is included in the boilerplate `dl_load_func()' macro
-provided in `gawkapi.h' (discussed later, in *note Extension API
+provided in `gawkapi.h' (discussed in *note Extension API
Boilerplate::).
@@ -24674,7 +24675,7 @@ functions) toward the top of your source file, using
predefined names
as described here. The boilerplate needed is also provided in comments
in the `gawkapi.h' header file:
- /* Boiler plate code: */
+ /* Boilerplate code: */
int plugin_is_GPL_compatible;
static gawk_api_t *const api;
@@ -24724,7 +24725,7 @@ in the `gawkapi.h' header file:
to point to a string giving the name and version of your extension.
`static awk_ext_func_t func_table[] = { ... };'
- This is an array of one or more `awk_ext_func_t' structures as
+ This is an array of one or more `awk_ext_func_t' structures, as
described earlier (*note Extension Functions::). It can then be
looped over for multiple calls to `add_ext_func()'.
@@ -24837,7 +24838,7 @@ appropriate information:
`stat()' fails. It fills in the following elements:
`"name"'
- The name of the file that was `stat()''ed.
+ The name of the file that was `stat()'ed.
`"dev"'
`"ino"'
@@ -24885,7 +24886,7 @@ appropriate information:
The file is a directory.
`"fifo"'
- The file is a named-pipe (also known as a FIFO).
+ The file is a named pipe (also known as a FIFO).
`"file"'
The file is just a regular file.
@@ -24905,7 +24906,7 @@ appropriate information:
systems, "a priori" knowledge is used to provide a value. Where no
value can be determined, it defaults to 512.
- Several additional elements may be present depending upon the
+ Several additional elements may be present, depending upon the
operating system and the type of the file. You can test for them in
your `awk' program by using the `in' operator (*note Reference to
Elements::):
@@ -24934,9 +24935,9 @@ File: gawk.info, Node: Internal File Ops, Next: Using
Internal File Ops, Prev
Here is the C code for these extensions.(1)
The file includes a number of standard header files, and then
-includes the `gawkapi.h' header file which provides the API definitions.
-Those are followed by the necessary variable declarations to make use
-of the API macros and boilerplate code (*note Extension API
+includes the `gawkapi.h' header file, which provides the API
+definitions. Those are followed by the necessary variable declarations
+to make use of the API macros and boilerplate code (*note Extension API
Boilerplate::):
#ifdef HAVE_CONFIG_H
@@ -24972,9 +24973,9 @@ Boilerplate::):
By convention, for an `awk' function `foo()', the C function that
implements it is called `do_foo()'. The function should have two
-arguments: the first is an `int' usually called `nargs', that
+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':
+is a pointer to an `awk_value_t' structure, usually named `result':
/* do_chdir --- provide dynamically loaded chdir() function for gawk */
@@ -25010,8 +25011,8 @@ is numbered zero.
}
The `stat()' extension is more involved. First comes a function
-that turns a numeric mode into a printable representation (e.g., 644
-becomes `-rw-r--r--'). This is omitted here for brevity:
+that turns a numeric mode into a printable representation (e.g., octal
+`0644' becomes `-rw-r--r--'). This is omitted here for brevity:
/* format_mode --- turn a stat mode field into something readable */
@@ -25061,8 +25062,8 @@ contain the result of the `stat()':
The following function does most of the work to fill in the
`awk_array_t' result array with values obtained from a valid `struct
-stat'. It is done in a separate function to support the `stat()'
-function for `gawk' and also to support the `fts()' extension which is
+stat'. This work is done in a separate function to support the `stat()'
+function for `gawk' and also to support the `fts()' extension, which is
included in the same file but whose code is not shown here (*note
Extension Sample File Functions::).
@@ -25174,8 +25175,8 @@ argument is optional. If present, it causes `do_stat()'
to use the
`stat()' system call instead of the `lstat()' system call. This is
done by using a function pointer: `statfunc'. `statfunc' is
initialized to point to `lstat()' (instead of `stat()') to get the file
-information, in case the file is a symbolic link. However, if there
-were three arguments, `statfunc' is set point to `stat()', instead.
+information, in case the file is a symbolic link. However, if the third
+argument is included, `statfunc' is set to point to `stat()', instead.
Here is the `do_stat()' function, which starts with variable
declarations and argument checking:
@@ -25224,7 +25225,7 @@ returns:
/* always empty out the array */
clear_array(array);
- /* stat the file, if error, set ERRNO and return */
+ /* stat the file; if error, set ERRNO and return */
ret = statfunc(name, & sbuf);
if (ret < 0) {
update_ERRNO_int(errno);
@@ -25243,7 +25244,8 @@ When done, the function returns the result from
`fill_stat_array()':
function(s) into `gawk'.
The `filefuncs' extension also provides an `fts()' function, which
-we omit here. For its sake there is an initialization function:
+we omit here (*note Extension Sample File Functions::). For its sake,
+there is an initialization function:
/* init_filefuncs --- initialization routine */
@@ -25367,9 +25369,9 @@ File: gawk.info, Node: Extension Samples, Next:
gawkextlib, Prev: Extension E
16.7 The Sample Extensions in the `gawk' Distribution
=====================================================
-This minor node provides brief overviews of the sample extensions that
+This minor node provides a brief overview of the sample extensions that
come in the `gawk' distribution. Some of them are intended for
-production use (e.g., the `filefuncs', `readdir' and `inplace'
+production use (e.g., the `filefuncs', `readdir', and `inplace'
extensions). Others mainly provide example code that shows how to use
the extension API.
@@ -25406,13 +25408,13 @@ follows. The usage is:
`result = chdir("/some/directory")'
The `chdir()' function is a direct hook to the `chdir()' system
call to change the current directory. It returns zero upon
- success or less than zero upon error. In the latter case, it
- updates `ERRNO'.
+ success or a value less than zero upon error. In the latter case,
+ it updates `ERRNO'.
`result = stat("/some/path", statdata' [`, follow']`)'
The `stat()' function provides a hook into the `stat()' system
- call. It returns zero upon success or less than zero upon error.
- In the latter case, it updates `ERRNO'.
+ call. It returns zero upon success or a value less than zero upon
+ error. In the latter case, it updates `ERRNO'.
By default, it uses the `lstat()' system call. However, if passed
a third argument, it uses `stat()' instead.
@@ -25439,23 +25441,23 @@ follows. The usage is:
`"minor"' `st_minor' Device files
`"blksize"'`st_blksize' All
`"pmode"' A human-readable version of the All
- mode value, such as printed by
- `ls'. For example,
- `"-rwxr-xr-x"'
+ mode value, like that printed by
+ `ls' (for example,
+ `"-rwxr-xr-x"')
`"linkval"'The value of the symbolic link Symbolic
links
- `"type"' The type of the file as a string. All
- One of `"file"', `"blockdev"',
- `"chardev"', `"directory"',
- `"socket"', `"fifo"', `"symlink"',
- `"door"', or `"unknown"'. Not
- all systems support all file
- types.
+ `"type"' The type of the file as a All
+ string--one of `"file"',
+ `"blockdev"', `"chardev"',
+ `"directory"', `"socket"',
+ `"fifo"', `"symlink"', `"door"',
+ or `"unknown"' (not all systems
+ support all file types)
`flags = or(FTS_PHYSICAL, ...)'
`result = fts(pathlist, flags, filedata)'
Walk the file trees provided in `pathlist' and fill in the
- `filedata' array as described next. `flags' is the bitwise OR of
+ `filedata' array, as described next. `flags' is the bitwise OR of
several predefined values, also described in a moment. Return
zero if there were no errors, otherwise return -1.
@@ -25508,10 +25510,11 @@ requested hierarchies.
filesystem.
`filedata'
- The `filedata' array is first cleared. Then, `fts()' creates an
- element in `filedata' for every element in `pathlist'. The index
- is the name of the directory or file given in `pathlist'. The
- element for this index is itself an array. There are two cases:
+ The `filedata' array holds the results. `fts()' first clears it.
+ Then it creates an element in `filedata' for every element in
+ `pathlist'. The index is the name of the directory or file given
+ in `pathlist'. The element for this index is itself an array.
+ There are two cases:
_The path is a file_
In this case, the array contains two or three elements:
@@ -25547,7 +25550,7 @@ requested hierarchies.
elements as for a file: `"path"', `"stat"', and `"error"'.
The `fts()' function returns zero if there were no errors.
-Otherwise it returns -1.
+Otherwise, it returns -1.
NOTE: The `fts()' extension does not exactly mimic the interface
of the C library `fts()' routines, choosing instead to provide an
@@ -25586,14 +25589,14 @@ adds one constant (`FNM_NOMATCH'), and an array of
flag values named
The arguments to `fnmatch()' are:
`pattern'
- The file name wildcard to match.
+ The file name wildcard to match
`string'
- The file name string.
+ The file name string
`flag'
Either zero, or the bitwise OR of one or more of the flags in the
- `FNM' array.
+ `FNM' array
The flags are as follows:
@@ -25627,13 +25630,13 @@ The `fork' extension adds three functions, as follows:
`pid = fork()'
This function creates a new process. The return value is zero in
- the child and the process-ID number of the child in the parent, or
+ the child and the process ID number of the child in the parent, or
-1 upon error. In the latter case, `ERRNO' indicates the problem.
In the child, `PROCINFO["pid"]' and `PROCINFO["ppid"]' are updated
to reflect the correct values.
`ret = waitpid(pid)'
- This function takes a numeric argument, which is the process-ID to
+ This function takes a numeric argument, which is the process ID to
wait for. The return value is that of the `waitpid()' system call.
`ret = wait()'
@@ -25657,8 +25660,8 @@ File: gawk.info, Node: Extension Sample Inplace,
Next: Extension Sample Ord,
16.7.4 Enabling In-Place File Editing
-------------------------------------
-The `inplace' extension emulates GNU `sed''s `-i' option which performs
-"in place" editing of each input file. It uses the bundled
+The `inplace' extension emulates GNU `sed''s `-i' option, which
+performs "in-place" editing of each input file. It uses the bundled
`inplace.awk' include file to invoke the extension properly:
# inplace --- load and invoke the inplace extension.
@@ -25741,11 +25744,11 @@ returned as a record.
The record consists of three fields. The first two are the inode
number and the file name, separated by a forward slash character. On
systems where the directory entry contains the file type, the record
-has a third field (also separated by a slash) which is a single letter
+has a third field (also separated by a slash), which is a single letter
indicating the type of the file. The letters and their corresponding
file types are shown in *note table-readdir-file-types::.
-Letter File Type
+Letter File type
--------------------------------------------------------------------------
`b' Block device
`c' Character device
@@ -25792,7 +25795,7 @@ unwary. Here is an example:
print "don't panic" > "/dev/stdout"
}
- The output from this program is: `cinap t'nod'.
+ The output from this program is `cinap t'nod'.
File: gawk.info, Node: Extension Sample Rev2way, Next: Extension Sample Read
write array, Prev: Extension Sample Revout, Up: Extension Samples
@@ -25840,7 +25843,7 @@ The `rwarray' extension adds two functions, named
`writea()' and
`reada()' is the inverse of `writea()'; it reads the file named as
its first argument, filling in the array named as the second
argument. It clears the array first. Here too, the return value
- is one on success and zero upon failure.
+ is one on success, or zero upon failure.
The array created by `reada()' is identical to that written by
`writea()' in the sense that the contents are the same. However, due to
@@ -25924,7 +25927,7 @@ The `time' extension adds two functions, named
`gettimeofday()' and
Attempt to sleep for SECONDS seconds. If SECONDS is negative, or
the attempt to sleep fails, return -1 and set `ERRNO'. Otherwise,
return zero after sleeping for the indicated amount of time. Note
- that SECONDS may be a floating-point (non-integral) value.
+ that SECONDS may be a floating-point (nonintegral) value.
Implementation details: depending on platform availability, this
function tries to use `nanosleep()' or `select()' to implement the
delay.
@@ -25952,7 +25955,9 @@ provides a number of `gawk' extensions, including one
for processing
XML files. This is the evolution of the original `xgawk' (XML `gawk')
project.
- As of this writing, there are six extensions:
+ As of this writing, there are seven extensions:
+
+ * `errno' extension
* GD graphics library extension
@@ -25961,7 +25966,7 @@ project.
* PostgreSQL extension
* MPFR library extension (this provides access to a number of MPFR
- functions which `gawk''s native MPFR support does not)
+ functions that `gawk''s native MPFR support does not)
* Redis extension
@@ -26002,7 +26007,7 @@ follows. First, build and install `gawk':
If you have installed `gawk' in the standard way, then you will
likely not need the `--with-gawk' option when configuring `gawkextlib'.
-You may also need to use the `sudo' utility to install both `gawk' and
+You may need to use the `sudo' utility to install both `gawk' and
`gawkextlib', depending upon how your system works.
If you write an extension that you wish to share with other `gawk'
@@ -26024,7 +26029,7 @@ File: gawk.info, Node: Extension summary, Next:
Extension Exercises, Prev: ga
a variable named `plugin_is_GPL_compatible'.
* Communication between `gawk' and an extension is two-way. `gawk'
- passes a `struct' to the extension which contains various data
+ passes a `struct' to the extension that contains various data
fields and function pointers. The extension can then call into
`gawk' via the supplied function pointers to accomplish certain
tasks.
@@ -26035,7 +26040,7 @@ File: gawk.info, Node: Extension summary, Next:
Extension Exercises, Prev: ga
convention, implementation functions are named `do_XXXX()' for
some `awk'-level function `XXXX()'.
- * The API is defined in a header file named `gawkpi.h'. You must
+ * The API is defined in a header file named `gawkapi.h'. You must
include a number of standard header files _before_ including it in
your source file.
@@ -26065,16 +26070,16 @@ File: gawk.info, Node: Extension summary, Next:
Extension Exercises, Prev: ga
* Manipulating arrays (retrieving, adding, deleting, and
modifying elements; getting the count of elements in an array;
creating a new array; clearing an array; and flattening an
- array for easy C style looping over all its indices and
+ array for easy C-style looping over all its indices and
elements)
* The API defines a number of standard data types for representing
`awk' values, array elements, and arrays.
- * The API provide convenience functions for constructing values. It
- also provides memory management functions to ensure compatibility
- between memory allocated by `gawk' and memory allocated by an
- extension.
+ * The API provides convenience functions for constructing values.
+ It also provides memory management functions to ensure
+ compatibility between memory allocated by `gawk' and memory
+ allocated by an extension.
* _All_ memory passed from `gawk' to an extension must be treated as
read-only by the extension.
@@ -26092,8 +26097,8 @@ File: gawk.info, Node: Extension summary, Next:
Extension Exercises, Prev: ga
header file make this easier to do.
* The `gawk' distribution includes a number of small but useful
- sample extensions. The `gawkextlib' project includes several more,
- larger, extensions. If you wish to write an extension and
+ sample extensions. The `gawkextlib' project includes several more
+ (larger) extensions. If you wish to write an extension and
contribute it to the community of `gawk' users, the `gawkextlib'
project is the place to do so.
@@ -32657,7 +32662,7 @@ Index
(line 99)
* exp: Numeric Functions. (line 18)
* expand utility: Very Simple. (line 73)
-* Expat XML parser library: gawkextlib. (line 33)
+* Expat XML parser library: gawkextlib. (line 35)
* exponent: Numeric Functions. (line 18)
* expressions: Expressions. (line 6)
* expressions, as patterns: Expression Patterns. (line 6)
@@ -33071,7 +33076,7 @@ Index
* git utility <2>: Accessing The Source.
(line 10)
* git utility <3>: Other Versions. (line 29)
-* git utility: gawkextlib. (line 27)
+* git utility: gawkextlib. (line 29)
* Git, use of for gawk source code: Derived Files. (line 6)
* GNITS mailing list: Acknowledgments. (line 52)
* GNU awk, See gawk: Preface. (line 51)
@@ -34905,137 +34910,137 @@ Ref: figure-call-new-function919155
Node: Extension API Description921142
Node: Extension API Functions Introduction922592
Node: General Data Types927413
-Ref: General Data Types-Footnote-1933312
-Node: Memory Allocation Functions933611
-Ref: Memory Allocation Functions-Footnote-1936450
-Node: Constructor Functions936546
-Node: Registration Functions938280
-Node: Extension Functions938965
-Node: Exit Callback Functions941262
-Node: Extension Version String942510
-Node: Input Parsers943175
-Node: Output Wrappers953054
-Node: Two-way processors957569
-Node: Printing Messages959773
-Ref: Printing Messages-Footnote-1960849
-Node: Updating `ERRNO'961001
-Node: Requesting Values961741
-Ref: table-value-types-returned962469
-Node: Accessing Parameters963426
-Node: Symbol Table Access964657
-Node: Symbol table by name965171
-Node: Symbol table by cookie967152
-Ref: Symbol table by cookie-Footnote-1971296
-Node: Cached values971359
-Ref: Cached values-Footnote-1974858
-Node: Array Manipulation974949
-Ref: Array Manipulation-Footnote-1976047
-Node: Array Data Types976084
-Ref: Array Data Types-Footnote-1978739
-Node: Array Functions978831
-Node: Flattening Arrays982685
-Node: Creating Arrays989577
-Node: Extension API Variables994348
-Node: Extension Versioning994984
-Node: Extension API Informational Variables996885
-Node: Extension API Boilerplate997950
-Node: Finding Extensions1001759
-Node: Extension Example1002319
-Node: Internal File Description1003091
-Node: Internal File Ops1007158
-Ref: Internal File Ops-Footnote-11018828
-Node: Using Internal File Ops1018968
-Ref: Using Internal File Ops-Footnote-11021351
-Node: Extension Samples1021624
-Node: Extension Sample File Functions1023150
-Node: Extension Sample Fnmatch1030788
-Node: Extension Sample Fork1032279
-Node: Extension Sample Inplace1033494
-Node: Extension Sample Ord1035169
-Node: Extension Sample Readdir1036005
-Ref: table-readdir-file-types1036881
-Node: Extension Sample Revout1037692
-Node: Extension Sample Rev2way1038282
-Node: Extension Sample Read write array1039022
-Node: Extension Sample Readfile1040962
-Node: Extension Sample Time1042057
-Node: Extension Sample API Tests1043406
-Node: gawkextlib1043897
-Node: Extension summary1046555
-Node: Extension Exercises1050244
-Node: Language History1050966
-Node: V7/SVR3.11052622
-Node: SVR41054803
-Node: POSIX1056248
-Node: BTL1057637
-Node: POSIX/GNU1058371
-Node: Feature History1063935
-Node: Common Extensions1077033
-Node: Ranges and Locales1078357
-Ref: Ranges and Locales-Footnote-11082975
-Ref: Ranges and Locales-Footnote-21083002
-Ref: Ranges and Locales-Footnote-31083236
-Node: Contributors1083457
-Node: History summary1088998
-Node: Installation1090368
-Node: Gawk Distribution1091314
-Node: Getting1091798
-Node: Extracting1092621
-Node: Distribution contents1094256
-Node: Unix Installation1099973
-Node: Quick Installation1100590
-Node: Additional Configuration Options1103014
-Node: Configuration Philosophy1104752
-Node: Non-Unix Installation1107121
-Node: PC Installation1107579
-Node: PC Binary Installation1108898
-Node: PC Compiling1110746
-Ref: PC Compiling-Footnote-11113767
-Node: PC Testing1113876
-Node: PC Using1115052
-Node: Cygwin1119167
-Node: MSYS1119990
-Node: VMS Installation1120490
-Node: VMS Compilation1121282
-Ref: VMS Compilation-Footnote-11122504
-Node: VMS Dynamic Extensions1122562
-Node: VMS Installation Details1124246
-Node: VMS Running1126498
-Node: VMS GNV1129334
-Node: VMS Old Gawk1130068
-Node: Bugs1130538
-Node: Other Versions1134421
-Node: Installation summary1140845
-Node: Notes1141901
-Node: Compatibility Mode1142766
-Node: Additions1143548
-Node: Accessing The Source1144473
-Node: Adding Code1145908
-Node: New Ports1152065
-Node: Derived Files1156547
-Ref: Derived Files-Footnote-11162022
-Ref: Derived Files-Footnote-21162056
-Ref: Derived Files-Footnote-31162652
-Node: Future Extensions1162766
-Node: Implementation Limitations1163372
-Node: Extension Design1164620
-Node: Old Extension Problems1165774
-Ref: Old Extension Problems-Footnote-11167291
-Node: Extension New Mechanism Goals1167348
-Ref: Extension New Mechanism Goals-Footnote-11170708
-Node: Extension Other Design Decisions1170897
-Node: Extension Future Growth1173005
-Node: Old Extension Mechanism1173841
-Node: Notes summary1175603
-Node: Basic Concepts1176789
-Node: Basic High Level1177470
-Ref: figure-general-flow1177742
-Ref: figure-process-flow1178341
-Ref: Basic High Level-Footnote-11181570
-Node: Basic Data Typing1181755
-Node: Glossary1185083
-Node: Copying1217012
-Node: GNU Free Documentation License1254568
-Node: Index1279704
+Ref: General Data Types-Footnote-1933313
+Node: Memory Allocation Functions933612
+Ref: Memory Allocation Functions-Footnote-1936451
+Node: Constructor Functions936550
+Node: Registration Functions938285
+Node: Extension Functions938970
+Node: Exit Callback Functions941267
+Node: Extension Version String942515
+Node: Input Parsers943178
+Node: Output Wrappers953053
+Node: Two-way processors957566
+Node: Printing Messages959829
+Ref: Printing Messages-Footnote-1960905
+Node: Updating `ERRNO'961057
+Node: Requesting Values961797
+Ref: table-value-types-returned962524
+Node: Accessing Parameters963481
+Node: Symbol Table Access964715
+Node: Symbol table by name965229
+Node: Symbol table by cookie967249
+Ref: Symbol table by cookie-Footnote-1971394
+Node: Cached values971457
+Ref: Cached values-Footnote-1974953
+Node: Array Manipulation975044
+Ref: Array Manipulation-Footnote-1976142
+Node: Array Data Types976179
+Ref: Array Data Types-Footnote-1978834
+Node: Array Functions978926
+Node: Flattening Arrays982785
+Node: Creating Arrays989687
+Node: Extension API Variables994458
+Node: Extension Versioning995094
+Node: Extension API Informational Variables996985
+Node: Extension API Boilerplate998050
+Node: Finding Extensions1001859
+Node: Extension Example1002419
+Node: Internal File Description1003191
+Node: Internal File Ops1007258
+Ref: Internal File Ops-Footnote-11019009
+Node: Using Internal File Ops1019149
+Ref: Using Internal File Ops-Footnote-11021532
+Node: Extension Samples1021805
+Node: Extension Sample File Functions1023333
+Node: Extension Sample Fnmatch1031014
+Node: Extension Sample Fork1032502
+Node: Extension Sample Inplace1033717
+Node: Extension Sample Ord1035393
+Node: Extension Sample Readdir1036229
+Ref: table-readdir-file-types1037106
+Node: Extension Sample Revout1037917
+Node: Extension Sample Rev2way1038506
+Node: Extension Sample Read write array1039246
+Node: Extension Sample Readfile1041186
+Node: Extension Sample Time1042281
+Node: Extension Sample API Tests1043629
+Node: gawkextlib1044120
+Node: Extension summary1046798
+Node: Extension Exercises1050487
+Node: Language History1051209
+Node: V7/SVR3.11052865
+Node: SVR41055046
+Node: POSIX1056491
+Node: BTL1057880
+Node: POSIX/GNU1058614
+Node: Feature History1064178
+Node: Common Extensions1077276
+Node: Ranges and Locales1078600
+Ref: Ranges and Locales-Footnote-11083218
+Ref: Ranges and Locales-Footnote-21083245
+Ref: Ranges and Locales-Footnote-31083479
+Node: Contributors1083700
+Node: History summary1089241
+Node: Installation1090611
+Node: Gawk Distribution1091557
+Node: Getting1092041
+Node: Extracting1092864
+Node: Distribution contents1094499
+Node: Unix Installation1100216
+Node: Quick Installation1100833
+Node: Additional Configuration Options1103257
+Node: Configuration Philosophy1104995
+Node: Non-Unix Installation1107364
+Node: PC Installation1107822
+Node: PC Binary Installation1109141
+Node: PC Compiling1110989
+Ref: PC Compiling-Footnote-11114010
+Node: PC Testing1114119
+Node: PC Using1115295
+Node: Cygwin1119410
+Node: MSYS1120233
+Node: VMS Installation1120733
+Node: VMS Compilation1121525
+Ref: VMS Compilation-Footnote-11122747
+Node: VMS Dynamic Extensions1122805
+Node: VMS Installation Details1124489
+Node: VMS Running1126741
+Node: VMS GNV1129577
+Node: VMS Old Gawk1130311
+Node: Bugs1130781
+Node: Other Versions1134664
+Node: Installation summary1141088
+Node: Notes1142144
+Node: Compatibility Mode1143009
+Node: Additions1143791
+Node: Accessing The Source1144716
+Node: Adding Code1146151
+Node: New Ports1152308
+Node: Derived Files1156790
+Ref: Derived Files-Footnote-11162265
+Ref: Derived Files-Footnote-21162299
+Ref: Derived Files-Footnote-31162895
+Node: Future Extensions1163009
+Node: Implementation Limitations1163615
+Node: Extension Design1164863
+Node: Old Extension Problems1166017
+Ref: Old Extension Problems-Footnote-11167534
+Node: Extension New Mechanism Goals1167591
+Ref: Extension New Mechanism Goals-Footnote-11170951
+Node: Extension Other Design Decisions1171140
+Node: Extension Future Growth1173248
+Node: Old Extension Mechanism1174084
+Node: Notes summary1175846
+Node: Basic Concepts1177032
+Node: Basic High Level1177713
+Ref: figure-general-flow1177985
+Ref: figure-process-flow1178584
+Ref: Basic High Level-Footnote-11181813
+Node: Basic Data Typing1181998
+Node: Glossary1185326
+Node: Copying1217255
+Node: GNU Free Documentation License1254811
+Node: Index1279947
End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index e7d979d..76d0c54 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -31636,7 +31636,7 @@ If you know that you wish to
use the same numeric or string @emph{value} for one or more variables,
you can create the value once, retaining a @dfn{value cookie} for it,
and then pass in that value cookie whenever you wish to set the value of a
-variable. This both storage space within the running @command{gawk}
+variable. This saves storage space within the running @command{gawk}
process and reduces the time needed to create the value.
@node Memory Allocation Functions
@@ -31665,13 +31665,13 @@ be passed to @command{gawk}.
@item void gawk_free(void *ptr);
Call the correct version of @code{free()} to release storage that was
-allocated with @code{gawk_malloc()}, @code{gawk_calloc()} or
@code{gawk_realloc()}.
+allocated with @code{gawk_malloc()}, @code{gawk_calloc()}, or
@code{gawk_realloc()}.
@end table
The API has to provide these functions because it is possible
for an extension to be compiled and linked against a different
version of the C library than was used for the @command{gawk}
address@hidden is more common on MS-Windows systems, but
address@hidden is more common on MS-Windows systems, but it
can happen on Unix-like systems as well.} If @command{gawk} were
to use its version of @code{free()} when the memory came from an
unrelated version of @code{malloc()}, unexpected behavior would
@@ -31681,7 +31681,7 @@ Two convenience macros may be used for allocating
storage
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.
+procedure calls that do not return a value:
@table @code
@item #define emalloc(pointer, type, size, message) @dots{}
@@ -31718,7 +31718,7 @@ 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{gawk_realloc()},
+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
@@ -31743,7 +31743,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 @code{gawk_malloc()},
@code{gawk_calloc()} or @code{gawk_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}.
@@ -31794,7 +31794,7 @@ The fields are:
@table @code
@item const char *name;
The name of the new function.
address@hidden level code calls the function by this name.
address@hidden code calls the function by this name.
This is a regular C string.
Function names must obey the rules for @command{awk}
@@ -31808,7 +31808,7 @@ This is a pointer to the C function that provides the
extension's
functionality.
The function must fill in @code{*result} with either a number
or a string. @command{gawk} takes ownership of any string memory.
-As mentioned earlier, string memory @strong{must} come from one of
+As mentioned earlier, string memory @emph{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
@@ -31860,20 +31860,20 @@ The @code{exit_status} parameter is the exit status
value that
@command{gawk} intends to pass to the @code{exit()} system call.
@item arg0
-A pointer to private data which @command{gawk} saves in order to pass to
+A pointer to private data that @command{gawk} saves in order to pass to
the function pointed to by @code{funcp}.
@end table
@end table
-Exit callback functions are called in last-in-first-out (LIFO)
+Exit callback functions are called in last-in, first-out (LIFO)
order---that is, in the reverse order in which they are registered with
@command{gawk}.
@node Extension Version String
@subsubsection Registering An Extension Version String
-You can register a version string which indicates the name and
-version of your extension, with @command{gawk}, as follows:
+You can register a version string that indicates the name and
+version of your extension with @command{gawk}, as follows:
@table @code
@item void register_ext_version(const char *version);
@@ -31895,7 +31895,7 @@ of @code{RS} to find the end of the record, and then
uses @code{FS}
Additionally, it sets the value of @code{RT} (@pxref{Built-in Variables}).
If you want, you can provide your own custom input parser. An input
-parser's job is to return a record to the @command{gawk} record processing
+parser's job is to return a record to the @command{gawk} record-processing
code, along with indicators for the value and length of the data to be
used for @code{RT}, if any.
@@ -31913,9 +31913,9 @@ It should not change any state (variable values, etc.)
within @command{gawk}.
@item awk_bool_t @var{XXX}_take_control_of(awk_input_buf_t *iobuf);
When @command{gawk} decides to hand control of the file over to the
input parser, it calls this function. This function in turn must fill
-in certain fields in the @code{awk_input_buf_t} structure, and ensure
+in certain fields in the @code{awk_input_buf_t} structure and ensure
that certain conditions are true. It should then return true. If an
-error of some kind occurs, it should not fill in any fields, and should
+error of some kind occurs, it should not fill in any fields and should
return false; then @command{gawk} will not use the input parser.
The details are presented shortly.
@end table
@@ -32008,7 +32008,7 @@ in the @code{struct stat}, or any combination of these
factors.
Once @address@hidden()} has returned true, and
@command{gawk} has decided to use your input parser, it calls
address@hidden@var{XXX}_take_control_of()}. That function then fills one of
address@hidden@var{XXX}_take_control_of()}. That function then fills
either the @code{get_record} field or the @code{read_func} field in
the @code{awk_input_buf_t}. It must also ensure that @code{fd} is @emph{not}
set to @code{INVALID_HANDLE}. The following list describes the fields that
@@ -32030,21 +32030,21 @@ records. Said function is the core of the input
parser. Its behavior
is described in the text following this list.
@item ssize_t (*read_func)();
-This function pointer should point to function that has the
+This function pointer should point to a function that has the
same behavior as the standard POSIX @code{read()} system call.
It is an alternative to the @code{get_record} pointer. Its behavior
is also described in the text following this list.
@item void (*close_func)(struct awk_input *iobuf);
This function pointer should point to a function that does
-the ``tear down.'' It should release any resources allocated by
+the ``teardown.'' It should release any resources allocated by
@address@hidden()}. It may also close the file. If it
does so, it should set the @code{fd} field to @code{INVALID_HANDLE}.
If @code{fd} is still not @code{INVALID_HANDLE} after the call to this
function, @command{gawk} calls the regular @code{close()} system call.
-Having a ``tear down'' function is optional. If your input parser does
+Having a ``teardown'' function is optional. If your input parser does
not need it, do not set this field. Then, @command{gawk} calls the
regular @code{close()} system call on the file descriptor, so it should
be valid.
@@ -32055,7 +32055,7 @@ input records. The parameters are as follows:
@table @code
@item char **out
-This is a pointer to a @code{char *} variable which is set to point
+This is a pointer to a @code{char *} variable that is set to point
to the record. @command{gawk} makes its own copy of the data, so
the extension must manage this storage.
@@ -32108,17 +32108,17 @@ set this field explicitly.
You must choose one method or the other: either a function that
returns a record, or one that returns raw data. In particular,
if you supply a function to get a record, @command{gawk} will
-call it, and never call the raw read function.
+call it, and will never call the raw read function.
@end quotation
@command{gawk} ships with a sample extension that reads directories,
-returning records for each entry in the directory (@pxref{Extension
+returning records for each entry in a directory (@pxref{Extension
Sample Readdir}). You may wish to use that code as a guide for writing
your own input parser.
When writing an input parser, you should think about (and document)
how it is expected to interact with @command{awk} code. You may want
-it to always be called, and take effect as appropriate (as the
+it to always be called, and to take effect as appropriate (as the
@code{readdir} extension does). Or you may want it to take effect
based upon the value of an @command{awk} variable, as the XML extension
from the @code{gawkextlib} project does (@pxref{gawkextlib}).
@@ -32228,7 +32228,7 @@ a pointer to any private data associated with the file.
These pointers should be set to point to functions that perform
the equivalent function as the @code{<stdio.h>} functions do, if appropriate.
@command{gawk} uses these function pointers for all output.
address@hidden initializes the pointers to point to internal, ``pass through''
address@hidden initializes the pointers to point to internal ``pass-through''
functions that just call the regular @code{<stdio.h>} functions, so an
extension only needs to redefine those functions that are appropriate for
what it does.
@@ -32239,7 +32239,7 @@ upon the @code{name} and @code{mode} fields, and any
additional state
(such as @command{awk} variable values) that is appropriate.
When @command{gawk} calls @address@hidden()}, that function should fill
-in the other fields, as appropriate, except for @code{fp}, which it should just
+in the other fields as appropriate, except for @code{fp}, which it should just
use normally.
You register your output wrapper with the following function:
@@ -32279,14 +32279,14 @@ The fields are as follows:
The name of the two-way processor.
@item awk_bool_t (*can_take_two_way)(const char *name);
-This function returns true if it wants to take over two-way I/O for this
@value{FN}.
+The function pointed to by this field should return true if it wants to take
over two-way I/O for this @value{FN}.
It should not change any state (variable
values, etc.) within @command{gawk}.
@item awk_bool_t (*take_control_of)(const char *name,
@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @
awk_input_buf_t *inbuf,
@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @
awk_output_buf_t *outbuf);
-This function should fill in the @code{awk_input_buf_t} and
+The function pointed to by this field should fill in the
@code{awk_input_buf_t} and
@code{awk_outut_buf_t} structures pointed to by @code{inbuf} and
@code{outbuf}, respectively. These structures were described earlier.
@@ -32315,7 +32315,7 @@ Register the two-way processor pointed to by
@code{two_way_processor} with
You can print different kinds of warning messages from your
extension, as described here. Note that for these functions,
-you must pass in the extension id received from @command{gawk}
+you must pass in the extension ID received from @command{gawk}
when the extension was loaded:@footnote{Because the API uses only ISO C 90
features, it cannot make use of the ISO C 99 variadic macro feature to hide
that parameter. More's the pity.}
@@ -32368,7 +32368,7 @@ 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
+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}.
@@ -32401,32 +32401,32 @@ value type, as appropriate. This behavior is
summarized in
<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>
+ <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>
+ <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>False</para></entry>
+ <entry><para>False</para></entry>
<entry><para>Array</para></entry>
- <entry><para>false</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>
+ <entry><para>False</para></entry>
+ <entry><para>False</para></entry>
</row>
<row>
<entry></entry>
@@ -32438,11 +32438,11 @@ value type, as appropriate. This behavior is
summarized in
</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>
+ <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>
@@ -32460,12 +32460,12 @@ value type, as appropriate. This behavior is
summarized in
@end tex
@multitable @columnfractions .166 .166 .198 .15 .15 .166
@headitem @tab @tab String @tab Number @tab Array @tab Undefined
address@hidden @tab @b{String} @tab String @tab String @tab false @tab false
address@hidden @tab @b{Number} @tab Number if can be converted, else false @tab
Number @tab false @tab false
address@hidden @b{Type} @tab @b{Array} @tab false @tab false @tab Array @tab
false
address@hidden @b{Requested} @tab @b{Scalar} @tab Scalar @tab Scalar @tab false
@tab false
address@hidden @tab @b{String} @tab String @tab String @tab False @tab False
address@hidden @tab @b{Number} @tab Number if can be converted, else false @tab
Number @tab False @tab False
address@hidden @b{Type} @tab @b{Array} @tab False @tab False @tab Array @tab
False
address@hidden @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
address@hidden @tab @b{Value Cookie} @tab false @tab false @tab false @tab false
address@hidden @tab @b{Value cookie} @tab False @tab False @tab False @tab False
@end multitable
@end ifnotdocbook
@end ifnotplaintext
@@ -32476,21 +32476,21 @@ value type, as appropriate. This behavior is
summarized in
+------------+------------+-----------+-----------+
| String | Number | Array | Undefined |
+-----------+-----------+------------+------------+-----------+-----------+
-| | String | String | String | false | false |
+| | String | String | String | False | False |
| |-----------+------------+------------+-----------+-----------+
-| | Number | Number if | Number | false | false |
+| | Number | Number if | Number | False | False |
| | | can be | | | |
| | | converted, | | | |
| | | else false | | | |
| |-----------+------------+------------+-----------+-----------+
-| Type | Array | false | false | Array | false |
+| Type | Array | False | False | Array | False |
| Requested |-----------+------------+------------+-----------+-----------+
-| | Scalar | Scalar | Scalar | false | false |
+| | Scalar | Scalar | Scalar | False | False |
| |-----------+------------+------------+-----------+-----------+
| | Undefined | String | Number | Array | Undefined |
| |-----------+------------+------------+-----------+-----------+
-| | Value | false | false | false | false |
-| | Cookie | | | | |
+| | Value | False | False | False | False |
+| | cookie | | | | |
+-----------+-----------+------------+------------+-----------+-----------+
@end example
@end ifplaintext
@@ -32507,16 +32507,16 @@ passed to your extension function. They are:
@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_valtype_t wanted,
@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_value_t *result);
Fill in the @code{awk_value_t} structure pointed to by @code{result}
-with the @code{count}'th argument. Return true if the actual
-type matches @code{wanted}, false otherwise. In the latter
+with the @code{count}th argument. Return true if the actual
+type matches @code{wanted}, and false otherwise. In the latter
case, @address@hidden>}val_type} indicates the actual type
-(@pxref{table-value-types-returned}). Counts are zero based---the first
+(@pxref{table-value-types-returned}). Counts are zero-based---the first
argument is numbered zero, the second one, and so on. @code{wanted}
indicates the type of value expected.
@item awk_bool_t set_argument(size_t count, awk_array_t array);
Convert a parameter that was undefined into an array; this provides
-call-by-reference for arrays. Return false if @code{count} is too big,
+call by reference for arrays. Return false if @code{count} is too big,
or if the argument's type is not undefined. @DBXREF{Array Manipulation}
for more information on creating arrays.
@end table
@@ -32540,8 +32540,9 @@ allows you to create and release cached values.
The following routines provide the ability to access and update
global @command{awk}-level variables by name. In compiler terminology,
identifiers of different kinds are termed @dfn{symbols}, thus the ``sym''
-in the routines' names. The data structure which stores information
+in the routines' names. The data structure that stores information
about symbols is termed a @dfn{symbol table}.
+The functions are as follows:
@table @code
@item awk_bool_t sym_lookup(const char *name,
@@ -32550,14 +32551,14 @@ 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}, and false otherwise.
In the latter case, @code{result->val_type} indicates the actual type
(@pxref{table-value-types-returned}).
@item awk_bool_t sym_update(const char *name, awk_value_t *value);
Update the variable named by the string @code{name}, which is a regular
C string. The variable is added to @command{gawk}'s symbol table
-if it is not there. Return true if everything worked, false otherwise.
+if it is not there. Return true if everything worked, and false otherwise.
Changing types (scalar to array or vice versa) of an existing variable
is @emph{not} allowed, nor may this routine be used to update an array.
@@ -32582,7 +32583,7 @@ populate it.
A @dfn{scalar cookie} is an opaque handle that provides access
to a global variable or array. It is an optimization that
avoids looking up variables in @command{gawk}'s symbol table every time
-access is needed. This was discussed earlier in @ref{General Data Types}.
+access is needed. This was discussed earlier, in @ref{General Data Types}.
The following functions let you work with scalar cookies:
@@ -32698,7 +32699,7 @@ and carefully check the return values from the API
functions.
@subsubsection Creating and Using Cached Values
The routines in this section allow you to create and release
-cached values. As with scalar cookies, in theory, cached values
+cached values. Like scalar cookies, in theory, cached values
are not necessary. You can create numbers and strings using
the functions in @ref{Constructor Functions}. You can then
assign those values to variables using @code{sym_update()}
@@ -32776,7 +32777,7 @@ Using value cookies in this way saves considerable
storage, as all of
@code{VAR1} through @code{VAR100} share the same value.
You might be wondering, ``Is this sharing problematic?
-What happens if @command{awk} code assigns a new value to @code{VAR1},
+What happens if @command{awk} code assigns a new value to @code{VAR1};
are all the others changed too?''
That's a great question. The answer is that no, it's not a problem.
@@ -32880,7 +32881,7 @@ modify them.
@node Array Functions
@subsubsection Array Functions
-The following functions relate to individual array elements.
+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);
@@ -32899,13 +32900,13 @@ Return false if @code{wanted} does not match the
actual type or if
@code{index} is not in the array (@pxref{table-value-types-returned}).
The value for @code{index} can be numeric, in which case @command{gawk}
-converts it to a string. Using non-integral values is possible, but
+converts it to a string. Using nonintegral values is possible, but
requires that you understand how such values are converted to strings
-(@pxref{Conversion}); thus using integral values is safest.
+(@pxref{Conversion}); thus, using integral values is safest.
As with @emph{all} strings passed into @command{gawk} from an extension,
the string value of @code{index} must come from @code{gawk_malloc()},
address@hidden()} or @code{gawk_realloc()}, and
address@hidden()}, or @code{gawk_realloc()}, and
@command{gawk} releases the storage.
@item awk_bool_t set_array_element(awk_array_t a_cookie,
@@ -32961,7 +32962,7 @@ flatten an array and work with it.
@item awk_bool_t release_flattened_array(awk_array_t a_cookie,
@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @
awk_flat_array_t *data);
When done with a flattened array, release the storage using this function.
-You must pass in both the original array cookie, and the address of
+You must pass in both the original array cookie and the address of
the created @code{awk_flat_array_t} structure.
The function returns true upon success, false otherwise.
@end table
@@ -32971,7 +32972,7 @@ The function returns true upon success, false otherwise.
To @dfn{flatten} an array is to create a structure that
represents the full array in a fashion that makes it easy
-for C code to traverse the entire array. Test code
+for C code to traverse the entire array. Some of the code
in @file{extension/testext.c} does this, and also serves
as a nice example showing how to use the APIs.
@@ -33028,9 +33029,9 @@ dump_array_and_delete(int nargs, awk_value_t *result)
@end example
The function then proceeds in steps, as follows. First, retrieve
-the name of the array, passed as the first argument. Then
-retrieve the array itself. If either operation fails, print
-error messages and return:
+the name of the array, passed as the first argument, followed by
+the array itself. If either operation fails, print an
+error message and return:
@example
/* get argument named array as flat array and print it */
@@ -33066,7 +33067,7 @@ and print it:
@end example
The third step is to actually flatten the array, and then
-to double check that the count in the @code{awk_flat_array_t}
+to double-check that the count in the @code{awk_flat_array_t}
is the same as the count just retrieved:
@example
@@ -33087,7 +33088,7 @@ is the same as the count just retrieved:
The fourth step is to retrieve the index of the element
to be deleted, which was passed as the second argument.
Remember that argument counts passed to @code{get_argument()}
-are zero-based, thus the second argument is numbered one:
+are zero-based, and thus the second argument is numbered one:
@example
if (! get_argument(1, AWK_STRING, & value3)) @{
@@ -33102,7 +33103,7 @@ element values. In addition, upon finding the element
with the
index that is supposed to be deleted, the function sets the
@code{AWK_ELEMENT_DELETE} bit in the @code{flags} field
of the element. When the array is released, @command{gawk}
-traverses the flattened array, and deletes any elements which
+traverses the flattened array, and deletes any elements that
have this flag bit set:
@example
@@ -33390,10 +33391,10 @@ The API versions are available at compile time as
constants:
@table @code
@item GAWK_API_MAJOR_VERSION
-The major version of the API.
+The major version of the API
@item GAWK_API_MINOR_VERSION
-The minor version of the API.
+The minor version of the API
@end table
The minor version increases when new functions are added to the API. Such
@@ -33411,14 +33412,14 @@ constant integers:
@table @code
@item api->major_version
-The major version of the running @command{gawk}.
+The major version of the running @command{gawk}
@item api->minor_version
-The minor version of the running @command{gawk}.
+The minor version of the running @command{gawk}
@end table
It is up to the extension to decide if there are API incompatibilities.
-Typically a check like this is enough:
+Typically, a check like this is enough:
@example
if (api->major_version != GAWK_API_MAJOR_VERSION
@@ -33432,7 +33433,7 @@ if (api->major_version != GAWK_API_MAJOR_VERSION
@end example
Such code is included in the boilerplate @code{dl_load_func()} macro
-provided in @file{gawkapi.h} (discussed later, in
+provided in @file{gawkapi.h} (discussed in
@ref{Extension API Boilerplate}).
@node Extension API Informational Variables
@@ -33479,7 +33480,7 @@ as described here. The boilerplate needed is also
provided in comments
in the @file{gawkapi.h} header file:
@example
-/* Boiler plate code: */
+/* Boilerplate code: */
int plugin_is_GPL_compatible;
static gawk_api_t *const api;
@@ -33538,7 +33539,7 @@ to @code{NULL}, or to point to a string giving the name
and version of
your extension.
@item static awk_ext_func_t func_table[] = @{ @dots{} @};
-This is an array of one or more @code{awk_ext_func_t} structures
+This is an array of one or more @code{awk_ext_func_t} structures,
as described earlier (@pxref{Extension Functions}).
It can then be looped over for multiple calls to
@code{add_ext_func()}.
@@ -33669,7 +33670,7 @@ the @code{stat()} fails. It fills in the following
elements:
@table @code
@item "name"
-The name of the file that was @code{stat()}'ed.
+The name of the file that was @code{stat()}ed.
@item "dev"
@itemx "ino"
@@ -33725,7 +33726,7 @@ interprocess communications).
The file is a directory.
@item "fifo"
-The file is a named-pipe (also known as a FIFO).
+The file is a named pipe (also known as a FIFO).
@item "file"
The file is just a regular file.
@@ -33748,7 +33749,7 @@ For some other systems, @dfn{a priori} knowledge is
used to provide
a value. Where no value can be determined, it defaults to 512.
@end table
-Several additional elements may be present depending upon the operating
+Several additional elements may be present, depending upon the operating
system and the type of the file. You can test for them in your @command{awk}
program by using the @code{in} operator
(@pxref{Reference to Elements}):
@@ -33778,7 +33779,7 @@ edited slightly for presentation. See
@file{extension/filefuncs.c}
in the @command{gawk} distribution for the complete version.}
The file includes a number of standard header files, and then includes
-the @file{gawkapi.h} header file which provides the API definitions.
+the @file{gawkapi.h} header file, which provides the API definitions.
Those are followed by the necessary variable declarations
to make use of the API macros and boilerplate code
(@pxref{Extension API Boilerplate}):
@@ -33819,9 +33820,9 @@ int plugin_is_GPL_compatible;
@cindex programming conventions, @command{gawk} extensions
By convention, for an @command{awk} function @code{foo()}, the C function
that implements it is called @code{do_foo()}. The function should have
-two arguments: the first is an @code{int} usually called @code{nargs},
+two arguments. The first is an @code{int}, usually called @code{nargs},
that represents the number of actual arguments for the function.
-The second is a pointer to an @code{awk_value_t}, usually named
+The second is a pointer to an @code{awk_value_t} structure, usually named
@code{result}:
@example
@@ -33867,7 +33868,7 @@ Finally, the function returns the return value to the
@command{awk} level:
The @code{stat()} extension is more involved. First comes a function
that turns a numeric mode into a printable representation
-(e.g., 644 becomes @samp{-rw-r--r--}). This is omitted here for brevity:
+(e.g., octal @code{0644} becomes @samp{-rw-r--r--}). This is omitted here for
brevity:
@example
/* format_mode --- turn a stat mode field into something readable */
@@ -33923,9 +33924,9 @@ array_set_numeric(awk_array_t array, const char *sub,
double num)
The following function does most of the work to fill in
the @code{awk_array_t} result array with values obtained
-from a valid @code{struct stat}. It is done in a separate function
+from a valid @code{struct stat}. This work is done in a separate function
to support the @code{stat()} function for @command{gawk} and also
-to support the @code{fts()} extension which is included in
+to support the @code{fts()} extension, which is included in
the same file but whose code is not shown here
(@pxref{Extension Sample File Functions}).
@@ -34046,8 +34047,8 @@ the @code{stat()} system call instead of the
@code{lstat()} system
call. This is done by using a function pointer: @code{statfunc}.
@code{statfunc} is initialized to point to @code{lstat()} (instead
of @code{stat()}) to get the file information, in case the file is a
-symbolic link. However, if there were three arguments, @code{statfunc}
-is set point to @code{stat()}, instead.
+symbolic link. However, if the third argument is included, @code{statfunc}
+is set to point to @code{stat()}, instead.
Here is the @code{do_stat()} function, which starts with
variable declarations and argument checking:
@@ -34103,7 +34104,7 @@ Next, it gets the information for the file. If the
called function
/* always empty out the array */
clear_array(array);
- /* stat the file, if error, set ERRNO and return */
+ /* stat the file; if error, set ERRNO and return */
ret = statfunc(name, & sbuf);
if (ret < 0) @{
update_ERRNO_int(errno);
@@ -34125,7 +34126,9 @@ Finally, it's necessary to provide the ``glue'' that
loads the
new function(s) into @command{gawk}.
The @code{filefuncs} extension also provides an @code{fts()}
-function, which we omit here. For its sake there is an initialization
+function, which we omit here
+(@pxref{Extension Sample File Functions}).
+For its sake, there is an initialization
function:
@example
@@ -34250,9 +34253,9 @@ $ @kbd{AWKLIBPATH=$PWD gawk -f testff.awk}
@section The Sample Extensions in the @command{gawk} Distribution
@cindex extensions distributed with @command{gawk}
-This @value{SECTION} provides brief overviews of the sample extensions
+This @value{SECTION} provides a brief overview of the sample extensions
that come in the @command{gawk} distribution. Some of them are intended
-for production use (e.g., the @code{filefuncs}, @code{readdir} and
+for production use (e.g., the @code{filefuncs}, @code{readdir}, and
@code{inplace} extensions). Others mainly provide example code that
shows how to use the extension API.
@@ -34288,14 +34291,14 @@ This is how you load the extension.
@item @code{result = chdir("/some/directory")}
The @code{chdir()} function is a direct hook to the @code{chdir()}
system call to change the current directory. It returns zero
-upon success or less than zero upon error. In the latter case, it updates
address@hidden
+upon success or a value less than zero upon error.
+In the latter case, it updates @code{ERRNO}.
@cindex @code{stat()} extension function
@item @code{result = stat("/some/path", statdata} address@hidden,
address@hidden)}
The @code{stat()} function provides a hook into the
@code{stat()} system call.
-It returns zero upon success or less than zero upon error.
+It returns zero upon success or a value less than zero upon error.
In the latter case, it updates @code{ERRNO}.
By default, it uses the @code{lstat()} system call. However, if passed
@@ -34322,10 +34325,10 @@ array with information retrieved from the filesystem,
as follows:
@item @code{"major"} @tab @code{st_major} @tab Device files
@item @code{"minor"} @tab @code{st_minor} @tab Device files
@item @code{"blksize"} @tab @code{st_blksize} @tab All
address@hidden @code{"pmode"} @tab A human-readable version of the mode value,
such as printed by
address@hidden For example, @code{"-rwxr-xr-x"} @tab All
address@hidden @code{"pmode"} @tab A human-readable version of the mode value,
like that printed by
address@hidden (for example, @code{"-rwxr-xr-x"}) @tab All
@item @code{"linkval"} @tab The value of the symbolic link @tab Symbolic links
address@hidden @code{"type"} @tab The type of the file as a string. One of
address@hidden @code{"type"} @tab The type of the file as a string---one of
@code{"file"},
@code{"blockdev"},
@code{"chardev"},
@@ -34335,15 +34338,15 @@ array with information retrieved from the filesystem,
as follows:
@code{"symlink"},
@code{"door"},
or
address@hidden"unknown"}.
-Not all systems support all file types. @tab All
address@hidden"unknown"}
+(not all systems support all file types) @tab All
@end multitable
@cindex @code{fts()} extension function
@item @code{flags = or(FTS_PHYSICAL, ...)}
@itemx @code{result = fts(pathlist, flags, filedata)}
Walk the file trees provided in @code{pathlist} and fill in the
address@hidden array as described next. @code{flags} is the bitwise
address@hidden array, as described next. @code{flags} is the bitwise
OR of several predefined values, also described in a moment.
Return zero if there were no errors, otherwise return @minus{}1.
@end table
@@ -34399,7 +34402,8 @@ During a traversal, do not cross onto a different
mounted filesystem.
@end table
@item filedata
-The @code{filedata} array is first cleared. Then, @code{fts()} creates
+The @code{filedata} array holds the results.
address@hidden()} first clears it. Then it creates
an element in @code{filedata} for every element in @code{pathlist}.
The index is the name of the directory or file given in @code{pathlist}.
The element for this index is itself an array. There are two cases:
@@ -34441,7 +34445,7 @@ for a file: @code{"path"}, @code{"stat"}, and
@code{"error"}.
@end table
The @code{fts()} function returns zero if there were no errors.
-Otherwise it returns @minus{}1.
+Otherwise, it returns @minus{}1.
@quotation NOTE
The @code{fts()} extension does not exactly mimic the
@@ -34483,14 +34487,14 @@ The arguments to @code{fnmatch()} are:
@table @code
@item pattern
-The @value{FN} wildcard to match.
+The @value{FN} wildcard to match
@item string
-The @value{FN} string.
+The @value{FN} string
@item flag
Either zero, or the bitwise OR of one or more of the
-flags in the @code{FNM} array.
+flags in the @code{FNM} array
@end table
The flags are as follows:
@@ -34527,14 +34531,14 @@ This is how you load the extension.
@cindex @code{fork()} extension function
@item pid = fork()
This function creates a new process. The return value is zero in the
-child and the process-ID number of the child in the parent, or @minus{}1
+child and the process ID number of the child in the parent, or @minus{}1
upon error. In the latter case, @code{ERRNO} indicates the problem.
In the child, @code{PROCINFO["pid"]} and @code{PROCINFO["ppid"]} are
updated to reflect the correct values.
@cindex @code{waitpid()} extension function
@item ret = waitpid(pid)
-This function takes a numeric argument, which is the process-ID to
+This function takes a numeric argument, which is the process ID to
wait for. The return value is that of the
@code{waitpid()} system call.
@@ -34562,8 +34566,8 @@ else
@subsection Enabling In-Place File Editing
@cindex @code{inplace} extension
-The @code{inplace} extension emulates GNU @command{sed}'s @option{-i} option
-which performs ``in place'' editing of each input file.
+The @code{inplace} extension emulates GNU @command{sed}'s @option{-i} option,
+which performs ``in-place'' editing of each input file.
It uses the bundled @file{inplace.awk} include file to invoke the extension
properly:
@@ -34659,14 +34663,14 @@ they are read, with each entry returned as a record.
The record consists of three fields. The first two are the inode number and the
@value{FN}, separated by a forward slash character.
On systems where the directory entry contains the file type, the record
-has a third field (also separated by a slash) which is a single letter
+has a third field (also separated by a slash), which is a single letter
indicating the type of the file. The letters and their corresponding file
types are shown in @ref{table-readdir-file-types}.
@float Table,table-readdir-file-types
@caption{File types returned by the @code{readdir} extension}
@multitable @columnfractions .1 .9
address@hidden Letter @tab File Type
address@hidden Letter @tab File type
@item @code{b} @tab Block device
@item @code{c} @tab Character device
@item @code{d} @tab Directory
@@ -34694,7 +34698,7 @@ Here is an example:
@@load "readdir"
@dots{}
BEGIN @{ FS = "/" @}
address@hidden print "file name is", $2 @}
address@hidden print "@value{FN} is", $2 @}
@end example
@node Extension Sample Revout
@@ -34715,8 +34719,7 @@ BEGIN @{
@}
@end example
-The output from this program is:
address@hidden t'nod}.
+The output from this program is @samp{cinap t'nod}.
@node Extension Sample Rev2way
@subsection Two-Way I/O Example
@@ -34771,7 +34774,7 @@ success, or zero upon failure.
@code{reada()} is the inverse of @code{writea()};
it reads the file named as its first argument, filling in
the array named as the second argument. It clears the array first.
-Here too, the return value is one on success and zero upon failure.
+Here too, the return value is one on success, or zero upon failure.
@end table
The array created by @code{reada()} is identical to that written by
@@ -34859,7 +34862,7 @@ it tries to use @code{GetSystemTimeAsFileTime()}.
Attempt to sleep for @var{seconds} seconds. If @var{seconds} is negative,
or the attempt to sleep fails, return @minus{}1 and set @code{ERRNO}.
Otherwise, return zero after sleeping for the indicated amount of time.
-Note that @var{seconds} may be a floating-point (non-integral) value.
+Note that @var{seconds} may be a floating-point (nonintegral) value.
Implementation details: depending on platform availability, this function
tries to use @code{nanosleep()} or @code{select()} to implement the delay.
@end table
@@ -34886,10 +34889,13 @@ project provides a number of @command{gawk}
extensions, including one for
processing XML files. This is the evolution of the original @command{xgawk}
(XML @command{gawk}) project.
-As of this writing, there are six extensions:
+As of this writing, there are seven extensions:
@itemize @value{BULLET}
@item
address@hidden extension
+
address@hidden
GD graphics library extension
@item
@@ -34900,7 +34906,7 @@ PostgreSQL extension
@item
MPFR library extension
-(this provides access to a number of MPFR functions which @command{gawk}'s
+(this provides access to a number of MPFR functions that @command{gawk}'s
native MPFR support does not)
@item
@@ -34954,7 +34960,7 @@ make install @ii{Install the
extensions}
If you have installed @command{gawk} in the standard way, then you
will likely not need the @option{--with-gawk} option when configuring
address@hidden You may also need to use the @command{sudo} utility
address@hidden You may need to use the @command{sudo} utility
to install both @command{gawk} and @code{gawkextlib}, depending upon
how your system works.
@@ -34979,7 +34985,7 @@ named @code{plugin_is_GPL_compatible}.
@item
Communication between @command{gawk} and an extension is two-way.
address@hidden passes a @code{struct} to the extension which contains
address@hidden passes a @code{struct} to the extension that contains
various data fields and function pointers. The extension can then call
into @command{gawk} via the supplied function pointers to accomplish
certain tasks.
@@ -34992,7 +34998,7 @@ By convention, implementation functions are named
@address@hidden()}
for some @command{awk}-level function @address@hidden()}.
@item
-The API is defined in a header file named @file{gawkpi.h}. You must include
+The API is defined in a header file named @file{gawkapi.h}. You must include
a number of standard header files @emph{before} including it in your source
file.
@item
@@ -35037,7 +35043,7 @@ getting the count of elements in an array;
creating a new array;
clearing an array;
and
-flattening an array for easy C style looping over all its indices and elements)
+flattening an array for easy C-style looping over all its indices and elements)
@end itemize
@item
@@ -35045,7 +35051,7 @@ The API defines a number of standard data types for
representing
@command{awk} values, array elements, and arrays.
@item
-The API provide convenience functions for constructing values.
+The API provides convenience functions for constructing values.
It also provides memory management functions to ensure compatibility
between memory allocated by @command{gawk} and memory allocated by an
extension.
@@ -35071,8 +35077,8 @@ file make this easier to do.
@item
The @command{gawk} distribution includes a number of small but useful
-sample extensions. The @code{gawkextlib} project includes several more,
-larger, extensions. If you wish to write an extension and contribute it
+sample extensions. The @code{gawkextlib} project includes several more
+(larger) extensions. If you wish to write an extension and contribute it
to the community of @command{gawk} users, the @code{gawkextlib} project
is the place to do so.
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index c41d5a6..16847eb 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -30727,7 +30727,7 @@ If you know that you wish to
use the same numeric or string @emph{value} for one or more variables,
you can create the value once, retaining a @dfn{value cookie} for it,
and then pass in that value cookie whenever you wish to set the value of a
-variable. This both storage space within the running @command{gawk}
+variable. This saves storage space within the running @command{gawk}
process and reduces the time needed to create the value.
@node Memory Allocation Functions
@@ -30756,13 +30756,13 @@ be passed to @command{gawk}.
@item void gawk_free(void *ptr);
Call the correct version of @code{free()} to release storage that was
-allocated with @code{gawk_malloc()}, @code{gawk_calloc()} or
@code{gawk_realloc()}.
+allocated with @code{gawk_malloc()}, @code{gawk_calloc()}, or
@code{gawk_realloc()}.
@end table
The API has to provide these functions because it is possible
for an extension to be compiled and linked against a different
version of the C library than was used for the @command{gawk}
address@hidden is more common on MS-Windows systems, but
address@hidden is more common on MS-Windows systems, but it
can happen on Unix-like systems as well.} If @command{gawk} were
to use its version of @code{free()} when the memory came from an
unrelated version of @code{malloc()}, unexpected behavior would
@@ -30772,7 +30772,7 @@ Two convenience macros may be used for allocating
storage
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.
+procedure calls that do not return a value:
@table @code
@item #define emalloc(pointer, type, size, message) @dots{}
@@ -30809,7 +30809,7 @@ 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{gawk_realloc()},
+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
@@ -30834,7 +30834,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 @code{gawk_malloc()},
@code{gawk_calloc()} or @code{gawk_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}.
@@ -30885,7 +30885,7 @@ The fields are:
@table @code
@item const char *name;
The name of the new function.
address@hidden level code calls the function by this name.
address@hidden code calls the function by this name.
This is a regular C string.
Function names must obey the rules for @command{awk}
@@ -30899,7 +30899,7 @@ This is a pointer to the C function that provides the
extension's
functionality.
The function must fill in @code{*result} with either a number
or a string. @command{gawk} takes ownership of any string memory.
-As mentioned earlier, string memory @strong{must} come from one of
+As mentioned earlier, string memory @emph{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
@@ -30951,20 +30951,20 @@ The @code{exit_status} parameter is the exit status
value that
@command{gawk} intends to pass to the @code{exit()} system call.
@item arg0
-A pointer to private data which @command{gawk} saves in order to pass to
+A pointer to private data that @command{gawk} saves in order to pass to
the function pointed to by @code{funcp}.
@end table
@end table
-Exit callback functions are called in last-in-first-out (LIFO)
+Exit callback functions are called in last-in, first-out (LIFO)
order---that is, in the reverse order in which they are registered with
@command{gawk}.
@node Extension Version String
@subsubsection Registering An Extension Version String
-You can register a version string which indicates the name and
-version of your extension, with @command{gawk}, as follows:
+You can register a version string that indicates the name and
+version of your extension with @command{gawk}, as follows:
@table @code
@item void register_ext_version(const char *version);
@@ -30986,7 +30986,7 @@ of @code{RS} to find the end of the record, and then
uses @code{FS}
Additionally, it sets the value of @code{RT} (@pxref{Built-in Variables}).
If you want, you can provide your own custom input parser. An input
-parser's job is to return a record to the @command{gawk} record processing
+parser's job is to return a record to the @command{gawk} record-processing
code, along with indicators for the value and length of the data to be
used for @code{RT}, if any.
@@ -31004,9 +31004,9 @@ It should not change any state (variable values, etc.)
within @command{gawk}.
@item awk_bool_t @var{XXX}_take_control_of(awk_input_buf_t *iobuf);
When @command{gawk} decides to hand control of the file over to the
input parser, it calls this function. This function in turn must fill
-in certain fields in the @code{awk_input_buf_t} structure, and ensure
+in certain fields in the @code{awk_input_buf_t} structure and ensure
that certain conditions are true. It should then return true. If an
-error of some kind occurs, it should not fill in any fields, and should
+error of some kind occurs, it should not fill in any fields and should
return false; then @command{gawk} will not use the input parser.
The details are presented shortly.
@end table
@@ -31099,7 +31099,7 @@ in the @code{struct stat}, or any combination of these
factors.
Once @address@hidden()} has returned true, and
@command{gawk} has decided to use your input parser, it calls
address@hidden@var{XXX}_take_control_of()}. That function then fills one of
address@hidden@var{XXX}_take_control_of()}. That function then fills
either the @code{get_record} field or the @code{read_func} field in
the @code{awk_input_buf_t}. It must also ensure that @code{fd} is @emph{not}
set to @code{INVALID_HANDLE}. The following list describes the fields that
@@ -31121,21 +31121,21 @@ records. Said function is the core of the input
parser. Its behavior
is described in the text following this list.
@item ssize_t (*read_func)();
-This function pointer should point to function that has the
+This function pointer should point to a function that has the
same behavior as the standard POSIX @code{read()} system call.
It is an alternative to the @code{get_record} pointer. Its behavior
is also described in the text following this list.
@item void (*close_func)(struct awk_input *iobuf);
This function pointer should point to a function that does
-the ``tear down.'' It should release any resources allocated by
+the ``teardown.'' It should release any resources allocated by
@address@hidden()}. It may also close the file. If it
does so, it should set the @code{fd} field to @code{INVALID_HANDLE}.
If @code{fd} is still not @code{INVALID_HANDLE} after the call to this
function, @command{gawk} calls the regular @code{close()} system call.
-Having a ``tear down'' function is optional. If your input parser does
+Having a ``teardown'' function is optional. If your input parser does
not need it, do not set this field. Then, @command{gawk} calls the
regular @code{close()} system call on the file descriptor, so it should
be valid.
@@ -31146,7 +31146,7 @@ input records. The parameters are as follows:
@table @code
@item char **out
-This is a pointer to a @code{char *} variable which is set to point
+This is a pointer to a @code{char *} variable that is set to point
to the record. @command{gawk} makes its own copy of the data, so
the extension must manage this storage.
@@ -31199,17 +31199,17 @@ set this field explicitly.
You must choose one method or the other: either a function that
returns a record, or one that returns raw data. In particular,
if you supply a function to get a record, @command{gawk} will
-call it, and never call the raw read function.
+call it, and will never call the raw read function.
@end quotation
@command{gawk} ships with a sample extension that reads directories,
-returning records for each entry in the directory (@pxref{Extension
+returning records for each entry in a directory (@pxref{Extension
Sample Readdir}). You may wish to use that code as a guide for writing
your own input parser.
When writing an input parser, you should think about (and document)
how it is expected to interact with @command{awk} code. You may want
-it to always be called, and take effect as appropriate (as the
+it to always be called, and to take effect as appropriate (as the
@code{readdir} extension does). Or you may want it to take effect
based upon the value of an @command{awk} variable, as the XML extension
from the @code{gawkextlib} project does (@pxref{gawkextlib}).
@@ -31319,7 +31319,7 @@ a pointer to any private data associated with the file.
These pointers should be set to point to functions that perform
the equivalent function as the @code{<stdio.h>} functions do, if appropriate.
@command{gawk} uses these function pointers for all output.
address@hidden initializes the pointers to point to internal, ``pass through''
address@hidden initializes the pointers to point to internal ``pass-through''
functions that just call the regular @code{<stdio.h>} functions, so an
extension only needs to redefine those functions that are appropriate for
what it does.
@@ -31330,7 +31330,7 @@ upon the @code{name} and @code{mode} fields, and any
additional state
(such as @command{awk} variable values) that is appropriate.
When @command{gawk} calls @address@hidden()}, that function should fill
-in the other fields, as appropriate, except for @code{fp}, which it should just
+in the other fields as appropriate, except for @code{fp}, which it should just
use normally.
You register your output wrapper with the following function:
@@ -31370,14 +31370,14 @@ The fields are as follows:
The name of the two-way processor.
@item awk_bool_t (*can_take_two_way)(const char *name);
-This function returns true if it wants to take over two-way I/O for this
@value{FN}.
+The function pointed to by this field should return true if it wants to take
over two-way I/O for this @value{FN}.
It should not change any state (variable
values, etc.) within @command{gawk}.
@item awk_bool_t (*take_control_of)(const char *name,
@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @
awk_input_buf_t *inbuf,
@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @
awk_output_buf_t *outbuf);
-This function should fill in the @code{awk_input_buf_t} and
+The function pointed to by this field should fill in the
@code{awk_input_buf_t} and
@code{awk_outut_buf_t} structures pointed to by @code{inbuf} and
@code{outbuf}, respectively. These structures were described earlier.
@@ -31406,7 +31406,7 @@ Register the two-way processor pointed to by
@code{two_way_processor} with
You can print different kinds of warning messages from your
extension, as described here. Note that for these functions,
-you must pass in the extension id received from @command{gawk}
+you must pass in the extension ID received from @command{gawk}
when the extension was loaded:@footnote{Because the API uses only ISO C 90
features, it cannot make use of the ISO C 99 variadic macro feature to hide
that parameter. More's the pity.}
@@ -31459,7 +31459,7 @@ 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
+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}.
@@ -31492,32 +31492,32 @@ value type, as appropriate. This behavior is
summarized in
<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>
+ <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>
+ <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>False</para></entry>
+ <entry><para>False</para></entry>
<entry><para>Array</para></entry>
- <entry><para>false</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>
+ <entry><para>False</para></entry>
+ <entry><para>False</para></entry>
</row>
<row>
<entry></entry>
@@ -31529,11 +31529,11 @@ value type, as appropriate. This behavior is
summarized in
</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>
+ <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>
@@ -31551,12 +31551,12 @@ value type, as appropriate. This behavior is
summarized in
@end tex
@multitable @columnfractions .166 .166 .198 .15 .15 .166
@headitem @tab @tab String @tab Number @tab Array @tab Undefined
address@hidden @tab @b{String} @tab String @tab String @tab false @tab false
address@hidden @tab @b{Number} @tab Number if can be converted, else false @tab
Number @tab false @tab false
address@hidden @b{Type} @tab @b{Array} @tab false @tab false @tab Array @tab
false
address@hidden @b{Requested} @tab @b{Scalar} @tab Scalar @tab Scalar @tab false
@tab false
address@hidden @tab @b{String} @tab String @tab String @tab False @tab False
address@hidden @tab @b{Number} @tab Number if can be converted, else false @tab
Number @tab False @tab False
address@hidden @b{Type} @tab @b{Array} @tab False @tab False @tab Array @tab
False
address@hidden @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
address@hidden @tab @b{Value Cookie} @tab false @tab false @tab false @tab false
address@hidden @tab @b{Value cookie} @tab False @tab False @tab False @tab False
@end multitable
@end ifnotdocbook
@end ifnotplaintext
@@ -31567,21 +31567,21 @@ value type, as appropriate. This behavior is
summarized in
+------------+------------+-----------+-----------+
| String | Number | Array | Undefined |
+-----------+-----------+------------+------------+-----------+-----------+
-| | String | String | String | false | false |
+| | String | String | String | False | False |
| |-----------+------------+------------+-----------+-----------+
-| | Number | Number if | Number | false | false |
+| | Number | Number if | Number | False | False |
| | | can be | | | |
| | | converted, | | | |
| | | else false | | | |
| |-----------+------------+------------+-----------+-----------+
-| Type | Array | false | false | Array | false |
+| Type | Array | False | False | Array | False |
| Requested |-----------+------------+------------+-----------+-----------+
-| | Scalar | Scalar | Scalar | false | false |
+| | Scalar | Scalar | Scalar | False | False |
| |-----------+------------+------------+-----------+-----------+
| | Undefined | String | Number | Array | Undefined |
| |-----------+------------+------------+-----------+-----------+
-| | Value | false | false | false | false |
-| | Cookie | | | | |
+| | Value | False | False | False | False |
+| | cookie | | | | |
+-----------+-----------+------------+------------+-----------+-----------+
@end example
@end ifplaintext
@@ -31598,16 +31598,16 @@ passed to your extension function. They are:
@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_valtype_t wanted,
@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ awk_value_t *result);
Fill in the @code{awk_value_t} structure pointed to by @code{result}
-with the @code{count}'th argument. Return true if the actual
-type matches @code{wanted}, false otherwise. In the latter
+with the @code{count}th argument. Return true if the actual
+type matches @code{wanted}, and false otherwise. In the latter
case, @address@hidden>}val_type} indicates the actual type
-(@pxref{table-value-types-returned}). Counts are zero based---the first
+(@pxref{table-value-types-returned}). Counts are zero-based---the first
argument is numbered zero, the second one, and so on. @code{wanted}
indicates the type of value expected.
@item awk_bool_t set_argument(size_t count, awk_array_t array);
Convert a parameter that was undefined into an array; this provides
-call-by-reference for arrays. Return false if @code{count} is too big,
+call by reference for arrays. Return false if @code{count} is too big,
or if the argument's type is not undefined. @DBXREF{Array Manipulation}
for more information on creating arrays.
@end table
@@ -31631,8 +31631,9 @@ allows you to create and release cached values.
The following routines provide the ability to access and update
global @command{awk}-level variables by name. In compiler terminology,
identifiers of different kinds are termed @dfn{symbols}, thus the ``sym''
-in the routines' names. The data structure which stores information
+in the routines' names. The data structure that stores information
about symbols is termed a @dfn{symbol table}.
+The functions are as follows:
@table @code
@item awk_bool_t sym_lookup(const char *name,
@@ -31641,14 +31642,14 @@ 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}, and false otherwise.
In the latter case, @code{result->val_type} indicates the actual type
(@pxref{table-value-types-returned}).
@item awk_bool_t sym_update(const char *name, awk_value_t *value);
Update the variable named by the string @code{name}, which is a regular
C string. The variable is added to @command{gawk}'s symbol table
-if it is not there. Return true if everything worked, false otherwise.
+if it is not there. Return true if everything worked, and false otherwise.
Changing types (scalar to array or vice versa) of an existing variable
is @emph{not} allowed, nor may this routine be used to update an array.
@@ -31673,7 +31674,7 @@ populate it.
A @dfn{scalar cookie} is an opaque handle that provides access
to a global variable or array. It is an optimization that
avoids looking up variables in @command{gawk}'s symbol table every time
-access is needed. This was discussed earlier in @ref{General Data Types}.
+access is needed. This was discussed earlier, in @ref{General Data Types}.
The following functions let you work with scalar cookies:
@@ -31789,7 +31790,7 @@ and carefully check the return values from the API
functions.
@subsubsection Creating and Using Cached Values
The routines in this section allow you to create and release
-cached values. As with scalar cookies, in theory, cached values
+cached values. Like scalar cookies, in theory, cached values
are not necessary. You can create numbers and strings using
the functions in @ref{Constructor Functions}. You can then
assign those values to variables using @code{sym_update()}
@@ -31867,7 +31868,7 @@ Using value cookies in this way saves considerable
storage, as all of
@code{VAR1} through @code{VAR100} share the same value.
You might be wondering, ``Is this sharing problematic?
-What happens if @command{awk} code assigns a new value to @code{VAR1},
+What happens if @command{awk} code assigns a new value to @code{VAR1};
are all the others changed too?''
That's a great question. The answer is that no, it's not a problem.
@@ -31971,7 +31972,7 @@ modify them.
@node Array Functions
@subsubsection Array Functions
-The following functions relate to individual array elements.
+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);
@@ -31990,13 +31991,13 @@ Return false if @code{wanted} does not match the
actual type or if
@code{index} is not in the array (@pxref{table-value-types-returned}).
The value for @code{index} can be numeric, in which case @command{gawk}
-converts it to a string. Using non-integral values is possible, but
+converts it to a string. Using nonintegral values is possible, but
requires that you understand how such values are converted to strings
-(@pxref{Conversion}); thus using integral values is safest.
+(@pxref{Conversion}); thus, using integral values is safest.
As with @emph{all} strings passed into @command{gawk} from an extension,
the string value of @code{index} must come from @code{gawk_malloc()},
address@hidden()} or @code{gawk_realloc()}, and
address@hidden()}, or @code{gawk_realloc()}, and
@command{gawk} releases the storage.
@item awk_bool_t set_array_element(awk_array_t a_cookie,
@@ -32052,7 +32053,7 @@ flatten an array and work with it.
@item awk_bool_t release_flattened_array(awk_array_t a_cookie,
@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @
awk_flat_array_t *data);
When done with a flattened array, release the storage using this function.
-You must pass in both the original array cookie, and the address of
+You must pass in both the original array cookie and the address of
the created @code{awk_flat_array_t} structure.
The function returns true upon success, false otherwise.
@end table
@@ -32062,7 +32063,7 @@ The function returns true upon success, false otherwise.
To @dfn{flatten} an array is to create a structure that
represents the full array in a fashion that makes it easy
-for C code to traverse the entire array. Test code
+for C code to traverse the entire array. Some of the code
in @file{extension/testext.c} does this, and also serves
as a nice example showing how to use the APIs.
@@ -32119,9 +32120,9 @@ dump_array_and_delete(int nargs, awk_value_t *result)
@end example
The function then proceeds in steps, as follows. First, retrieve
-the name of the array, passed as the first argument. Then
-retrieve the array itself. If either operation fails, print
-error messages and return:
+the name of the array, passed as the first argument, followed by
+the array itself. If either operation fails, print an
+error message and return:
@example
/* get argument named array as flat array and print it */
@@ -32157,7 +32158,7 @@ and print it:
@end example
The third step is to actually flatten the array, and then
-to double check that the count in the @code{awk_flat_array_t}
+to double-check that the count in the @code{awk_flat_array_t}
is the same as the count just retrieved:
@example
@@ -32178,7 +32179,7 @@ is the same as the count just retrieved:
The fourth step is to retrieve the index of the element
to be deleted, which was passed as the second argument.
Remember that argument counts passed to @code{get_argument()}
-are zero-based, thus the second argument is numbered one:
+are zero-based, and thus the second argument is numbered one:
@example
if (! get_argument(1, AWK_STRING, & value3)) @{
@@ -32193,7 +32194,7 @@ element values. In addition, upon finding the element
with the
index that is supposed to be deleted, the function sets the
@code{AWK_ELEMENT_DELETE} bit in the @code{flags} field
of the element. When the array is released, @command{gawk}
-traverses the flattened array, and deletes any elements which
+traverses the flattened array, and deletes any elements that
have this flag bit set:
@example
@@ -32481,10 +32482,10 @@ The API versions are available at compile time as
constants:
@table @code
@item GAWK_API_MAJOR_VERSION
-The major version of the API.
+The major version of the API
@item GAWK_API_MINOR_VERSION
-The minor version of the API.
+The minor version of the API
@end table
The minor version increases when new functions are added to the API. Such
@@ -32502,14 +32503,14 @@ constant integers:
@table @code
@item api->major_version
-The major version of the running @command{gawk}.
+The major version of the running @command{gawk}
@item api->minor_version
-The minor version of the running @command{gawk}.
+The minor version of the running @command{gawk}
@end table
It is up to the extension to decide if there are API incompatibilities.
-Typically a check like this is enough:
+Typically, a check like this is enough:
@example
if (api->major_version != GAWK_API_MAJOR_VERSION
@@ -32523,7 +32524,7 @@ if (api->major_version != GAWK_API_MAJOR_VERSION
@end example
Such code is included in the boilerplate @code{dl_load_func()} macro
-provided in @file{gawkapi.h} (discussed later, in
+provided in @file{gawkapi.h} (discussed in
@ref{Extension API Boilerplate}).
@node Extension API Informational Variables
@@ -32570,7 +32571,7 @@ as described here. The boilerplate needed is also
provided in comments
in the @file{gawkapi.h} header file:
@example
-/* Boiler plate code: */
+/* Boilerplate code: */
int plugin_is_GPL_compatible;
static gawk_api_t *const api;
@@ -32629,7 +32630,7 @@ to @code{NULL}, or to point to a string giving the name
and version of
your extension.
@item static awk_ext_func_t func_table[] = @{ @dots{} @};
-This is an array of one or more @code{awk_ext_func_t} structures
+This is an array of one or more @code{awk_ext_func_t} structures,
as described earlier (@pxref{Extension Functions}).
It can then be looped over for multiple calls to
@code{add_ext_func()}.
@@ -32760,7 +32761,7 @@ the @code{stat()} fails. It fills in the following
elements:
@table @code
@item "name"
-The name of the file that was @code{stat()}'ed.
+The name of the file that was @code{stat()}ed.
@item "dev"
@itemx "ino"
@@ -32816,7 +32817,7 @@ interprocess communications).
The file is a directory.
@item "fifo"
-The file is a named-pipe (also known as a FIFO).
+The file is a named pipe (also known as a FIFO).
@item "file"
The file is just a regular file.
@@ -32839,7 +32840,7 @@ For some other systems, @dfn{a priori} knowledge is
used to provide
a value. Where no value can be determined, it defaults to 512.
@end table
-Several additional elements may be present depending upon the operating
+Several additional elements may be present, depending upon the operating
system and the type of the file. You can test for them in your @command{awk}
program by using the @code{in} operator
(@pxref{Reference to Elements}):
@@ -32869,7 +32870,7 @@ edited slightly for presentation. See
@file{extension/filefuncs.c}
in the @command{gawk} distribution for the complete version.}
The file includes a number of standard header files, and then includes
-the @file{gawkapi.h} header file which provides the API definitions.
+the @file{gawkapi.h} header file, which provides the API definitions.
Those are followed by the necessary variable declarations
to make use of the API macros and boilerplate code
(@pxref{Extension API Boilerplate}):
@@ -32910,9 +32911,9 @@ int plugin_is_GPL_compatible;
@cindex programming conventions, @command{gawk} extensions
By convention, for an @command{awk} function @code{foo()}, the C function
that implements it is called @code{do_foo()}. The function should have
-two arguments: the first is an @code{int} usually called @code{nargs},
+two arguments. The first is an @code{int}, usually called @code{nargs},
that represents the number of actual arguments for the function.
-The second is a pointer to an @code{awk_value_t}, usually named
+The second is a pointer to an @code{awk_value_t} structure, usually named
@code{result}:
@example
@@ -32958,7 +32959,7 @@ Finally, the function returns the return value to the
@command{awk} level:
The @code{stat()} extension is more involved. First comes a function
that turns a numeric mode into a printable representation
-(e.g., 644 becomes @samp{-rw-r--r--}). This is omitted here for brevity:
+(e.g., octal @code{0644} becomes @samp{-rw-r--r--}). This is omitted here for
brevity:
@example
/* format_mode --- turn a stat mode field into something readable */
@@ -33014,9 +33015,9 @@ array_set_numeric(awk_array_t array, const char *sub,
double num)
The following function does most of the work to fill in
the @code{awk_array_t} result array with values obtained
-from a valid @code{struct stat}. It is done in a separate function
+from a valid @code{struct stat}. This work is done in a separate function
to support the @code{stat()} function for @command{gawk} and also
-to support the @code{fts()} extension which is included in
+to support the @code{fts()} extension, which is included in
the same file but whose code is not shown here
(@pxref{Extension Sample File Functions}).
@@ -33137,8 +33138,8 @@ the @code{stat()} system call instead of the
@code{lstat()} system
call. This is done by using a function pointer: @code{statfunc}.
@code{statfunc} is initialized to point to @code{lstat()} (instead
of @code{stat()}) to get the file information, in case the file is a
-symbolic link. However, if there were three arguments, @code{statfunc}
-is set point to @code{stat()}, instead.
+symbolic link. However, if the third argument is included, @code{statfunc}
+is set to point to @code{stat()}, instead.
Here is the @code{do_stat()} function, which starts with
variable declarations and argument checking:
@@ -33194,7 +33195,7 @@ Next, it gets the information for the file. If the
called function
/* always empty out the array */
clear_array(array);
- /* stat the file, if error, set ERRNO and return */
+ /* stat the file; if error, set ERRNO and return */
ret = statfunc(name, & sbuf);
if (ret < 0) @{
update_ERRNO_int(errno);
@@ -33216,7 +33217,9 @@ Finally, it's necessary to provide the ``glue'' that
loads the
new function(s) into @command{gawk}.
The @code{filefuncs} extension also provides an @code{fts()}
-function, which we omit here. For its sake there is an initialization
+function, which we omit here
+(@pxref{Extension Sample File Functions}).
+For its sake, there is an initialization
function:
@example
@@ -33341,9 +33344,9 @@ $ @kbd{AWKLIBPATH=$PWD gawk -f testff.awk}
@section The Sample Extensions in the @command{gawk} Distribution
@cindex extensions distributed with @command{gawk}
-This @value{SECTION} provides brief overviews of the sample extensions
+This @value{SECTION} provides a brief overview of the sample extensions
that come in the @command{gawk} distribution. Some of them are intended
-for production use (e.g., the @code{filefuncs}, @code{readdir} and
+for production use (e.g., the @code{filefuncs}, @code{readdir}, and
@code{inplace} extensions). Others mainly provide example code that
shows how to use the extension API.
@@ -33379,14 +33382,14 @@ This is how you load the extension.
@item @code{result = chdir("/some/directory")}
The @code{chdir()} function is a direct hook to the @code{chdir()}
system call to change the current directory. It returns zero
-upon success or less than zero upon error. In the latter case, it updates
address@hidden
+upon success or a value less than zero upon error.
+In the latter case, it updates @code{ERRNO}.
@cindex @code{stat()} extension function
@item @code{result = stat("/some/path", statdata} address@hidden,
address@hidden)}
The @code{stat()} function provides a hook into the
@code{stat()} system call.
-It returns zero upon success or less than zero upon error.
+It returns zero upon success or a value less than zero upon error.
In the latter case, it updates @code{ERRNO}.
By default, it uses the @code{lstat()} system call. However, if passed
@@ -33413,10 +33416,10 @@ array with information retrieved from the filesystem,
as follows:
@item @code{"major"} @tab @code{st_major} @tab Device files
@item @code{"minor"} @tab @code{st_minor} @tab Device files
@item @code{"blksize"} @tab @code{st_blksize} @tab All
address@hidden @code{"pmode"} @tab A human-readable version of the mode value,
such as printed by
address@hidden For example, @code{"-rwxr-xr-x"} @tab All
address@hidden @code{"pmode"} @tab A human-readable version of the mode value,
like that printed by
address@hidden (for example, @code{"-rwxr-xr-x"}) @tab All
@item @code{"linkval"} @tab The value of the symbolic link @tab Symbolic links
address@hidden @code{"type"} @tab The type of the file as a string. One of
address@hidden @code{"type"} @tab The type of the file as a string---one of
@code{"file"},
@code{"blockdev"},
@code{"chardev"},
@@ -33426,15 +33429,15 @@ array with information retrieved from the filesystem,
as follows:
@code{"symlink"},
@code{"door"},
or
address@hidden"unknown"}.
-Not all systems support all file types. @tab All
address@hidden"unknown"}
+(not all systems support all file types) @tab All
@end multitable
@cindex @code{fts()} extension function
@item @code{flags = or(FTS_PHYSICAL, ...)}
@itemx @code{result = fts(pathlist, flags, filedata)}
Walk the file trees provided in @code{pathlist} and fill in the
address@hidden array as described next. @code{flags} is the bitwise
address@hidden array, as described next. @code{flags} is the bitwise
OR of several predefined values, also described in a moment.
Return zero if there were no errors, otherwise return @minus{}1.
@end table
@@ -33490,7 +33493,8 @@ During a traversal, do not cross onto a different
mounted filesystem.
@end table
@item filedata
-The @code{filedata} array is first cleared. Then, @code{fts()} creates
+The @code{filedata} array holds the results.
address@hidden()} first clears it. Then it creates
an element in @code{filedata} for every element in @code{pathlist}.
The index is the name of the directory or file given in @code{pathlist}.
The element for this index is itself an array. There are two cases:
@@ -33532,7 +33536,7 @@ for a file: @code{"path"}, @code{"stat"}, and
@code{"error"}.
@end table
The @code{fts()} function returns zero if there were no errors.
-Otherwise it returns @minus{}1.
+Otherwise, it returns @minus{}1.
@quotation NOTE
The @code{fts()} extension does not exactly mimic the
@@ -33574,14 +33578,14 @@ The arguments to @code{fnmatch()} are:
@table @code
@item pattern
-The @value{FN} wildcard to match.
+The @value{FN} wildcard to match
@item string
-The @value{FN} string.
+The @value{FN} string
@item flag
Either zero, or the bitwise OR of one or more of the
-flags in the @code{FNM} array.
+flags in the @code{FNM} array
@end table
The flags are as follows:
@@ -33618,14 +33622,14 @@ This is how you load the extension.
@cindex @code{fork()} extension function
@item pid = fork()
This function creates a new process. The return value is zero in the
-child and the process-ID number of the child in the parent, or @minus{}1
+child and the process ID number of the child in the parent, or @minus{}1
upon error. In the latter case, @code{ERRNO} indicates the problem.
In the child, @code{PROCINFO["pid"]} and @code{PROCINFO["ppid"]} are
updated to reflect the correct values.
@cindex @code{waitpid()} extension function
@item ret = waitpid(pid)
-This function takes a numeric argument, which is the process-ID to
+This function takes a numeric argument, which is the process ID to
wait for. The return value is that of the
@code{waitpid()} system call.
@@ -33653,8 +33657,8 @@ else
@subsection Enabling In-Place File Editing
@cindex @code{inplace} extension
-The @code{inplace} extension emulates GNU @command{sed}'s @option{-i} option
-which performs ``in place'' editing of each input file.
+The @code{inplace} extension emulates GNU @command{sed}'s @option{-i} option,
+which performs ``in-place'' editing of each input file.
It uses the bundled @file{inplace.awk} include file to invoke the extension
properly:
@@ -33750,14 +33754,14 @@ they are read, with each entry returned as a record.
The record consists of three fields. The first two are the inode number and the
@value{FN}, separated by a forward slash character.
On systems where the directory entry contains the file type, the record
-has a third field (also separated by a slash) which is a single letter
+has a third field (also separated by a slash), which is a single letter
indicating the type of the file. The letters and their corresponding file
types are shown in @ref{table-readdir-file-types}.
@float Table,table-readdir-file-types
@caption{File types returned by the @code{readdir} extension}
@multitable @columnfractions .1 .9
address@hidden Letter @tab File Type
address@hidden Letter @tab File type
@item @code{b} @tab Block device
@item @code{c} @tab Character device
@item @code{d} @tab Directory
@@ -33785,7 +33789,7 @@ Here is an example:
@@load "readdir"
@dots{}
BEGIN @{ FS = "/" @}
address@hidden print "file name is", $2 @}
address@hidden print "@value{FN} is", $2 @}
@end example
@node Extension Sample Revout
@@ -33806,8 +33810,7 @@ BEGIN @{
@}
@end example
-The output from this program is:
address@hidden t'nod}.
+The output from this program is @samp{cinap t'nod}.
@node Extension Sample Rev2way
@subsection Two-Way I/O Example
@@ -33862,7 +33865,7 @@ success, or zero upon failure.
@code{reada()} is the inverse of @code{writea()};
it reads the file named as its first argument, filling in
the array named as the second argument. It clears the array first.
-Here too, the return value is one on success and zero upon failure.
+Here too, the return value is one on success, or zero upon failure.
@end table
The array created by @code{reada()} is identical to that written by
@@ -33950,7 +33953,7 @@ it tries to use @code{GetSystemTimeAsFileTime()}.
Attempt to sleep for @var{seconds} seconds. If @var{seconds} is negative,
or the attempt to sleep fails, return @minus{}1 and set @code{ERRNO}.
Otherwise, return zero after sleeping for the indicated amount of time.
-Note that @var{seconds} may be a floating-point (non-integral) value.
+Note that @var{seconds} may be a floating-point (nonintegral) value.
Implementation details: depending on platform availability, this function
tries to use @code{nanosleep()} or @code{select()} to implement the delay.
@end table
@@ -33977,10 +33980,13 @@ project provides a number of @command{gawk}
extensions, including one for
processing XML files. This is the evolution of the original @command{xgawk}
(XML @command{gawk}) project.
-As of this writing, there are six extensions:
+As of this writing, there are seven extensions:
@itemize @value{BULLET}
@item
address@hidden extension
+
address@hidden
GD graphics library extension
@item
@@ -33991,7 +33997,7 @@ PostgreSQL extension
@item
MPFR library extension
-(this provides access to a number of MPFR functions which @command{gawk}'s
+(this provides access to a number of MPFR functions that @command{gawk}'s
native MPFR support does not)
@item
@@ -34045,7 +34051,7 @@ make install @ii{Install the
extensions}
If you have installed @command{gawk} in the standard way, then you
will likely not need the @option{--with-gawk} option when configuring
address@hidden You may also need to use the @command{sudo} utility
address@hidden You may need to use the @command{sudo} utility
to install both @command{gawk} and @code{gawkextlib}, depending upon
how your system works.
@@ -34070,7 +34076,7 @@ named @code{plugin_is_GPL_compatible}.
@item
Communication between @command{gawk} and an extension is two-way.
address@hidden passes a @code{struct} to the extension which contains
address@hidden passes a @code{struct} to the extension that contains
various data fields and function pointers. The extension can then call
into @command{gawk} via the supplied function pointers to accomplish
certain tasks.
@@ -34083,7 +34089,7 @@ By convention, implementation functions are named
@address@hidden()}
for some @command{awk}-level function @address@hidden()}.
@item
-The API is defined in a header file named @file{gawkpi.h}. You must include
+The API is defined in a header file named @file{gawkapi.h}. You must include
a number of standard header files @emph{before} including it in your source
file.
@item
@@ -34128,7 +34134,7 @@ getting the count of elements in an array;
creating a new array;
clearing an array;
and
-flattening an array for easy C style looping over all its indices and elements)
+flattening an array for easy C-style looping over all its indices and elements)
@end itemize
@item
@@ -34136,7 +34142,7 @@ The API defines a number of standard data types for
representing
@command{awk} values, array elements, and arrays.
@item
-The API provide convenience functions for constructing values.
+The API provides convenience functions for constructing values.
It also provides memory management functions to ensure compatibility
between memory allocated by @command{gawk} and memory allocated by an
extension.
@@ -34162,8 +34168,8 @@ file make this easier to do.
@item
The @command{gawk} distribution includes a number of small but useful
-sample extensions. The @code{gawkextlib} project includes several more,
-larger, extensions. If you wish to write an extension and contribute it
+sample extensions. The @code{gawkextlib} project includes several more
+(larger) extensions. If you wish to write an extension and contribute it
to the community of @command{gawk} users, the @code{gawkextlib} project
is the place to do so.
diff --git a/extension/ChangeLog b/extension/ChangeLog
index e30ad59..22eee5e 100644
--- a/extension/ChangeLog
+++ b/extension/ChangeLog
@@ -1,3 +1,7 @@
+2015-02-11 Arnold D. Robbins <address@hidden>
+
+ * filefuncs.c: Punctuation fix.
+
2015-01-24 Arnold D. Robbins <address@hidden>
Infrastructure updates.
diff --git a/extension/filefuncs.c b/extension/filefuncs.c
index a20e9ff..ddb1ecd 100644
--- a/extension/filefuncs.c
+++ b/extension/filefuncs.c
@@ -490,7 +490,7 @@ do_stat(int nargs, awk_value_t *result)
/* always empty out the array */
clear_array(array);
- /* stat the file, if error, set ERRNO and return */
+ /* stat the file; if error, set ERRNO and return */
ret = statfunc(name, & sbuf);
if (ret < 0) {
update_ERRNO_int(errno);
diff --git a/gawkapi.h b/gawkapi.h
index d821545..7a58bd4 100644
--- a/gawkapi.h
+++ b/gawkapi.h
@@ -846,7 +846,7 @@ make_number(double num, awk_value_t *result)
extern int dl_load(const gawk_api_t *const api_p, awk_ext_id_t id);
#if 0
-/* Boiler plate code: */
+/* Boilerplate code: */
int plugin_is_GPL_compatible;
static gawk_api_t *const api;
-----------------------------------------------------------------------
Summary of changes:
ChangeLog | 4 +
doc/ChangeLog | 4 +
doc/gawk.info | 575 +++++++++++++++++++++++++------------------------
doc/gawk.texi | 272 ++++++++++++------------
doc/gawktexi.in | 272 ++++++++++++------------
extension/ChangeLog | 4 +
extension/filefuncs.c | 2 +-
gawkapi.h | 2 +-
8 files changed, 582 insertions(+), 553 deletions(-)
hooks/post-receive
--
gawk
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [gawk-diffs] [SCM] gawk branch, gawk-4.1-stable, updated. gawk-4.1.0-586-g2f49027,
Arnold Robbins <=