[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[gawk-diffs] [SCM] gawk branch, master, updated. b1746329b7749a8f760bab0
|
From: |
Arnold Robbins |
|
Subject: |
[gawk-diffs] [SCM] gawk branch, master, updated. b1746329b7749a8f760bab04c12e5127a23e46ed |
|
Date: |
Thu, 31 Mar 2011 21:01:06 +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, master has been updated
via b1746329b7749a8f760bab04c12e5127a23e46ed (commit)
from 089e787a5a970f8005cf4ee34b152bf1747b14b0 (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=b1746329b7749a8f760bab04c12e5127a23e46ed
commit b1746329b7749a8f760bab04c12e5127a23e46ed
Author: Arnold D. Robbins <address@hidden>
Date: Thu Mar 31 22:59:51 2011 +0200
Lots of documentation updates.
diff --git a/ChangeLog b/ChangeLog
index 3762626..7264bb3 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+Thu Mar 31 22:57:36 2011 Arnold D. Robbins <address@hidden>
+
+ * Checklist: Updated. This is a git-only file.
+ * POSIX.STD: Revised some.
+
Tue Mar 29 20:52:38 2011 John Haque <address@hidden>
* awkgram.y (LEXT_NEXT): Don't issue an error message if the next
diff --git a/Checklist b/Checklist
index 47c11cb..52e314f 100644
--- a/Checklist
+++ b/Checklist
@@ -45,3 +45,6 @@ The simplest way of making sure that no PO file is forgotten,
is to
run the following command just before rolling a new release:
rsync -Lrtvz translationproject.org::tp/latest/gawk/ po
+
+Major releases:
+- Rotate the ChangeLog and NEWS files.
diff --git a/POSIX.STD b/POSIX.STD
index a5b2fe3..1555d7b 100644
--- a/POSIX.STD
+++ b/POSIX.STD
@@ -1,11 +1,11 @@
- Copyright (C) 1992, 1995, 1998, 2001, 2006, 2007, 2010
+ Copyright (C) 1992, 1995, 1998, 2001, 2006, 2007, 2010, 2011
Free Software Foundation, Inc.
Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved.
--------------------------------------------------------------------------
-Wed Dec 1 21:51:31 IST 2010
+Thu Mar 31 22:31:57 IST 2011
============================
This file documents several things related to the 2008 POSIX standard
that I noted after reviewing it.
@@ -39,3 +39,5 @@ The following things aren't described by POSIX but ought to
be:
3. What happens with substr() if start is <= 0, or greater than the length
of the string, or if length is <= 0.
+
+4. Whether "next" can be invoked from a function body.
diff --git a/doc/gawk.info b/doc/gawk.info
index 7009125..fde2546 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -304,6 +304,8 @@ texts being (a) (see below), and with the Back-Cover Texts
being (b)
* Scanning an Array:: A variation of the `for' statement. It
loops through the indices of an array's
existing elements.
+* Controlling Scanning:: Controlling the order in which arrays
+ are scanned.
* Delete:: The `delete' statement removes an
element from an array.
* Numeric Array Subscripts:: How to use numbers as subscripts in
@@ -9411,10 +9413,10 @@ with a pound sign (`#').
order in which array indices will be processed by `for (index
in array) ...' loops. The value should contain one to three
words; separate pairs of words by a single space. One word
- controls sort direction, "ascending" or "descending;" another
- controls the sort key, "index" or "value;" and the remaining
+ controls sort direction, `ascending' or `descending'; another
+ controls the sort key, `index' or `value'; and the remaining
one, which is only valid for sorting by index, is comparison
- mode, "string" or "number." When two or three words are
+ mode, `string' or `number'. When two or three words are
present, they may be specified in any order, so `ascending
index string' and `string ascending index' are equivalent.
Also, each word may be truncated, so `asc index str' and `a i
@@ -9423,17 +9425,18 @@ with a pound sign (`#').
letter each.
You can omit direction and/or key type and/or comparison
- mode. Provided that at least one is present, missing parts
- of a sort specification default to `ascending', `index', and
- (for indices only) `string', respectively. An empty string,
- `""', is the same as `unsorted' and will cause `for (index in
- array) ...' to process the indices in arbitrary order.
- Another thing to note is that the array sorting takes place
- at the time `for (... in ...)' is about to start executing,
- so changing the value of `PROCINFO["sorted_in"]' during loop
- execution does not have any effect on the order in which any
- remaining array elements get processed. *Note Scanning an
- Array::, for more information.
+ mode. Provided that at least one is present, the missing
+ parts of a sort specification default to `ascending',
+ `index', and (for indices only) `string', respectively. An
+ empty string, `""', is the same as `unsorted' and will cause
+ `for (index in array) ...' to process the indices in
+ arbitrary order. Another thing to note is that the array
+ sorting takes place at the time the `for' loop is about to
+ start executing, so changing the value of
+ `PROCINFO["sorted_in"]' during loop execution does not have
+ any effect on the order in which any remaining array elements
+ get processed. *Note Scanning an Array::, for more
+ information.
`PROCINFO["strftime"]'
The default time format string for `strftime()'. Assigning a
@@ -9900,7 +9903,11 @@ File: gawk.info, Node: Scanning an Array, Prev: Array
Example, Up: Array Basi
8.1.5 Scanning All Elements of an Array
---------------------------------------
-In programs that use arrays, it is often necessary to use a loop that
+* Menu:
+
+* Controlling Scanning:: Controlling the order in which arrays are scanned.
+
+ In programs that use arrays, it is often necessary to use a loop that
executes once for each element of an array. In other languages, where
arrays are contiguous and indices are limited to positive integers,
this is easy: all the valid indices can be found by counting from the
@@ -9950,41 +9957,51 @@ statements in the loop body; it is not predictable
whether the `for'
loop will reach them. Similarly, changing VAR inside the loop may
produce strange results. It is best to avoid such things.
- As an extension, `gawk' makes it possible for you to loop over the
+
+File: gawk.info, Node: Controlling Scanning, Up: Scanning an Array
+
+8.1.5.1 Controlling Array Scanning Order
+........................................
+
+As an extension, `gawk' makes it possible for you to loop over the
elements of an array in order, based on the value of
`PROCINFO["sorted_in"]' (*note Auto-set::). Several sorting options
are available:
-`"ascending index string"'
- Order by indices compared as strings, the most basic sort.
+`ascending index string'
+ Order by indices compared as strings; this is the most basic sort.
(Internally, array indices are always strings, so with `a[2*5] = 1'
the index is actually `"10"' rather than numeric 10.)
-`"ascending index number"'
+`ascending index number'
Order by indices but force them to be treated as numbers in the
process. Any index with non-numeric value will end up positioned
- as if it were 0.
+ as if it were zero.
-`"ascending value"'
+`ascending value'
Order by element values rather than by indices. Comparisons are
done as numeric when both values being compared are numeric, or
- done as strings when either or both aren't numeric. Sub-arrays,
- if present, come out last.
+ done as strings when either or both aren't numeric (*note Variable
+ Typing::). Subarrays, if present, come out last.
-`"descending index string"'
+`descending index string'
Reverse order from the most basic sort.
-`"descending index number"'
+`descending index number'
Numeric indices ordered from high to low.
-`"descending value"'
- Element values ordered from high to low. Sub-arrays, if present,
+`descending value'
+ Element values ordered from high to low. Subarrays, if present,
come out first.
-`"unsorted"'
+`unsorted'
Array elements are processed in arbitrary order, the normal `awk'
behavior.
+ The array traversal order is determined before the `for' loop starts
+to run. Changing `PROCINFO["sorted_in"]' in the looop body will not
+affect the loop.
+
Portions of the sort specification string may be truncated or
omitted. The default is `ascending' for direction, `index' for sort
key type, and (when sorting by index only) `string' for comparison mode.
@@ -10008,31 +10025,31 @@ For example:
-| 3 3
-| 4 4
- As a side note, sorting the array indices before traversing the
-array has been reported to add 15% to 20% overhead to the execution
-time of `awk' programs. For this reason, sorted array traversal is not
-the default.
-
When sorting an array by element values, if a value happens to be a
-sub-array then it is considered to be greater than any string or
-numeric value, regardless of what the sub-array itself contains, and
-all sub-arrays are treated as being equal to each other. Their order
+subarray then it is considered to be greater than any string or numeric
+value, regardless of what the subarray itself contains, and all
+subarrays are treated as being equal to each other. Their order
relative to each other is determined by their index strings.
- Sorting by array element values (for values other than sub-arrays)
+ Sorting by array element values (for values other than subarrays)
always uses basic `awk' comparison mode: if both values happen to be
numbers then they're compared as numbers, otherwise they're compared as
strings.
When string comparisons are made during a sort, either for element
values where one or both aren't numbers or for element indices handled
-as strings, the value of `IGNORECASE' controls whether the comparisons
-treat corresponding upper and lower case letters as equivalent or
-distinct.
+as strings, the value of `IGNORECASE' (*note Built-in Variables::)
+controls whether the comparisons treat corresponding upper and lower
+case letters as equivalent or distinct.
This sorting extension is disabled in POSIX mode, since the
`PROCINFO' array is not special in that case.
+ As a side note, sorting the array indices before traversing the
+array has been reported to add 15% to 20% overhead to the execution
+time of `awk' programs. For this reason, sorted array traversal is not
+the default.
+
File: gawk.info, Node: Delete, Next: Numeric Array Subscripts, Prev: Array
Basics, Up: Arrays
@@ -20013,7 +20030,7 @@ File: gawk.info, Node: Extracting, Next: Distribution
contents, Prev: Getting
B.1.2 Extracting the Distribution
---------------------------------
-`gawk' is distributed as several `tar' file compressed with different
+`gawk' is distributed as several `tar' files compressed with different
compression programs: `gzip', `bzip2', and `xz'. For simplicity, the
rest of these instructions assume you are using the one compressed with
the GNU Zip program, `gzip'.
@@ -20072,9 +20089,15 @@ Various `.c', `.y', and `.h' files
A detailed list of source code changes as bugs are fixed or
improvements made.
+`ChangeLog.0'
+ An older list of source code changes.
+
`NEWS'
A list of changes to `gawk' since the last release or patch.
+`NEWS.0'
+ An older list of changes to `gawk'.
+
`COPYING'
The GNU General Public License.
@@ -20089,12 +20112,14 @@ Various `.c', `.y', and `.h' files
not limits in `gawk' itself.
`POSIX.STD'
- A description of one area in which the POSIX standard for `awk' is
- incorrect as well as how `gawk' handles the problem.
+ A description of behaviors in the POSIX standard for `awk' which
+ are left undefined, or where `gawk' may not comply fully, as well
+ as a list of things that the POSIX standard should describe but
+ does not.
`doc/awkforai.txt'
- A short article describing why `gawk' is a good language for AI
- (Artificial Intelligence) programming.
+ A short article describing why `gawk' is a good language for
+ Artificial Intelligence (AI) programming.
`doc/bc_notes'
A brief description of `gawk''s "byte code" internals.
@@ -20259,7 +20284,7 @@ run `make check'. All of the tests should succeed. If
these steps do
not work, or if any of the tests fail, check the files in the
`README_d' directory to see if you've found a known problem. If the
failure is not described there, please send in a bug report (*note
-Bugs::.)
+Bugs::).
File: gawk.info, Node: Additional Configuration Options, Next: Configuration
Philosophy, Prev: Quick Installation, Up: Unix Installation
@@ -20270,10 +20295,6 @@ B.2.2 Additional Configuration Options
There are several additional options you may use on the `configure'
command line when compiling `gawk' from scratch, including:
-`--with-whiny-user-strftime'
- Force use of the included version of the `strftime()' function for
- deficient systems.
-
`--disable-lint'
Disable all lint checking within `gawk'. The `--lint' and
`--lint-old' options (*note Options::) are accepted, but silently
@@ -20294,6 +20315,10 @@ command line when compiling `gawk' from scratch,
including:
desirable, but it may bring you some slight performance
improvement.
+`--with-whiny-user-strftime'
+ Force use of the included version of the `strftime()' function for
+ deficient systems.
+
Use the command `./configure --help' to see the full list of options
that `configure' supplies.
@@ -20630,8 +20655,8 @@ B.3.1.5 Using `gawk' In The Cygwin Environment
are using the Cygwin environment (http://www.cygwin.com). This
environment provides an excellent simulation of Unix, using the GNU
tools, such as Bash, the GNU Compiler Collection (GCC), GNU Make, and
-other GNU tools. Compilation and installation for Cygwin is the same
-as for a Unix system:
+other GNU programs. Compilation and installation for Cygwin is the
+same as for a Unix system:
tar -xvpzf gawk-4.0.0.tar.gz
cd gawk-4.0.0
@@ -20666,9 +20691,8 @@ File: gawk.info, Node: VMS Installation, Prev: PC
Installation, Up: Non-Unix
B.3.2 How to Compile and Install `gawk' on VMS
----------------------------------------------
-This node describes how to compile and install `gawk' under VMS.
-
- The older designation "VMS" is used throughout to refer to OpenVMS.
+This node describes how to compile and install `gawk' under VMS. The
+older designation "VMS" is used throughout to refer to OpenVMS.
* Menu:
@@ -20868,11 +20892,11 @@ considered authoritative if it conflicts with this
Info file.
The people maintaining the non-Unix ports of `gawk' are as follows:
-MS-Windows using MINGW Eli Zaretskii, <address@hidden>.
- Scott Deifik, <address@hidden>.
-OS/2 Andreas Buening, <address@hidden>.
-VMS Pat Rankin, <address@hidden>.
-z/OS (OS/390) Dave Pitts, <address@hidden>.
+MS-Windows with MINGW and DJGPP Eli Zaretskii, <address@hidden>.
+ Scott Deifik, <address@hidden>.
+OS/2 Andreas Buening, <address@hidden>.
+VMS Pat Rankin, <address@hidden>.
+z/OS (OS/390) Dave Pitts, <address@hidden>.
If your bug is also reproducible under Unix, please send a copy of
your report to the <address@hidden> email list as well.
@@ -21073,7 +21097,7 @@ File: gawk.info, Node: Accessing The Source, Next:
Adding Code, Up: Additions
C.2.1 Accessing The `gawk' Git Repository
-----------------------------------------
-As `gawk' is Free Software, the source code is always available *note
+As `gawk' is Free Software, the source code is always available. *note
Gawk Distribution::, describes how to get and build the formal,
released versions of `gawk'.
@@ -21118,13 +21142,21 @@ possible to include your changes:
If that's not possible, continue with the rest of the steps in
this list.
- 2. Get the latest version. It is much easier for me to integrate
+ 2. Be prepared to sign the appropriate paperwork. In order for the
+ FSF to distribute your changes, you must either place those
+ changes in the public domain and submit a signed statement to that
+ effect, or assign the copyright in your changes to the FSF. Both
+ of these actions are easy to do and _many_ people have done so
+ already. If you have questions, please contact me (*note Bugs::),
+ or <address@hidden>.
+
+ 3. Get the latest version. It is much easier for me to integrate
changes if they are relative to the most recent distributed
version of `gawk'. If your version of `gawk' is very old, I may
not be able to integrate them at all. (*Note Getting::, for
information on getting the latest version of `gawk'.)
- 3. See *note (Version)Top:: standards, GNU Coding Standards. This
+ 4. See *note (Version)Top:: standards, GNU Coding Standards. This
document describes how GNU software should be written. If you
haven't read it, please do so, preferably _before_ starting to
modify `gawk'. (The `GNU Coding Standards' are available from the
@@ -21132,7 +21164,7 @@ possible to include your changes:
(http://www.gnu.org/prep/standards_toc.html). Texinfo, Info, and
DVI versions are also available.)
- 4. Use the `gawk' coding style. The C code for `gawk' follows the
+ 5. Use the `gawk' coding style. The C code for `gawk' follows the
instructions in the `GNU Coding Standards', with minor exceptions.
The code is formatted using the traditional "K&R" style,
particularly as regards to the placement of braces and the use of
@@ -21143,8 +21175,8 @@ possible to include your changes:
* Put the name of the function at the beginning of its own line.
- * Put the return type of the function, even if it is `int()',
- on the line above the line with the name and arguments of the
+ * Put the return type of the function, even if it is `int', on
+ the line above the line with the name and arguments of the
function.
* Put spaces around parentheses used in control structures
@@ -21180,18 +21212,19 @@ possible to include your changes:
worth the minor benefit of not having to free the storage.
Instead, use `malloc()' and `free()'.
+ * Do not use comparisons of the form `! strcmp(a, b)' or
+ similar. As Henry Spencer once said, "`strcmp()' is not a
+ boolean!" Instead, use `strcmp(a, b) == 0'.
+
+ * If adding new bit flag values, use explicit hexadecimal
+ constants (`0x001', `0x002', `0x004', and son on) instead of
+ shifting one left by successive amounts (`(1<<0)', `(1<<1)',
+ and so on).
+
NOTE: If I have to reformat your code to follow the coding
style used in `gawk', I may not bother to integrate your
changes at all.
- 5. Be prepared to sign the appropriate paperwork. In order for the
- FSF to distribute your changes, you must either place those
- changes in the public domain and submit a signed statement to that
- effect, or assign the copyright in your changes to the FSF. Both
- of these actions are easy to do and _many_ people have done so
- already. If you have questions, please contact me (*note Bugs::),
- or <address@hidden>.
-
6. Update the documentation. Along with your new code, please supply
new sections and/or chapters for this Info file. If at all
possible, please use real Texinfo, instead of just supplying
@@ -21236,7 +21269,14 @@ steps:
1. Follow the guidelines in *note Adding Code::, concerning coding
style, submission of diffs, and so on.
- 2. When doing a port, bear in mind that your code must coexist
+ 2. Be prepared to sign the appropriate paperwork. In order for the
+ FSF to distribute your code, you must either place your code in
+ the public domain and submit a signed statement to that effect, or
+ assign the copyright in your code to the FSF. Both of these
+ actions are easy to do and _many_ people have done so already. If
+ you have questions, please contact me, or <address@hidden>.
+
+ 3. When doing a port, bear in mind that your code must coexist
peacefully with the rest of `gawk' and the other ports. Avoid
gratuitous changes to the system-independent parts of the code. If
at all possible, avoid sprinkling `#ifdef's just for your port
@@ -21247,7 +21287,7 @@ steps:
can, of course, distribute your changes on your own, as long as
you comply with the GPL (*note Copying::).
- 3. A number of the files that come with `gawk' are maintained by other
+ 4. A number of the files that come with `gawk' are maintained by other
people. Thus, you should not change them unless it is for a very
good reason; i.e., changes are not out of the question, but
changes to these files are scrutinized extra carefully. The files
@@ -21256,13 +21296,13 @@ steps:
`regexec.c', `regexex.c', `regex.h', `regex_internal.c', and
`regex_internal.h'.
- 4. Be willing to continue to maintain the port. Non-Unix operating
+ 5. Be willing to continue to maintain the port. Non-Unix operating
systems are supported by volunteers who maintain the code needed
to compile and run `gawk' on their systems. If noone volunteers to
maintain a port, it becomes unsupported and it may be necessary to
remove it from the distribution.
- 5. Supply an appropriate `gawkmisc.???' file. Each port has its own
+ 6. Supply an appropriate `gawkmisc.???' file. Each port has its own
`gawkmisc.???' that implements certain operating system specific
functions. This is cleaner than a plethora of `#ifdef's scattered
throughout the code. The `gawkmisc.c' in the main source
@@ -21278,7 +21318,7 @@ steps:
(Currently, this is only an issue for the PC operating system
ports.)
- 6. Supply a `Makefile' as well as any other C source and header files
+ 7. Supply a `Makefile' as well as any other C source and header files
that are necessary for your operating system. All your code
should be in a separate subdirectory, with a name that is the same
as, or reminiscent of, either your operating system or the
@@ -21288,17 +21328,10 @@ steps:
avoid using names for your files that duplicate the names of files
in the main source directory.
- 7. Update the documentation. Please write a section (or sections)
+ 8. Update the documentation. Please write a section (or sections)
for this Info file describing the installation and compilation
steps needed to compile and/or install `gawk' for your system.
- 8. Be prepared to sign the appropriate paperwork. In order for the
- FSF to distribute your code, you must either place your code in
- the public domain and submit a signed statement to that effect, or
- assign the copyright in your code to the FSF. Both of these
- actions are easy to do and _many_ people have done so already. If
- you have questions, please contact me, or <address@hidden>.
-
Following these steps makes it much easier to integrate your changes
into `gawk' and have them coexist happily with other operating systems'
code that is already there.
@@ -21423,7 +21456,7 @@ when writing extensions. The next minor node shows how
they are used:
`NODE **assoc_lookup(NODE *symbol, NODE *subs, int reference)'
Finds, and installs if necessary, array elements. `symbol' is the
array, `subs' is the subscript. This is usually a value created
- with `make_string' (see below). `reference' should be `TRUE' if
+ with `make_string()' (see below). `reference' should be `TRUE' if
it is an error to use the value before it is created. Typically,
`FALSE' is the correct value to use from extension functions.
@@ -21444,7 +21477,7 @@ when writing extensions. The next minor node shows how
they are used:
`void unref(NODE *n)'
This macro releases the memory associated with a `NODE' allocated
- with `make_string' or `make_number'. Understanding of `gawk'
+ with `make_string()' or `make_number()'. Understanding of `gawk'
memory management is helpful.
`void make_builtin(const char *name, NODE *(*func)(NODE *), int count)'
@@ -21483,13 +21516,12 @@ when writing extensions. The next minor node shows
how they are used:
`void update_ERRNO(void)'
This function is called from within a C extension function to set
the value of `gawk''s `ERRNO' variable, based on the current value
- of the C `errno' variable. It is provided as a convenience.
+ of the C `errno' global variable. It is provided as a convenience.
`void update_ERRNO_saved(int errno_saved)'
This function is called from within a C extension function to set
- the value of `gawk''s `ERRNO' variable, based on the saved value
- of the C `errno' variable provided as the argument. It is
- provided as a convenience.
+ the value of `gawk''s `ERRNO' variable, based on the error value
+ provided as the argument. It is provided as a convenience.
`void register_deferred_variable(const char *name, NODE *(*load_func)(void))'
This function is called to register a function to be called when a
@@ -21514,13 +21546,13 @@ when writing extensions. The next minor node shows
how they are used:
containing additional state associated with the input processing),
and no further open hooks are called.
- The function called will most likely want to set the `IOBUF'
- `get_record()' method to indicate that future input records should
+ The function called will most likely want to set the `IOBUF''s
+ `get_record' method to indicate that future input records should
be retrieved by calling that method instead of using the standard
`gawk' input processing.
- And the function will also probably want to set the `IOBUF'
- `close_func()' method to be called when the file is closed to clean
+ And the function will also probably want to set the `IOBUF''s
+ `close_func' method to be called when the file is closed to clean
up any state associated with the input.
Finally, hook functions should be prepared to receive an `IOBUF'
@@ -21541,7 +21573,8 @@ function parameter.
NODE *the_arg;
- the_arg = get_array_argument(2, FALSE); /* assume need 3rd arg, 0-based */
+ /* assume need 3rd arg, 0-based */
+ the_arg = get_array_argument(2, FALSE);
Again, you should spend time studying the `gawk' internals; don't
just blindly copy this code.
@@ -21583,8 +21616,8 @@ implements these functions for `gawk' in an external
extension library.
File: gawk.info, Node: Internal File Description, Next: Internal File Ops,
Up: Sample Library
-C.3.3.1 Using `chdir' and `stat'
-................................
+C.3.3.1 Using `chdir()' and `stat()'
+....................................
This minor node shows how to use the new functions at the `awk' level
once they've been integrated into the running `gawk' interpreter.
@@ -21734,18 +21767,18 @@ other POSIX-compliant systems:(1)
The file includes the `"awk.h"' header file for definitions for the
`gawk' internals. It includes `<sys/sysmacros.h>' for access to the
-`major' and `minor' macros.
+`major()' and `minor'() macros.
By convention, for an `awk' function `foo', the function that
implements it is called `do_foo'. The function should take a `int'
argument, usually called `nargs', that represents the number of defined
arguments for the function. The `newdir' variable represents the new
-directory to change to, retrieved with `get_scalar_argument'. Note
+directory to change to, retrieved with `get_scalar_argument()'. Note
that the first argument is numbered zero.
- This code actually accomplishes the `chdir'. It first forces the
-argument to be a string and passes the string value to the `chdir'
-system call. If the `chdir' fails, `ERRNO' is updated.
+ This code actually accomplishes the `chdir()'. It first forces the
+argument to be a string and passes the string value to the `chdir()'
+system call. If the `chdir()' fails, `ERRNO' is updated.
(void) force_string(newdir);
ret = chdir(newdir->stptr);
@@ -21757,7 +21790,7 @@ system call. If the `chdir' fails, `ERRNO' is updated.
return make_number((AWKNUM) ret);
}
- The `stat' built-in is more involved. First comes a function that
+ The `stat()' built-in 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:
@@ -21769,7 +21802,7 @@ turns a numeric mode into a printable representation
(e.g., 644 becomes
...
}
- Next comes the `do_stat' function. It starts with variable
+ Next comes the `do_stat()' function. It starts with variable
declarations and argument checking:
/* do_stat --- provide a stat() function for gawk */
@@ -21792,7 +21825,7 @@ Then, it always clears the array. The code use
`lstat()' (instead of
`stat()') to get the file information, in case the file is a symbolic
link. If there's an error, it sets `ERRNO' and returns:
- /* directory is first arg, array to hold results is second */
+ /* file is first arg, array to hold results is second */
file = get_scalar_argument(0, FALSE);
array = get_array_argument(1, FALSE);
@@ -21832,7 +21865,7 @@ calls are shown here, since they all follow the same
pattern:
Finally, it's necessary to provide the "glue" that loads the new
function(s) into `gawk'. By convention, each library has a routine
-named `dlload' that does the job:
+named `dlload()' that does the job:
/* dlload --- load new builtins in this library */
@@ -21849,9 +21882,9 @@ implement system calls such as `chown()', `chmod()',
and `umask()'.
---------- Footnotes ----------
- (1) This version is edited slightly for presentation. The complete
-version can be found in `extension/filefuncs.c' in the `gawk'
-distribution.
+ (1) This version is edited slightly for presentation. See
+`extension/filefuncs.c' in the `gawk' distribution for the complete
+version.
File: gawk.info, Node: Using Internal File Ops, Prev: Internal File Ops,
Up: Sample Library
@@ -24312,9 +24345,9 @@ Index
* --command option: Options. (line 229)
* --copyright option: Options. (line 85)
* --disable-lint configuration option: Additional Configuration Options.
- (line 13)
+ (line 9)
* --disable-nls configuration option: Additional Configuration Options.
- (line 28)
+ (line 24)
* --dump-variables option <1>: Library Names. (line 45)
* --dump-variables option: Options. (line 90)
* --exec option: Options. (line 112)
@@ -24349,7 +24382,7 @@ Index
* --use-lc-numeric option: Options. (line 173)
* --version option: Options. (line 248)
* --with-whiny-user-strftime configuration option: Additional Configuration
Options.
- (line 9)
+ (line 29)
* -b option: Options. (line 68)
* -C option: Options. (line 85)
* -d option: Options. (line 90)
@@ -24512,7 +24545,7 @@ Index
(line 67)
* advanced features, data files as single record: Records. (line 175)
* advanced features, fixed-width data: Constant Size. (line 9)
-* advanced features, FNR/NR variables: Auto-set. (line 229)
+* advanced features, FNR/NR variables: Auto-set. (line 230)
* advanced features, gawk: Advanced Features. (line 6)
* advanced features, gawk, network programming: TCP/IP Networking.
(line 6)
@@ -24573,11 +24606,11 @@ Index
* arrays, elements, assigning: Assigning Elements. (line 6)
* arrays, elements, deleting: Delete. (line 6)
* arrays, elements, installing: Internals. (line 79)
-* arrays, elements, order of: Scanning an Array. (line 48)
+* arrays, elements, order of: Scanning an Array. (line 52)
* arrays, elements, referencing: Reference to Elements.
(line 6)
* arrays, elements, retrieving number of: String Functions. (line 29)
-* arrays, for statement and: Scanning an Array. (line 20)
+* arrays, for statement and: Scanning an Array. (line 24)
* arrays, IGNORECASE variable and: Array Intro. (line 92)
* arrays, indexing: Array Intro. (line 50)
* arrays, merging into strings: Join Function. (line 6)
@@ -24593,7 +24626,7 @@ Index
* arrays, subscripts, uninitialized variables as: Uninitialized Subscripts.
(line 6)
* artificial intelligence, gawk and: Distribution contents.
- (line 47)
+ (line 55)
* ASCII <1>: Glossary. (line 137)
* ASCII: Ordinal Functions. (line 45)
* asort() function (gawk) <1>: String Functions. (line 29)
@@ -24879,7 +24912,7 @@ Index
* close() function, two-way pipes and: Two-way I/O. (line 77)
* Close, Diane <1>: Contributors. (line 21)
* Close, Diane: Manual History. (line 41)
-* close_func() input method: Internals. (line 161)
+* close_func() input method: Internals. (line 160)
* collating elements: Bracket Expressions. (line 70)
* collating symbols: Bracket Expressions. (line 77)
* Colombo, Antonio: Acknowledgments. (line 60)
@@ -24949,11 +24982,11 @@ Index
* condition debugger command: Breakpoint Control. (line 54)
* conditional expressions: Conditional Exp. (line 6)
* configuration option, --disable-lint: Additional Configuration Options.
- (line 13)
+ (line 9)
* configuration option, --disable-nls: Additional Configuration Options.
- (line 28)
+ (line 24)
* configuration option, --with-whiny-user-strftime: Additional Configuration
Options.
- (line 9)
+ (line 29)
* configuration options, gawk: Additional Configuration Options.
(line 6)
* constants, nondecimal: Nondecimal Data. (line 6)
@@ -25012,7 +25045,7 @@ Index
(line 47)
* dark corner, FILENAME variable <1>: Auto-set. (line 92)
* dark corner, FILENAME variable: Getline Notes. (line 19)
-* dark corner, FNR/NR variables: Auto-set. (line 229)
+* dark corner, FNR/NR variables: Auto-set. (line 230)
* dark corner, format-control characters: Control Letters. (line 18)
* dark corner, FS as null string: Single Character Fields.
(line 20)
@@ -25211,7 +25244,7 @@ Index
* differences in awk and gawk, regular expressions: Case-sensitivity.
(line 26)
* differences in awk and gawk, RS/RT variables: Records. (line 167)
-* differences in awk and gawk, RT variable: Auto-set. (line 218)
+* differences in awk and gawk, RT variable: Auto-set. (line 219)
* differences in awk and gawk, single-character fields: Single Character
Fields.
(line 6)
* differences in awk and gawk, split() function: String Functions.
@@ -25263,7 +25296,7 @@ Index
(line 6)
* elements in arrays, assigning: Assigning Elements. (line 6)
* elements in arrays, deleting: Delete. (line 6)
-* elements in arrays, order of: Scanning an Array. (line 48)
+* elements in arrays, order of: Scanning an Array. (line 52)
* elements in arrays, scanning: Scanning an Array. (line 6)
* email address for bug reports, address@hidden: Bugs. (line 30)
* EMISTERED: TCP/IP Networking. (line 6)
@@ -25293,7 +25326,7 @@ Index
* endgrent() user-defined function: Group Functions. (line 218)
* endpwent() function (C library): Passwd Functions. (line 210)
* endpwent() user-defined function: Passwd Functions. (line 213)
-* ENVIRON array <1>: Internals. (line 150)
+* ENVIRON array <1>: Internals. (line 149)
* ENVIRON array: Auto-set. (line 60)
* environment variables: Auto-set. (line 60)
* epoch, definition of: Glossary. (line 235)
@@ -25351,7 +25384,7 @@ Index
(line 9)
* expressions, selecting: Conditional Exp. (line 6)
* Extended Regular Expressions (EREs): Bracket Expressions. (line 23)
-* eXtensible Markup Language (XML): Internals. (line 161)
+* eXtensible Markup Language (XML): Internals. (line 160)
* extension() function (gawk): Using Internal File Ops.
(line 15)
* extensions, Brian Kernighan's awk <1>: Other Versions. (line 13)
@@ -25492,9 +25525,9 @@ Index
* floating-point, numbers, AWKNUM internal type: Internals. (line 19)
* FNR variable <1>: Auto-set. (line 102)
* FNR variable: Records. (line 6)
-* FNR variable, changing: Auto-set. (line 229)
+* FNR variable, changing: Auto-set. (line 230)
* for statement: For Statement. (line 6)
-* for statement, in arrays: Scanning an Array. (line 20)
+* for statement, in arrays: Scanning an Array. (line 24)
* force_number() internal function: Internals. (line 27)
* force_string() internal function: Internals. (line 32)
* force_wstring() internal function: Internals. (line 37)
@@ -25595,7 +25628,7 @@ Index
* gawk, break statement in: Break Statement. (line 51)
* gawk, built-in variables and: Built-in Variables. (line 14)
* gawk, character classes and: Bracket Expressions. (line 91)
-* gawk, coding style in: Adding Code. (line 30)
+* gawk, coding style in: Adding Code. (line 38)
* gawk, command-line options: GNU Regexp Operators.
(line 70)
* gawk, comparison operators and: Comparison Operators.
@@ -25666,7 +25699,7 @@ Index
* gawk, regular expressions, operators: GNU Regexp Operators.
(line 6)
* gawk, regular expressions, precedence: Regexp Operators. (line 157)
-* gawk, RT variable in <1>: Auto-set. (line 218)
+* gawk, RT variable in <1>: Auto-set. (line 219)
* gawk, RT variable in <2>: Getline/Variable/File.
(line 10)
* gawk, RT variable in <3>: Multiple Line. (line 129)
@@ -25692,7 +25725,7 @@ Index
* get_argument() internal function: Internals. (line 120)
* get_array_argument() internal macro: Internals. (line 136)
* get_curfunc_arg_count() internal function: Internals. (line 42)
-* get_record() input method: Internals. (line 161)
+* get_record() input method: Internals. (line 160)
* get_scalar_argument() internal macro: Internals. (line 133)
* getaddrinfo() function (C library): TCP/IP Networking. (line 38)
* getgrent() function (C library): Group Functions. (line 6)
@@ -25807,7 +25840,7 @@ Index
* in operator <3>: Precedence. (line 83)
* in operator: Comparison Operators.
(line 11)
-* in operator, arrays and <1>: Scanning an Array. (line 17)
+* in operator, arrays and <1>: Scanning an Array. (line 21)
* in operator, arrays and: Reference to Elements.
(line 37)
* increment operators: Increment Ops. (line 6)
@@ -25845,7 +25878,7 @@ Index
* integers: Basic Data Typing. (line 21)
* integers, unsigned: Basic Data Typing. (line 30)
* interacting with other programs: I/O Functions. (line 63)
-* internal constant, INVALID_HANDLE: Internals. (line 161)
+* internal constant, INVALID_HANDLE: Internals. (line 160)
* internal function, assoc_clear(): Internals. (line 75)
* internal function, assoc_lookup(): Internals. (line 79)
* internal function, dupnode(): Internals. (line 96)
@@ -25855,18 +25888,18 @@ Index
* internal function, get_actual_argument(): Internals. (line 125)
* internal function, get_argument(): Internals. (line 120)
* internal function, get_curfunc_arg_count(): Internals. (line 42)
-* internal function, iop_alloc(): Internals. (line 161)
+* internal function, iop_alloc(): Internals. (line 160)
* internal function, make_builtin(): Internals. (line 106)
* internal function, make_number(): Internals. (line 91)
* internal function, make_string(): Internals. (line 86)
-* internal function, register_deferred_variable(): Internals. (line 150)
-* internal function, register_open_hook(): Internals. (line 161)
+* internal function, register_deferred_variable(): Internals. (line 149)
+* internal function, register_open_hook(): Internals. (line 160)
* internal function, unref(): Internals. (line 101)
* internal function, update_ERRNO(): Internals. (line 139)
* internal function, update_ERRNO_saved(): Internals. (line 144)
* internal macro, get_array_argument(): Internals. (line 136)
* internal macro, get_scalar_argument(): Internals. (line 133)
-* internal structure, IOBUF: Internals. (line 161)
+* internal structure, IOBUF: Internals. (line 160)
* internal type, AWKNUM: Internals. (line 19)
* internal type, NODE: Internals. (line 23)
* internal variable, nargs: Internals. (line 49)
@@ -25895,10 +25928,10 @@ Index
* interpreted programs <1>: Glossary. (line 356)
* interpreted programs: Basic High Level. (line 14)
* interval expressions: Regexp Operators. (line 116)
-* INVALID_HANDLE internal constant: Internals. (line 161)
+* INVALID_HANDLE internal constant: Internals. (line 160)
* inventory-shipped file: Sample Data Files. (line 32)
-* IOBUF internal structure: Internals. (line 161)
-* iop_alloc() internal function: Internals. (line 161)
+* IOBUF internal structure: Internals. (line 160)
+* iop_alloc() internal function: Internals. (line 160)
* isarray() function (gawk): Type Functions. (line 11)
* ISO: Glossary. (line 367)
* ISO 8859-1: Glossary. (line 137)
@@ -26113,7 +26146,7 @@ Index
* not Boolean-logic operator: Boolean Ops. (line 6)
* NR variable <1>: Auto-set. (line 118)
* NR variable: Records. (line 6)
-* NR variable, changing: Auto-set. (line 229)
+* NR variable, changing: Auto-set. (line 230)
* null strings <1>: Basic Data Typing. (line 50)
* null strings <2>: Truth Values. (line 6)
* null strings <3>: Regexp Field Splitting.
@@ -26396,7 +26429,7 @@ Index
* private variables: Library Names. (line 11)
* processes, two-way communications with: Two-way I/O. (line 23)
* processing data: Basic High Level. (line 6)
-* PROCINFO array <1>: Internals. (line 150)
+* PROCINFO array <1>: Internals. (line 149)
* PROCINFO array <2>: Id Program. (line 15)
* PROCINFO array <3>: Group Functions. (line 6)
* PROCINFO array <4>: Passwd Functions. (line 6)
@@ -26491,8 +26524,8 @@ Index
* regexp constants, slashes vs. quotes: Computed Regexps. (line 28)
* regexp constants, vs. string constants: Computed Regexps. (line 38)
* regexp, See regular expressions: Regexp. (line 6)
-* register_deferred_variable() internal function: Internals. (line 150)
-* register_open_hook() internal function: Internals. (line 161)
+* register_deferred_variable() internal function: Internals. (line 149)
+* register_open_hook() internal function: Internals. (line 160)
* regular expressions: Regexp. (line 6)
* regular expressions as field separators: Field Separators. (line 50)
* regular expressions, anchors in: Regexp Operators. (line 22)
@@ -26545,7 +26578,7 @@ Index
* right angle bracket (>), >> operator (I/O): Redirection. (line 50)
* right shift, bitwise: Bitwise Functions. (line 32)
* Ritchie, Dennis: Basic Data Typing. (line 74)
-* RLENGTH variable: Auto-set. (line 205)
+* RLENGTH variable: Auto-set. (line 206)
* RLENGTH variable, match() function and: String Functions. (line 205)
* Robbins, Arnold <1>: Future Extensions. (line 6)
* Robbins, Arnold <2>: Bugs. (line 32)
@@ -26570,9 +26603,9 @@ Index
* RS variable: Records. (line 20)
* RS variable, multiline records and: Multiple Line. (line 17)
* rshift() function (gawk): Bitwise Functions. (line 51)
-* RSTART variable: Auto-set. (line 211)
+* RSTART variable: Auto-set. (line 212)
* RSTART variable, match() function and: String Functions. (line 205)
-* RT variable <1>: Auto-set. (line 218)
+* RT variable <1>: Auto-set. (line 219)
* RT variable <2>: Getline/Variable/File.
(line 10)
* RT variable <3>: Multiple Line. (line 129)
@@ -26777,9 +26810,9 @@ Index
* tee.awk program: Tee Program. (line 26)
* terminating records: Records. (line 112)
* testbits.awk program: Bitwise Functions. (line 68)
-* Texinfo <1>: Adding Code. (line 90)
+* Texinfo <1>: Adding Code. (line 99)
* Texinfo <2>: Distribution contents.
- (line 71)
+ (line 79)
* Texinfo <3>: Extract Program. (line 12)
* Texinfo <4>: Dupword Program. (line 17)
* Texinfo <5>: Library Functions. (line 22)
@@ -26981,7 +27014,7 @@ Index
* wstptr internal variable: Internals. (line 61)
* xgawk: Other Versions. (line 119)
* xgettext utility: String Extraction. (line 13)
-* XML (eXtensible Markup Language): Internals. (line 161)
+* XML (eXtensible Markup Language): Internals. (line 160)
* XOR bitwise operation: Bitwise Functions. (line 6)
* xor() function (gawk): Bitwise Functions. (line 54)
* Yawitz, Efraim: Contributors. (line 104)
@@ -27018,406 +27051,407 @@ Index
Tag Table:
Node: Top1346
-Node: Foreword29921
-Node: Preface34266
-Ref: Preface-Footnote-137233
-Ref: Preface-Footnote-237339
-Node: History37571
-Node: Names39962
-Ref: Names-Footnote-141439
-Node: This Manual41511
-Ref: This Manual-Footnote-146459
-Node: Conventions46559
-Node: Manual History48693
-Ref: Manual History-Footnote-151963
-Ref: Manual History-Footnote-252004
-Node: How To Contribute52078
-Node: Acknowledgments53222
-Node: Getting Started57553
-Node: Running gawk59932
-Node: One-shot61118
-Node: Read Terminal62343
-Ref: Read Terminal-Footnote-163993
-Ref: Read Terminal-Footnote-264269
-Node: Long64440
-Node: Executable Scripts65816
-Ref: Executable Scripts-Footnote-167685
-Ref: Executable Scripts-Footnote-267787
-Node: Comments68238
-Node: Quoting70705
-Node: DOS Quoting75328
-Node: Sample Data Files76003
-Node: Very Simple79035
-Node: Two Rules83634
-Node: More Complex85781
-Ref: More Complex-Footnote-188711
-Node: Statements/Lines88796
-Ref: Statements/Lines-Footnote-193258
-Node: Other Features93523
-Node: When94451
-Node: Invoking Gawk96598
-Node: Command Line97983
-Node: Options98766
-Ref: Options-Footnote-1111898
-Node: Other Arguments111923
-Node: Naming Standard Input114581
-Node: Environment Variables115675
-Node: AWKPATH Variable116119
-Ref: AWKPATH Variable-Footnote-1118716
-Node: Other Environment Variables118976
-Node: Exit Status121316
-Node: Include Files121991
-Node: Obsolete125476
-Node: Undocumented126162
-Node: Regexp126403
-Node: Regexp Usage127855
-Node: Escape Sequences129881
-Node: Regexp Operators135644
-Ref: Regexp Operators-Footnote-1142841
-Ref: Regexp Operators-Footnote-2142988
-Node: Bracket Expressions143086
-Ref: table-char-classes144889
-Node: GNU Regexp Operators147533
-Node: Case-sensitivity151256
-Ref: Case-sensitivity-Footnote-1154224
-Ref: Case-sensitivity-Footnote-2154459
-Node: Leftmost Longest154567
-Node: Computed Regexps155768
-Node: Locales159194
-Node: Reading Files162901
-Node: Records164842
-Ref: Records-Footnote-1173516
-Node: Fields173553
-Ref: Fields-Footnote-1176586
-Node: Nonconstant Fields176672
-Node: Changing Fields178874
-Node: Field Separators184852
-Node: Default Field Splitting187481
-Node: Regexp Field Splitting188598
-Node: Single Character Fields191940
-Node: Command Line Field Separator192999
-Node: Field Splitting Summary196440
-Ref: Field Splitting Summary-Footnote-1199632
-Node: Constant Size199733
-Node: Splitting By Content204317
-Ref: Splitting By Content-Footnote-1208043
-Node: Multiple Line208083
-Ref: Multiple Line-Footnote-1213930
-Node: Getline214109
-Node: Plain Getline216337
-Node: Getline/Variable218426
-Node: Getline/File219567
-Node: Getline/Variable/File220889
-Ref: Getline/Variable/File-Footnote-1222488
-Node: Getline/Pipe222575
-Node: Getline/Variable/Pipe225135
-Node: Getline/Coprocess226242
-Node: Getline/Variable/Coprocess227485
-Node: Getline Notes228199
-Node: Getline Summary230141
-Ref: table-getline-variants230484
-Node: Command line directories231340
-Node: Printing231965
-Node: Print233596
-Node: Print Examples234933
-Node: Output Separators237717
-Node: OFMT239477
-Node: Printf240835
-Node: Basic Printf241741
-Node: Control Letters243280
-Node: Format Modifiers247092
-Node: Printf Examples253101
-Node: Redirection255816
-Node: Special Files262800
-Node: Special FD263333
-Ref: Special FD-Footnote-1266957
-Node: Special Network267031
-Node: Special Caveats267881
-Node: Close Files And Pipes268677
-Ref: Close Files And Pipes-Footnote-1275700
-Ref: Close Files And Pipes-Footnote-2275848
-Node: Expressions275998
-Node: Values277067
-Node: Constants277743
-Node: Scalar Constants278423
-Ref: Scalar Constants-Footnote-1279282
-Node: Nondecimal-numbers279464
-Node: Regexp Constants282523
-Node: Using Constant Regexps282998
-Node: Variables286053
-Node: Using Variables286708
-Node: Assignment Options288432
-Node: Conversion290304
-Ref: table-locale-affects295680
-Ref: Conversion-Footnote-1296304
-Node: All Operators296413
-Node: Arithmetic Ops297043
-Node: Concatenation299548
-Ref: Concatenation-Footnote-1302341
-Node: Assignment Ops302461
-Ref: table-assign-ops307449
-Node: Increment Ops308857
-Node: Truth Values and Conditions312327
-Node: Truth Values313410
-Node: Typing and Comparison314459
-Node: Variable Typing315248
-Ref: Variable Typing-Footnote-1319145
-Node: Comparison Operators319267
-Ref: table-relational-ops319677
-Node: POSIX String Comparison323226
-Ref: POSIX String Comparison-Footnote-1324182
-Node: Boolean Ops324320
-Ref: Boolean Ops-Footnote-1328398
-Node: Conditional Exp328489
-Node: Function Calls330221
-Node: Precedence333815
-Node: Patterns and Actions337468
-Node: Pattern Overview338522
-Node: Regexp Patterns340188
-Node: Expression Patterns340731
-Node: Ranges344305
-Node: BEGIN/END347271
-Node: Using BEGIN/END348033
-Ref: Using BEGIN/END-Footnote-1350764
-Node: I/O And BEGIN/END350870
-Node: BEGINFILE/ENDFILE353152
-Node: Empty355983
-Node: Using Shell Variables356299
-Node: Action Overview358584
-Node: Statements360941
-Node: If Statement362795
-Node: While Statement364294
-Node: Do Statement366338
-Node: For Statement367494
-Node: Switch Statement370646
-Node: Break Statement372743
-Node: Continue Statement374733
-Node: Next Statement376520
-Node: Nextfile Statement378910
-Node: Exit Statement381386
-Node: Built-in Variables383802
-Node: User-modified384897
-Ref: User-modified-Footnote-1392923
-Node: Auto-set392985
-Ref: Auto-set-Footnote-1403716
-Node: ARGC and ARGV403921
-Node: Arrays407772
-Node: Array Basics409343
-Node: Array Intro410054
-Node: Reference to Elements414372
-Node: Assigning Elements416642
-Node: Array Example417133
-Node: Scanning an Array418865
-Node: Delete424132
-Ref: Delete-Footnote-1426567
-Node: Numeric Array Subscripts426624
-Node: Uninitialized Subscripts428807
-Node: Multi-dimensional430435
-Node: Multi-scanning433526
-Node: Array Sorting435110
-Ref: Array Sorting-Footnote-1438204
-Node: Arrays of Arrays438398
-Node: Functions442971
-Node: Built-in443793
-Node: Calling Built-in444871
-Node: Numeric Functions446859
-Ref: Numeric Functions-Footnote-1450624
-Ref: Numeric Functions-Footnote-2450981
-Ref: Numeric Functions-Footnote-3451029
-Node: String Functions451298
-Ref: String Functions-Footnote-1473800
-Ref: String Functions-Footnote-2473929
-Ref: String Functions-Footnote-3474177
-Node: Gory Details474264
-Ref: table-sub-escapes475943
-Ref: table-posix-sub477257
-Ref: table-gensub-escapes478170
-Node: I/O Functions479341
-Ref: I/O Functions-Footnote-1485996
-Node: Time Functions486143
-Ref: Time Functions-Footnote-1497035
-Ref: Time Functions-Footnote-2497103
-Ref: Time Functions-Footnote-3497261
-Ref: Time Functions-Footnote-4497372
-Ref: Time Functions-Footnote-5497484
-Ref: Time Functions-Footnote-6497711
-Node: Bitwise Functions497977
-Ref: table-bitwise-ops498535
-Ref: Bitwise Functions-Footnote-1502695
-Node: Type Functions502879
-Node: I18N Functions503349
-Node: User-defined504976
-Node: Definition Syntax505780
-Ref: Definition Syntax-Footnote-1510690
-Node: Function Example510759
-Node: Function Caveats513353
-Node: Calling A Function513774
-Node: Variable Scope514889
-Node: Pass By Value/Reference516864
-Node: Return Statement520304
-Node: Dynamic Typing523285
-Node: Indirect Calls524020
-Node: Internationalization533705
-Node: I18N and L10N535131
-Node: Explaining gettext535817
-Ref: Explaining gettext-Footnote-1540883
-Ref: Explaining gettext-Footnote-2541067
-Node: Programmer i18n541232
-Node: Translator i18n545432
-Node: String Extraction546225
-Ref: String Extraction-Footnote-1547186
-Node: Printf Ordering547272
-Ref: Printf Ordering-Footnote-1550056
-Node: I18N Portability550120
-Ref: I18N Portability-Footnote-1552569
-Node: I18N Example552632
-Ref: I18N Example-Footnote-1555267
-Node: Gawk I18N555339
-Node: Advanced Features555956
-Node: Nondecimal Data557275
-Node: Two-way I/O558856
-Ref: Two-way I/O-Footnote-1564290
-Node: TCP/IP Networking564360
-Node: Profiling567204
-Node: Library Functions574678
-Ref: Library Functions-Footnote-1577783
-Node: Library Names577954
-Ref: Library Names-Footnote-1581425
-Ref: Library Names-Footnote-2581645
-Node: General Functions581731
-Node: Nextfile Function582794
-Node: Strtonum Function587175
-Node: Assert Function590131
-Node: Round Function593457
-Node: Cliff Random Function595000
-Node: Ordinal Functions596016
-Ref: Ordinal Functions-Footnote-1599086
-Ref: Ordinal Functions-Footnote-2599338
-Node: Join Function599547
-Ref: Join Function-Footnote-1601318
-Node: Gettimeofday Function601518
-Node: Data File Management605233
-Node: Filetrans Function605865
-Node: Rewind Function610101
-Node: File Checking611554
-Node: Empty Files612648
-Node: Ignoring Assigns614878
-Node: Getopt Function616431
-Ref: Getopt Function-Footnote-1627735
-Node: Passwd Functions627938
-Ref: Passwd Functions-Footnote-1636913
-Node: Group Functions637001
-Node: Walking Arrays645085
-Node: Sample Programs646654
-Node: Running Examples647319
-Node: Clones648047
-Node: Cut Program649271
-Node: Egrep Program659116
-Ref: Egrep Program-Footnote-1666889
-Node: Id Program666999
-Node: Split Program670615
-Ref: Split Program-Footnote-1674134
-Node: Tee Program674262
-Node: Uniq Program677065
-Node: Wc Program684494
-Ref: Wc Program-Footnote-1688760
-Ref: Wc Program-Footnote-2688960
-Node: Miscellaneous Programs689052
-Node: Dupword Program690240
-Node: Alarm Program692271
-Node: Translate Program697020
-Ref: Translate Program-Footnote-1701407
-Ref: Translate Program-Footnote-2701635
-Node: Labels Program701769
-Ref: Labels Program-Footnote-1705140
-Node: Word Sorting705224
-Node: History Sorting709108
-Node: Extract Program710947
-Ref: Extract Program-Footnote-1718430
-Node: Simple Sed718558
-Node: Igawk Program721620
-Ref: Igawk Program-Footnote-1736653
-Ref: Igawk Program-Footnote-2736854
-Node: Anagram Program736992
-Node: Signature Program740060
-Node: Debugger741160
-Node: Debugging742071
-Node: Debugging Concepts742484
-Node: Debugging Terms744340
-Node: Awk Debugging746962
-Node: Sample dgawk session747854
-Node: dgawk invocation748346
-Node: Finding The Bug749528
-Node: List of Debugger Commands756014
-Node: Breakpoint Control757325
-Node: Dgawk Execution Control760961
-Node: Viewing And Changing Data764312
-Node: Dgawk Stack767649
-Node: Dgawk Info769109
-Node: Miscellaneous Dgawk Commands773057
-Node: Readline Support778485
-Node: Dgawk Limitations779323
-Node: Language History781512
-Node: V7/SVR3.1782950
-Node: SVR4785271
-Node: POSIX786713
-Node: BTL787721
-Node: POSIX/GNU788455
-Node: Common Extensions793556
-Node: Contributors794657
-Node: Installation798796
-Node: Gawk Distribution799690
-Node: Getting800174
-Node: Extracting801000
-Node: Distribution contents802691
-Node: Unix Installation807709
-Node: Quick Installation808326
-Node: Additional Configuration Options810288
-Node: Configuration Philosophy811765
-Node: Non-Unix Installation814107
-Node: PC Installation814565
-Node: PC Binary Installation815864
-Node: PC Compiling817712
-Node: PC Testing820656
-Node: PC Using821832
-Node: Cygwin826017
-Node: MSYS827014
-Node: VMS Installation827528
-Node: VMS Compilation828134
-Ref: VMS Compilation-Footnote-1829141
-Node: VMS Installation Details829199
-Node: VMS Running830834
-Node: VMS Old Gawk832441
-Node: Bugs832915
-Node: Other Versions836780
-Node: Notes842059
-Node: Compatibility Mode842751
-Node: Additions843534
-Node: Accessing The Source844346
-Node: Adding Code845769
-Node: New Ports851317
-Node: Dynamic Extensions855430
-Node: Internals856806
-Node: Plugin License865922
-Node: Sample Library866556
-Node: Internal File Description867242
-Node: Internal File Ops870949
-Ref: Internal File Ops-Footnote-1875717
-Node: Using Internal File Ops875865
-Node: Future Extensions878242
-Node: Basic Concepts880746
-Node: Basic High Level881503
-Ref: Basic High Level-Footnote-1885538
-Node: Basic Data Typing885723
-Node: Floating Point Issues890248
-Node: String Conversion Precision891331
-Ref: String Conversion Precision-Footnote-1893025
-Node: Unexpected Results893134
-Node: POSIX Floating Point Problems894960
-Ref: POSIX Floating Point Problems-Footnote-1898662
-Node: Glossary898700
-Node: Copying922843
-Node: GNU Free Documentation License960400
-Node: Index985537
+Node: Foreword30042
+Node: Preface34387
+Ref: Preface-Footnote-137354
+Ref: Preface-Footnote-237460
+Node: History37692
+Node: Names40083
+Ref: Names-Footnote-141560
+Node: This Manual41632
+Ref: This Manual-Footnote-146580
+Node: Conventions46680
+Node: Manual History48814
+Ref: Manual History-Footnote-152084
+Ref: Manual History-Footnote-252125
+Node: How To Contribute52199
+Node: Acknowledgments53343
+Node: Getting Started57674
+Node: Running gawk60053
+Node: One-shot61239
+Node: Read Terminal62464
+Ref: Read Terminal-Footnote-164114
+Ref: Read Terminal-Footnote-264390
+Node: Long64561
+Node: Executable Scripts65937
+Ref: Executable Scripts-Footnote-167806
+Ref: Executable Scripts-Footnote-267908
+Node: Comments68359
+Node: Quoting70826
+Node: DOS Quoting75449
+Node: Sample Data Files76124
+Node: Very Simple79156
+Node: Two Rules83755
+Node: More Complex85902
+Ref: More Complex-Footnote-188832
+Node: Statements/Lines88917
+Ref: Statements/Lines-Footnote-193379
+Node: Other Features93644
+Node: When94572
+Node: Invoking Gawk96719
+Node: Command Line98104
+Node: Options98887
+Ref: Options-Footnote-1112019
+Node: Other Arguments112044
+Node: Naming Standard Input114702
+Node: Environment Variables115796
+Node: AWKPATH Variable116240
+Ref: AWKPATH Variable-Footnote-1118837
+Node: Other Environment Variables119097
+Node: Exit Status121437
+Node: Include Files122112
+Node: Obsolete125597
+Node: Undocumented126283
+Node: Regexp126524
+Node: Regexp Usage127976
+Node: Escape Sequences130002
+Node: Regexp Operators135765
+Ref: Regexp Operators-Footnote-1142962
+Ref: Regexp Operators-Footnote-2143109
+Node: Bracket Expressions143207
+Ref: table-char-classes145010
+Node: GNU Regexp Operators147654
+Node: Case-sensitivity151377
+Ref: Case-sensitivity-Footnote-1154345
+Ref: Case-sensitivity-Footnote-2154580
+Node: Leftmost Longest154688
+Node: Computed Regexps155889
+Node: Locales159315
+Node: Reading Files163022
+Node: Records164963
+Ref: Records-Footnote-1173637
+Node: Fields173674
+Ref: Fields-Footnote-1176707
+Node: Nonconstant Fields176793
+Node: Changing Fields178995
+Node: Field Separators184973
+Node: Default Field Splitting187602
+Node: Regexp Field Splitting188719
+Node: Single Character Fields192061
+Node: Command Line Field Separator193120
+Node: Field Splitting Summary196561
+Ref: Field Splitting Summary-Footnote-1199753
+Node: Constant Size199854
+Node: Splitting By Content204438
+Ref: Splitting By Content-Footnote-1208164
+Node: Multiple Line208204
+Ref: Multiple Line-Footnote-1214051
+Node: Getline214230
+Node: Plain Getline216458
+Node: Getline/Variable218547
+Node: Getline/File219688
+Node: Getline/Variable/File221010
+Ref: Getline/Variable/File-Footnote-1222609
+Node: Getline/Pipe222696
+Node: Getline/Variable/Pipe225256
+Node: Getline/Coprocess226363
+Node: Getline/Variable/Coprocess227606
+Node: Getline Notes228320
+Node: Getline Summary230262
+Ref: table-getline-variants230605
+Node: Command line directories231461
+Node: Printing232086
+Node: Print233717
+Node: Print Examples235054
+Node: Output Separators237838
+Node: OFMT239598
+Node: Printf240956
+Node: Basic Printf241862
+Node: Control Letters243401
+Node: Format Modifiers247213
+Node: Printf Examples253222
+Node: Redirection255937
+Node: Special Files262921
+Node: Special FD263454
+Ref: Special FD-Footnote-1267078
+Node: Special Network267152
+Node: Special Caveats268002
+Node: Close Files And Pipes268798
+Ref: Close Files And Pipes-Footnote-1275821
+Ref: Close Files And Pipes-Footnote-2275969
+Node: Expressions276119
+Node: Values277188
+Node: Constants277864
+Node: Scalar Constants278544
+Ref: Scalar Constants-Footnote-1279403
+Node: Nondecimal-numbers279585
+Node: Regexp Constants282644
+Node: Using Constant Regexps283119
+Node: Variables286174
+Node: Using Variables286829
+Node: Assignment Options288553
+Node: Conversion290425
+Ref: table-locale-affects295801
+Ref: Conversion-Footnote-1296425
+Node: All Operators296534
+Node: Arithmetic Ops297164
+Node: Concatenation299669
+Ref: Concatenation-Footnote-1302462
+Node: Assignment Ops302582
+Ref: table-assign-ops307570
+Node: Increment Ops308978
+Node: Truth Values and Conditions312448
+Node: Truth Values313531
+Node: Typing and Comparison314580
+Node: Variable Typing315369
+Ref: Variable Typing-Footnote-1319266
+Node: Comparison Operators319388
+Ref: table-relational-ops319798
+Node: POSIX String Comparison323347
+Ref: POSIX String Comparison-Footnote-1324303
+Node: Boolean Ops324441
+Ref: Boolean Ops-Footnote-1328519
+Node: Conditional Exp328610
+Node: Function Calls330342
+Node: Precedence333936
+Node: Patterns and Actions337589
+Node: Pattern Overview338643
+Node: Regexp Patterns340309
+Node: Expression Patterns340852
+Node: Ranges344426
+Node: BEGIN/END347392
+Node: Using BEGIN/END348154
+Ref: Using BEGIN/END-Footnote-1350885
+Node: I/O And BEGIN/END350991
+Node: BEGINFILE/ENDFILE353273
+Node: Empty356104
+Node: Using Shell Variables356420
+Node: Action Overview358705
+Node: Statements361062
+Node: If Statement362916
+Node: While Statement364415
+Node: Do Statement366459
+Node: For Statement367615
+Node: Switch Statement370767
+Node: Break Statement372864
+Node: Continue Statement374854
+Node: Next Statement376641
+Node: Nextfile Statement379031
+Node: Exit Statement381507
+Node: Built-in Variables383923
+Node: User-modified385018
+Ref: User-modified-Footnote-1393044
+Node: Auto-set393106
+Ref: Auto-set-Footnote-1403848
+Node: ARGC and ARGV404053
+Node: Arrays407904
+Node: Array Basics409475
+Node: Array Intro410186
+Node: Reference to Elements414504
+Node: Assigning Elements416774
+Node: Array Example417265
+Node: Scanning an Array418997
+Node: Controlling Scanning421373
+Node: Delete424711
+Ref: Delete-Footnote-1427146
+Node: Numeric Array Subscripts427203
+Node: Uninitialized Subscripts429386
+Node: Multi-dimensional431014
+Node: Multi-scanning434105
+Node: Array Sorting435689
+Ref: Array Sorting-Footnote-1438783
+Node: Arrays of Arrays438977
+Node: Functions443550
+Node: Built-in444372
+Node: Calling Built-in445450
+Node: Numeric Functions447438
+Ref: Numeric Functions-Footnote-1451203
+Ref: Numeric Functions-Footnote-2451560
+Ref: Numeric Functions-Footnote-3451608
+Node: String Functions451877
+Ref: String Functions-Footnote-1474379
+Ref: String Functions-Footnote-2474508
+Ref: String Functions-Footnote-3474756
+Node: Gory Details474843
+Ref: table-sub-escapes476522
+Ref: table-posix-sub477836
+Ref: table-gensub-escapes478749
+Node: I/O Functions479920
+Ref: I/O Functions-Footnote-1486575
+Node: Time Functions486722
+Ref: Time Functions-Footnote-1497614
+Ref: Time Functions-Footnote-2497682
+Ref: Time Functions-Footnote-3497840
+Ref: Time Functions-Footnote-4497951
+Ref: Time Functions-Footnote-5498063
+Ref: Time Functions-Footnote-6498290
+Node: Bitwise Functions498556
+Ref: table-bitwise-ops499114
+Ref: Bitwise Functions-Footnote-1503274
+Node: Type Functions503458
+Node: I18N Functions503928
+Node: User-defined505555
+Node: Definition Syntax506359
+Ref: Definition Syntax-Footnote-1511269
+Node: Function Example511338
+Node: Function Caveats513932
+Node: Calling A Function514353
+Node: Variable Scope515468
+Node: Pass By Value/Reference517443
+Node: Return Statement520883
+Node: Dynamic Typing523864
+Node: Indirect Calls524599
+Node: Internationalization534284
+Node: I18N and L10N535710
+Node: Explaining gettext536396
+Ref: Explaining gettext-Footnote-1541462
+Ref: Explaining gettext-Footnote-2541646
+Node: Programmer i18n541811
+Node: Translator i18n546011
+Node: String Extraction546804
+Ref: String Extraction-Footnote-1547765
+Node: Printf Ordering547851
+Ref: Printf Ordering-Footnote-1550635
+Node: I18N Portability550699
+Ref: I18N Portability-Footnote-1553148
+Node: I18N Example553211
+Ref: I18N Example-Footnote-1555846
+Node: Gawk I18N555918
+Node: Advanced Features556535
+Node: Nondecimal Data557854
+Node: Two-way I/O559435
+Ref: Two-way I/O-Footnote-1564869
+Node: TCP/IP Networking564939
+Node: Profiling567783
+Node: Library Functions575257
+Ref: Library Functions-Footnote-1578362
+Node: Library Names578533
+Ref: Library Names-Footnote-1582004
+Ref: Library Names-Footnote-2582224
+Node: General Functions582310
+Node: Nextfile Function583373
+Node: Strtonum Function587754
+Node: Assert Function590710
+Node: Round Function594036
+Node: Cliff Random Function595579
+Node: Ordinal Functions596595
+Ref: Ordinal Functions-Footnote-1599665
+Ref: Ordinal Functions-Footnote-2599917
+Node: Join Function600126
+Ref: Join Function-Footnote-1601897
+Node: Gettimeofday Function602097
+Node: Data File Management605812
+Node: Filetrans Function606444
+Node: Rewind Function610680
+Node: File Checking612133
+Node: Empty Files613227
+Node: Ignoring Assigns615457
+Node: Getopt Function617010
+Ref: Getopt Function-Footnote-1628314
+Node: Passwd Functions628517
+Ref: Passwd Functions-Footnote-1637492
+Node: Group Functions637580
+Node: Walking Arrays645664
+Node: Sample Programs647233
+Node: Running Examples647898
+Node: Clones648626
+Node: Cut Program649850
+Node: Egrep Program659695
+Ref: Egrep Program-Footnote-1667468
+Node: Id Program667578
+Node: Split Program671194
+Ref: Split Program-Footnote-1674713
+Node: Tee Program674841
+Node: Uniq Program677644
+Node: Wc Program685073
+Ref: Wc Program-Footnote-1689339
+Ref: Wc Program-Footnote-2689539
+Node: Miscellaneous Programs689631
+Node: Dupword Program690819
+Node: Alarm Program692850
+Node: Translate Program697599
+Ref: Translate Program-Footnote-1701986
+Ref: Translate Program-Footnote-2702214
+Node: Labels Program702348
+Ref: Labels Program-Footnote-1705719
+Node: Word Sorting705803
+Node: History Sorting709687
+Node: Extract Program711526
+Ref: Extract Program-Footnote-1719009
+Node: Simple Sed719137
+Node: Igawk Program722199
+Ref: Igawk Program-Footnote-1737232
+Ref: Igawk Program-Footnote-2737433
+Node: Anagram Program737571
+Node: Signature Program740639
+Node: Debugger741739
+Node: Debugging742650
+Node: Debugging Concepts743063
+Node: Debugging Terms744919
+Node: Awk Debugging747541
+Node: Sample dgawk session748433
+Node: dgawk invocation748925
+Node: Finding The Bug750107
+Node: List of Debugger Commands756593
+Node: Breakpoint Control757904
+Node: Dgawk Execution Control761540
+Node: Viewing And Changing Data764891
+Node: Dgawk Stack768228
+Node: Dgawk Info769688
+Node: Miscellaneous Dgawk Commands773636
+Node: Readline Support779064
+Node: Dgawk Limitations779902
+Node: Language History782091
+Node: V7/SVR3.1783529
+Node: SVR4785850
+Node: POSIX787292
+Node: BTL788300
+Node: POSIX/GNU789034
+Node: Common Extensions794135
+Node: Contributors795236
+Node: Installation799375
+Node: Gawk Distribution800269
+Node: Getting800753
+Node: Extracting801579
+Node: Distribution contents803271
+Node: Unix Installation808493
+Node: Quick Installation809110
+Node: Additional Configuration Options811072
+Node: Configuration Philosophy812549
+Node: Non-Unix Installation814891
+Node: PC Installation815349
+Node: PC Binary Installation816648
+Node: PC Compiling818496
+Node: PC Testing821440
+Node: PC Using822616
+Node: Cygwin826801
+Node: MSYS827801
+Node: VMS Installation828315
+Node: VMS Compilation828918
+Ref: VMS Compilation-Footnote-1829925
+Node: VMS Installation Details829983
+Node: VMS Running831618
+Node: VMS Old Gawk833225
+Node: Bugs833699
+Node: Other Versions837609
+Node: Notes842888
+Node: Compatibility Mode843580
+Node: Additions844363
+Node: Accessing The Source845175
+Node: Adding Code846600
+Node: New Ports852567
+Node: Dynamic Extensions856680
+Node: Internals858056
+Node: Plugin License867159
+Node: Sample Library867793
+Node: Internal File Description868479
+Node: Internal File Ops872194
+Ref: Internal File Ops-Footnote-1876975
+Node: Using Internal File Ops877115
+Node: Future Extensions879492
+Node: Basic Concepts881996
+Node: Basic High Level882753
+Ref: Basic High Level-Footnote-1886788
+Node: Basic Data Typing886973
+Node: Floating Point Issues891498
+Node: String Conversion Precision892581
+Ref: String Conversion Precision-Footnote-1894275
+Node: Unexpected Results894384
+Node: POSIX Floating Point Problems896210
+Ref: POSIX Floating Point Problems-Footnote-1899912
+Node: Glossary899950
+Node: Copying924093
+Node: GNU Free Documentation License961650
+Node: Index986787
End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 1b34628..17df090 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -501,6 +501,8 @@ particular records in a file and perform operations upon
them.
* Scanning an Array:: A variation of the @code{for} statement. It
loops through the indices of an array's
existing elements.
+* Controlling Scanning:: Controlling the order in which arrays
+ are scanned.
* Delete:: The @code{delete} statement removes an
element from an array.
* Numeric Array Subscripts:: How to use numbers as subscripts in
@@ -12759,10 +12761,10 @@ order in which array indices will be processed by
@samp{for (index in array) @dots{}} loops.
The value should contain one to three words; separate pairs of words
by a single space.
-One word controls sort direction, ``ascending'' or ``descending;''
-another controls the sort key, ``index'' or ``value;'' and the remaining
+One word controls sort direction, @samp{ascending} or @samp{descending};
+another controls the sort key, @samp{index} or @samp{value}; and the remaining
one, which is only valid for sorting by index, is comparison mode,
-``string'' or ``number.'' When two or three words are present, they may
address@hidden or @samp{number}. When two or three words are present, they may
be specified in any order, so @samp{ascending index string} and
@samp{string ascending index} are equivalent. Also, each word may
be truncated, so @samp{asc index str} and @samp{a i s} are also
@@ -12770,13 +12772,13 @@ equivalent. Note that a separating space is required
even when the
words have been shortened down to one letter each.
You can omit direction and/or key type and/or comparison mode. Provided
-that at least one is present, missing parts of a sort specification
+that at least one is present, the missing parts of a sort specification
default to @samp{ascending}, @samp{index}, and (for indices only)
@samp{string},
respectively.
An empty string, @code{""}, is the same as @samp{unsorted} and will cause
@samp{for (index in array) @dots{}} to process the indices in
arbitrary order. Another thing to note is that the array sorting
-takes place at the time @samp{for (@dots{} in @dots{})} is about to
+takes place at the time the @code{for} loop is about to
start executing, so changing the value of @code{PROCINFO["sorted_in"]}
during loop execution does not have any effect on the order in which any
remaining array elements get processed.
@@ -13385,6 +13387,10 @@ END @{
@cindex elements in arrays, scanning
@cindex arrays, scanning
address@hidden
+* Controlling Scanning:: Controlling the order in which arrays are scanned.
address@hidden menu
+
In programs that use arrays, it is often necessary to use a loop that
executes once for each element of an array. In other languages, where
arrays are contiguous and indices are limited to positive integers,
@@ -13449,42 +13455,49 @@ the loop body; it is not predictable whether the
@code{for} loop will
reach them. Similarly, changing @var{var} inside the loop may produce
strange results. It is best to avoid such things.
address@hidden Controlling Scanning
address@hidden Controlling Array Scanning Order
+
As an extension, @command{gawk} makes it possible for you to
loop over the elements of an array in order, based on the value of
@code{PROCINFO["sorted_in"]} (@pxref{Auto-set}).
Several sorting options are available:
address@hidden @code
address@hidden "ascending index string"
-Order by indices compared as strings, the most basic sort.
-(Internally, array indices are always strings, so with @code{a[2*5] = 1}
address@hidden @samp
address@hidden ascending index string
+Order by indices compared as strings; this is the most basic sort.
+(Internally, array indices are always strings, so with @samp{a[2*5] = 1}
the index is actually @code{"10"} rather than numeric 10.)
address@hidden "ascending index number"
address@hidden ascending index number
Order by indices but force them to be treated as numbers in the process.
-Any index with non-numeric value will end up positioned as if it were 0.
+Any index with non-numeric value will end up positioned as if it were zero.
address@hidden "ascending value"
address@hidden ascending value
Order by element values rather than by indices. Comparisons are done
as numeric when both values being compared are numeric, or done as
-strings when either or both aren't numeric. Sub-arrays, if present,
-come out last.
+strings when either or both aren't numeric (@pxref{Variable Typing}).
+Subarrays, if present, come out last.
address@hidden "descending index string"
address@hidden descending index string
Reverse order from the most basic sort.
address@hidden "descending index number"
address@hidden descending index number
Numeric indices ordered from high to low.
address@hidden "descending value"
-Element values ordered from high to low. Sub-arrays, if present,
address@hidden descending value
+Element values ordered from high to low. Subarrays, if present,
come out first.
address@hidden "unsorted"
address@hidden unsorted
Array elements are processed in arbitrary order, the normal @command{awk}
behavior.
@end table
+The array traversal order is determined before the @code{for} loop
+starts to run. Changing @code{PROCINFO["sorted_in"]} in the looop body
+will not affect the loop.
+
Portions of the sort specification string may be truncated or omitted.
The default is @samp{ascending} for direction, @samp{index} for sort key type,
and (when sorting by index only) @samp{string} for comparison mode.
@@ -13510,34 +13523,35 @@ $ @kbd{gawk 'BEGIN @{}
@print{} 4 4
@end example
-As a side note, sorting the array indices before traversing
-the array has been reported to add 15% to 20% overhead to the
-execution time of @command{awk} programs. For this reason,
-sorted array traversal is not the default.
address@hidden The @command{gawk}
address@hidden maintainers believe that only the people who wish to use a
address@hidden feature should have to pay for it.
-
When sorting an array by element values, if a value happens to be
-a sub-array then it is considered to be greater than any string or
-numeric value, regardless of what the sub-array itself contains,
-and all sub-arrays are treated as being equal to each other. Their
+a subarray then it is considered to be greater than any string or
+numeric value, regardless of what the subarray itself contains,
+and all subarrays are treated as being equal to each other. Their
order relative to each other is determined by their index strings.
-Sorting by array element values (for values other than sub-arrays)
+Sorting by array element values (for values other than subarrays)
always uses basic @command{awk} comparison mode: if both values
happen to be numbers then they're compared as numbers, otherwise
they're compared as strings.
When string comparisons are made during a sort, either for element
values where one or both aren't numbers or for element indices
-handled as strings, the value of @code{IGNORECASE} controls whether
+handled as strings, the value of @code{IGNORECASE}
+(@pxref{Built-in Variables}) controls whether
the comparisons treat corresponding upper and lower case letters as
equivalent or distinct.
This sorting extension is disabled in POSIX mode,
since the @code{PROCINFO} array is not special in that case.
+As a side note, sorting the array indices before traversing
+the array has been reported to add 15% to 20% overhead to the
+execution time of @command{awk} programs. For this reason,
+sorted array traversal is not the default.
address@hidden The @command{gawk}
address@hidden maintainers believe that only the people who wish to use a
address@hidden feature should have to pay for it.
+
@node Delete
@section The @code{delete} Statement
@cindex @code{delete} statement
@@ -26983,7 +26997,7 @@ will be less busy, and you can usually find one closer
to your site.
@node Extracting
@appendixsubsec Extracting the Distribution
address@hidden is distributed as several @code{tar} file compressed with
address@hidden is distributed as several @code{tar} files compressed with
different compression programs: @command{gzip}, @command{bzip2},
and @command{xz}. For simplicity, the rest of these instructions assume
you are using the one compressed with the GNU Zip program, @code{gzip}.
@@ -27054,9 +27068,15 @@ A file providing an overview of the configuration and
installation process.
@item ChangeLog
A detailed list of source code changes as bugs are fixed or improvements made.
address@hidden ChangeLog.0
+An older list of source code changes.
+
@item NEWS
A list of changes to @command{gawk} since the last release or patch.
address@hidden NEWS.0
+An older list of changes to @command{gawk}.
+
@item COPYING
The GNU General Public License.
@@ -27071,13 +27091,14 @@ Most of these depend on the hardware or operating
system software and
are not limits in @command{gawk} itself.
@item POSIX.STD
-A description of one area in which the POSIX standard for @command{awk} is
-incorrect as well as how @command{gawk} handles the problem.
+A description of behaviors in the POSIX standard for @command{awk} which
+are left undefined, or where @command{gawk} may not comply fully, as well
+as a list of things that the POSIX standard should describe but does not.
@cindex artificial address@hidden @command{gawk} and
@item doc/awkforai.txt
A short article describing why @command{gawk} is a good language for
-AI (Artificial Intelligence) programming.
+Artificial Intelligence (AI) programming.
@item doc/bc_notes
A brief description of @command{gawk}'s ``byte code'' internals.
@@ -27275,8 +27296,7 @@ run @samp{make check}. All of the tests should succeed.
If these steps do not work, or if any of the tests fail,
check the files in the @file{README_d} directory to see if you've
found a known problem. If the failure is not described there,
-please send in a bug report
-(@pxref{Bugs}.)
+please send in a bug report (@pxref{Bugs}).
@node Additional Configuration Options
@appendixsubsec Additional Configuration Options
@@ -27288,12 +27308,6 @@ command line when compiling @command{gawk} from
scratch, including:
@table @code
address@hidden @code{--with-whiny-user-strftime} configuration option
address@hidden configuration option, @code{--with-whiny-user-strftime}
address@hidden --with-whiny-user-strftime
-Force use of the included version of the @code{strftime()}
-function for deficient systems.
-
@cindex @code{--disable-lint} configuration option
@cindex configuration option, @code{--disable-lint}
@item --disable-lint
@@ -27320,6 +27334,12 @@ to fail. This option may be removed at a later date.
Disable all message-translation facilities.
This is usually not desirable, but it may bring you some slight performance
improvement.
+
address@hidden @code{--with-whiny-user-strftime} configuration option
address@hidden configuration option, @code{--with-whiny-user-strftime}
address@hidden --with-whiny-user-strftime
+Force use of the included version of the @code{strftime()}
+function for deficient systems.
@end table
Use the command @samp{./configure --help} to see the full list of
@@ -27725,7 +27745,7 @@ moved into the @code{BEGIN} rule.
if you are using the @uref{http://www.cygwin.com, Cygwin environment}.
This environment provides an excellent simulation of Unix, using the
GNU tools, such as Bash, the GNU Compiler Collection (GCC), GNU Make,
-and other GNU tools. Compilation and installation for Cygwin is the
+and other GNU programs. Compilation and installation for Cygwin is the
same as for a Unix system:
@example
@@ -27766,7 +27786,6 @@ translation of @code{"\r\n"}, since it won't. Caveat
Emptor!
@cindex @command{gawk}, VMS version of
@cindex installation, VMS
This @value{SUBSECTION} describes how to compile and install @command{gawk}
under VMS.
-
The older designation ``VMS'' is used throughout to refer to OpenVMS.
@menu
@@ -28032,10 +28051,10 @@ authoritative if it conflicts with this
@value{DOCUMENT}.
The people maintaining the non-Unix ports of @command{gawk} are
as follows:
address@hidden {MS-Windows using MINGW}
{123456789012345678901234567890123456789001234567890}
address@hidden {MS-Windows with MINGW and DJGPP}
{123456789012345678901234567890123456789001234567890}
@cindex Zaretskii, Eli
@cindex Deifik, Scott
address@hidden MS-Windows using MINGW @tab Eli Zaretskii,
@EMAIL{eliz@@gnu.org,eliz at gnu dot org}.
address@hidden MS-Windows with MINGW and DJGPP @tab Eli Zaretskii,
@EMAIL{eliz@@gnu.org,eliz at gnu dot org}.
@item @tab Scott Deifik, @EMAIL{scottd.mail@@sbcglobal.net,scottd dot mail at
sbcglobal dot net}.
@cindex Buening, Andreas
@@ -28209,7 +28228,7 @@ This is an embeddable @command{awk} interpreter derived
from
@command{mawk}. For more information see
@uref{http://repo.hu/projects/libmawk/}.
address@hidden QSE Awk
address@hidden @w{QSE Awk}
@cindex QSE Awk
@cindex source code, QSE Awk
This is an embeddable @command{awk} interpreter. For more information
@@ -28307,7 +28326,7 @@ as well as any considerations you should bear in mind.
@node Accessing The Source
@appendixsubsec Accessing The @command{gawk} Git Repository
-As @command{gawk} is Free Software, the source code is always available
+As @command{gawk} is Free Software, the source code is always available.
@ref{Gawk Distribution}, describes how to get and build the formal,
released versions of @command{gawk}.
@@ -28366,6 +28385,16 @@ consider writing it as an extension module
If that's not possible, continue with the rest of the steps in this list.
@item
+Be prepared to sign the appropriate paperwork.
+In order for the FSF to distribute your changes, you must either place
+those changes in the public domain and submit a signed statement to that
+effect, or assign the copyright in your changes to the FSF.
+Both of these actions are easy to do and @emph{many} people have done so
+already. If you have questions, please contact me
+(@pxref{Bugs}),
+or @EMAIL{assign@@gnu.org,assign at gnu dot org}.
+
address@hidden
Get the latest version.
It is much easier for me to integrate changes if they are relative to
the most recent distributed version of @command{gawk}. If your version of
@@ -28404,7 +28433,7 @@ Use ANSI/ISO style (prototype) function headers when
defining functions.
Put the name of the function at the beginning of its own line.
@item
-Put the return type of the function, even if it is @code{int()}, on the
+Put the return type of the function, even if it is @code{int}, on the
line above the line with the name and arguments of the function.
@item
@@ -28447,6 +28476,17 @@ Do not use the @code{alloca()} function for allocating
memory off the
stack. Its use causes more portability trouble than is worth the minor
benefit of not having to free the storage. Instead, use @code{malloc()}
and @code{free()}.
+
address@hidden
+Do not use comparisons of the form @samp{! strcmp(a, b)} or similar.
+As Henry Spencer once said, address@hidden()} is not a boolean!''
+Instead, use @samp{strcmp(a, b) == 0}.
+
address@hidden
+If adding new bit flag values, use explicit hexadecimal constants
+(@code{0x001}, @code{0x002}, @code{0x004}, and son on) instead of
+shifting one left by successive amounts (@samp{(1<<0)}, @samp{(1<<1)},
+and so on).
@end itemize
@quotation NOTE
@@ -28454,16 +28494,6 @@ If I have to reformat your code to follow the coding
style used in
@command{gawk}, I may not bother to integrate your changes at all.
@end quotation
address@hidden
-Be prepared to sign the appropriate paperwork.
-In order for the FSF to distribute your changes, you must either place
-those changes in the public domain and submit a signed statement to that
-effect, or assign the copyright in your changes to the FSF.
-Both of these actions are easy to do and @emph{many} people have done so
-already. If you have questions, please contact me
-(@pxref{Bugs}),
-or @EMAIL{assign@@gnu.org,assign at gnu dot org}.
-
@cindex Texinfo
@item
Update the documentation.
@@ -28527,6 +28557,17 @@ the previous @value{SECTION}
concerning coding style, submission of diffs, and so on.
@item
+Be prepared to sign the appropriate paperwork.
+In order for the FSF to distribute your code, you must either place
+your code in the public domain and submit a signed statement to that
+effect, or assign the copyright in your code to the FSF.
address@hidden
+Both of these actions are easy to do and @emph{many} people have done so
+already. If you have questions, please contact me, or
address@hidden@@gnu.org}.
address@hidden ifinfo
+
address@hidden
When doing a port, bear in mind that your code must coexist peacefully
with the rest of @command{gawk} and the other ports. Avoid gratuitous
changes to the system-independent parts of the code. If at all possible,
@@ -28588,17 +28629,6 @@ Update the documentation.
Please write a section (or sections) for this @value{DOCUMENT} describing the
installation and compilation steps needed to compile and/or install
@command{gawk} for your system.
-
address@hidden
-Be prepared to sign the appropriate paperwork.
-In order for the FSF to distribute your code, you must either place
-your code in the public domain and submit a signed statement to that
-effect, or assign the copyright in your code to the FSF.
address@hidden
-Both of these actions are easy to do and @emph{many} people have done so
-already. If you have questions, please contact me, or
address@hidden@@gnu.org}.
address@hidden ifinfo
@end enumerate
Following these steps makes it much easier to integrate your changes
@@ -28782,7 +28812,7 @@ Make sure that @samp{n->type == Node_var_array} first.
@item NODE **assoc_lookup(NODE *symbol, NODE *subs, int reference)
Finds, and installs if necessary, array elements.
@code{symbol} is the array, @code{subs} is the subscript.
-This is usually a value created with @code{make_string} (see below).
+This is usually a value created with @code{make_string()} (see below).
@code{reference} should be @code{TRUE} if it is an error to use the
value before it is created. Typically, @code{FALSE} is the
correct value to use from extension functions.
@@ -28817,7 +28847,7 @@ understanding of @command{gawk} memory management is
helpful.
@cindex internal function, @code{unref()}
@item void unref(NODE *n)
This macro releases the memory associated with a @code{NODE}
-allocated with @code{make_string} or @code{make_number}.
+allocated with @code{make_string()} or @code{make_number()}.
Understanding of @command{gawk} memory management is helpful.
@cindex @code{make_builtin()} internal function
@@ -28874,7 +28904,7 @@ This is a convenience macro that calls
@code{get_actual_argument()}.
@item void update_ERRNO(void)
This function is called from within a C extension function to set
the value of @command{gawk}'s @code{ERRNO} variable, based on the current
-value of the C @code{errno} variable.
+value of the C @code{errno} global variable.
It is provided as a convenience.
@cindex @code{ERRNO} variable
@@ -28882,8 +28912,8 @@ It is provided as a convenience.
@cindex internal function, @code{update_ERRNO_saved()}
@item void update_ERRNO_saved(int errno_saved)
This function is called from within a C extension function to set
-the value of @command{gawk}'s @code{ERRNO} variable, based on the saved
-value of the C @code{errno} variable provided as the argument.
+the value of @command{gawk}'s @code{ERRNO} variable, based on the error
+value provided as the argument.
It is provided as a convenience.
@cindex @code{ENVIRON} array
@@ -28924,13 +28954,13 @@ to the @code{IOBUF}'s @code{opaque} field (which will
presumably point
to a structure containing additional state associated with the input
processing), and no further open hooks are called.
-The function called will most likely want to set the @code{IOBUF}
address@hidden()} method to indicate that future input records should
+The function called will most likely want to set the @code{IOBUF}'s
address@hidden method to indicate that future input records should
be retrieved by calling that method instead of using the standard
@command{gawk} input processing.
-And the function will also probably want to set the @code{IOBUF}
address@hidden()} method to be called when the file is closed to clean
+And the function will also probably want to set the @code{IOBUF}'s
address@hidden method to be called when the file is closed to clean
up any state associated with the input.
Finally, hook functions should be prepared to receive an @code{IOBUF}
@@ -28950,11 +28980,12 @@ from a function parameter.
The following boilerplate code shows how to do this:
address@hidden
address@hidden
NODE *the_arg;
-the_arg = get_array_argument(2, FALSE); /* assume need 3rd arg, 0-based */
address@hidden smallexample
+/* assume need 3rd arg, 0-based */
+the_arg = get_array_argument(2, FALSE);
address@hidden example
Again, you should spend time studying the @command{gawk} internals;
don't just blindly copy this code.
@@ -29001,7 +29032,7 @@ external extension library.
@end menu
@node Internal File Description
address@hidden Using @code{chdir} and @code{stat}
address@hidden Using @code{chdir()} and @code{stat()}
This @value{SECTION} shows how to use the new functions at the @command{awk}
level once they've been integrated into the running @command{gawk}
@@ -29148,8 +29179,9 @@ of that number, respectively.
Here is the C code for these extensions. They were written for
GNU/Linux. The code needs some more work for complete portability
to other POSIX-compliant systems:@footnote{This version is edited
-slightly for presentation. The complete version can be found in
address@hidden/filefuncs.c} in the @command{gawk} distribution.}
+slightly for presentation. See
address@hidden/filefuncs.c} in the @command{gawk} distribution
+for the complete version.}
@c break line for page breaking
@example
@@ -29175,7 +29207,7 @@ do_chdir(int nargs)
The file includes the @code{"awk.h"} header file for definitions
for the @command{gawk} internals. It includes @code{<sys/sysmacros.h>}
-for access to the @code{major} and @code{minor} macros.
+for access to the @code{major()} and @code{minor}() macros.
@cindex programming conventions, @command{gawk} internals
By convention, for an @command{awk} function @code{foo}, the function that
@@ -29183,12 +29215,12 @@ implements it is called @samp{do_foo}. The function
should take
a @samp{int} argument, usually called @code{nargs}, that
represents the number of defined arguments for the function. The @code{newdir}
variable represents the new directory to change to, retrieved
-with @code{get_scalar_argument}. Note that the first argument is
+with @code{get_scalar_argument()}. Note that the first argument is
numbered zero.
-This code actually accomplishes the @code{chdir}. It first forces
+This code actually accomplishes the @code{chdir()}. It first forces
the argument to be a string and passes the string value to the
address@hidden system call. If the @code{chdir} fails, @code{ERRNO}
address@hidden()} system call. If the @code{chdir()} fails, @code{ERRNO}
is updated.
@example
@@ -29205,7 +29237,7 @@ Finally, the function returns the return value to the
@command{awk} level:
@}
@end example
-The @code{stat} built-in is more involved. First comes a function
+The @code{stat()} built-in 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:
@@ -29220,7 +29252,7 @@ format_mode(unsigned long fmode)
@}
@end example
-Next comes the @code{do_stat} function. It starts with
+Next comes the @code{do_stat()} function. It starts with
variable declarations and argument checking:
@ignore
@@ -29253,7 +29285,7 @@ If there's an error, it sets @code{ERRNO} and returns:
@c comment made multiline for page breaking
@example
- /* directory is first arg, array to hold results is second */
+ /* file is first arg, array to hold results is second */
file = get_scalar_argument(0, FALSE);
array = get_array_argument(1, FALSE);
@@ -29299,7 +29331,7 @@ When done, return the @code{lstat()} return value:
@cindex programming conventions, @command{gawk} internals
Finally, it's necessary to provide the ``glue'' that loads the
new function(s) into @command{gawk}. By convention, each library has
-a routine named @code{dlload} that does the job:
+a routine named @code{dlload()} that does the job:
@example
/* dlload --- load new builtins in this library */
diff --git a/extension/ChangeLog b/extension/ChangeLog
index 926bf0b..3e1de05 100644
--- a/extension/ChangeLog
+++ b/extension/ChangeLog
@@ -1,4 +1,8 @@
-Thu Jan 13 20:37:02 2011 Andrew J. Schorr <address@hidden>
+Thu Mar 31 22:58:19 2011 Arnold D. Robbins <address@hidden>
+
+ * filefuncs.c (do_stat): Fix a comment. Also in doc.
+
+Thu Jan 13 20:37:02 2011 Andrew J. Schorr <address@hidden>
* filefuncs.c (do_stat): Malloc the buffer to read the contents
of the link. From mail of June 21, 2005.
diff --git a/extension/filefuncs.c b/extension/filefuncs.c
index 7efa912..ad7828f 100644
--- a/extension/filefuncs.c
+++ b/extension/filefuncs.c
@@ -172,7 +172,7 @@ do_stat(int nargs)
if (do_lint && get_curfunc_arg_count() > 2)
lintwarn("stat: called with too many arguments");
- /* directory is first arg, array to hold results is second */
+ /* file is first arg, array to hold results is second */
file = get_scalar_argument(0, FALSE);
array = get_array_argument(1, FALSE);
-----------------------------------------------------------------------
Summary of changes:
ChangeLog | 5 +
Checklist | 3 +
POSIX.STD | 6 +-
doc/gawk.info | 1140 +++++++++++++++++++++++++------------------------
doc/gawk.texi | 222 ++++++----
extension/ChangeLog | 6 +-
extension/filefuncs.c | 2 +-
7 files changed, 732 insertions(+), 652 deletions(-)
hooks/post-receive
--
gawk
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [gawk-diffs] [SCM] gawk branch, master, updated. b1746329b7749a8f760bab04c12e5127a23e46ed,
Arnold Robbins <=