aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorArnold D. Robbins <arnold@skeeve.com>2014-05-05 17:46:19 +0300
committerArnold D. Robbins <arnold@skeeve.com>2014-05-05 17:46:19 +0300
commit628837bf58f885225532b6c2de41b60ffa7c14e9 (patch)
treef05a2ad526edae084835e9a7a88712eae3e9b33c
parentc1d7f8b0dfa6264148c3369e46fbe68dd6add2dc (diff)
downloadegawk-628837bf58f885225532b6c2de41b60ffa7c14e9.tar.gz
egawk-628837bf58f885225532b6c2de41b60ffa7c14e9.tar.bz2
egawk-628837bf58f885225532b6c2de41b60ffa7c14e9.zip
Doc edits, through Chapter 9.
Diffstat
-rw-r--r--awklib/eg/lib/ctime.awk2
-rw-r--r--doc/ChangeLog4
-rw-r--r--doc/gawk.info985
-rw-r--r--doc/gawk.texi180
-rw-r--r--doc/gawktexi.in180
5 files changed, 697 insertions, 654 deletions
diff --git a/awklib/eg/lib/ctime.awk b/awklib/eg/lib/ctime.awk
index f37856c6..ca750370 100644
--- a/awklib/eg/lib/ctime.awk
+++ b/awklib/eg/lib/ctime.awk
@@ -4,7 +4,7 @@
function ctime(ts, format)
{
- format = "%a %b %e %H:%M:%S %Z %Y"
+ format = PROCINFO["strftime"]
if (ts == 0)
ts = systime() # use current time as default
return strftime(format, ts)
diff --git a/doc/ChangeLog b/doc/ChangeLog
index 238aefe8..194cf695 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,7 @@
+2014-05-05 Arnold D. Robbins <arnold@skeeve.com>
+
+ * gawktexi.in: Editing progress. Through Chapter 9.
+
2014-05-05 Michal Jaegermann <michal@harddata.com>
* array-elements.fig: Fix subscripts to be aligned
diff --git a/doc/gawk.info b/doc/gawk.info
index dfe1589e..706dace1 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -8406,7 +8406,9 @@ File: gawk.info, Node: Locales, Prev: Precedence, Up: Expressions
====================================
Modern systems support the notion of "locales": a way to tell the
-system about the local character set and language.
+system about the local character set and language. The ISO C standard
+defines a default `"C"' locale, which is an environment that is typical
+of what many C programmers are used to.
Once upon a time, the locale setting used to affect regexp matching
(*note Ranges and Locales::), but this is no longer true.
@@ -8418,6 +8420,13 @@ much better performance when reading records. Otherwise, `gawk' has to
make several function calls, _per input character_, to find the record
terminator.
+ Locales can affect how dates and times are formatted (*note Time
+Functions::). For example, a common way to abbreviate the date
+September 4, 2015 in the United States is "9/4/15." In many countries
+in Europe, however, it is abbreviated "4.9.15." Thus, the `%x'
+specification in a `"US"' locale might produce `9/4/15', while in a
+`"EUROPE"' locale, it might produce `4.9.15'.
+
According to POSIX, string comparison is also affected by locales
(similar to regular expressions). The details are presented in *note
POSIX String Comparison::.
@@ -11330,12 +11339,22 @@ returns the number of characters in a string, and not the number of
bytes used to represent those characters. Similarly, `index()' works
with character indices, and not byte indices.
+ CAUTION: A number of functions deal with indices into strings.
+ For these functions, the first character of a string is at
+ position (index) one. This is different from C and the languages
+ descended from it, where the first character is at position zero.
+ You need to remember this when doing index calculations,
+ particularly if you are used to C.
+
In the following list, optional parameters are enclosed in square
brackets ([ ]). Several functions perform string substitution; the
full discussion is provided in the description of the `sub()' function,
which comes towards the end since the list is presented in alphabetic
-order. Those functions that are specific to `gawk' are marked with a
-pound sign (`#'):
+order.
+
+ Those functions that are specific to `gawk' are marked with a pound
+sign (`#'). They are not available in compatibility mode (*note
+Options::):
* Menu:
@@ -11343,8 +11362,8 @@ pound sign (`#'):
`&' with `sub()', `gsub()', and
`gensub()'.
-`asort('SOURCE [`,' DEST [`,' HOW ] ]`)' #
-`asorti('SOURCE [`,' DEST [`,' HOW ] ]`)' #
+`asort('SOURCE [`,' DEST [`,' HOW ] ]`) #'
+`asorti('SOURCE [`,' DEST [`,' HOW ] ]`) #'
These two functions are similar in behavior, so they are described
together.
@@ -11391,10 +11410,7 @@ pound sign (`#'):
a[2] = "last"
a[3] = "middle"
- `asort()' and `asorti()' are `gawk' extensions; they are not
- available in compatibility mode (*note Options::).
-
-`gensub(REGEXP, REPLACEMENT, HOW' [`, TARGET']`)' #
+`gensub(REGEXP, REPLACEMENT, HOW' [`, TARGET']`) #'
Search the target string TARGET for matches of the regular
expression REGEXP. If HOW is a string beginning with `g' or `G'
(short for "global"), then replace all matches of REGEXP with
@@ -11444,9 +11460,6 @@ pound sign (`#'):
If REGEXP does not match TARGET, `gensub()''s return value is the
original unchanged value of TARGET.
- `gensub()' is a `gawk' extension; it is not available in
- compatibility mode (*note Options::).
-
`gsub(REGEXP, REPLACEMENT' [`, TARGET']`)'
Search TARGET for _all_ of the longest, leftmost, _nonoverlapping_
matching substrings it can find and replace them with REPLACEMENT.
@@ -11471,8 +11484,7 @@ pound sign (`#'):
$ awk 'BEGIN { print index("peanut", "an") }'
-| 3
- If FIND is not found, `index()' returns zero. (Remember that
- string indices in `awk' start at one.)
+ If FIND is not found, `index()' returns zero.
It is a fatal error to use a regexp constant for FIND.
@@ -11518,12 +11530,12 @@ pound sign (`#'):
`match(STRING, REGEXP' [`, ARRAY']`)'
Search STRING for the longest, leftmost substring matched by the
- regular expression, REGEXP and return the character position, or
- "index", at which that substring begins (one, if it starts at the
+ regular expression, REGEXP and return the character position
+ (index) at which that substring begins (one, if it starts at the
beginning of STRING). If no match is found, return zero.
- The REGEXP argument may be either a regexp constant (`/.../') or a
- string constant (`"..."'). In the latter case, the string is
+ The REGEXP argument may be either a regexp constant (`/'...`/') or
+ a string constant (`"'...`"'). In the latter case, the string is
treated as a regexp to be matched. *Note Computed Regexps::, for a
discussion of the difference between the two forms, and the
implications for writing your program correctly.
@@ -11603,7 +11615,7 @@ pound sign (`#'):
compatibility mode (*note Options::), using a third argument is a
fatal error.
-`patsplit(STRING, ARRAY' [`, FIELDPAT' [`, SEPS' ] ]`)' #
+`patsplit(STRING, ARRAY' [`, FIELDPAT' [`, SEPS' ] ]`) #'
Divide STRING into pieces defined by FIELDPAT and store the pieces
in ARRAY and the separator strings in the SEPS array. The first
piece is stored in `ARRAY[1]', the second piece in `ARRAY[2]', and
@@ -11622,9 +11634,6 @@ pound sign (`#'):
Before splitting the string, `patsplit()' deletes any previously
existing elements in the arrays ARRAY and SEPS.
- The `patsplit()' function is a `gawk' extension. In compatibility
- mode (*note Options::), it is not available.
-
`split(STRING, ARRAY' [`, FIELDSEP' [`, SEPS' ] ]`)'
Divide STRING into pieces separated by FIELDSEP and store the
pieces in ARRAY and the separator strings in the SEPS array. The
@@ -11690,6 +11699,9 @@ pound sign (`#'):
has one element only. The value of that element is the original
STRING.
+ In POSIX mode (*note Options::), the fourth argument is not
+ allowed.
+
`sprintf(FORMAT, EXPRESSION1, ...)'
Return (without printing) the string that `printf' would have
printed out with the same arguments (*note Printf::). For example:
@@ -11698,7 +11710,7 @@ pound sign (`#'):
assigns the string `pi = 3.14 (approx.)' to the variable `pival'.
-`strtonum(STR)' #
+`strtonum(STR) #'
Examine STR and return its numeric value. If STR begins with a
leading `0', `strtonum()' assumes that STR is an octal number. If
STR begins with a leading `0x' or `0X', `strtonum()' assumes that
@@ -11715,9 +11727,6 @@ pound sign (`#'):
Note also that `strtonum()' uses the current locale's decimal point
for recognizing numbers (*note Locales::).
- `strtonum()' is a `gawk' extension; it is not available in
- compatibility mode (*note Options::).
-
`sub(REGEXP, REPLACEMENT' [`, TARGET']`)'
Search TARGET, which is treated as a string, for the leftmost,
longest substring matched by the regular expression REGEXP.
@@ -11725,8 +11734,8 @@ pound sign (`#'):
REPLACEMENT. The modified string becomes the new value of TARGET.
Return the number of substitutions made (zero or one).
- The REGEXP argument may be either a regexp constant (`/.../') or a
- string constant (`"..."'). In the latter case, the string is
+ The REGEXP argument may be either a regexp constant (`/'...`/') or
+ a string constant (`"'...`"'). In the latter case, the string is
treated as a regexp to be matched. *Note Computed Regexps::, for a
discussion of the difference between the two forms, and the
implications for writing your program correctly.
@@ -11869,9 +11878,9 @@ backslashes and ampersands into the replacement text, you need to
remember that there are several levels of "escape processing" going on.
First, there is the "lexical" level, which is when `awk' reads your
-program and builds an internal copy of it that can be executed. Then
-there is the runtime level, which is when `awk' actually scans the
-replacement string to determine what to generate.
+program and builds an internal copy of it to execute. Then there is
+the runtime level, which is when `awk' actually scans the replacement
+string to determine what to generate.
At both levels, `awk' looks for a defined set of characters that can
come after a backslash. At the lexical level, it looks for the escape
@@ -12063,6 +12072,9 @@ parameters are enclosed in square brackets ([ ]):
not matter. *Note Two-way I/O::, which discusses this feature in
more detail and gives an example.
+ Note that the second argument to `close()' is a `gawk' extension;
+ it is not available in compatibility mode (*note Options::).
+
`fflush('[FILENAME]`)'
Flush any buffered output associated with FILENAME, which is
either a file opened for writing or a shell command for
@@ -12079,10 +12091,10 @@ parameters are enclosed in square brackets ([ ]):
function--`gawk' also buffers its output and the `fflush()'
function forces `gawk' to flush its buffers.
- `fflush()' was added to Brian Kernighan's version of `awk' in
- April of 1992. For two decades, it was not part of the POSIX
- standard. As of December, 2012, it was accepted for inclusion
- into the POSIX standard. See the Austin Group website
+ `fflush()' was added to Brian Kernighan's `awk' in April of 1992.
+ For two decades, it was not part of the POSIX standard. As of
+ December, 2012, it was accepted for inclusion into the POSIX
+ standard. See the Austin Group website
(http://austingroupbugs.net/view.php?id=634).
POSIX standardizes `fflush()' as follows: If there is no argument,
@@ -12100,7 +12112,7 @@ parameters are enclosed in square brackets ([ ]):
to flush only the standard output.
`fflush()' returns zero if the buffer is successfully flushed;
- otherwise, it returns non-zero (`gawk' returns -1). In the case
+ otherwise, it returns non-zero. (`gawk' returns -1.) In the case
where all buffers are flushed, the return value is zero only if
all buffers were flushed successfully. Otherwise, it is -1, and
`gawk' warns about the problem FILENAME.
@@ -12270,7 +12282,7 @@ enclosed in square brackets ([ ]):
If DATESPEC does not contain enough elements or if the resulting
time is out of range, `mktime()' returns -1.
-``strftime(' [FORMAT [`,' TIMESTAMP [`,' UTC-FLAG ]]]`)''
+`strftime(' [FORMAT [`,' TIMESTAMP [`,' UTC-FLAG] ] ]`)'
Format the time specified by TIMESTAMP based on the contents of
the FORMAT string and return the result. It is similar to the
function of the same name in ISO C. If UTC-FLAG is present and is
@@ -12350,11 +12362,11 @@ the following date format specifications:
`%g'
The year modulo 100 of the ISO 8601 week number, as a decimal
- number (00-99). For example, January 1, 1993 is in week 53 of
- 1992. Thus, the year of its ISO 8601 week number is 1992, even
- though its year is 1993. Similarly, December 31, 1973 is in week
- 1 of 1974. Thus, the year of its ISO week number is 1974, even
- though its year is 1973.
+ number (00-99). For example, January 1, 2012 is in week 53 of
+ 2011. Thus, the year of its ISO 8601 week number is 2011, even
+ though its year is 2012. Similarly, December 31, 2012 is in week
+ 1 of 2013. Thus, the year of its ISO week number is 2013, even
+ though its year is 2012.
`%G'
The full year of the ISO week number, as a decimal number.
@@ -12434,7 +12446,7 @@ the following date format specifications:
The year modulo 100 as a decimal number (00-99).
`%Y'
- The full year as a decimal number (e.g., 2011).
+ The full year as a decimal number (e.g., 2015).
`%z'
The timezone offset in a +HHMM format (e.g., the format necessary
@@ -12456,15 +12468,6 @@ the following date format specifications:
If a conversion specifier is not one of the above, the behavior is
undefined.(6)
- Informally, a "locale" is the geographic place in which a program is
-meant to run. For example, a common way to abbreviate the date
-September 4, 2012 in the United States is "9/4/12." In many countries
-in Europe, however, it is abbreviated "4.9.12." Thus, the `%x'
-specification in a `"US"' locale might produce `9/4/12', while in a
-`"EUROPE"' locale, it might produce `4.9.12'. The ISO C standard
-defines a default `"C"' locale, which is an environment that is typical
-of what many C programmers are used to.
-
For systems that are not yet fully standards-compliant, `gawk'
supplies a copy of `strftime()' from the GNU C Library. It supports
all of the just-listed format specifications. If that version is used
@@ -12494,7 +12497,7 @@ to the standard output and interprets the current time according to the
format specifiers in the string. For example:
$ date '+Today is %A, %B %d, %Y.'
- -| Today is Wednesday, March 30, 2011.
+ -| Today is Monday, May 05, 2014.
Here is the `gawk' version of the `date' utility. It has a shell
"wrapper" to handle the `-u' option, which requires that `date' run as
@@ -12511,7 +12514,7 @@ if the time zone is set to UTC:
esac
gawk 'BEGIN {
- format = "%a %b %e %H:%M:%S %Z %Y"
+ format = PROCINFO["strftime"]
exitval = 0
if (ARGC > 2)
@@ -12689,8 +12692,8 @@ File: gawk.info, Node: Type Functions, Next: I18N Functions, Prev: Bitwise Fu
`gawk' provides a single function that lets you distinguish an array
from a scalar variable. This is necessary for writing code that
-traverses every element of a true multidimensional array (*note Arrays
-of Arrays::).
+traverses every element of an array of arrays. (*note Arrays of
+Arrays::).
`isarray(X)'
Return a true value if X is an array. Otherwise return false.
@@ -12720,7 +12723,7 @@ descriptions here are purposely brief. *Note Internationalization::,
for the full story. Optional parameters are enclosed in square
brackets ([ ]):
-``bindtextdomain(DIRECTORY' [`,' DOMAIN ]`)''
+`bindtextdomain(DIRECTORY' [`,' DOMAIN]`)'
Set the directory in which `gawk' will look for message
translation files, in case they will not or cannot be placed in
the "standard" locations (e.g., during testing). It returns the
@@ -12730,13 +12733,13 @@ brackets ([ ]):
the null string (`""'), then `bindtextdomain()' returns the
current binding for the given DOMAIN.
-``dcgettext(STRING' [`,' DOMAIN [`,' CATEGORY ]]`)''
+`dcgettext(STRING' [`,' DOMAIN [`,' CATEGORY] ]`)'
Return the translation of STRING in text domain DOMAIN for locale
category CATEGORY. The default value for DOMAIN is the current
value of `TEXTDOMAIN'. The default value for CATEGORY is
`"LC_MESSAGES"'.
-``dcngettext(STRING1, STRING2, NUMBER' [`,' DOMAIN [`,' CATEGORY ]]`)''
+`dcngettext(STRING1, STRING2, NUMBER' [`,' DOMAIN [`,' CATEGORY] ]`)'
Return the plural form used for NUMBER of the translation of
STRING1 and STRING2 in text domain DOMAIN for locale category
CATEGORY. STRING1 is the English singular variant of a message,
@@ -12799,7 +12802,7 @@ a parameter with the same name as the function itself.
In addition, according to the POSIX standard, function parameters
cannot have the same name as one of the special built-in variables
-(*note Built-in Variables::. Not all versions of `awk' enforce this
+(*note Built-in Variables::). Not all versions of `awk' enforce this
restriction.)
The BODY-OF-FUNCTION consists of `awk' statements. It is the most
@@ -12949,7 +12952,7 @@ an `awk' version of `ctime()':
function ctime(ts, format)
{
- format = "%a %b %e %H:%M:%S %Z %Y"
+ format = PROCINFO["strftime"]
if (ts == 0)
ts = systime() # use current time as default
return strftime(format, ts)
@@ -13003,9 +13006,10 @@ File: gawk.info, Node: Variable Scope, Next: Pass By Value/Reference, Prev: C
9.2.3.2 Controlling Variable Scope
..................................
-There is no way to make a variable local to a `{ ... }' block in `awk',
-but you can make a variable local to a function. It is good practice to
-do so whenever a variable is needed only in that function.
+Unlike many languages, there is no way to make a variable local to a
+`{' ... `}' block in `awk', but you can make a variable local to a
+function. It is good practice to do so whenever a variable is needed
+only in that function.
To make a variable local to a function, simply declare the variable
as an argument after the actual function arguments (*note Definition
@@ -13228,7 +13232,7 @@ like this:
The EXPRESSION part is optional. Due most likely to an oversight,
POSIX does not define what the return value is if you omit the
-EXPRESSION. Technically speaking, this make the returned value
+EXPRESSION. Technically speaking, this makes the returned value
undefined, and therefore, unpredictable. In practice, though, all
versions of `awk' simply return the null string, which acts like zero
if used in a numeric context.
@@ -13322,8 +13326,8 @@ Here is an annotated sample program:
}
In this example, the first call to `foo()' generates a fatal error,
-so `gawk' will not report the second error. If you comment out that
-call, though, then `gawk' will report the second error.
+so `awk' will not report the second error. If you comment out that
+call, though, then `awk' does report the second error.
Usually, such things aren't a big issue, but it's worth being aware
of them.
@@ -30218,7 +30222,7 @@ Index
* --re-interval option: Options. (line 279)
* --sandbox option: Options. (line 286)
* --sandbox option, disabling system() function: I/O Functions.
- (line 94)
+ (line 97)
* --sandbox option, input redirection with getline: Getline. (line 19)
* --sandbox option, output redirection with print, printf: Redirection.
(line 6)
@@ -30453,7 +30457,7 @@ Index
(line 6)
* array scanning order, controlling: Controlling Scanning.
(line 14)
-* array, number of elements: String Functions. (line 194)
+* array, number of elements: String Functions. (line 197)
* arrays: Arrays. (line 6)
* arrays of arrays: Arrays of Arrays. (line 6)
* arrays, an example of using: Array Example. (line 6)
@@ -30469,7 +30473,7 @@ Index
* arrays, elements, deleting: Delete. (line 6)
* arrays, elements, order of access by in operator: Scanning an Array.
(line 48)
-* arrays, elements, retrieving number of: String Functions. (line 32)
+* arrays, elements, retrieving number of: String Functions. (line 42)
* arrays, for statement and: Scanning an Array. (line 20)
* arrays, indexing: Array Intro. (line 50)
* arrays, merging into strings: Join Function. (line 6)
@@ -30496,12 +30500,12 @@ Index
* ASCII: Ordinal Functions. (line 45)
* asort <1>: Array Sorting Functions.
(line 6)
-* asort: String Functions. (line 32)
+* asort: String Functions. (line 42)
* asort() function (gawk), arrays, sorting: Array Sorting Functions.
(line 6)
* asorti <1>: Array Sorting Functions.
(line 6)
-* asorti: String Functions. (line 32)
+* asorti: String Functions. (line 42)
* asorti() function (gawk), arrays, sorting: Array Sorting Functions.
(line 6)
* assert() function (C library): Assert Function. (line 6)
@@ -30726,7 +30730,7 @@ Index
* Brennan, Michael <3>: Simple Sed. (line 25)
* Brennan, Michael <4>: Delete. (line 56)
* Brennan, Michael: Foreword. (line 83)
-* Brian Kernighan's awk <1>: I/O Functions. (line 40)
+* Brian Kernighan's awk <1>: I/O Functions. (line 43)
* Brian Kernighan's awk <2>: Gory Details. (line 15)
* Brian Kernighan's awk <3>: String Functions. (line 490)
* Brian Kernighan's awk <4>: Delete. (line 48)
@@ -30755,9 +30759,9 @@ Index
* Buening, Andreas <2>: Contributors. (line 92)
* Buening, Andreas: Acknowledgments. (line 60)
* buffering, input/output <1>: Two-way I/O. (line 70)
-* buffering, input/output: I/O Functions. (line 137)
-* buffering, interactive vs. noninteractive: I/O Functions. (line 106)
-* buffers, flushing: I/O Functions. (line 29)
+* buffering, input/output: I/O Functions. (line 140)
+* buffering, interactive vs. noninteractive: I/O Functions. (line 109)
+* buffers, flushing: I/O Functions. (line 32)
* buffers, operators for: GNU Regexp Operators.
(line 48)
* bug reports, email address, bug-gawk@gnu.org: Bugs. (line 30)
@@ -30866,7 +30870,7 @@ Index
* common extensions, delete to delete entire arrays: Delete. (line 39)
* common extensions, func keyword: Definition Syntax. (line 83)
* common extensions, length() applied to an array: String Functions.
- (line 194)
+ (line 197)
* common extensions, RS as a regexp: gawk split records. (line 6)
* common extensions, single character fields: Single Character Fields.
(line 6)
@@ -30920,7 +30924,7 @@ Index
* controlling array scanning order: Controlling Scanning.
(line 14)
* convert string to lower case: String Functions. (line 521)
-* convert string to number: String Functions. (line 385)
+* convert string to number: String Functions. (line 388)
* convert string to upper case: String Functions. (line 527)
* converting integer array subscripts: Numeric Array Subscripts.
(line 31)
@@ -30986,7 +30990,7 @@ Index
(line 20)
* dark corner, input files: awk split records. (line 110)
* dark corner, invoking awk: Command Line. (line 16)
-* dark corner, length() function: String Functions. (line 180)
+* dark corner, length() function: String Functions. (line 183)
* dark corner, locale's decimal point character: Conversion. (line 75)
* dark corner, multiline records: Multiple Line. (line 35)
* dark corner, NF variable, decrementing: Changing Fields. (line 107)
@@ -31005,7 +31009,7 @@ Index
* database, group, reading: Group Functions. (line 6)
* database, users, reading: Passwd Functions. (line 6)
* date utility, GNU: Time Functions. (line 17)
-* date utility, POSIX: Time Functions. (line 263)
+* date utility, POSIX: Time Functions. (line 254)
* dates, converting to timestamps: Time Functions. (line 76)
* dates, information related to, localization: Explaining gettext.
(line 115)
@@ -31142,7 +31146,7 @@ Index
* deleting entire arrays: Delete. (line 39)
* Demaille, Akim: Acknowledgments. (line 60)
* describe call stack frame, in debugger: Debugger Info. (line 27)
-* differences between gawk and awk: String Functions. (line 194)
+* differences between gawk and awk: String Functions. (line 197)
* differences in awk and gawk, ARGC/ARGV variables: ARGC and ARGV.
(line 88)
* differences in awk and gawk, ARGIND variable: Auto-set. (line 44)
@@ -31189,7 +31193,7 @@ Index
(line 34)
* differences in awk and gawk, LINT variable: User-modified. (line 88)
* differences in awk and gawk, match() function: String Functions.
- (line 257)
+ (line 260)
* differences in awk and gawk, print/printf statements: Format Modifiers.
(line 13)
* differences in awk and gawk, PROCINFO array: Auto-set. (line 128)
@@ -31385,10 +31389,10 @@ Index
* extensions, common, \x escape sequence: Escape Sequences. (line 61)
* extensions, common, BINMODE variable: PC Using. (line 33)
* extensions, common, delete to delete entire arrays: Delete. (line 39)
-* extensions, common, fflush() function: I/O Functions. (line 40)
+* extensions, common, fflush() function: I/O Functions. (line 43)
* extensions, common, func keyword: Definition Syntax. (line 83)
* extensions, common, length() applied to an array: String Functions.
- (line 194)
+ (line 197)
* extensions, common, RS as a regexp: gawk split records. (line 6)
* extensions, common, single character fields: Single Character Fields.
(line 6)
@@ -31407,7 +31411,7 @@ Index
* features, undocumented: Undocumented. (line 6)
* Fenlason, Jay <1>: Contributors. (line 18)
* Fenlason, Jay: History. (line 30)
-* fflush: I/O Functions. (line 25)
+* fflush: I/O Functions. (line 28)
* field numbers: Nonconstant Fields. (line 6)
* field operator $: Fields. (line 19)
* field operators, dollar sign as: Fields. (line 19)
@@ -31500,7 +31504,7 @@ Index
* files, source, search path for: Igawk Program. (line 368)
* files, splitting: Split Program. (line 6)
* files, Texinfo, extracting programs from: Extract Program. (line 6)
-* find substring in string: String Functions. (line 151)
+* find substring in string: String Functions. (line 155)
* finding extensions: Finding Extensions. (line 6)
* finish debugger command: Debugger Execution Control.
(line 39)
@@ -31513,7 +31517,7 @@ Index
* floating-point, numbers, arbitrary precision: Arbitrary Precision Arithmetic.
(line 6)
* floating-point, VAX/VMS: VMS Running. (line 51)
-* flush buffered output: I/O Functions. (line 25)
+* flush buffered output: I/O Functions. (line 28)
* fnmatch() extension function: Extension Sample Fnmatch.
(line 12)
* FNR variable <1>: Auto-set. (line 99)
@@ -31532,7 +31536,7 @@ Index
* format time string: Time Functions. (line 48)
* formats, numeric output: OFMT. (line 6)
* formatting output: Printf. (line 6)
-* formatting strings: String Functions. (line 378)
+* formatting strings: String Functions. (line 381)
* forward slash (/) to enclose regular expressions: Regexp. (line 10)
* forward slash (/), / operator: Precedence. (line 55)
* forward slash (/), /= operator <1>: Precedence. (line 95)
@@ -31661,7 +31665,7 @@ Index
* gawk, hexadecimal numbers and: Nondecimal-numbers. (line 42)
* gawk, IGNORECASE variable in <1>: Array Sorting Functions.
(line 83)
-* gawk, IGNORECASE variable in <2>: String Functions. (line 48)
+* gawk, IGNORECASE variable in <2>: String Functions. (line 58)
* gawk, IGNORECASE variable in <3>: Array Intro. (line 92)
* gawk, IGNORECASE variable in <4>: User-modified. (line 76)
* gawk, IGNORECASE variable in: Case-sensitivity. (line 26)
@@ -31715,7 +31719,7 @@ Index
* General Public License (GPL): Glossary. (line 306)
* General Public License, See GPL: Manual History. (line 11)
* generate time values: Time Functions. (line 25)
-* gensub <1>: String Functions. (line 82)
+* gensub <1>: String Functions. (line 89)
* gensub: Using Constant Regexps.
(line 43)
* gensub() function (gawk), escape processing: Gory Details. (line 6)
@@ -31791,7 +31795,7 @@ Index
* group file: Group Functions. (line 6)
* group ID of gawk user: Auto-set. (line 172)
* groups, information about: Group Functions. (line 6)
-* gsub <1>: String Functions. (line 135)
+* gsub <1>: String Functions. (line 139)
* gsub: Using Constant Regexps.
(line 43)
* gsub() function, arguments of: String Functions. (line 460)
@@ -31855,7 +31859,7 @@ Index
(line 37)
* in operator, use in loops: Scanning an Array. (line 17)
* increment operators: Increment Ops. (line 6)
-* index: String Functions. (line 151)
+* index: String Functions. (line 155)
* indexing arrays: Array Intro. (line 50)
* indirect function calls: Indirect Calls. (line 6)
* infinite precision: Arbitrary Precision Arithmetic.
@@ -31873,7 +31877,7 @@ Index
* input files, running awk without: Read Terminal. (line 6)
* input files, variable assignments and: Other Arguments. (line 19)
* input pipeline: Getline/Pipe. (line 9)
-* input record, length of: String Functions. (line 171)
+* input record, length of: String Functions. (line 174)
* input redirection: Getline/File. (line 6)
* input, data, nondecimal: Nondecimal Data. (line 6)
* input, explicit: Getline. (line 6)
@@ -31898,7 +31902,7 @@ Index
* integers, arbitrary precision: Arbitrary Precision Integers.
(line 6)
* integers, unsigned: General Arithmetic. (line 15)
-* interacting with other programs: I/O Functions. (line 72)
+* interacting with other programs: I/O Functions. (line 75)
* internationalization <1>: I18N and L10N. (line 6)
* internationalization: I18N Functions. (line 6)
* internationalization, localization <1>: Internationalization.
@@ -31919,7 +31923,7 @@ Index
* interpreted programs: Basic High Level. (line 15)
* interval expressions, regexp operator: Regexp Operators. (line 117)
* inventory-shipped file: Sample Data Files. (line 32)
-* invoke shell command: I/O Functions. (line 72)
+* invoke shell command: I/O Functions. (line 75)
* isarray: Type Functions. (line 11)
* ISO: Glossary. (line 368)
* ISO 8859-1: Glossary. (line 133)
@@ -31977,9 +31981,9 @@ Index
* left shift: Bitwise Functions. (line 46)
* left shift, bitwise: Bitwise Functions. (line 32)
* leftmost longest match: Multiple Line. (line 26)
-* length: String Functions. (line 164)
-* length of input record: String Functions. (line 171)
-* length of string: String Functions. (line 164)
+* length: String Functions. (line 167)
+* length of input record: String Functions. (line 174)
+* length of string: String Functions. (line 167)
* Lesser General Public License (LGPL): Glossary. (line 397)
* LGPL (Lesser General Public License): Glossary. (line 397)
* libmawk: Other Versions. (line 120)
@@ -32071,10 +32075,10 @@ Index
(line 6)
* marked strings, extracting: String Extraction. (line 6)
* Marx, Groucho: Increment Ops. (line 60)
-* match: String Functions. (line 204)
-* match regexp in string: String Functions. (line 204)
+* match: String Functions. (line 207)
+* match regexp in string: String Functions. (line 207)
* match() function, RSTART/RLENGTH variables: String Functions.
- (line 221)
+ (line 224)
* matching, expressions, See comparison expressions: Typing and Comparison.
(line 9)
* matching, leftmost longest: Multiple Line. (line 26)
@@ -32174,7 +32178,7 @@ Index
* null strings, converting numbers to strings: Conversion. (line 21)
* null strings, matching: Gory Details. (line 164)
* number as string of bits: Bitwise Functions. (line 109)
-* number of array elements: String Functions. (line 194)
+* number of array elements: String Functions. (line 197)
* number sign (#), #! (executable scripts): Executable Scripts.
(line 6)
* number sign (#), commenting: Comments. (line 6)
@@ -32263,7 +32267,7 @@ Index
(line 20)
* output redirection: Redirection. (line 6)
* output wrapper: Output Wrappers. (line 6)
-* output, buffering: I/O Functions. (line 29)
+* output, buffering: I/O Functions. (line 32)
* output, duplicating into files: Tee Program. (line 6)
* output, files, closing: Close Files And Pipes.
(line 6)
@@ -32280,7 +32284,7 @@ Index
* parentheses (), in a profile: Profiling. (line 146)
* parentheses (), regexp operator: Regexp Operators. (line 80)
* password file: Passwd Functions. (line 16)
-* patsplit: String Functions. (line 291)
+* patsplit: String Functions. (line 294)
* patterns: Patterns and Actions.
(line 6)
* patterns, comparison expressions as: Expression Patterns. (line 14)
@@ -32336,7 +32340,7 @@ Index
* portability, gawk: New Ports. (line 6)
* portability, gettext library and: Explaining gettext. (line 10)
* portability, internationalization and: I18N Portability. (line 6)
-* portability, length() function: String Functions. (line 173)
+* portability, length() function: String Functions. (line 176)
* portability, new awk vs. old awk: Conversion. (line 55)
* portability, next statement in user-defined functions: Pass By Value/Reference.
(line 91)
@@ -32374,14 +32378,14 @@ Index
* POSIX awk, changes in awk versions: POSIX. (line 6)
* POSIX awk, continue statement and: Continue Statement. (line 43)
* POSIX awk, CONVFMT variable and: User-modified. (line 30)
-* POSIX awk, date utility and: Time Functions. (line 263)
+* POSIX awk, date utility and: Time Functions. (line 254)
* POSIX awk, field separators and <1>: Field Splitting Summary.
(line 40)
* POSIX awk, field separators and: Fields. (line 6)
* POSIX awk, FS variable and: User-modified. (line 60)
* POSIX awk, function keyword in: Definition Syntax. (line 83)
* POSIX awk, functions and, gsub()/sub(): Gory Details. (line 54)
-* POSIX awk, functions and, length(): String Functions. (line 173)
+* POSIX awk, functions and, length(): String Functions. (line 176)
* POSIX awk, GNU long options and: Options. (line 15)
* POSIX awk, interval expressions in: Regexp Operators. (line 136)
* POSIX awk, next/nextfile statements and: Next Statement. (line 45)
@@ -32619,7 +32623,7 @@ Index
* right shift, bitwise: Bitwise Functions. (line 32)
* Ritchie, Dennis: Basic Data Typing. (line 55)
* RLENGTH variable: Auto-set. (line 244)
-* RLENGTH variable, match() function and: String Functions. (line 221)
+* RLENGTH variable, match() function and: String Functions. (line 224)
* Robbins, Arnold <1>: Future Extensions. (line 6)
* Robbins, Arnold <2>: Bugs. (line 32)
* Robbins, Arnold <3>: Contributors. (line 139)
@@ -32648,7 +32652,7 @@ Index
* RS variable, multiline records and: Multiple Line. (line 17)
* rshift: Bitwise Functions. (line 52)
* RSTART variable: Auto-set. (line 250)
-* RSTART variable, match() function and: String Functions. (line 221)
+* RSTART variable, match() function and: String Functions. (line 224)
* RT variable <1>: Auto-set. (line 257)
* RT variable <2>: Multiple Line. (line 129)
* RT variable: awk split records. (line 124)
@@ -32673,8 +32677,8 @@ Index
* Schorr, Andrew: Acknowledgments. (line 60)
* Schreiber, Bert: Acknowledgments. (line 38)
* Schreiber, Rita: Acknowledgments. (line 38)
-* search and replace in strings: String Functions. (line 82)
-* search in string: String Functions. (line 151)
+* search and replace in strings: String Functions. (line 89)
+* search in string: String Functions. (line 155)
* search paths <1>: VMS Running. (line 58)
* search paths <2>: PC Using. (line 10)
* search paths: Igawk Program. (line 368)
@@ -32759,13 +32763,13 @@ Index
(line 38)
* sidebar, Changing NR and FNR: Auto-set. (line 299)
* sidebar, Controlling Output Buffering with system(): I/O Functions.
- (line 135)
+ (line 138)
* sidebar, Escape Sequences for Metacharacters: Escape Sequences.
(line 128)
* sidebar, FS and IGNORECASE: Field Splitting Summary.
(line 64)
* sidebar, Interactive Versus Noninteractive Buffering: I/O Functions.
- (line 104)
+ (line 107)
* sidebar, Matching the Null String: Gory Details. (line 162)
* sidebar, Operator Evaluation Order: Increment Ops. (line 58)
* sidebar, Piping into sh: Redirection. (line 140)
@@ -32809,8 +32813,8 @@ Index
* sleep() extension function: Extension Sample Time.
(line 23)
* Solaris, POSIX-compliant awk: Other Versions. (line 96)
-* sort array: String Functions. (line 32)
-* sort array indices: String Functions. (line 32)
+* sort array: String Functions. (line 42)
+* sort array indices: String Functions. (line 42)
* sort function, arrays, sorting: Array Sorting Functions.
(line 6)
* sort utility: Word Sorting. (line 50)
@@ -32835,11 +32839,11 @@ Index
* sparse arrays: Array Intro. (line 71)
* Spencer, Henry: Glossary. (line 12)
* split: String Functions. (line 313)
-* split string into array: String Functions. (line 291)
+* split string into array: String Functions. (line 294)
* split utility: Split Program. (line 6)
* split() function, array elements, deleting: Delete. (line 61)
* split.awk program: Split Program. (line 30)
-* sprintf <1>: String Functions. (line 378)
+* sprintf <1>: String Functions. (line 381)
* sprintf: OFMT. (line 15)
* sprintf() function, OFMT variable and: User-modified. (line 114)
* sprintf() function, print/printf statements and: Round Function.
@@ -32877,9 +32881,9 @@ Index
* string constants, vs. regexp constants: Computed Regexps. (line 39)
* string extraction (internationalization): String Extraction.
(line 6)
-* string length: String Functions. (line 164)
+* string length: String Functions. (line 167)
* string operators: Concatenation. (line 8)
-* string, regular expression match: String Functions. (line 204)
+* string, regular expression match: String Functions. (line 207)
* string-manipulation functions: String Functions. (line 6)
* string-matching operators: Regexp Usage. (line 19)
* string-translation functions: I18N Functions. (line 6)
@@ -32896,7 +32900,7 @@ Index
* strings, null: Regexp Field Splitting.
(line 43)
* strings, numeric: Variable Typing. (line 6)
-* strtonum: String Functions. (line 385)
+* strtonum: String Functions. (line 388)
* strtonum() function (gawk), --non-decimal-data option and: Nondecimal Data.
(line 36)
* sub <1>: String Functions. (line 406)
@@ -32915,7 +32919,7 @@ Index
* SUBSEP variable: User-modified. (line 146)
* SUBSEP variable, and multidimensional arrays: Multidimensional.
(line 16)
-* substitute in string: String Functions. (line 82)
+* substitute in string: String Functions. (line 89)
* substr: String Functions. (line 479)
* substring: String Functions. (line 479)
* Sumner, Andrew: Other Versions. (line 64)
@@ -32924,7 +32928,7 @@ Index
* SYMTAB array: Auto-set. (line 261)
* syntactic ambiguity: /= operator vs. /=.../ regexp constant: Assignment Ops.
(line 148)
-* system: I/O Functions. (line 72)
+* system: I/O Functions. (line 75)
* systime: Time Functions. (line 66)
* t debugger command (alias for tbreak): Breakpoint Control. (line 90)
* tbreak debugger command: Breakpoint Control. (line 90)
@@ -32994,7 +32998,7 @@ Index
(line 23)
* troubleshooting, fatal errors, printf format strings: Format Modifiers.
(line 159)
-* troubleshooting, fflush() function: I/O Functions. (line 60)
+* troubleshooting, fflush() function: I/O Functions. (line 63)
* troubleshooting, function call syntax: Function Calls. (line 30)
* troubleshooting, gawk: Compatibility Mode. (line 6)
* troubleshooting, gawk, bug reports: Bugs. (line 9)
@@ -33002,8 +33006,7 @@ Index
(line 16)
* troubleshooting, getline function: File Checking. (line 25)
* troubleshooting, gsub()/sub() functions: String Functions. (line 470)
-* troubleshooting, match() function: String Functions. (line 286)
-* troubleshooting, patsplit() function: String Functions. (line 309)
+* troubleshooting, match() function: String Functions. (line 289)
* troubleshooting, print statement, omitting commas: Print Examples.
(line 31)
* troubleshooting, printing: Redirection. (line 118)
@@ -33013,7 +33016,7 @@ Index
(line 39)
* troubleshooting, string concatenation: Concatenation. (line 26)
* troubleshooting, substr() function: String Functions. (line 497)
-* troubleshooting, system() function: I/O Functions. (line 94)
+* troubleshooting, system() function: I/O Functions. (line 97)
* troubleshooting, typographical errors, global variables: Options.
(line 98)
* true, logical: Truth Values. (line 6)
@@ -33354,370 +33357,370 @@ Node: Conditional Exp350997
Node: Function Calls352724
Node: Precedence356482
Node: Locales360151
-Node: Patterns and Actions361240
-Node: Pattern Overview362294
-Node: Regexp Patterns363971
-Node: Expression Patterns364514
-Node: Ranges368295
-Node: BEGIN/END371401
-Node: Using BEGIN/END372163
-Ref: Using BEGIN/END-Footnote-1374899
-Node: I/O And BEGIN/END375005
-Node: BEGINFILE/ENDFILE377290
-Node: Empty380226
-Node: Using Shell Variables380543
-Node: Action Overview382826
-Node: Statements385171
-Node: If Statement387025
-Node: While Statement388524
-Node: Do Statement390568
-Node: For Statement391724
-Node: Switch Statement394876
-Node: Break Statement396979
-Node: Continue Statement399034
-Node: Next Statement400827
-Node: Nextfile Statement403217
-Node: Exit Statement405872
-Node: Built-in Variables408274
-Node: User-modified409370
-Ref: User-modified-Footnote-1417055
-Node: Auto-set417117
-Ref: Auto-set-Footnote-1429682
-Ref: Auto-set-Footnote-2429887
-Node: ARGC and ARGV429943
-Node: Arrays433797
-Node: Array Basics435295
-Node: Array Intro436121
-Ref: figure-array-elements438094
-Node: Reference to Elements440501
-Node: Assigning Elements442774
-Node: Array Example443265
-Node: Scanning an Array444997
-Node: Controlling Scanning448012
-Ref: Controlling Scanning-Footnote-1453185
-Node: Delete453501
-Ref: Delete-Footnote-1456266
-Node: Numeric Array Subscripts456323
-Node: Uninitialized Subscripts458506
-Node: Multidimensional460131
-Node: Multiscanning463224
-Node: Arrays of Arrays464813
-Node: Functions469453
-Node: Built-in470272
-Node: Calling Built-in471350
-Node: Numeric Functions473338
-Ref: Numeric Functions-Footnote-1477172
-Ref: Numeric Functions-Footnote-2477529
-Ref: Numeric Functions-Footnote-3477577
-Node: String Functions477846
-Ref: String Functions-Footnote-1500849
-Ref: String Functions-Footnote-2500978
-Ref: String Functions-Footnote-3501226
-Node: Gory Details501313
-Ref: table-sub-escapes502992
-Ref: table-sub-posix-92504346
-Ref: table-sub-proposed505697
-Ref: table-posix-sub507051
-Ref: table-gensub-escapes508596
-Ref: Gory Details-Footnote-1509772
-Ref: Gory Details-Footnote-2509823
-Node: I/O Functions509974
-Ref: I/O Functions-Footnote-1516970
-Node: Time Functions517117
-Ref: Time Functions-Footnote-1528110
-Ref: Time Functions-Footnote-2528178
-Ref: Time Functions-Footnote-3528336
-Ref: Time Functions-Footnote-4528447
-Ref: Time Functions-Footnote-5528559
-Ref: Time Functions-Footnote-6528786
-Node: Bitwise Functions529052
-Ref: table-bitwise-ops529614
-Ref: Bitwise Functions-Footnote-1533859
-Node: Type Functions534043
-Node: I18N Functions535194
-Node: User-defined536846
-Node: Definition Syntax537650
-Ref: Definition Syntax-Footnote-1542564
-Node: Function Example542633
-Ref: Function Example-Footnote-1545282
-Node: Function Caveats545304
-Node: Calling A Function545822
-Node: Variable Scope546777
-Node: Pass By Value/Reference549740
-Node: Return Statement553248
-Node: Dynamic Typing556229
-Node: Indirect Calls557160
-Node: Library Functions566847
-Ref: Library Functions-Footnote-1570360
-Ref: Library Functions-Footnote-2570503
-Node: Library Names570674
-Ref: Library Names-Footnote-1574147
-Ref: Library Names-Footnote-2574367
-Node: General Functions574453
-Node: Strtonum Function575481
-Node: Assert Function578411
-Node: Round Function581737
-Node: Cliff Random Function583278
-Node: Ordinal Functions584294
-Ref: Ordinal Functions-Footnote-1587371
-Ref: Ordinal Functions-Footnote-2587623
-Node: Join Function587834
-Ref: Join Function-Footnote-1589605
-Node: Getlocaltime Function589805
-Node: Readfile Function593546
-Node: Data File Management595385
-Node: Filetrans Function596017
-Node: Rewind Function600086
-Node: File Checking601473
-Node: Empty Files602567
-Node: Ignoring Assigns604797
-Node: Getopt Function606351
-Ref: Getopt Function-Footnote-1617654
-Node: Passwd Functions617857
-Ref: Passwd Functions-Footnote-1626835
-Node: Group Functions626923
-Node: Walking Arrays635007
-Node: Sample Programs637143
-Node: Running Examples637817
-Node: Clones638545
-Node: Cut Program639769
-Node: Egrep Program649620
-Ref: Egrep Program-Footnote-1657393
-Node: Id Program657503
-Node: Split Program661152
-Ref: Split Program-Footnote-1664671
-Node: Tee Program664799
-Node: Uniq Program667602
-Node: Wc Program675031
-Ref: Wc Program-Footnote-1679297
-Ref: Wc Program-Footnote-2679497
-Node: Miscellaneous Programs679589
-Node: Dupword Program680777
-Node: Alarm Program682808
-Node: Translate Program687615
-Ref: Translate Program-Footnote-1692002
-Ref: Translate Program-Footnote-2692250
-Node: Labels Program692384
-Ref: Labels Program-Footnote-1695755
-Node: Word Sorting695839
-Node: History Sorting699723
-Node: Extract Program701562
-Ref: Extract Program-Footnote-1709065
-Node: Simple Sed709193
-Node: Igawk Program712255
-Ref: Igawk Program-Footnote-1727426
-Ref: Igawk Program-Footnote-2727627
-Node: Anagram Program727765
-Node: Signature Program730833
-Node: Advanced Features731933
-Node: Nondecimal Data733819
-Node: Array Sorting735402
-Node: Controlling Array Traversal736099
-Node: Array Sorting Functions744383
-Ref: Array Sorting Functions-Footnote-1748252
-Node: Two-way I/O748446
-Ref: Two-way I/O-Footnote-1753878
-Node: TCP/IP Networking753960
-Node: Profiling756804
-Node: Internationalization764307
-Node: I18N and L10N765732
-Node: Explaining gettext766418
-Ref: Explaining gettext-Footnote-1771486
-Ref: Explaining gettext-Footnote-2771670
-Node: Programmer i18n771835
-Node: Translator i18n776062
-Node: String Extraction776856
-Ref: String Extraction-Footnote-1777817
-Node: Printf Ordering777903
-Ref: Printf Ordering-Footnote-1780685
-Node: I18N Portability780749
-Ref: I18N Portability-Footnote-1783198
-Node: I18N Example783261
-Ref: I18N Example-Footnote-1785899
-Node: Gawk I18N785971
-Node: Debugger786592
-Node: Debugging787563
-Node: Debugging Concepts787996
-Node: Debugging Terms789852
-Node: Awk Debugging792449
-Node: Sample Debugging Session793341
-Node: Debugger Invocation793861
-Node: Finding The Bug795194
-Node: List of Debugger Commands801681
-Node: Breakpoint Control803015
-Node: Debugger Execution Control806679
-Node: Viewing And Changing Data810039
-Node: Execution Stack813395
-Node: Debugger Info814862
-Node: Miscellaneous Debugger Commands818856
-Node: Readline Support824034
-Node: Limitations824865
-Node: Arbitrary Precision Arithmetic827117
-Ref: Arbitrary Precision Arithmetic-Footnote-1828766
-Node: General Arithmetic828914
-Node: Floating Point Issues830634
-Node: String Conversion Precision831515
-Ref: String Conversion Precision-Footnote-1833220
-Node: Unexpected Results833329
-Node: POSIX Floating Point Problems835482
-Ref: POSIX Floating Point Problems-Footnote-1839307
-Node: Integer Programming839345
-Node: Floating-point Programming841084
-Ref: Floating-point Programming-Footnote-1847415
-Ref: Floating-point Programming-Footnote-2847685
-Node: Floating-point Representation847949
-Node: Floating-point Context849114
-Ref: table-ieee-formats849953
-Node: Rounding Mode851337
-Ref: table-rounding-modes851816
-Ref: Rounding Mode-Footnote-1854831
-Node: Gawk and MPFR855010
-Node: Arbitrary Precision Floats856419
-Ref: Arbitrary Precision Floats-Footnote-1858862
-Node: Setting Precision859178
-Ref: table-predefined-precision-strings859864
-Node: Setting Rounding Mode862009
-Ref: table-gawk-rounding-modes862413
-Node: Floating-point Constants863600
-Node: Changing Precision865029
-Ref: Changing Precision-Footnote-1866426
-Node: Exact Arithmetic866600
-Node: Arbitrary Precision Integers869738
-Ref: Arbitrary Precision Integers-Footnote-1872753
-Node: Dynamic Extensions872900
-Node: Extension Intro874358
-Node: Plugin License875623
-Node: Extension Mechanism Outline876308
-Ref: load-extension876725
-Ref: load-new-function878203
-Ref: call-new-function879198
-Node: Extension API Description881213
-Node: Extension API Functions Introduction882500
-Node: General Data Types887427
-Ref: General Data Types-Footnote-1893122
-Node: Requesting Values893421
-Ref: table-value-types-returned894158
-Node: Memory Allocation Functions895112
-Ref: Memory Allocation Functions-Footnote-1897858
-Node: Constructor Functions897954
-Node: Registration Functions899712
-Node: Extension Functions900397
-Node: Exit Callback Functions902699
-Node: Extension Version String903948
-Node: Input Parsers904598
-Node: Output Wrappers914355
-Node: Two-way processors918865
-Node: Printing Messages921073
-Ref: Printing Messages-Footnote-1922150
-Node: Updating `ERRNO'922302
-Node: Accessing Parameters923041
-Node: Symbol Table Access924271
-Node: Symbol table by name924785
-Node: Symbol table by cookie926761
-Ref: Symbol table by cookie-Footnote-1930893
-Node: Cached values930956
-Ref: Cached values-Footnote-1934446
-Node: Array Manipulation934537
-Ref: Array Manipulation-Footnote-1935635
-Node: Array Data Types935674
-Ref: Array Data Types-Footnote-1938377
-Node: Array Functions938469
-Node: Flattening Arrays942305
-Node: Creating Arrays949157
-Node: Extension API Variables953882
-Node: Extension Versioning954518
-Node: Extension API Informational Variables956419
-Node: Extension API Boilerplate957505
-Node: Finding Extensions961309
-Node: Extension Example961869
-Node: Internal File Description962599
-Node: Internal File Ops966690
-Ref: Internal File Ops-Footnote-1978199
-Node: Using Internal File Ops978339
-Ref: Using Internal File Ops-Footnote-1980686
-Node: Extension Samples980952
-Node: Extension Sample File Functions982476
-Node: Extension Sample Fnmatch990963
-Node: Extension Sample Fork992732
-Node: Extension Sample Inplace993945
-Node: Extension Sample Ord995723
-Node: Extension Sample Readdir996559
-Node: Extension Sample Revout998091
-Node: Extension Sample Rev2way998684
-Node: Extension Sample Read write array999374
-Node: Extension Sample Readfile1001257
-Node: Extension Sample API Tests1002357
-Node: Extension Sample Time1002882
-Node: gawkextlib1004246
-Node: Language History1007027
-Node: V7/SVR3.11008620
-Node: SVR41010940
-Node: POSIX1012382
-Node: BTL1013768
-Node: POSIX/GNU1014502
-Node: Feature History1020101
-Node: Common Extensions1033077
-Node: Ranges and Locales1034389
-Ref: Ranges and Locales-Footnote-11039006
-Ref: Ranges and Locales-Footnote-21039033
-Ref: Ranges and Locales-Footnote-31039267
-Node: Contributors1039488
-Node: Installation1044869
-Node: Gawk Distribution1045763
-Node: Getting1046247
-Node: Extracting1047073
-Node: Distribution contents1048765
-Node: Unix Installation1054486
-Node: Quick Installation1055103
-Node: Additional Configuration Options1057549
-Node: Configuration Philosophy1059285
-Node: Non-Unix Installation1061639
-Node: PC Installation1062097
-Node: PC Binary Installation1063396
-Node: PC Compiling1065244
-Node: PC Testing1068188
-Node: PC Using1069364
-Node: Cygwin1073532
-Node: MSYS1074341
-Node: VMS Installation1074855
-Node: VMS Compilation1075651
-Ref: VMS Compilation-Footnote-11076903
-Node: VMS Dynamic Extensions1076961
-Node: VMS Installation Details1078334
-Node: VMS Running1080585
-Node: VMS GNV1083419
-Node: VMS Old Gawk1084142
-Node: Bugs1084612
-Node: Other Versions1088530
-Node: Notes1094614
-Node: Compatibility Mode1095414
-Node: Additions1096197
-Node: Accessing The Source1097124
-Node: Adding Code1098564
-Node: New Ports1104609
-Node: Derived Files1108744
-Ref: Derived Files-Footnote-11114065
-Ref: Derived Files-Footnote-21114099
-Ref: Derived Files-Footnote-31114699
-Node: Future Extensions1114797
-Node: Implementation Limitations1115380
-Node: Extension Design1116628
-Node: Old Extension Problems1117782
-Ref: Old Extension Problems-Footnote-11119290
-Node: Extension New Mechanism Goals1119347
-Ref: Extension New Mechanism Goals-Footnote-11122712
-Node: Extension Other Design Decisions1122898
-Node: Extension Future Growth1125004
-Node: Old Extension Mechanism1125840
-Node: Basic Concepts1127580
-Node: Basic High Level1128261
-Ref: figure-general-flow1128533
-Ref: figure-process-flow1129132
-Ref: Basic High Level-Footnote-11132361
-Node: Basic Data Typing1132546
-Node: Glossary1135901
-Node: Copying1161132
-Node: GNU Free Documentation License1198688
-Node: Index1223824
+Node: Patterns and Actions361754
+Node: Pattern Overview362808
+Node: Regexp Patterns364485
+Node: Expression Patterns365028
+Node: Ranges368809
+Node: BEGIN/END371915
+Node: Using BEGIN/END372677
+Ref: Using BEGIN/END-Footnote-1375413
+Node: I/O And BEGIN/END375519
+Node: BEGINFILE/ENDFILE377804
+Node: Empty380740
+Node: Using Shell Variables381057
+Node: Action Overview383340
+Node: Statements385685
+Node: If Statement387539
+Node: While Statement389038
+Node: Do Statement391082
+Node: For Statement392238
+Node: Switch Statement395390
+Node: Break Statement397493
+Node: Continue Statement399548
+Node: Next Statement401341
+Node: Nextfile Statement403731
+Node: Exit Statement406386
+Node: Built-in Variables408788
+Node: User-modified409884
+Ref: User-modified-Footnote-1417569
+Node: Auto-set417631
+Ref: Auto-set-Footnote-1430196
+Ref: Auto-set-Footnote-2430401
+Node: ARGC and ARGV430457
+Node: Arrays434311
+Node: Array Basics435809
+Node: Array Intro436635
+Ref: figure-array-elements438608
+Node: Reference to Elements441015
+Node: Assigning Elements443288
+Node: Array Example443779
+Node: Scanning an Array445511
+Node: Controlling Scanning448526
+Ref: Controlling Scanning-Footnote-1453699
+Node: Delete454015
+Ref: Delete-Footnote-1456780
+Node: Numeric Array Subscripts456837
+Node: Uninitialized Subscripts459020
+Node: Multidimensional460645
+Node: Multiscanning463738
+Node: Arrays of Arrays465327
+Node: Functions469967
+Node: Built-in470786
+Node: Calling Built-in471864
+Node: Numeric Functions473852
+Ref: Numeric Functions-Footnote-1477686
+Ref: Numeric Functions-Footnote-2478043
+Ref: Numeric Functions-Footnote-3478091
+Node: String Functions478360
+Ref: String Functions-Footnote-1501371
+Ref: String Functions-Footnote-2501500
+Ref: String Functions-Footnote-3501748
+Node: Gory Details501835
+Ref: table-sub-escapes503504
+Ref: table-sub-posix-92504858
+Ref: table-sub-proposed506209
+Ref: table-posix-sub507563
+Ref: table-gensub-escapes509108
+Ref: Gory Details-Footnote-1510284
+Ref: Gory Details-Footnote-2510335
+Node: I/O Functions510486
+Ref: I/O Functions-Footnote-1517609
+Node: Time Functions517756
+Ref: Time Functions-Footnote-1528220
+Ref: Time Functions-Footnote-2528288
+Ref: Time Functions-Footnote-3528446
+Ref: Time Functions-Footnote-4528557
+Ref: Time Functions-Footnote-5528669
+Ref: Time Functions-Footnote-6528896
+Node: Bitwise Functions529162
+Ref: table-bitwise-ops529724
+Ref: Bitwise Functions-Footnote-1533969
+Node: Type Functions534153
+Node: I18N Functions535295
+Node: User-defined536940
+Node: Definition Syntax537744
+Ref: Definition Syntax-Footnote-1542659
+Node: Function Example542728
+Ref: Function Example-Footnote-1545372
+Node: Function Caveats545394
+Node: Calling A Function545912
+Node: Variable Scope546867
+Node: Pass By Value/Reference549855
+Node: Return Statement553363
+Node: Dynamic Typing556345
+Node: Indirect Calls557274
+Node: Library Functions566961
+Ref: Library Functions-Footnote-1570474
+Ref: Library Functions-Footnote-2570617
+Node: Library Names570788
+Ref: Library Names-Footnote-1574261
+Ref: Library Names-Footnote-2574481
+Node: General Functions574567
+Node: Strtonum Function575595
+Node: Assert Function578525
+Node: Round Function581851
+Node: Cliff Random Function583392
+Node: Ordinal Functions584408
+Ref: Ordinal Functions-Footnote-1587485
+Ref: Ordinal Functions-Footnote-2587737
+Node: Join Function587948
+Ref: Join Function-Footnote-1589719
+Node: Getlocaltime Function589919
+Node: Readfile Function593660
+Node: Data File Management595499
+Node: Filetrans Function596131
+Node: Rewind Function600200
+Node: File Checking601587
+Node: Empty Files602681
+Node: Ignoring Assigns604911
+Node: Getopt Function606465
+Ref: Getopt Function-Footnote-1617768
+Node: Passwd Functions617971
+Ref: Passwd Functions-Footnote-1626949
+Node: Group Functions627037
+Node: Walking Arrays635121
+Node: Sample Programs637257
+Node: Running Examples637931
+Node: Clones638659
+Node: Cut Program639883
+Node: Egrep Program649734
+Ref: Egrep Program-Footnote-1657507
+Node: Id Program657617
+Node: Split Program661266
+Ref: Split Program-Footnote-1664785
+Node: Tee Program664913
+Node: Uniq Program667716
+Node: Wc Program675145
+Ref: Wc Program-Footnote-1679411
+Ref: Wc Program-Footnote-2679611
+Node: Miscellaneous Programs679703
+Node: Dupword Program680891
+Node: Alarm Program682922
+Node: Translate Program687729
+Ref: Translate Program-Footnote-1692116
+Ref: Translate Program-Footnote-2692364
+Node: Labels Program692498
+Ref: Labels Program-Footnote-1695869
+Node: Word Sorting695953
+Node: History Sorting699837
+Node: Extract Program701676
+Ref: Extract Program-Footnote-1709179
+Node: Simple Sed709307
+Node: Igawk Program712369
+Ref: Igawk Program-Footnote-1727540
+Ref: Igawk Program-Footnote-2727741
+Node: Anagram Program727879
+Node: Signature Program730947
+Node: Advanced Features732047
+Node: Nondecimal Data733933
+Node: Array Sorting735516
+Node: Controlling Array Traversal736213
+Node: Array Sorting Functions744497
+Ref: Array Sorting Functions-Footnote-1748366
+Node: Two-way I/O748560
+Ref: Two-way I/O-Footnote-1753992
+Node: TCP/IP Networking754074
+Node: Profiling756918
+Node: Internationalization764421
+Node: I18N and L10N765846
+Node: Explaining gettext766532
+Ref: Explaining gettext-Footnote-1771600
+Ref: Explaining gettext-Footnote-2771784
+Node: Programmer i18n771949
+Node: Translator i18n776176
+Node: String Extraction776970
+Ref: String Extraction-Footnote-1777931
+Node: Printf Ordering778017
+Ref: Printf Ordering-Footnote-1780799
+Node: I18N Portability780863
+Ref: I18N Portability-Footnote-1783312
+Node: I18N Example783375
+Ref: I18N Example-Footnote-1786013
+Node: Gawk I18N786085
+Node: Debugger786706
+Node: Debugging787677
+Node: Debugging Concepts788110
+Node: Debugging Terms789966
+Node: Awk Debugging792563
+Node: Sample Debugging Session793455
+Node: Debugger Invocation793975
+Node: Finding The Bug795308
+Node: List of Debugger Commands801795
+Node: Breakpoint Control803129
+Node: Debugger Execution Control806793
+Node: Viewing And Changing Data810153
+Node: Execution Stack813509
+Node: Debugger Info814976
+Node: Miscellaneous Debugger Commands818970
+Node: Readline Support824148
+Node: Limitations824979
+Node: Arbitrary Precision Arithmetic827231
+Ref: Arbitrary Precision Arithmetic-Footnote-1828880
+Node: General Arithmetic829028
+Node: Floating Point Issues830748
+Node: String Conversion Precision831629
+Ref: String Conversion Precision-Footnote-1833334
+Node: Unexpected Results833443
+Node: POSIX Floating Point Problems835596
+Ref: POSIX Floating Point Problems-Footnote-1839421
+Node: Integer Programming839459
+Node: Floating-point Programming841198
+Ref: Floating-point Programming-Footnote-1847529
+Ref: Floating-point Programming-Footnote-2847799
+Node: Floating-point Representation848063
+Node: Floating-point Context849228
+Ref: table-ieee-formats850067
+Node: Rounding Mode851451
+Ref: table-rounding-modes851930
+Ref: Rounding Mode-Footnote-1854945
+Node: Gawk and MPFR855124
+Node: Arbitrary Precision Floats856533
+Ref: Arbitrary Precision Floats-Footnote-1858976
+Node: Setting Precision859292
+Ref: table-predefined-precision-strings859978
+Node: Setting Rounding Mode862123
+Ref: table-gawk-rounding-modes862527
+Node: Floating-point Constants863714
+Node: Changing Precision865143
+Ref: Changing Precision-Footnote-1866540
+Node: Exact Arithmetic866714
+Node: Arbitrary Precision Integers869852
+Ref: Arbitrary Precision Integers-Footnote-1872867
+Node: Dynamic Extensions873014
+Node: Extension Intro874472
+Node: Plugin License875737
+Node: Extension Mechanism Outline876422
+Ref: load-extension876839
+Ref: load-new-function878317
+Ref: call-new-function879312
+Node: Extension API Description881327
+Node: Extension API Functions Introduction882614
+Node: General Data Types887541
+Ref: General Data Types-Footnote-1893236
+Node: Requesting Values893535
+Ref: table-value-types-returned894272
+Node: Memory Allocation Functions895226
+Ref: Memory Allocation Functions-Footnote-1897972
+Node: Constructor Functions898068
+Node: Registration Functions899826
+Node: Extension Functions900511
+Node: Exit Callback Functions902813
+Node: Extension Version String904062
+Node: Input Parsers904712
+Node: Output Wrappers914469
+Node: Two-way processors918979
+Node: Printing Messages921187
+Ref: Printing Messages-Footnote-1922264
+Node: Updating `ERRNO'922416
+Node: Accessing Parameters923155
+Node: Symbol Table Access924385
+Node: Symbol table by name924899
+Node: Symbol table by cookie926875
+Ref: Symbol table by cookie-Footnote-1931007
+Node: Cached values931070
+Ref: Cached values-Footnote-1934560
+Node: Array Manipulation934651
+Ref: Array Manipulation-Footnote-1935749
+Node: Array Data Types935788
+Ref: Array Data Types-Footnote-1938491
+Node: Array Functions938583
+Node: Flattening Arrays942419
+Node: Creating Arrays949271
+Node: Extension API Variables953996
+Node: Extension Versioning954632
+Node: Extension API Informational Variables956533
+Node: Extension API Boilerplate957619
+Node: Finding Extensions961423
+Node: Extension Example961983
+Node: Internal File Description962713
+Node: Internal File Ops966804
+Ref: Internal File Ops-Footnote-1978313
+Node: Using Internal File Ops978453
+Ref: Using Internal File Ops-Footnote-1980800
+Node: Extension Samples981066
+Node: Extension Sample File Functions982590
+Node: Extension Sample Fnmatch991077
+Node: Extension Sample Fork992846
+Node: Extension Sample Inplace994059
+Node: Extension Sample Ord995837
+Node: Extension Sample Readdir996673
+Node: Extension Sample Revout998205
+Node: Extension Sample Rev2way998798
+Node: Extension Sample Read write array999488
+Node: Extension Sample Readfile1001371
+Node: Extension Sample API Tests1002471
+Node: Extension Sample Time1002996
+Node: gawkextlib1004360
+Node: Language History1007141
+Node: V7/SVR3.11008734
+Node: SVR41011054
+Node: POSIX1012496
+Node: BTL1013882
+Node: POSIX/GNU1014616
+Node: Feature History1020215
+Node: Common Extensions1033191
+Node: Ranges and Locales1034503
+Ref: Ranges and Locales-Footnote-11039120
+Ref: Ranges and Locales-Footnote-21039147
+Ref: Ranges and Locales-Footnote-31039381
+Node: Contributors1039602
+Node: Installation1044983
+Node: Gawk Distribution1045877
+Node: Getting1046361
+Node: Extracting1047187
+Node: Distribution contents1048879
+Node: Unix Installation1054600
+Node: Quick Installation1055217
+Node: Additional Configuration Options1057663
+Node: Configuration Philosophy1059399
+Node: Non-Unix Installation1061753
+Node: PC Installation1062211
+Node: PC Binary Installation1063510
+Node: PC Compiling1065358
+Node: PC Testing1068302
+Node: PC Using1069478
+Node: Cygwin1073646
+Node: MSYS1074455
+Node: VMS Installation1074969
+Node: VMS Compilation1075765
+Ref: VMS Compilation-Footnote-11077017
+Node: VMS Dynamic Extensions1077075
+Node: VMS Installation Details1078448
+Node: VMS Running1080699
+Node: VMS GNV1083533
+Node: VMS Old Gawk1084256
+Node: Bugs1084726
+Node: Other Versions1088644
+Node: Notes1094728
+Node: Compatibility Mode1095528
+Node: Additions1096311
+Node: Accessing The Source1097238
+Node: Adding Code1098678
+Node: New Ports1104723
+Node: Derived Files1108858
+Ref: Derived Files-Footnote-11114179
+Ref: Derived Files-Footnote-21114213
+Ref: Derived Files-Footnote-31114813
+Node: Future Extensions1114911
+Node: Implementation Limitations1115494
+Node: Extension Design1116742
+Node: Old Extension Problems1117896
+Ref: Old Extension Problems-Footnote-11119404
+Node: Extension New Mechanism Goals1119461
+Ref: Extension New Mechanism Goals-Footnote-11122826
+Node: Extension Other Design Decisions1123012
+Node: Extension Future Growth1125118
+Node: Old Extension Mechanism1125954
+Node: Basic Concepts1127694
+Node: Basic High Level1128375
+Ref: figure-general-flow1128647
+Ref: figure-process-flow1129246
+Ref: Basic High Level-Footnote-11132475
+Node: Basic Data Typing1132660
+Node: Glossary1136015
+Node: Copying1161246
+Node: GNU Free Documentation License1198802
+Node: Index1223938

End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 569c2f33..3a81e85b 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -12194,27 +12194,35 @@ For maximum portability, do not use them.
@section Where You Are Makes A Difference
@cindex locale, definition of
-Modern systems support the notion of @dfn{locales}: a way to tell
-the system about the local character set and language.
+Modern systems support the notion of @dfn{locales}: a way to tell the
+system about the local character set and language. The ISO C standard
+defines a default @code{"C"} locale, which is an environment that is
+typical of what many C programmers are used to.
Once upon a time, the locale setting used to affect regexp matching
(@pxref{Ranges and Locales}), but this is no longer true.
-Locales can affect record splitting.
-For the normal case of @samp{RS = "\n"}, the locale is largely irrelevant.
-For other single-character record separators, setting @samp{LC_ALL=C}
-in the environment
-will give you much better performance when reading records. Otherwise,
+Locales can affect record splitting. For the normal case of @samp{RS =
+"\n"}, the locale is largely irrelevant. For other single-character
+record separators, setting @samp{LC_ALL=C} in the environment will
+give you much better performance when reading records. Otherwise,
@command{gawk} has to make several function calls, @emph{per input
character}, to find the record terminator.
-According to POSIX, string comparison is also affected by locales
-(similar to regular expressions). The details are presented in
-@ref{POSIX String Comparison}.
+Locales can affect how dates and times are formatted (@pxref{Time
+Functions}). For example, a common way to abbreviate the date September
+4, 2015 in the United States is ``9/4/15.'' In many countries in
+Europe, however, it is abbreviated ``4.9.15.'' Thus, the @samp{%x}
+specification in a @code{"US"} locale might produce @samp{9/4/15},
+while in a @code{"EUROPE"} locale, it might produce @samp{4.9.15}.
+
+According to POSIX, string comparison is also affected by locales (similar
+to regular expressions). The details are presented in @ref{POSIX String
+Comparison}.
Finally, the locale affects the value of the decimal point character
-used when @command{gawk} parses input data. This is discussed in
-detail in @ref{Conversion}.
+used when @command{gawk} parses input data. This is discussed in detail
+in @ref{Conversion}.
@c ENDOFRANGE exps
@@ -15950,7 +15958,14 @@ Optional parameters are enclosed in square brackets@w{ ([ ]):}
@cindexawkfunc{atan2}
@cindex arctangent
Return the arctangent of @code{@var{y} / @var{x}} in radians.
-You can use @samp{pi = atan2(0, -1)} to retrieve the value of @value{PI}.
+You can use @samp{pi = atan2(0, -1)} to retrieve the value of
+@ifnotdocbook
+@value{PI}.
+@end ifnotdocbook
+@docbook
+&pgr;.
+
+@end docbook
@item @code{cos(@var{x})}
@cindexawkfunc{cos}
@@ -16093,12 +16108,23 @@ example, @code{length()} returns the number of characters in a string,
and not the number of bytes used to represent those characters. Similarly,
@code{index()} works with character indices, and not byte indices.
+@quotation CAUTION
+A number of functions deal with indices into strings. For these
+functions, the first character of a string is at position (index) one.
+This is different from C and the languages descended from it, where the
+first character is at position zero. You need to remember this when
+doing index calculations, particularly if you are used to C.
+@end quotation
+
In the following list, optional parameters are enclosed in square brackets@w{ ([ ]).}
Several functions perform string substitution; the full discussion is
provided in the description of the @code{sub()} function, which comes
towards the end since the list is presented in alphabetic order.
+
Those functions that are specific to @command{gawk} are marked with a
-pound sign@w{ (@samp{#}):}
+pound sign (@samp{#}). They are not available in compatibility mode
+(@pxref{Options}):
+
@menu
* Gory Details:: More than you want to know about @samp{\} and
@@ -16108,8 +16134,8 @@ pound sign@w{ (@samp{#}):}
@c @asis for docbook
@table @asis
-@item @code{asort(}@var{source} [@code{,} @var{dest} [@code{,} @var{how} ] ]@code{)} #
-@itemx @code{asorti(}@var{source} [@code{,} @var{dest} [@code{,} @var{how} ] ]@code{)} #
+@item @code{asort(}@var{source} [@code{,} @var{dest} [@code{,} @var{how} ] ]@code{) #}
+@itemx @code{asorti(}@var{source} [@code{,} @var{dest} [@code{,} @var{how} ] ]@code{) #}
@cindexgawkfunc{asorti}
@cindex sort array
@cindex arrays, elements, retrieving number of
@@ -16173,10 +16199,7 @@ a[2] = "last"
a[3] = "middle"
@end example
-@code{asort()} and @code{asorti()} are @command{gawk} extensions; they
-are not available in compatibility mode (@pxref{Options}).
-
-@item @code{gensub(@var{regexp}, @var{replacement}, @var{how}} [@code{, @var{target}}]@code{)} #
+@item @code{gensub(@var{regexp}, @var{replacement}, @var{how}} [@code{, @var{target}}]@code{) #}
@cindexgawkfunc{gensub}
@cindex search and replace in strings
@cindex substitute in string
@@ -16238,9 +16261,6 @@ a warning message.
If @var{regexp} does not match @var{target}, @code{gensub()}'s return value
is the original unchanged value of @var{target}.
-@code{gensub()} is a @command{gawk} extension; it is not available
-in compatibility mode (@pxref{Options}).
-
@item @code{gsub(@var{regexp}, @var{replacement}} [@code{, @var{target}}]@code{)}
@cindexawkfunc{gsub}
Search @var{target} for
@@ -16278,7 +16298,6 @@ $ @kbd{awk 'BEGIN @{ print index("peanut", "an") @}'}
@noindent
If @var{find} is not found, @code{index()} returns zero.
-(Remember that string indices in @command{awk} start at one.)
It is a fatal error to use a regexp constant for @var{find}.
@@ -16289,8 +16308,19 @@ It is a fatal error to use a regexp constant for @var{find}.
Return the number of characters in @var{string}. If
@var{string} is a number, the length of the digit string representing
that number is returned. For example, @code{length("abcde")} is five. By
-contrast, @code{length(15 * 35)} works out to three. In this example, 15 * 35 =
-525, and 525 is then converted to the string @code{"525"}, which has
+contrast, @code{length(15 * 35)} works out to three. In this example,
+@iftex
+@math{15 @cdot 35 = 525},
+@end iftex
+@ifnottex
+@ifnotdocbook
+15 * 35 = 525,
+@end ifnotdocbook
+@end ifnottex
+@docbook
+15 &sdot; 35 = 525, @c
+@end docbook
+and 525 is then converted to the string @code{"525"}, which has
three characters.
@cindex length of input record
@@ -16353,12 +16383,12 @@ If @option{--posix} is supplied, using an array argument is a fatal error
@cindex match regexp in string
Search @var{string} for the
longest, leftmost substring matched by the regular expression,
-@var{regexp} and return the character position, or @dfn{index},
+@var{regexp} and return the character position (index)
at which that substring begins (one, if it starts at the beginning of
@var{string}). If no match is found, return zero.
The @var{regexp} argument may be either a regexp constant
-(@code{/@dots{}/}) or a string constant (@code{"@dots{}"}).
+(@code{/}@dots{}@code{/}) or a string constant (@code{"}@dots{}@code{"}).
In the latter case, the string is treated as a regexp to be matched.
@xref{Computed Regexps}, for a
discussion of the difference between the two forms, and the
@@ -16464,7 +16494,7 @@ The @var{array} argument to @code{match()} is a
(@pxref{Options}),
using a third argument is a fatal error.
-@item @code{patsplit(@var{string}, @var{array}} [@code{, @var{fieldpat}} [@code{, @var{seps}} ] ]@code{)} #
+@item @code{patsplit(@var{string}, @var{array}} [@code{, @var{fieldpat}} [@code{, @var{seps}} ] ]@code{) #}
@cindexgawkfunc{patsplit}
@cindex split string into array
Divide
@@ -16490,12 +16520,6 @@ manner similar to the way input lines are split into fields using @code{FPAT}
Before splitting the string, @code{patsplit()} deletes any previously existing
elements in the arrays @var{array} and @var{seps}.
-@cindex troubleshooting, @code{patsplit()} function
-The @code{patsplit()} function is a
-@command{gawk} extension. In compatibility mode
-(@pxref{Options}),
-it is not available.
-
@item @code{split(@var{string}, @var{array}} [@code{, @var{fieldsep}} [@code{, @var{seps}} ] ]@code{)}
@cindexawkfunc{split}
Divide @var{string} into pieces separated by @var{fieldsep}
@@ -16581,6 +16605,8 @@ If @var{string} does not match @var{fieldsep} at all (but is not null),
@var{array} has one element only. The value of that element is the original
@var{string}.
+In POSIX mode (@pxref{Options}), the fourth argument is not allowed.
+
@item @code{sprintf(@var{format}, @var{expression1}, @dots{})}
@cindexawkfunc{sprintf}
@cindex formatting strings
@@ -16598,7 +16624,7 @@ assigns the string @w{@samp{pi = 3.14 (approx.)}} to the variable @code{pival}.
@cindexgawkfunc{strtonum}
@cindex convert string to number
-@item @code{strtonum(@var{str})} #
+@item @code{strtonum(@var{str}) #}
Examine @var{str} and return its numeric value. If @var{str}
begins with a leading @samp{0}, @code{strtonum()} assumes that @var{str}
is an octal number. If @var{str} begins with a leading @samp{0x} or
@@ -16620,9 +16646,6 @@ you use the @option{--non-decimal-data} option, which isn't recommended.
Note also that @code{strtonum()} uses the current locale's decimal point
for recognizing numbers (@pxref{Locales}).
-@code{strtonum()} is a @command{gawk} extension; it is not available
-in compatibility mode (@pxref{Options}).
-
@item @code{sub(@var{regexp}, @var{replacement}} [@code{, @var{target}}]@code{)}
@cindexawkfunc{sub}
@cindex replace in string
@@ -16634,7 +16657,7 @@ The modified string becomes the new value of @var{target}.
Return the number of substitutions made (zero or one).
The @var{regexp} argument may be either a regexp constant
-(@code{/@dots{}/}) or a string constant (@code{"@dots{}"}).
+(@code{/}@dots{}@code{/}) or a string constant (@code{"}@dots{}@code{"}).
In the latter case, the string is treated as a regexp to be matched.
@xref{Computed Regexps}, for a
discussion of the difference between the two forms, and the
@@ -16818,7 +16841,7 @@ that there are several levels of @dfn{escape processing} going on.
First, there is the @dfn{lexical} level, which is when @command{awk} reads
your program
-and builds an internal copy of it that can be executed.
+and builds an internal copy of it to execute.
Then there is the runtime level, which is when @command{awk} actually scans the
replacement string to determine what to generate.
@@ -17245,6 +17268,9 @@ not matter.
@xref{Two-way I/O},
which discusses this feature in more detail and gives an example.
+Note that the second argument to @code{close()} is a @command{gawk}
+extension; it is not available in compatibility mode (@pxref{Options}).
+
@item @code{fflush(}[@var{filename}]@code{)}
@cindexawkfunc{fflush}
@cindex flush buffered output
@@ -17267,7 +17293,7 @@ buffers its output and the @code{fflush()} function forces
@cindex extensions, common@comma{} @code{fflush()} function
@cindex Brian Kernighan's @command{awk}
-@code{fflush()} was added to Brian Kernighan's version of @command{awk} in
+@code{fflush()} was added to Brian Kernighan's @command{awk} in
April of 1992. For two decades, it was not part of the POSIX standard.
As of December, 2012, it was accepted for inclusion into the POSIX
standard.
@@ -17295,7 +17321,7 @@ only the standard output.
@c @cindex warnings, automatic
@cindex troubleshooting, @code{fflush()} function
@code{fflush()} returns zero if the buffer is successfully flushed;
-otherwise, it returns non-zero (@command{gawk} returns @minus{}1).
+otherwise, it returns non-zero. (@command{gawk} returns @minus{}1.)
In the case where all buffers are flushed, the return value is zero
only if all buffers were flushed successfully. Otherwise, it is
@minus{}1, and @command{gawk} warns about the problem @var{filename}.
@@ -17630,8 +17656,9 @@ However, recent versions
of @command{mawk} (@pxref{Other Versions}) also support these functions.
Optional parameters are enclosed in square brackets ([ ]):
-@table @code
-@item mktime(@var{datespec})
+@c @asis for docbook
+@table @asis
+@item @code{mktime(@var{datespec})}
@cindexgawkfunc{mktime}
@cindex generate time values
Turn @var{datespec} into a timestamp in the same form
@@ -17661,7 +17688,7 @@ is out of range, @code{mktime()} returns @minus{}1.
@cindex @command{gawk}, @code{PROCINFO} array in
@cindex @code{PROCINFO} array
-@item @code{strftime(} [@var{format} [@code{,} @var{timestamp} [@code{,} @var{utc-flag} ]]]@code{)}
+@item @code{strftime(} [@var{format} [@code{,} @var{timestamp} [@code{,} @var{utc-flag}] ] ]@code{)}
@c STARTOFRANGE strf
@cindexgawkfunc{strftime}
@cindex format time string
@@ -17683,7 +17710,7 @@ output that is equivalent to that of the @command{date} utility.
You can assign a new value to @code{PROCINFO["strftime"]} to
change the default format; see below for the various format directives.
-@item systime()
+@item @code{systime()}
@cindexgawkfunc{systime}
@cindex timestamps
@cindex current system time
@@ -17758,10 +17785,10 @@ This is the ISO 8601 date format.
@item %g
The year modulo 100 of the ISO 8601 week number, as a decimal number (00--99).
-For example, January 1, 1993 is in week 53 of 1992. Thus, the year
-of its ISO 8601 week number is 1992, even though its year is 1993.
-Similarly, December 31, 1973 is in week 1 of 1974. Thus, the year
-of its ISO week number is 1974, even though its year is 1973.
+For example, January 1, 2012 is in week 53 of 2011. Thus, the year
+of its ISO 8601 week number is 2011, even though its year is 2012.
+Similarly, December 31, 2012 is in week 1 of 2013. Thus, the year
+of its ISO week number is 2013, even though its year is 2012.
@item %G
The full year of the ISO week number, as a decimal number.
@@ -17842,7 +17869,7 @@ The locale's ``appropriate'' time representation.
The year modulo 100 as a decimal number (00--99).
@item %Y
-The full year as a decimal number (e.g., 2011).
+The full year as a decimal number (e.g., 2015).
@c @cindex RFC 822
@c @cindex RFC 1036
@@ -17876,17 +17903,6 @@ uses the system's version of @code{strftime()} if it's there.
Typically, the conversion specifier either does not appear in the
returned string or appears literally.}
-@c @cindex locale, definition of
-Informally, a @dfn{locale} is the geographic place in which a program
-is meant to run. For example, a common way to abbreviate the date
-September 4, 2012 in the United States is ``9/4/12.''
-In many countries in Europe, however, it is abbreviated ``4.9.12.''
-Thus, the @samp{%x} specification in a @code{"US"} locale might produce
-@samp{9/4/12}, while in a @code{"EUROPE"} locale, it might produce
-@samp{4.9.12}. The ISO C standard defines a default @code{"C"}
-locale, which is an environment that is typical of what many C programmers
-are used to.
-
For systems that are not yet fully standards-compliant,
@command{gawk} supplies a copy of
@code{strftime()} from the GNU C Library.
@@ -17939,7 +17955,7 @@ the string. For example:
@example
$ date '+Today is %A, %B %d, %Y.'
-@print{} Today is Wednesday, March 30, 2011.
+@print{} Today is Monday, May 05, 2014.
@end example
Here is the @command{gawk} version of the @command{date} utility.
@@ -17959,7 +17975,7 @@ case $1 in
esac
gawk 'BEGIN @{
- format = "%a %b %e %H:%M:%S %Z %Y"
+ format = PROCINFO["strftime"]
exitval = 0
if (ARGC > 2)
@@ -18047,7 +18063,6 @@ Operands | 0 | 1 | 0 | 1 | 0 | 1
@end tex
@docbook
-<!-- FIXME: Fix ID and add xref in text. -->
<table id="table-bitwise-ops">
<title>Bitwise Operations</title>
@@ -18293,7 +18308,7 @@ results of the @code{compl()}, @code{lshift()}, and @code{rshift()} functions.
@command{gawk} provides a single function that lets you distinguish
an array from a scalar variable. This is necessary for writing code
-that traverses every element of a true multidimensional array
+that traverses every element of an array of arrays.
(@pxref{Arrays of Arrays}).
@table @code
@@ -18331,10 +18346,10 @@ The descriptions here are purposely brief.
for the full story.
Optional parameters are enclosed in square brackets ([ ]):
-@table @code
+@table @asis
@cindexgawkfunc{bindtextdomain}
@cindex set directory of message catalogs
-@item @code{bindtextdomain(@var{directory}} [@code{,} @var{domain} ]@code{)}
+@item @code{bindtextdomain(@var{directory}} [@code{,} @var{domain}]@code{)}
Set the directory in which
@command{gawk} will look for message translation files, in case they
will not or cannot be placed in the ``standard'' locations
@@ -18348,14 +18363,14 @@ given @var{domain}.
@cindexgawkfunc{dcgettext}
@cindex translate string
-@item @code{dcgettext(@var{string}} [@code{,} @var{domain} [@code{,} @var{category} ]]@code{)}
+@item @code{dcgettext(@var{string}} [@code{,} @var{domain} [@code{,} @var{category}] ]@code{)}
Return the translation of @var{string} in
text domain @var{domain} for locale category @var{category}.
The default value for @var{domain} is the current value of @code{TEXTDOMAIN}.
The default value for @var{category} is @code{"LC_MESSAGES"}.
@cindexgawkfunc{dcngettext}
-@item @code{dcngettext(@var{string1}, @var{string2}, @var{number}} [@code{,} @var{domain} [@code{,} @var{category} ]]@code{)}
+@item @code{dcngettext(@var{string1}, @var{string2}, @var{number}} [@code{,} @var{domain} [@code{,} @var{category}] ]@code{)}
Return the plural form used for @var{number} of the
translation of @var{string1} and @var{string2} in text domain
@var{domain} for locale category @var{category}. @var{string1} is the
@@ -18427,10 +18442,10 @@ the call. The local variables are initialized to the empty string.
A function cannot have two parameters with the same name, nor may it
have a parameter with the same name as the function itself.
-In addition, according to the POSIX standard, function parameters cannot have the same
-name as one of the special built-in variables
-(@pxref{Built-in Variables}. Not all versions of @command{awk}
-enforce this restriction.)
+In addition, according to the POSIX standard, function parameters
+cannot have the same name as one of the special built-in variables
+(@pxref{Built-in Variables}). Not all versions of @command{awk} enforce
+this restriction.)
The @var{body-of-function} consists of @command{awk} statements. It is the
most important part of the definition, because it says what the function
@@ -18615,7 +18630,7 @@ to create an @command{awk} version of @code{ctime()}:
function ctime(ts, format)
@{
- format = "%a %b %e %H:%M:%S %Z %Y"
+ format = PROCINFO["strftime"]
if (ts == 0)
ts = systime() # use current time as default
return strftime(format, ts)
@@ -18667,7 +18682,8 @@ an error.
@cindex local variables, in a function
@cindex variables, local to a function
-There is no way to make a variable local to a @code{@{ @dots{} @}} block in
+Unlike many languages,
+there is no way to make a variable local to a @code{@{} @dots{} @code{@}} block in
@command{awk}, but you can make a variable local to a function. It is
good practice to do so whenever a variable is needed only in that
function.
@@ -18936,7 +18952,7 @@ return @r{[}@var{expression}@r{]}
The @var{expression} part is optional.
Due most likely to an oversight, POSIX does not define what the return
value is if you omit the @var{expression}. Technically speaking, this
-make the returned value undefined, and therefore, unpredictable.
+makes the returned value undefined, and therefore, unpredictable.
In practice, though, all versions of @command{awk} simply return the
null string, which acts like zero if used in a numeric context.
@@ -19039,9 +19055,9 @@ BEGIN @{
@end example
In this example, the first call to @code{foo()} generates
-a fatal error, so @command{gawk} will not report the second
-error. If you comment out that call, though, then @command{gawk}
-will report the second error.
+a fatal error, so @command{awk} will not report the second
+error. If you comment out that call, though, then @command{awk}
+does report the second error.
Usually, such things aren't a big issue, but it's worth
being aware of them.
@@ -37070,6 +37086,7 @@ Wikipedia article}, for information on additional versions.
@c ENDOFRANGE ingawk
@c ENDOFRANGE awkim
+@ifclear FOR_PRINT
@node Notes
@appendix Implementation Notes
@c STARTOFRANGE gawii
@@ -40249,6 +40266,7 @@ to permit their use in free software.
@c Local Variables:
@c ispell-local-pdict: "ispell-dict"
@c End:
+@end ifclear
@ifnotdocbook
@node Index
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index 06206642..ee781f12 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -11574,27 +11574,35 @@ For maximum portability, do not use them.
@section Where You Are Makes A Difference
@cindex locale, definition of
-Modern systems support the notion of @dfn{locales}: a way to tell
-the system about the local character set and language.
+Modern systems support the notion of @dfn{locales}: a way to tell the
+system about the local character set and language. The ISO C standard
+defines a default @code{"C"} locale, which is an environment that is
+typical of what many C programmers are used to.
Once upon a time, the locale setting used to affect regexp matching
(@pxref{Ranges and Locales}), but this is no longer true.
-Locales can affect record splitting.
-For the normal case of @samp{RS = "\n"}, the locale is largely irrelevant.
-For other single-character record separators, setting @samp{LC_ALL=C}
-in the environment
-will give you much better performance when reading records. Otherwise,
+Locales can affect record splitting. For the normal case of @samp{RS =
+"\n"}, the locale is largely irrelevant. For other single-character
+record separators, setting @samp{LC_ALL=C} in the environment will
+give you much better performance when reading records. Otherwise,
@command{gawk} has to make several function calls, @emph{per input
character}, to find the record terminator.
-According to POSIX, string comparison is also affected by locales
-(similar to regular expressions). The details are presented in
-@ref{POSIX String Comparison}.
+Locales can affect how dates and times are formatted (@pxref{Time
+Functions}). For example, a common way to abbreviate the date September
+4, 2015 in the United States is ``9/4/15.'' In many countries in
+Europe, however, it is abbreviated ``4.9.15.'' Thus, the @samp{%x}
+specification in a @code{"US"} locale might produce @samp{9/4/15},
+while in a @code{"EUROPE"} locale, it might produce @samp{4.9.15}.
+
+According to POSIX, string comparison is also affected by locales (similar
+to regular expressions). The details are presented in @ref{POSIX String
+Comparison}.
Finally, the locale affects the value of the decimal point character
-used when @command{gawk} parses input data. This is discussed in
-detail in @ref{Conversion}.
+used when @command{gawk} parses input data. This is discussed in detail
+in @ref{Conversion}.
@c ENDOFRANGE exps
@@ -15284,7 +15292,14 @@ Optional parameters are enclosed in square brackets@w{ ([ ]):}
@cindexawkfunc{atan2}
@cindex arctangent
Return the arctangent of @code{@var{y} / @var{x}} in radians.
-You can use @samp{pi = atan2(0, -1)} to retrieve the value of @value{PI}.
+You can use @samp{pi = atan2(0, -1)} to retrieve the value of
+@ifnotdocbook
+@value{PI}.
+@end ifnotdocbook
+@docbook
+&pgr;.
+
+@end docbook
@item @code{cos(@var{x})}
@cindexawkfunc{cos}
@@ -15427,12 +15442,23 @@ example, @code{length()} returns the number of characters in a string,
and not the number of bytes used to represent those characters. Similarly,
@code{index()} works with character indices, and not byte indices.
+@quotation CAUTION
+A number of functions deal with indices into strings. For these
+functions, the first character of a string is at position (index) one.
+This is different from C and the languages descended from it, where the
+first character is at position zero. You need to remember this when
+doing index calculations, particularly if you are used to C.
+@end quotation
+
In the following list, optional parameters are enclosed in square brackets@w{ ([ ]).}
Several functions perform string substitution; the full discussion is
provided in the description of the @code{sub()} function, which comes
towards the end since the list is presented in alphabetic order.
+
Those functions that are specific to @command{gawk} are marked with a
-pound sign@w{ (@samp{#}):}
+pound sign (@samp{#}). They are not available in compatibility mode
+(@pxref{Options}):
+
@menu
* Gory Details:: More than you want to know about @samp{\} and
@@ -15442,8 +15468,8 @@ pound sign@w{ (@samp{#}):}
@c @asis for docbook
@table @asis
-@item @code{asort(}@var{source} [@code{,} @var{dest} [@code{,} @var{how} ] ]@code{)} #
-@itemx @code{asorti(}@var{source} [@code{,} @var{dest} [@code{,} @var{how} ] ]@code{)} #
+@item @code{asort(}@var{source} [@code{,} @var{dest} [@code{,} @var{how} ] ]@code{) #}
+@itemx @code{asorti(}@var{source} [@code{,} @var{dest} [@code{,} @var{how} ] ]@code{) #}
@cindexgawkfunc{asorti}
@cindex sort array
@cindex arrays, elements, retrieving number of
@@ -15507,10 +15533,7 @@ a[2] = "last"
a[3] = "middle"
@end example
-@code{asort()} and @code{asorti()} are @command{gawk} extensions; they
-are not available in compatibility mode (@pxref{Options}).
-
-@item @code{gensub(@var{regexp}, @var{replacement}, @var{how}} [@code{, @var{target}}]@code{)} #
+@item @code{gensub(@var{regexp}, @var{replacement}, @var{how}} [@code{, @var{target}}]@code{) #}
@cindexgawkfunc{gensub}
@cindex search and replace in strings
@cindex substitute in string
@@ -15572,9 +15595,6 @@ a warning message.
If @var{regexp} does not match @var{target}, @code{gensub()}'s return value
is the original unchanged value of @var{target}.
-@code{gensub()} is a @command{gawk} extension; it is not available
-in compatibility mode (@pxref{Options}).
-
@item @code{gsub(@var{regexp}, @var{replacement}} [@code{, @var{target}}]@code{)}
@cindexawkfunc{gsub}
Search @var{target} for
@@ -15612,7 +15632,6 @@ $ @kbd{awk 'BEGIN @{ print index("peanut", "an") @}'}
@noindent
If @var{find} is not found, @code{index()} returns zero.
-(Remember that string indices in @command{awk} start at one.)
It is a fatal error to use a regexp constant for @var{find}.
@@ -15623,8 +15642,19 @@ It is a fatal error to use a regexp constant for @var{find}.
Return the number of characters in @var{string}. If
@var{string} is a number, the length of the digit string representing
that number is returned. For example, @code{length("abcde")} is five. By
-contrast, @code{length(15 * 35)} works out to three. In this example, 15 * 35 =
-525, and 525 is then converted to the string @code{"525"}, which has
+contrast, @code{length(15 * 35)} works out to three. In this example,
+@iftex
+@math{15 @cdot 35 = 525},
+@end iftex
+@ifnottex
+@ifnotdocbook
+15 * 35 = 525,
+@end ifnotdocbook
+@end ifnottex
+@docbook
+15 &sdot; 35 = 525, @c
+@end docbook
+and 525 is then converted to the string @code{"525"}, which has
three characters.
@cindex length of input record
@@ -15687,12 +15717,12 @@ If @option{--posix} is supplied, using an array argument is a fatal error
@cindex match regexp in string
Search @var{string} for the
longest, leftmost substring matched by the regular expression,
-@var{regexp} and return the character position, or @dfn{index},
+@var{regexp} and return the character position (index)
at which that substring begins (one, if it starts at the beginning of
@var{string}). If no match is found, return zero.
The @var{regexp} argument may be either a regexp constant
-(@code{/@dots{}/}) or a string constant (@code{"@dots{}"}).
+(@code{/}@dots{}@code{/}) or a string constant (@code{"}@dots{}@code{"}).
In the latter case, the string is treated as a regexp to be matched.
@xref{Computed Regexps}, for a
discussion of the difference between the two forms, and the
@@ -15798,7 +15828,7 @@ The @var{array} argument to @code{match()} is a
(@pxref{Options}),
using a third argument is a fatal error.
-@item @code{patsplit(@var{string}, @var{array}} [@code{, @var{fieldpat}} [@code{, @var{seps}} ] ]@code{)} #
+@item @code{patsplit(@var{string}, @var{array}} [@code{, @var{fieldpat}} [@code{, @var{seps}} ] ]@code{) #}
@cindexgawkfunc{patsplit}
@cindex split string into array
Divide
@@ -15824,12 +15854,6 @@ manner similar to the way input lines are split into fields using @code{FPAT}
Before splitting the string, @code{patsplit()} deletes any previously existing
elements in the arrays @var{array} and @var{seps}.
-@cindex troubleshooting, @code{patsplit()} function
-The @code{patsplit()} function is a
-@command{gawk} extension. In compatibility mode
-(@pxref{Options}),
-it is not available.
-
@item @code{split(@var{string}, @var{array}} [@code{, @var{fieldsep}} [@code{, @var{seps}} ] ]@code{)}
@cindexawkfunc{split}
Divide @var{string} into pieces separated by @var{fieldsep}
@@ -15915,6 +15939,8 @@ If @var{string} does not match @var{fieldsep} at all (but is not null),
@var{array} has one element only. The value of that element is the original
@var{string}.
+In POSIX mode (@pxref{Options}), the fourth argument is not allowed.
+
@item @code{sprintf(@var{format}, @var{expression1}, @dots{})}
@cindexawkfunc{sprintf}
@cindex formatting strings
@@ -15932,7 +15958,7 @@ assigns the string @w{@samp{pi = 3.14 (approx.)}} to the variable @code{pival}.
@cindexgawkfunc{strtonum}
@cindex convert string to number
-@item @code{strtonum(@var{str})} #
+@item @code{strtonum(@var{str}) #}
Examine @var{str} and return its numeric value. If @var{str}
begins with a leading @samp{0}, @code{strtonum()} assumes that @var{str}
is an octal number. If @var{str} begins with a leading @samp{0x} or
@@ -15954,9 +15980,6 @@ you use the @option{--non-decimal-data} option, which isn't recommended.
Note also that @code{strtonum()} uses the current locale's decimal point
for recognizing numbers (@pxref{Locales}).
-@code{strtonum()} is a @command{gawk} extension; it is not available
-in compatibility mode (@pxref{Options}).
-
@item @code{sub(@var{regexp}, @var{replacement}} [@code{, @var{target}}]@code{)}
@cindexawkfunc{sub}
@cindex replace in string
@@ -15968,7 +15991,7 @@ The modified string becomes the new value of @var{target}.
Return the number of substitutions made (zero or one).
The @var{regexp} argument may be either a regexp constant
-(@code{/@dots{}/}) or a string constant (@code{"@dots{}"}).
+(@code{/}@dots{}@code{/}) or a string constant (@code{"}@dots{}@code{"}).
In the latter case, the string is treated as a regexp to be matched.
@xref{Computed Regexps}, for a
discussion of the difference between the two forms, and the
@@ -16152,7 +16175,7 @@ that there are several levels of @dfn{escape processing} going on.
First, there is the @dfn{lexical} level, which is when @command{awk} reads
your program
-and builds an internal copy of it that can be executed.
+and builds an internal copy of it to execute.
Then there is the runtime level, which is when @command{awk} actually scans the
replacement string to determine what to generate.
@@ -16546,6 +16569,9 @@ not matter.
@xref{Two-way I/O},
which discusses this feature in more detail and gives an example.
+Note that the second argument to @code{close()} is a @command{gawk}
+extension; it is not available in compatibility mode (@pxref{Options}).
+
@item @code{fflush(}[@var{filename}]@code{)}
@cindexawkfunc{fflush}
@cindex flush buffered output
@@ -16568,7 +16594,7 @@ buffers its output and the @code{fflush()} function forces
@cindex extensions, common@comma{} @code{fflush()} function
@cindex Brian Kernighan's @command{awk}
-@code{fflush()} was added to Brian Kernighan's version of @command{awk} in
+@code{fflush()} was added to Brian Kernighan's @command{awk} in
April of 1992. For two decades, it was not part of the POSIX standard.
As of December, 2012, it was accepted for inclusion into the POSIX
standard.
@@ -16596,7 +16622,7 @@ only the standard output.
@c @cindex warnings, automatic
@cindex troubleshooting, @code{fflush()} function
@code{fflush()} returns zero if the buffer is successfully flushed;
-otherwise, it returns non-zero (@command{gawk} returns @minus{}1).
+otherwise, it returns non-zero. (@command{gawk} returns @minus{}1.)
In the case where all buffers are flushed, the return value is zero
only if all buffers were flushed successfully. Otherwise, it is
@minus{}1, and @command{gawk} warns about the problem @var{filename}.
@@ -16803,8 +16829,9 @@ However, recent versions
of @command{mawk} (@pxref{Other Versions}) also support these functions.
Optional parameters are enclosed in square brackets ([ ]):
-@table @code
-@item mktime(@var{datespec})
+@c @asis for docbook
+@table @asis
+@item @code{mktime(@var{datespec})}
@cindexgawkfunc{mktime}
@cindex generate time values
Turn @var{datespec} into a timestamp in the same form
@@ -16834,7 +16861,7 @@ is out of range, @code{mktime()} returns @minus{}1.
@cindex @command{gawk}, @code{PROCINFO} array in
@cindex @code{PROCINFO} array
-@item @code{strftime(} [@var{format} [@code{,} @var{timestamp} [@code{,} @var{utc-flag} ]]]@code{)}
+@item @code{strftime(} [@var{format} [@code{,} @var{timestamp} [@code{,} @var{utc-flag}] ] ]@code{)}
@c STARTOFRANGE strf
@cindexgawkfunc{strftime}
@cindex format time string
@@ -16856,7 +16883,7 @@ output that is equivalent to that of the @command{date} utility.
You can assign a new value to @code{PROCINFO["strftime"]} to
change the default format; see below for the various format directives.
-@item systime()
+@item @code{systime()}
@cindexgawkfunc{systime}
@cindex timestamps
@cindex current system time
@@ -16931,10 +16958,10 @@ This is the ISO 8601 date format.
@item %g
The year modulo 100 of the ISO 8601 week number, as a decimal number (00--99).
-For example, January 1, 1993 is in week 53 of 1992. Thus, the year
-of its ISO 8601 week number is 1992, even though its year is 1993.
-Similarly, December 31, 1973 is in week 1 of 1974. Thus, the year
-of its ISO week number is 1974, even though its year is 1973.
+For example, January 1, 2012 is in week 53 of 2011. Thus, the year
+of its ISO 8601 week number is 2011, even though its year is 2012.
+Similarly, December 31, 2012 is in week 1 of 2013. Thus, the year
+of its ISO week number is 2013, even though its year is 2012.
@item %G
The full year of the ISO week number, as a decimal number.
@@ -17015,7 +17042,7 @@ The locale's ``appropriate'' time representation.
The year modulo 100 as a decimal number (00--99).
@item %Y
-The full year as a decimal number (e.g., 2011).
+The full year as a decimal number (e.g., 2015).
@c @cindex RFC 822
@c @cindex RFC 1036
@@ -17049,17 +17076,6 @@ uses the system's version of @code{strftime()} if it's there.
Typically, the conversion specifier either does not appear in the
returned string or appears literally.}
-@c @cindex locale, definition of
-Informally, a @dfn{locale} is the geographic place in which a program
-is meant to run. For example, a common way to abbreviate the date
-September 4, 2012 in the United States is ``9/4/12.''
-In many countries in Europe, however, it is abbreviated ``4.9.12.''
-Thus, the @samp{%x} specification in a @code{"US"} locale might produce
-@samp{9/4/12}, while in a @code{"EUROPE"} locale, it might produce
-@samp{4.9.12}. The ISO C standard defines a default @code{"C"}
-locale, which is an environment that is typical of what many C programmers
-are used to.
-
For systems that are not yet fully standards-compliant,
@command{gawk} supplies a copy of
@code{strftime()} from the GNU C Library.
@@ -17112,7 +17128,7 @@ the string. For example:
@example
$ date '+Today is %A, %B %d, %Y.'
-@print{} Today is Wednesday, March 30, 2011.
+@print{} Today is Monday, May 05, 2014.
@end example
Here is the @command{gawk} version of the @command{date} utility.
@@ -17132,7 +17148,7 @@ case $1 in
esac
gawk 'BEGIN @{
- format = "%a %b %e %H:%M:%S %Z %Y"
+ format = PROCINFO["strftime"]
exitval = 0
if (ARGC > 2)
@@ -17220,7 +17236,6 @@ Operands | 0 | 1 | 0 | 1 | 0 | 1
@end tex
@docbook
-<!-- FIXME: Fix ID and add xref in text. -->
<table id="table-bitwise-ops">
<title>Bitwise Operations</title>
@@ -17466,7 +17481,7 @@ results of the @code{compl()}, @code{lshift()}, and @code{rshift()} functions.
@command{gawk} provides a single function that lets you distinguish
an array from a scalar variable. This is necessary for writing code
-that traverses every element of a true multidimensional array
+that traverses every element of an array of arrays.
(@pxref{Arrays of Arrays}).
@table @code
@@ -17504,10 +17519,10 @@ The descriptions here are purposely brief.
for the full story.
Optional parameters are enclosed in square brackets ([ ]):
-@table @code
+@table @asis
@cindexgawkfunc{bindtextdomain}
@cindex set directory of message catalogs
-@item @code{bindtextdomain(@var{directory}} [@code{,} @var{domain} ]@code{)}
+@item @code{bindtextdomain(@var{directory}} [@code{,} @var{domain}]@code{)}
Set the directory in which
@command{gawk} will look for message translation files, in case they
will not or cannot be placed in the ``standard'' locations
@@ -17521,14 +17536,14 @@ given @var{domain}.
@cindexgawkfunc{dcgettext}
@cindex translate string
-@item @code{dcgettext(@var{string}} [@code{,} @var{domain} [@code{,} @var{category} ]]@code{)}
+@item @code{dcgettext(@var{string}} [@code{,} @var{domain} [@code{,} @var{category}] ]@code{)}
Return the translation of @var{string} in
text domain @var{domain} for locale category @var{category}.
The default value for @var{domain} is the current value of @code{TEXTDOMAIN}.
The default value for @var{category} is @code{"LC_MESSAGES"}.
@cindexgawkfunc{dcngettext}
-@item @code{dcngettext(@var{string1}, @var{string2}, @var{number}} [@code{,} @var{domain} [@code{,} @var{category} ]]@code{)}
+@item @code{dcngettext(@var{string1}, @var{string2}, @var{number}} [@code{,} @var{domain} [@code{,} @var{category}] ]@code{)}
Return the plural form used for @var{number} of the
translation of @var{string1} and @var{string2} in text domain
@var{domain} for locale category @var{category}. @var{string1} is the
@@ -17600,10 +17615,10 @@ the call. The local variables are initialized to the empty string.
A function cannot have two parameters with the same name, nor may it
have a parameter with the same name as the function itself.
-In addition, according to the POSIX standard, function parameters cannot have the same
-name as one of the special built-in variables
-(@pxref{Built-in Variables}. Not all versions of @command{awk}
-enforce this restriction.)
+In addition, according to the POSIX standard, function parameters
+cannot have the same name as one of the special built-in variables
+(@pxref{Built-in Variables}). Not all versions of @command{awk} enforce
+this restriction.)
The @var{body-of-function} consists of @command{awk} statements. It is the
most important part of the definition, because it says what the function
@@ -17788,7 +17803,7 @@ to create an @command{awk} version of @code{ctime()}:
function ctime(ts, format)
@{
- format = "%a %b %e %H:%M:%S %Z %Y"
+ format = PROCINFO["strftime"]
if (ts == 0)
ts = systime() # use current time as default
return strftime(format, ts)
@@ -17840,7 +17855,8 @@ an error.
@cindex local variables, in a function
@cindex variables, local to a function
-There is no way to make a variable local to a @code{@{ @dots{} @}} block in
+Unlike many languages,
+there is no way to make a variable local to a @code{@{} @dots{} @code{@}} block in
@command{awk}, but you can make a variable local to a function. It is
good practice to do so whenever a variable is needed only in that
function.
@@ -18109,7 +18125,7 @@ return @r{[}@var{expression}@r{]}
The @var{expression} part is optional.
Due most likely to an oversight, POSIX does not define what the return
value is if you omit the @var{expression}. Technically speaking, this
-make the returned value undefined, and therefore, unpredictable.
+makes the returned value undefined, and therefore, unpredictable.
In practice, though, all versions of @command{awk} simply return the
null string, which acts like zero if used in a numeric context.
@@ -18212,9 +18228,9 @@ BEGIN @{
@end example
In this example, the first call to @code{foo()} generates
-a fatal error, so @command{gawk} will not report the second
-error. If you comment out that call, though, then @command{gawk}
-will report the second error.
+a fatal error, so @command{awk} will not report the second
+error. If you comment out that call, though, then @command{awk}
+does report the second error.
Usually, such things aren't a big issue, but it's worth
being aware of them.
@@ -36214,6 +36230,7 @@ Wikipedia article}, for information on additional versions.
@c ENDOFRANGE ingawk
@c ENDOFRANGE awkim
+@ifclear FOR_PRINT
@node Notes
@appendix Implementation Notes
@c STARTOFRANGE gawii
@@ -39393,6 +39410,7 @@ to permit their use in free software.
@c Local Variables:
@c ispell-local-pdict: "ispell-dict"
@c End:
+@end ifclear
@ifnotdocbook
@node Index
generated by cgit v1.2.3 (git 2.25.1) at 2025-05-04 21:13:21 +0000