diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ChangeLog | 21 | ||||
| -rw-r--r-- | doc/awkcard.in | 8 | ||||
| -rw-r--r-- | doc/gawk.1 | 15 | ||||
| -rw-r--r-- | doc/gawk.info | 1200 | ||||
| -rw-r--r-- | doc/gawk.texi | 100 | ||||
| -rw-r--r-- | doc/gawktexi.in | 100 |
6 files changed, 869 insertions, 575 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index 0a04a64b..82ae2ce3 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,14 @@ +2017-04-11 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Minor style edits. + +2017-04-10 Andrew J. Schorr <aschorr@telemetry-investments.com> + + * gawktexi.in: Document FIELDWIDTHS enhancement to support an optional + field skip prefix. Document new PROCINFO["FS"] value "API". + Document new get_record field_width argument that enables the API + parser to override the default field parsing mechanism. + 2017-04-07 Arnold D. Robbins <arnold@skeeve.com> * using-git.texi: Removed. @@ -9,6 +20,16 @@ * wordlist2: Updated. * Makefile.am: Fix spell checking. :-( +2017-03-22 Andrew J. Schorr <aschorr@telemetry-investments.com> + + * gawk.1: Document new PROCINFO["FS"] value "API". + +2017-03-22 Andrew J. Schorr <aschorr@telemetry-investments.com> + + * awkcard.in: Document FIELDWIDTHS enhancement to support an optional + field skip prefix. + * gawk.1: Ditto. + 2017-03-17 Arnold D. Robbins <arnold@skeeve.com> * gawktexi.in: Improve the discussion of quoting on diff --git a/doc/awkcard.in b/doc/awkcard.in index 418cc8d9..86aeee2e 100644 --- a/doc/awkcard.in +++ b/doc/awkcard.in @@ -556,8 +556,10 @@ fails, or if \*(FCclose()\*(FR fails. T} \*(FCFIELDWIDTHS\fP T{ -Whitespace separated list of field widths. Used -to parse the input into fields of fixed width, +Whitespace-separated list of field widths. +Each field width may optionally be preceded by a colon-separated +value specifying the number of characters to skip before the field starts. +Used to parse the input into fields of fixed width, instead of the value of \*(FCFS\fP.\*(CD T} \*(FCFILENAME\fP T{ @@ -1017,6 +1019,8 @@ also affects how fields are split when variable is set to a space-separated list of numbers, each field is expected to have a fixed width, and \*(GK splits up the record using the specified widths. +Each field width may optionally be preceded by a colon-separated +value specifying the number of characters to skip before the field starts. The value of \*(FCFS\fP is ignored. Assigning a new value to \*(FCFS\fP or \*(FCFPAT\fP overrides the use of \*(FCFIELDWIDTHS\*(FR. @@ -805,10 +805,13 @@ is a regular expression. .PP If the .B FIELDWIDTHS -variable is set to a space separated list of numbers, each field is +variable is set to a space-separated list of numbers, each field is expected to have fixed width, and .I gawk -splits up the record using the specified widths. The value of +splits up the record using the specified widths. +Each field width may optionally be preceded by a colon-separated +value specifying the number of characters to skip before the field starts. +The value of .B FS is ignored. Assigning a new value to @@ -959,12 +962,14 @@ For non-system errors, will be zero. .TP .B FIELDWIDTHS -A whitespace separated list of field widths. When set, +A whitespace-separated list of field widths. When set, .I gawk parses the input into fields of fixed width, instead of using the value of the .B FS variable as the field separator. +Each field width may optionally be preceded by a colon-separated +value specifying the number of characters to skip before the field starts. See .BR Fields , above. @@ -1133,8 +1138,10 @@ is in effect, \fB"FPAT"\fP if field splitting with .B FPAT is in effect, -or \fB"FIELDWIDTHS"\fP if field splitting with +\fB"FIELDWIDTHS"\fP if field splitting with .B FIELDWIDTHS +is in effect, +or \fB"API"\fP if API input parser field splitting is in effect. .TP \fBPROCINFO["gid"]\fP diff --git a/doc/gawk.info b/doc/gawk.info index 197dc2f7..42c3c197 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -5127,9 +5127,12 @@ by assigning a string containing space-separated numbers to the built-in variable 'FIELDWIDTHS'. Each number specifies the width of the field, _including_ columns between fields. If you want to ignore the columns between fields, you can specify the width as a separate field that is -subsequently ignored. It is a fatal error to supply a field width that -has a negative value. The following data is the output of the Unix 'w' -utility. It is useful to illustrate the use of 'FIELDWIDTHS': +subsequently ignored. Or, starting in version 4.2, each field width may +optionally be preceded by a colon-separated value specifying the number +of characters to skip before the field starts. It is a fatal error to +supply a field width that has a negative value. The following data is +the output of the Unix 'w' utility. It is useful to illustrate the use +of 'FIELDWIDTHS': 10:06pm up 21 days, 14:04, 23 users User tty login idle JCPU PCPU what @@ -5176,6 +5179,20 @@ calculated idle time: brent ttyp0 286 dave ttyq4 1296000 + Starting in version 4.2, this program could be rewritten to specify +'FIELDWIDTHS' like so: + BEGIN { FIELDWIDTHS = "8 1:5 4:7 6 1:6 1:6 2:33" } + This strips away some of the white space separating the fields. With +such a change, the program would produce the following results: + + hzang ttyV3 50 + eklye ttyV5 0 + dportein ttyV6 107 + gierd ttyD3 1 + dave ttyD4 0 + brent ttyp0 286 + dave ttyq4 1296000 + Another (possibly more practical) example of fixed-width input data is the input from a deck of balloting cards. In some parts of the United States, voters mark their choices by punching holes in computer @@ -5197,8 +5214,10 @@ value is '"FS"' if regular field splitting is being used, or REGULAR FIELD SPLITTING ... else if (PROCINFO["FS"] == "FIELDWIDTHS") FIXED-WIDTH FIELD SPLITTING ... - else + else if (PROCINFO["FS"] == "FPAT") CONTENT-BASED FIELD SPLITTING ... (see next minor node) + else + API INPUT PARSER FIELD SPLITTING ... (advanced feature) This information is useful when writing a function that needs to temporarily change 'FS' or 'FIELDWIDTHS', read some records, and then @@ -5304,7 +5323,10 @@ available for splitting regular strings (*note String Functions::). To recap, 'gawk' provides three independent methods to split input records into fields. The mechanism used is based on which of the three -variables--'FS', 'FIELDWIDTHS', or 'FPAT'--was last assigned to. +variables--'FS', 'FIELDWIDTHS', or 'FPAT'--was last assigned to. In +addition, an API input parser may choose to override the record parsing +mechanism; please refer to *note Input Parsers:: for further information +about this feature. ---------- Footnotes ---------- @@ -10441,9 +10463,12 @@ each variable.) 'FIELDWIDTHS #' A space-separated list of columns that tells 'gawk' how to split - input with fixed columnar boundaries. Assigning a value to - 'FIELDWIDTHS' overrides the use of 'FS' and 'FPAT' for field - splitting. *Note Constant Size:: for more information. + input with fixed columnar boundaries. Starting in version 4.2, + each field width may optionally be preceded by a colon-separated + value specifying the number of characters to skip before the field + starts. Assigning a value to 'FIELDWIDTHS' overrides the use of + 'FS' and 'FPAT' for field splitting. *Note Constant Size:: for + more information. 'FPAT #' A regular expression (as a string) that tells 'gawk' to create the @@ -10727,8 +10752,9 @@ they are not special: 'PROCINFO["FS"]' This is '"FS"' if field splitting with 'FS' is in effect, '"FIELDWIDTHS"' if field splitting with 'FIELDWIDTHS' is in - effect, or '"FPAT"' if field matching with 'FPAT' is in - effect. + effect, '"FPAT"' if field matching with 'FPAT' is in effect, + or '"API"' if field splitting is controlled by an API input + parser. 'PROCINFO["gid"]' The value of the 'getgid()' system call. @@ -24167,7 +24193,8 @@ for 'RT', if any. #define INVALID_HANDLE (-1) void *opaque; /* private data for input parsers */ int (*get_record)(char **out, struct awk_input *iobuf, - int *errcode, char **rt_start, size_t *rt_len); + int *errcode, char **rt_start, size_t *rt_len, + const awk_fieldwidth_info_t **field_width); ssize_t (*read_func)(); void (*close_func)(struct awk_input *iobuf); struct stat sbuf; /* stat buf */ @@ -24213,7 +24240,8 @@ may be filled by 'XXX_take_control_of()': ' struct awk_input *iobuf,' ' int *errcode,' ' char **rt_start,' -' size_t *rt_len);' +' size_t *rt_len,' +' const awk_fieldwidth_info_t **field_width);' This function pointer should point to a function that creates the input records. Said function is the core of the input parser. Its behavior is described in the text following this list. @@ -24263,6 +24291,20 @@ records. The parameters are as follows: '*rt_len' should be set to zero. 'gawk' makes its own copy of this data, so the extension must manage this storage. +'const awk_fieldwidth_info_t **field_width' + If 'field_width' is not 'NULL', then '*field_width' will be + initialized to 'NULL', and the function may set it to point to a + structure supplying field width information to override the default + field parsing mechanism. Note that this structure will not be + copied by 'gawk'; it must persist at least until the next call to + 'get_record' or 'close_func'. Note also that 'field_width' is + 'NULL' when 'getline' is assigning the results to a variable, thus + field parsing is not needed. If the parser does set + '*field_width', then 'gawk' uses this layout to parse the input + record, and the 'PROCINFO["FS"]' value will be '"API"' while this + record is active in '$0'. The 'awk_fieldwidth_info_t' data + structure is described below. + The return value is the length of the buffer pointed to by '*out', or 'EOF' if end-of-file was reached or an error occurred. @@ -24312,6 +24354,46 @@ activate an input parser (*note BEGINFILE/ENDFILE::). 'void register_input_parser(awk_input_parser_t *input_parser);' Register the input parser pointed to by 'input_parser' with 'gawk'. + If you would like to override the default field parsing mechanism for +a given record, then you must populate an 'awk_fieldwidth_info_t' +structure, which looks like this: + + typedef struct { + awk_bool_t use_chars; /* false ==> use bytes */ + size_t nf; /* number of fields in record (NF) */ + struct awk_field_info { + size_t skip; /* amount to skip before field starts */ + size_t len; /* length of field */ + } fields[1]; /* actual dimension should be nf */ + } awk_fieldwidth_info_t; + + The fields are: + +'awk_bool_t use_chars;' + Set this to 'awk_true' if the field lengths are specified in terms + of potentially multi-byte characters, and set it to 'awk_false' if + the lengths are in terms of bytes. Performance will be better if + the values are supplied in terms of bytes. + +'size_t nf;' + Set this to the number of fields in the input record, i.e. 'NF'. + +'struct awk_field_info fields[nf];' + This is a variable-length array whose actual dimension should be + 'nf'. For each field, the 'skip' element should be set to the + number of characters or bytes, as controlled by the 'use_chars' + flag, to skip before the start of this field. The 'len' element + provides the length of the field. The values in 'fields[0]' + provide the information for '$1', and so on through the + 'fields[nf-1]' element containing the information for '$NF'. + + A convenience macro 'awk_fieldwidth_info_size(NF)' is provided to +calculate the appropriate size of a variable-length +'awk_fieldwidth_info_t' structure containing 'NF' fields. This can be +used as an argument to 'malloc()' or in a union to allocate space +statically. Please refer to the 'readdir_test' sample extension for an +example. + File: gawk.info, Node: Output Wrappers, Next: Two-way processors, Prev: Input Parsers, Up: Registration Functions @@ -33052,8 +33134,8 @@ Index * caret (^), ^= operator: Assignment Ops. (line 129) * caret (^), ^= operator <1>: Precedence. (line 94) * case keyword: Switch Statement. (line 6) -* case sensitivity, and regexps: User-modified. (line 76) -* case sensitivity, and string comparisons: User-modified. (line 76) +* case sensitivity, and regexps: User-modified. (line 79) +* case sensitivity, and string comparisons: User-modified. (line 79) * case sensitivity, array indices and: Array Intro. (line 100) * case sensitivity, converting case: String Functions. (line 523) * case sensitivity, example programs: Library Functions. (line 53) @@ -33242,7 +33324,7 @@ Index * dark corner, field separators: Full Line Fields. (line 22) * dark corner, FILENAME variable: Getline Notes. (line 19) * dark corner, FILENAME variable <1>: Auto-set. (line 108) -* dark corner, FNR/NR variables: Auto-set. (line 357) +* dark corner, FNR/NR variables: Auto-set. (line 358) * dark corner, format-control characters: Control Letters. (line 18) * dark corner, format-control characters <1>: Control Letters. (line 93) @@ -33441,13 +33523,13 @@ Index * differences in awk and gawk, error messages: Special FD. (line 19) * differences in awk and gawk, FIELDWIDTHS variable: User-modified. (line 37) -* differences in awk and gawk, FPAT variable: User-modified. (line 43) +* differences in awk and gawk, FPAT variable: User-modified. (line 46) * differences in awk and gawk, FUNCTAB variable: Auto-set. (line 134) * differences in awk and gawk, function arguments (gawk): Calling Built-in. (line 16) * differences in awk and gawk, getline command: Getline. (line 19) * differences in awk and gawk, IGNORECASE variable: User-modified. - (line 76) + (line 79) * differences in awk and gawk, implementation limitations: Getline Notes. (line 14) * differences in awk and gawk, implementation limitations <1>: Redirection. @@ -33460,7 +33542,7 @@ Index (line 96) * differences in awk and gawk, line continuations: Conditional Exp. (line 34) -* differences in awk and gawk, LINT variable: User-modified. (line 87) +* differences in awk and gawk, LINT variable: User-modified. (line 90) * differences in awk and gawk, match() function: String Functions. (line 262) * differences in awk and gawk, print/printf statements: Format Modifiers. @@ -33477,7 +33559,7 @@ Index (line 6) * differences in awk and gawk, RS/RT variables: gawk split records. (line 58) -* differences in awk and gawk, RT variable: Auto-set. (line 295) +* differences in awk and gawk, RT variable: Auto-set. (line 296) * differences in awk and gawk, single-character fields: Single Character Fields. (line 6) * differences in awk and gawk, split() function: String Functions. @@ -33485,9 +33567,9 @@ Index * differences in awk and gawk, strings: Scalar Constants. (line 20) * differences in awk and gawk, strings, storing: gawk split records. (line 76) -* differences in awk and gawk, SYMTAB variable: Auto-set. (line 299) +* differences in awk and gawk, SYMTAB variable: Auto-set. (line 300) * differences in awk and gawk, TEXTDOMAIN variable: User-modified. - (line 152) + (line 155) * differences in awk and gawk, trunc-mod operation: Arithmetic Ops. (line 66) * directories, command-line: Command-line directories. @@ -33648,7 +33730,7 @@ Index (line 6) * extension API version: Extension Versioning. (line 6) -* extension API, version number: Auto-set. (line 246) +* extension API, version number: Auto-set. (line 247) * extension example: Extension Example. (line 6) * extension registration: Registration Functions. (line 6) @@ -33699,11 +33781,11 @@ Index (line 6) * field separator, POSIX and: Full Line Fields. (line 16) * field separators: Field Separators. (line 15) -* field separators <1>: User-modified. (line 50) -* field separators <2>: User-modified. (line 113) +* field separators <1>: User-modified. (line 53) +* field separators <2>: User-modified. (line 116) * field separators, choice of: Field Separators. (line 50) * field separators, FIELDWIDTHS variable and: User-modified. (line 37) -* field separators, FPAT variable and: User-modified. (line 43) +* field separators, FPAT variable and: User-modified. (line 46) * field separators, regular expressions as: Field Separators. (line 50) * field separators, regular expressions as <1>: Regexp Field Splitting. (line 6) @@ -33800,7 +33882,7 @@ Index (line 12) * FNR variable: Records. (line 6) * FNR variable <1>: Auto-set. (line 118) -* FNR variable, changing: Auto-set. (line 357) +* FNR variable, changing: Auto-set. (line 358) * for statement: For Statement. (line 6) * for statement, looping over arrays: Scanning an Array. (line 20) * fork() extension function: Extension Sample Fork. @@ -33824,7 +33906,7 @@ Index * forward slash (/), patterns and: Expression Patterns. (line 24) * FPAT variable: Splitting By Content. (line 25) -* FPAT variable <1>: User-modified. (line 43) +* FPAT variable <1>: User-modified. (line 46) * frame debugger command: Execution Stack. (line 27) * Free Documentation License (FDL): GNU Free Documentation License. (line 8) @@ -33834,7 +33916,7 @@ Index * Free Software Foundation (FSF) <3>: Glossary. (line 405) * FreeBSD: Glossary. (line 748) * FS variable: Field Separators. (line 15) -* FS variable <1>: User-modified. (line 50) +* FS variable <1>: User-modified. (line 53) * FS variable, --field-separator option and: Options. (line 21) * FS variable, as null string: Single Character Fields. (line 20) @@ -33904,7 +33986,7 @@ Index * G., Daniel Richard <1>: Maintainers. (line 14) * Garfinkle, Scott: Contributors. (line 35) * gawk program, dynamic profiling: Profiling. (line 177) -* gawk version: Auto-set. (line 221) +* gawk version: Auto-set. (line 222) * gawk, ARGIND variable in: Other Arguments. (line 15) * gawk, awk and: Preface. (line 21) * gawk, awk and <1>: This Manual. (line 14) @@ -33931,7 +34013,7 @@ Index * gawk, extensions, disabling: Options. (line 257) * gawk, features, adding: Adding Code. (line 6) * gawk, features, advanced: Advanced Features. (line 6) -* gawk, field separators and: User-modified. (line 71) +* gawk, field separators and: User-modified. (line 74) * gawk, FIELDWIDTHS variable in: Constant Size. (line 22) * gawk, FIELDWIDTHS variable in <1>: User-modified. (line 37) * gawk, file names in: Special Files. (line 6) @@ -33939,12 +34021,12 @@ Index * gawk, format-control characters <1>: Control Letters. (line 93) * gawk, FPAT variable in: Splitting By Content. (line 25) -* gawk, FPAT variable in <1>: User-modified. (line 43) +* gawk, FPAT variable in <1>: User-modified. (line 46) * gawk, FUNCTAB array in: Auto-set. (line 134) * gawk, function arguments and: Calling Built-in. (line 16) * gawk, hexadecimal numbers and: Nondecimal-numbers. (line 41) * gawk, IGNORECASE variable in: Case-sensitivity. (line 26) -* gawk, IGNORECASE variable in <1>: User-modified. (line 76) +* gawk, IGNORECASE variable in <1>: User-modified. (line 79) * gawk, IGNORECASE variable in <2>: Array Intro. (line 100) * gawk, IGNORECASE variable in <3>: String Functions. (line 58) * gawk, IGNORECASE variable in <4>: Array Sorting Functions. @@ -33962,7 +34044,7 @@ Index (line 6) * gawk, interval expressions and: Regexp Operators. (line 139) * gawk, line continuation in: Conditional Exp. (line 34) -* gawk, LINT variable in: User-modified. (line 87) +* gawk, LINT variable in: User-modified. (line 90) * gawk, list of contributors to: Contributors. (line 6) * gawk, MS-Windows version of: PC Using. (line 9) * gawk, newlines in: Statements/Lines. (line 12) @@ -33980,13 +34062,13 @@ Index * gawk, regular expressions, precedence: Regexp Operators. (line 161) * gawk, RT variable in: awk split records. (line 124) * gawk, RT variable in <1>: Multiple Line. (line 130) -* gawk, RT variable in <2>: Auto-set. (line 295) +* gawk, RT variable in <2>: Auto-set. (line 296) * gawk, See Also awk: Preface. (line 34) * gawk, source code, obtaining: Getting. (line 6) -* gawk, splitting fields and: Constant Size. (line 86) +* gawk, splitting fields and: Constant Size. (line 103) * gawk, string-translation functions: I18N Functions. (line 6) -* gawk, SYMTAB array in: Auto-set. (line 299) -* gawk, TEXTDOMAIN variable in: User-modified. (line 152) +* gawk, SYMTAB array in: Auto-set. (line 300) +* gawk, TEXTDOMAIN variable in: User-modified. (line 155) * gawk, timestamps: Time Functions. (line 6) * gawk, uses for: Preface. (line 34) * gawk, versions of, information about, printing: Options. (line 304) @@ -34082,7 +34164,7 @@ Index * Grigera, Juan: Contributors. (line 58) * group database, reading: Group Functions. (line 6) * group file: Group Functions. (line 6) -* group ID of gawk user: Auto-set. (line 170) +* group ID of gawk user: Auto-set. (line 171) * groups, information about: Group Functions. (line 6) * gsub: Standard Regexp Constants. (line 43) @@ -34122,7 +34204,7 @@ Index * igawk.sh program: Igawk Program. (line 124) * ignore breakpoint: Breakpoint Control. (line 87) * ignore debugger command: Breakpoint Control. (line 87) -* IGNORECASE variable: User-modified. (line 76) +* IGNORECASE variable: User-modified. (line 79) * IGNORECASE variable, and array indices: Array Intro. (line 100) * IGNORECASE variable, and array sorting functions: Array Sorting Functions. (line 83) @@ -34197,7 +34279,7 @@ Index * interacting with other programs: I/O Functions. (line 107) * internationalization: I18N Functions. (line 6) * internationalization <1>: I18N and L10N. (line 6) -* internationalization, localization: User-modified. (line 152) +* internationalization, localization: User-modified. (line 155) * internationalization, localization <1>: Internationalization. (line 13) * internationalization, localization, character classes: Bracket Expressions. @@ -34310,7 +34392,7 @@ Index * lines, duplicate, removing: History Sorting. (line 6) * lines, matching ranges of: Ranges. (line 6) * lines, skipping between markers: Ranges. (line 43) -* lint checking: User-modified. (line 87) +* lint checking: User-modified. (line 90) * lint checking, array elements: Delete. (line 34) * lint checking, array subscripts: Uninitialized Subscripts. (line 43) @@ -34320,7 +34402,7 @@ Index (line 343) * lint checking, undefined functions: Pass By Value/Reference. (line 85) -* LINT variable: User-modified. (line 87) +* LINT variable: User-modified. (line 90) * Linux: Manual History. (line 28) * Linux <1>: I18N Example. (line 57) * Linux <2>: Glossary. (line 748) @@ -34382,7 +34464,7 @@ Index * mawk utility <2>: Concatenation. (line 36) * mawk utility <3>: Nextfile Statement. (line 47) * mawk utility <4>: Other Versions. (line 48) -* maximum precision supported by MPFR library: Auto-set. (line 235) +* maximum precision supported by MPFR library: Auto-set. (line 236) * McIlroy, Doug: Glossary. (line 257) * McPhee, Patrick: Contributors. (line 101) * message object files: Explaining gettext. (line 42) @@ -34395,7 +34477,7 @@ Index * messages from extensions: Printing Messages. (line 6) * metacharacters in regular expressions: Regexp Operators. (line 6) * metacharacters, escape sequences for: Escape Sequences. (line 140) -* minimum precision required by MPFR library: Auto-set. (line 238) +* minimum precision required by MPFR library: Auto-set. (line 239) * mktime: Time Functions. (line 25) * modifiers, in format specifiers: Format Modifiers. (line 6) * monetary information, localization: Explaining gettext. (line 104) @@ -34453,7 +34535,7 @@ Index * not Boolean-logic operator: Boolean Ops. (line 6) * NR variable: Records. (line 6) * NR variable <1>: Auto-set. (line 143) -* NR variable, changing: Auto-set. (line 357) +* NR variable, changing: Auto-set. (line 358) * null strings: awk split records. (line 114) * null strings <1>: Regexp Field Splitting. (line 43) @@ -34479,7 +34561,7 @@ Index * numbers, converting: Strings And Numbers. (line 6) * numbers, converting <1>: Bitwise Functions. (line 108) * numbers, converting, to strings: User-modified. (line 30) -* numbers, converting, to strings <1>: User-modified. (line 104) +* numbers, converting, to strings <1>: User-modified. (line 107) * numbers, hexadecimal: Nondecimal-numbers. (line 6) * numbers, octal: Nondecimal-numbers. (line 6) * numbers, rounding: Round Function. (line 6) @@ -34493,11 +34575,11 @@ Index * octal values, enabling interpretation of: Options. (line 209) * OFMT variable: OFMT. (line 15) * OFMT variable <1>: Strings And Numbers. (line 56) -* OFMT variable <2>: User-modified. (line 104) +* OFMT variable <2>: User-modified. (line 107) * OFMT variable, POSIX awk and: OFMT. (line 27) * OFS variable: Changing Fields. (line 64) * OFS variable <1>: Output Separators. (line 6) -* OFS variable <2>: User-modified. (line 113) +* OFS variable <2>: User-modified. (line 116) * OpenBSD: Glossary. (line 748) * OpenSolaris: Other Versions. (line 100) * operating systems, BSD-based: Manual History. (line 28) @@ -34553,7 +34635,7 @@ Index * ord() user-defined function: Ordinal Functions. (line 16) * order of evaluation, concatenation: Concatenation. (line 41) * ORS variable: Output Separators. (line 20) -* ORS variable <1>: User-modified. (line 119) +* ORS variable <1>: User-modified. (line 122) * output field separator, See OFS variable: Changing Fields. (line 64) * output record separator, See ORS variable: Output Separators. (line 20) @@ -34573,7 +34655,7 @@ Index * p debugger command (alias for print): Viewing And Changing Data. (line 35) * Papadopoulos, Panos: Contributors. (line 129) -* parent process ID of gawk process: Auto-set. (line 210) +* parent process ID of gawk process: Auto-set. (line 211) * parentheses (), in a profile: Profiling. (line 146) * parentheses (), regexp operator: Regexp Operators. (line 81) * password file: Passwd Functions. (line 16) @@ -34696,7 +34778,7 @@ Index * POSIX, gawk extensions not included in: POSIX/GNU. (line 6) * POSIX, programs, implementing in awk: Clones. (line 6) * POSIXLY_CORRECT environment variable: Options. (line 343) -* PREC variable: User-modified. (line 124) +* PREC variable: User-modified. (line 127) * precedence: Increment Ops. (line 60) * precedence <1>: Precedence. (line 6) * precedence, regexp operators: Regexp Operators. (line 156) @@ -34711,7 +34793,7 @@ Index * print statement, commas, omitting: Print Examples. (line 30) * print statement, I/O operators in: Precedence. (line 70) * print statement, line continuations and: Print Examples. (line 75) -* print statement, OFMT variable and: User-modified. (line 113) +* print statement, OFMT variable and: User-modified. (line 116) * print statement, See Also redirection, of output: Redirection. (line 17) * print statement, sprintf() function and: Round Function. (line 6) @@ -34742,8 +34824,8 @@ Index * printing, unduplicated lines of text: Uniq Program. (line 6) * printing, user information: Id Program. (line 6) * private variables: Library Names. (line 11) -* process group ID of gawk process: Auto-set. (line 204) -* process ID of gawk process: Auto-set. (line 207) +* process group ID of gawk process: Auto-set. (line 205) +* process ID of gawk process: Auto-set. (line 208) * processes, two-way communications with: Two-way I/O. (line 6) * processing data: Basic High Level. (line 6) * PROCINFO array: Auto-set. (line 148) @@ -34758,7 +34840,7 @@ Index (line 26) * profiling awk programs: Profiling. (line 6) * profiling awk programs, dynamically: Profiling. (line 177) -* program identifiers: Auto-set. (line 173) +* program identifiers: Auto-set. (line 174) * program, definition of: Getting Started. (line 21) * programming conventions, --non-decimal-data option: Nondecimal Data. (line 35) @@ -34827,7 +34909,7 @@ Index * reading input files: Reading Files. (line 6) * recipe for a programming language: History. (line 6) * record separators: awk split records. (line 6) -* record separators <1>: User-modified. (line 133) +* record separators <1>: User-modified. (line 136) * record separators, changing: awk split records. (line 85) * record separators, regular expressions as: awk split records. (line 124) @@ -34869,7 +34951,7 @@ Index * regular expressions, as record separators: awk split records. (line 124) * regular expressions, case sensitivity: Case-sensitivity. (line 6) -* regular expressions, case sensitivity <1>: User-modified. (line 76) +* regular expressions, case sensitivity <1>: User-modified. (line 79) * regular expressions, computed: Computed Regexps. (line 6) * regular expressions, constants, See regexp constants: Regexp Usage. (line 57) @@ -34919,7 +35001,7 @@ Index * right shift: Bitwise Functions. (line 54) * right shift, bitwise: Bitwise Functions. (line 32) * Ritchie, Dennis: Basic Data Typing. (line 54) -* RLENGTH variable: Auto-set. (line 282) +* RLENGTH variable: Auto-set. (line 283) * RLENGTH variable, match() function and: String Functions. (line 227) * Robbins, Arnold: Command Line Field Separator. (line 71) @@ -34940,16 +35022,16 @@ Index * round to nearest integer: Numeric Functions. (line 24) * round() user-defined function: Round Function. (line 16) * rounding numbers: Round Function. (line 6) -* ROUNDMODE variable: User-modified. (line 128) +* ROUNDMODE variable: User-modified. (line 131) * RS variable: awk split records. (line 12) -* RS variable <1>: User-modified. (line 133) +* RS variable <1>: User-modified. (line 136) * RS variable, multiline records and: Multiple Line. (line 17) * rshift: Bitwise Functions. (line 54) -* RSTART variable: Auto-set. (line 288) +* RSTART variable: Auto-set. (line 289) * RSTART variable, match() function and: String Functions. (line 227) * RT variable: awk split records. (line 124) * RT variable <1>: Multiple Line. (line 130) -* RT variable <2>: Auto-set. (line 295) +* RT variable <2>: Auto-set. (line 296) * Rubin, Paul: History. (line 30) * Rubin, Paul <1>: Contributors. (line 16) * rule, definition of: Getting Started. (line 21) @@ -34967,7 +35049,7 @@ Index * scanning arrays: Scanning an Array. (line 6) * scanning multidimensional arrays: Multiscanning. (line 11) * Schorr, Andrew: Acknowledgments. (line 60) -* Schorr, Andrew <1>: Auto-set. (line 327) +* Schorr, Andrew <1>: Auto-set. (line 328) * Schorr, Andrew <2>: Contributors. (line 134) * Schreiber, Bert: Acknowledgments. (line 38) * Schreiber, Rita: Acknowledgments. (line 38) @@ -34994,17 +35076,17 @@ Index (line 19) * semicolon (;), separating statements in actions <2>: Statements. (line 10) -* separators, field: User-modified. (line 50) -* separators, field <1>: User-modified. (line 113) +* separators, field: User-modified. (line 53) +* separators, field <1>: User-modified. (line 116) * separators, field, FIELDWIDTHS variable and: User-modified. (line 37) -* separators, field, FPAT variable and: User-modified. (line 43) +* separators, field, FPAT variable and: User-modified. (line 46) * separators, for records: awk split records. (line 6) * separators, for records <1>: awk split records. (line 85) -* separators, for records <2>: User-modified. (line 133) +* separators, for records <2>: User-modified. (line 136) * separators, for records, regular expressions as: awk split records. (line 124) * separators, for statements in actions: Action Overview. (line 19) -* separators, subscript: User-modified. (line 146) +* separators, subscript: User-modified. (line 149) * set breakpoint: Breakpoint Control. (line 11) * set debugger command: Viewing And Changing Data. (line 58) @@ -35053,7 +35135,7 @@ Index * sidebar, Beware The Smoke and Mirrors!: Bitwise Functions. (line 126) * sidebar, Changing FS Does Not Affect the Fields: Full Line Fields. (line 14) -* sidebar, Changing NR and FNR: Auto-set. (line 355) +* sidebar, Changing NR and FNR: Auto-set. (line 356) * sidebar, Controlling Output Buffering with system(): I/O Functions. (line 164) * sidebar, Escape Sequences for Metacharacters: Escape Sequences. @@ -35138,7 +35220,7 @@ Index * split.awk program: Split Program. (line 30) * sprintf: OFMT. (line 15) * sprintf <1>: String Functions. (line 384) -* sprintf() function, OFMT variable and: User-modified. (line 113) +* sprintf() function, OFMT variable and: User-modified. (line 116) * sprintf() function, print/printf statements and: Round Function. (line 6) * sqrt: Numeric Functions. (line 93) @@ -35184,7 +35266,7 @@ Index * strings, converting <1>: Bitwise Functions. (line 108) * strings, converting letter case: String Functions. (line 523) * strings, converting, numbers to: User-modified. (line 30) -* strings, converting, numbers to <1>: User-modified. (line 104) +* strings, converting, numbers to <1>: User-modified. (line 107) * strings, empty, See null strings: awk split records. (line 114) * strings, extracting: String Extraction. (line 6) * strings, for localization: Programmer i18n. (line 13) @@ -35201,7 +35283,7 @@ Index * sub <1>: String Functions. (line 409) * sub() function, arguments of: String Functions. (line 463) * sub() function, escape processing: Gory Details. (line 6) -* subscript separators: User-modified. (line 146) +* subscript separators: User-modified. (line 149) * subscripts in arrays, multidimensional: Multidimensional. (line 10) * subscripts in arrays, multidimensional, scanning: Multiscanning. (line 11) @@ -35209,16 +35291,16 @@ Index (line 6) * subscripts in arrays, uninitialized variables as: Uninitialized Subscripts. (line 6) -* SUBSEP variable: User-modified. (line 146) +* SUBSEP variable: User-modified. (line 149) * SUBSEP variable, and multidimensional arrays: Multidimensional. (line 16) * substitute in string: String Functions. (line 89) * substr: String Functions. (line 482) * substring: String Functions. (line 482) * Sumner, Andrew: Other Versions. (line 68) -* supplementary groups of gawk process: Auto-set. (line 251) +* supplementary groups of gawk process: Auto-set. (line 252) * switch statement: Switch Statement. (line 6) -* SYMTAB array: Auto-set. (line 299) +* SYMTAB array: Auto-set. (line 300) * syntactic ambiguity: /= operator vs. /=.../ regexp constant: Assignment Ops. (line 149) * system: I/O Functions. (line 107) @@ -35247,7 +35329,7 @@ Index (line 6) * text, printing: Print. (line 22) * text, printing, unduplicated lines of: Uniq Program. (line 6) -* TEXTDOMAIN variable: User-modified. (line 152) +* TEXTDOMAIN variable: User-modified. (line 155) * TEXTDOMAIN variable <1>: Programmer i18n. (line 8) * TEXTDOMAIN variable, BEGIN pattern and: Programmer i18n. (line 60) * TEXTDOMAIN variable, portability and: I18N Portability. (line 20) @@ -35400,10 +35482,10 @@ Index * variables, uninitialized, as array subscripts: Uninitialized Subscripts. (line 6) * variables, user-defined: Variables. (line 6) -* version of gawk: Auto-set. (line 221) -* version of gawk extension API: Auto-set. (line 246) -* version of GNU MP library: Auto-set. (line 229) -* version of GNU MPFR library: Auto-set. (line 231) +* version of gawk: Auto-set. (line 222) +* version of gawk extension API: Auto-set. (line 247) +* version of GNU MP library: Auto-set. (line 230) +* version of GNU MPFR library: Auto-set. (line 232) * vertical bar (|): Regexp Operators. (line 70) * vertical bar (|), | operator (I/O): Getline/Pipe. (line 10) * vertical bar (|), | operator (I/O) <1>: Precedence. (line 64) @@ -35560,484 +35642,484 @@ Ref: Full Line Fields-Footnote-1228233 Ref: Full Line Fields-Footnote-2228279 Node: Field Splitting Summary228380 Node: Constant Size230454 -Node: Splitting By Content235032 -Ref: Splitting By Content-Footnote-1239003 -Node: Multiple Line239166 -Ref: Multiple Line-Footnote-1245048 -Node: Getline245227 -Node: Plain Getline247694 -Node: Getline/Variable250333 -Node: Getline/File251482 -Node: Getline/Variable/File252868 -Ref: Getline/Variable/File-Footnote-1254471 -Node: Getline/Pipe254559 -Node: Getline/Variable/Pipe257264 -Node: Getline/Coprocess258397 -Node: Getline/Variable/Coprocess259662 -Node: Getline Notes260402 -Node: Getline Summary263197 -Ref: table-getline-variants263619 -Node: Read Timeout264367 -Ref: Read Timeout-Footnote-1268273 -Node: Retrying Input268331 -Node: Command-line directories269530 -Node: Input Summary270436 -Node: Input Exercises273608 -Node: Printing274336 -Node: Print276170 -Node: Print Examples277627 -Node: Output Separators280407 -Node: OFMT282424 -Node: Printf283780 -Node: Basic Printf284565 -Node: Control Letters286139 -Node: Format Modifiers290127 -Node: Printf Examples296142 -Node: Redirection298628 -Node: Special FD305469 -Ref: Special FD-Footnote-1308637 -Node: Special Files308711 -Node: Other Inherited Files309328 -Node: Special Network310329 -Node: Special Caveats311189 -Node: Close Files And Pipes312138 -Ref: table-close-pipe-return-values319045 -Ref: Close Files And Pipes-Footnote-1319828 -Ref: Close Files And Pipes-Footnote-2319976 -Node: Nonfatal320128 -Node: Output Summary322453 -Node: Output Exercises323675 -Node: Expressions324354 -Node: Values325542 -Node: Constants326220 -Node: Scalar Constants326911 -Ref: Scalar Constants-Footnote-1327775 -Node: Nondecimal-numbers328025 -Node: Regexp Constants331026 -Node: Using Constant Regexps331552 -Node: Standard Regexp Constants332174 -Node: Strong Regexp Constants335362 -Node: Variables338320 -Node: Using Variables338977 -Node: Assignment Options340887 -Node: Conversion342760 -Node: Strings And Numbers343284 -Ref: Strings And Numbers-Footnote-1346347 -Node: Locale influences conversions346456 -Ref: table-locale-affects349214 -Node: All Operators349832 -Node: Arithmetic Ops350461 -Node: Concatenation352967 -Ref: Concatenation-Footnote-1355814 -Node: Assignment Ops355921 -Ref: table-assign-ops360912 -Node: Increment Ops362225 -Node: Truth Values and Conditions365685 -Node: Truth Values366759 -Node: Typing and Comparison367807 -Node: Variable Typing368627 -Ref: Variable Typing-Footnote-1375090 -Ref: Variable Typing-Footnote-2375162 -Node: Comparison Operators375239 -Ref: table-relational-ops375658 -Node: POSIX String Comparison379153 -Ref: POSIX String Comparison-Footnote-1380848 -Ref: POSIX String Comparison-Footnote-2380987 -Node: Boolean Ops381071 -Ref: Boolean Ops-Footnote-1385553 -Node: Conditional Exp385645 -Node: Function Calls387381 -Node: Precedence391258 -Node: Locales394917 -Node: Expressions Summary396549 -Node: Patterns and Actions399122 -Node: Pattern Overview400242 -Node: Regexp Patterns401919 -Node: Expression Patterns402461 -Node: Ranges406242 -Node: BEGIN/END409350 -Node: Using BEGIN/END410111 -Ref: Using BEGIN/END-Footnote-1412847 -Node: I/O And BEGIN/END412953 -Node: BEGINFILE/ENDFILE415267 -Node: Empty418174 -Node: Using Shell Variables418491 -Node: Action Overview420765 -Node: Statements423090 -Node: If Statement424938 -Node: While Statement426433 -Node: Do Statement428461 -Node: For Statement429609 -Node: Switch Statement432767 -Node: Break Statement435153 -Node: Continue Statement437245 -Node: Next Statement439072 -Node: Nextfile Statement441455 -Node: Exit Statement444107 -Node: Built-in Variables446510 -Node: User-modified447643 -Node: Auto-set455229 -Ref: Auto-set-Footnote-1469882 -Ref: Auto-set-Footnote-2470088 -Node: ARGC and ARGV470144 -Node: Pattern Action Summary474357 -Node: Arrays476787 -Node: Array Basics478116 -Node: Array Intro478960 -Ref: figure-array-elements480935 -Ref: Array Intro-Footnote-1483639 -Node: Reference to Elements483767 -Node: Assigning Elements486231 -Node: Array Example486722 -Node: Scanning an Array488481 -Node: Controlling Scanning491503 -Ref: Controlling Scanning-Footnote-1496902 -Node: Numeric Array Subscripts497218 -Node: Uninitialized Subscripts499402 -Node: Delete501021 -Ref: Delete-Footnote-1503773 -Node: Multidimensional503830 -Node: Multiscanning506925 -Node: Arrays of Arrays508516 -Node: Arrays Summary513283 -Node: Functions515376 -Node: Built-in516414 -Node: Calling Built-in517495 -Node: Numeric Functions519491 -Ref: Numeric Functions-Footnote-1524324 -Ref: Numeric Functions-Footnote-2524681 -Ref: Numeric Functions-Footnote-3524729 -Node: String Functions525001 -Ref: String Functions-Footnote-1548505 -Ref: String Functions-Footnote-2548633 -Ref: String Functions-Footnote-3548881 -Node: Gory Details548968 -Ref: table-sub-escapes550759 -Ref: table-sub-proposed552278 -Ref: table-posix-sub553641 -Ref: table-gensub-escapes555182 -Ref: Gory Details-Footnote-1556005 -Node: I/O Functions556159 -Ref: table-system-return-values562741 -Ref: I/O Functions-Footnote-1564721 -Ref: I/O Functions-Footnote-2564869 -Node: Time Functions564989 -Ref: Time Functions-Footnote-1575656 -Ref: Time Functions-Footnote-2575724 -Ref: Time Functions-Footnote-3575882 -Ref: Time Functions-Footnote-4575993 -Ref: Time Functions-Footnote-5576105 -Ref: Time Functions-Footnote-6576332 -Node: Bitwise Functions576598 -Ref: table-bitwise-ops577192 -Ref: Bitwise Functions-Footnote-1583225 -Ref: Bitwise Functions-Footnote-2583398 -Node: Type Functions583589 -Node: I18N Functions586264 -Node: User-defined587915 -Node: Definition Syntax588720 -Ref: Definition Syntax-Footnote-1594407 -Node: Function Example594478 -Ref: Function Example-Footnote-1597400 -Node: Function Caveats597422 -Node: Calling A Function597940 -Node: Variable Scope598898 -Node: Pass By Value/Reference601892 -Node: Return Statement605391 -Node: Dynamic Typing608370 -Node: Indirect Calls609300 -Ref: Indirect Calls-Footnote-1619551 -Node: Functions Summary619679 -Node: Library Functions622384 -Ref: Library Functions-Footnote-1625991 -Ref: Library Functions-Footnote-2626134 -Node: Library Names626305 -Ref: Library Names-Footnote-1629765 -Ref: Library Names-Footnote-2629988 -Node: General Functions630074 -Node: Strtonum Function631177 -Node: Assert Function634199 -Node: Round Function637525 -Node: Cliff Random Function639066 -Node: Ordinal Functions640082 -Ref: Ordinal Functions-Footnote-1643145 -Ref: Ordinal Functions-Footnote-2643397 -Node: Join Function643607 -Ref: Join Function-Footnote-1645377 -Node: Getlocaltime Function645577 -Node: Readfile Function649319 -Node: Shell Quoting651291 -Node: Data File Management652692 -Node: Filetrans Function653324 -Node: Rewind Function657420 -Node: File Checking659326 -Ref: File Checking-Footnote-1660660 -Node: Empty Files660861 -Node: Ignoring Assigns662840 -Node: Getopt Function664390 -Ref: Getopt Function-Footnote-1675859 -Node: Passwd Functions676059 -Ref: Passwd Functions-Footnote-1684898 -Node: Group Functions684986 -Ref: Group Functions-Footnote-1692884 -Node: Walking Arrays693091 -Node: Library Functions Summary696099 -Node: Library Exercises697505 -Node: Sample Programs697970 -Node: Running Examples698740 -Node: Clones699468 -Node: Cut Program700692 -Node: Egrep Program710621 -Ref: Egrep Program-Footnote-1718133 -Node: Id Program718243 -Node: Split Program721923 -Ref: Split Program-Footnote-1725382 -Node: Tee Program725511 -Node: Uniq Program728301 -Node: Wc Program735727 -Ref: Wc Program-Footnote-1739982 -Node: Miscellaneous Programs740076 -Node: Dupword Program741289 -Node: Alarm Program743319 -Node: Translate Program748174 -Ref: Translate Program-Footnote-1752739 -Node: Labels Program753009 -Ref: Labels Program-Footnote-1756360 -Node: Word Sorting756444 -Node: History Sorting760516 -Node: Extract Program762351 -Node: Simple Sed769880 -Node: Igawk Program772954 -Ref: Igawk Program-Footnote-1787285 -Ref: Igawk Program-Footnote-2787487 -Ref: Igawk Program-Footnote-3787609 -Node: Anagram Program787724 -Node: Signature Program790786 -Node: Programs Summary792033 -Node: Programs Exercises793247 -Ref: Programs Exercises-Footnote-1797376 -Node: Advanced Features797467 -Node: Nondecimal Data799457 -Node: Array Sorting801048 -Node: Controlling Array Traversal801748 -Ref: Controlling Array Traversal-Footnote-1810115 -Node: Array Sorting Functions810233 -Ref: Array Sorting Functions-Footnote-1815324 -Node: Two-way I/O815520 -Ref: Two-way I/O-Footnote-1822071 -Ref: Two-way I/O-Footnote-2822258 -Node: TCP/IP Networking822340 -Node: Profiling825458 -Ref: Profiling-Footnote-1834130 -Node: Advanced Features Summary834453 -Node: Internationalization836297 -Node: I18N and L10N837777 -Node: Explaining gettext838464 -Ref: Explaining gettext-Footnote-1844356 -Ref: Explaining gettext-Footnote-2844541 -Node: Programmer i18n844706 -Ref: Programmer i18n-Footnote-1849655 -Node: Translator i18n849704 -Node: String Extraction850498 -Ref: String Extraction-Footnote-1851630 -Node: Printf Ordering851716 -Ref: Printf Ordering-Footnote-1854502 -Node: I18N Portability854566 -Ref: I18N Portability-Footnote-1857022 -Node: I18N Example857085 -Ref: I18N Example-Footnote-1859891 -Node: Gawk I18N859964 -Node: I18N Summary860609 -Node: Debugger861950 -Node: Debugging862972 -Node: Debugging Concepts863413 -Node: Debugging Terms865222 -Node: Awk Debugging867797 -Node: Sample Debugging Session868703 -Node: Debugger Invocation869237 -Node: Finding The Bug870623 -Node: List of Debugger Commands877101 -Node: Breakpoint Control878434 -Node: Debugger Execution Control882128 -Node: Viewing And Changing Data885490 -Node: Execution Stack888864 -Node: Debugger Info890501 -Node: Miscellaneous Debugger Commands894572 -Node: Readline Support899660 -Node: Limitations900556 -Node: Debugging Summary902665 -Node: Arbitrary Precision Arithmetic903944 -Node: Computer Arithmetic905360 -Ref: table-numeric-ranges908951 -Ref: Computer Arithmetic-Footnote-1909673 -Node: Math Definitions909730 -Ref: table-ieee-formats913044 -Ref: Math Definitions-Footnote-1913647 -Node: MPFR features913752 -Node: FP Math Caution915469 -Ref: FP Math Caution-Footnote-1916541 -Node: Inexactness of computations916910 -Node: Inexact representation917870 -Node: Comparing FP Values919230 -Node: Errors accumulate920312 -Node: Getting Accuracy921745 -Node: Try To Round924455 -Node: Setting precision925354 -Ref: table-predefined-precision-strings926051 -Node: Setting the rounding mode927881 -Ref: table-gawk-rounding-modes928255 -Ref: Setting the rounding mode-Footnote-1931663 -Node: Arbitrary Precision Integers931842 -Ref: Arbitrary Precision Integers-Footnote-1936759 -Node: POSIX Floating Point Problems936908 -Ref: POSIX Floating Point Problems-Footnote-1940790 -Node: Floating point summary940828 -Node: Dynamic Extensions943018 -Node: Extension Intro944571 -Node: Plugin License945837 -Node: Extension Mechanism Outline946634 -Ref: figure-load-extension947073 -Ref: figure-register-new-function948638 -Ref: figure-call-new-function949730 -Node: Extension API Description951792 -Node: Extension API Functions Introduction953434 -Node: General Data Types958768 -Ref: General Data Types-Footnote-1965973 -Node: Memory Allocation Functions966272 -Ref: Memory Allocation Functions-Footnote-1969117 -Node: Constructor Functions969216 -Node: Registration Functions972215 -Node: Extension Functions972900 -Node: Exit Callback Functions978113 -Node: Extension Version String979363 -Node: Input Parsers980026 -Node: Output Wrappers989908 -Node: Two-way processors994420 -Node: Printing Messages996685 -Ref: Printing Messages-Footnote-1997856 -Node: Updating ERRNO998009 -Node: Requesting Values998748 -Ref: table-value-types-returned999485 -Node: Accessing Parameters1000421 -Node: Symbol Table Access1001656 -Node: Symbol table by name1002168 -Node: Symbol table by cookie1003957 -Ref: Symbol table by cookie-Footnote-11008142 -Node: Cached values1008206 -Ref: Cached values-Footnote-11011742 -Node: Array Manipulation1011833 -Ref: Array Manipulation-Footnote-11012924 -Node: Array Data Types1012961 -Ref: Array Data Types-Footnote-11015619 -Node: Array Functions1015711 -Node: Flattening Arrays1020110 -Node: Creating Arrays1027051 -Node: Redirection API1031820 -Node: Extension API Variables1034662 -Node: Extension Versioning1035295 -Ref: gawk-api-version1035732 -Node: Extension API Informational Variables1037460 -Node: Extension API Boilerplate1038524 -Node: Changes from API V11042386 -Node: Finding Extensions1043046 -Node: Extension Example1043605 -Node: Internal File Description1044403 -Node: Internal File Ops1048483 -Ref: Internal File Ops-Footnote-11059883 -Node: Using Internal File Ops1060023 -Ref: Using Internal File Ops-Footnote-11062406 -Node: Extension Samples1062680 -Node: Extension Sample File Functions1064209 -Node: Extension Sample Fnmatch1071858 -Node: Extension Sample Fork1073345 -Node: Extension Sample Inplace1074563 -Node: Extension Sample Ord1077773 -Node: Extension Sample Readdir1078609 -Ref: table-readdir-file-types1079498 -Node: Extension Sample Revout1080303 -Node: Extension Sample Rev2way1080892 -Node: Extension Sample Read write array1081632 -Node: Extension Sample Readfile1083574 -Node: Extension Sample Time1084669 -Node: Extension Sample API Tests1086017 -Node: gawkextlib1086509 -Node: Extension summary1088956 -Node: Extension Exercises1092658 -Node: Language History1094156 -Node: V7/SVR3.11095812 -Node: SVR41097964 -Node: POSIX1099398 -Node: BTL1100777 -Node: POSIX/GNU1101506 -Node: Feature History1107398 -Node: Common Extensions1121768 -Node: Ranges and Locales1123051 -Ref: Ranges and Locales-Footnote-11127667 -Ref: Ranges and Locales-Footnote-21127694 -Ref: Ranges and Locales-Footnote-31127929 -Node: Contributors1128150 -Node: History summary1133710 -Node: Installation1135090 -Node: Gawk Distribution1136034 -Node: Getting1136518 -Node: Extracting1137479 -Node: Distribution contents1139117 -Node: Unix Installation1145459 -Node: Quick Installation1146141 -Node: Shell Startup Files1148555 -Node: Additional Configuration Options1149644 -Node: Configuration Philosophy1151449 -Node: Non-Unix Installation1153818 -Node: PC Installation1154278 -Node: PC Binary Installation1155116 -Node: PC Compiling1155551 -Node: PC Using1156668 -Node: Cygwin1159713 -Node: MSYS1160483 -Node: VMS Installation1160984 -Node: VMS Compilation1161775 -Ref: VMS Compilation-Footnote-11163004 -Node: VMS Dynamic Extensions1163062 -Node: VMS Installation Details1164747 -Node: VMS Running1167000 -Node: VMS GNV1171279 -Node: VMS Old Gawk1172014 -Node: Bugs1172485 -Node: Bug address1173148 -Node: Usenet1175545 -Node: Maintainers1176322 -Node: Other Versions1177698 -Node: Installation summary1184282 -Node: Notes1185317 -Node: Compatibility Mode1186182 -Node: Additions1186964 -Node: Accessing The Source1187889 -Node: Adding Code1189324 -Node: New Ports1195542 -Node: Derived Files1200030 -Ref: Derived Files-Footnote-11205515 -Ref: Derived Files-Footnote-21205550 -Ref: Derived Files-Footnote-31206148 -Node: Future Extensions1206262 -Node: Implementation Limitations1206920 -Node: Extension Design1208103 -Node: Old Extension Problems1209257 -Ref: Old Extension Problems-Footnote-11210775 -Node: Extension New Mechanism Goals1210832 -Ref: Extension New Mechanism Goals-Footnote-11214196 -Node: Extension Other Design Decisions1214385 -Node: Extension Future Growth1216498 -Node: Old Extension Mechanism1217334 -Node: Notes summary1219097 -Node: Basic Concepts1220279 -Node: Basic High Level1220960 -Ref: figure-general-flow1221242 -Ref: figure-process-flow1221927 -Ref: Basic High Level-Footnote-11225228 -Node: Basic Data Typing1225413 -Node: Glossary1228741 -Node: Copying1260688 -Node: GNU Free Documentation License1298227 -Node: Index1323345 +Node: Splitting By Content235763 +Ref: Splitting By Content-Footnote-1239903 +Node: Multiple Line240066 +Ref: Multiple Line-Footnote-1245948 +Node: Getline246127 +Node: Plain Getline248594 +Node: Getline/Variable251233 +Node: Getline/File252382 +Node: Getline/Variable/File253768 +Ref: Getline/Variable/File-Footnote-1255371 +Node: Getline/Pipe255459 +Node: Getline/Variable/Pipe258164 +Node: Getline/Coprocess259297 +Node: Getline/Variable/Coprocess260562 +Node: Getline Notes261302 +Node: Getline Summary264097 +Ref: table-getline-variants264519 +Node: Read Timeout265267 +Ref: Read Timeout-Footnote-1269173 +Node: Retrying Input269231 +Node: Command-line directories270430 +Node: Input Summary271336 +Node: Input Exercises274508 +Node: Printing275236 +Node: Print277070 +Node: Print Examples278527 +Node: Output Separators281307 +Node: OFMT283324 +Node: Printf284680 +Node: Basic Printf285465 +Node: Control Letters287039 +Node: Format Modifiers291027 +Node: Printf Examples297042 +Node: Redirection299528 +Node: Special FD306369 +Ref: Special FD-Footnote-1309537 +Node: Special Files309611 +Node: Other Inherited Files310228 +Node: Special Network311229 +Node: Special Caveats312089 +Node: Close Files And Pipes313038 +Ref: table-close-pipe-return-values319945 +Ref: Close Files And Pipes-Footnote-1320728 +Ref: Close Files And Pipes-Footnote-2320876 +Node: Nonfatal321028 +Node: Output Summary323353 +Node: Output Exercises324575 +Node: Expressions325254 +Node: Values326442 +Node: Constants327120 +Node: Scalar Constants327811 +Ref: Scalar Constants-Footnote-1328675 +Node: Nondecimal-numbers328925 +Node: Regexp Constants331926 +Node: Using Constant Regexps332452 +Node: Standard Regexp Constants333074 +Node: Strong Regexp Constants336262 +Node: Variables339220 +Node: Using Variables339877 +Node: Assignment Options341787 +Node: Conversion343660 +Node: Strings And Numbers344184 +Ref: Strings And Numbers-Footnote-1347247 +Node: Locale influences conversions347356 +Ref: table-locale-affects350114 +Node: All Operators350732 +Node: Arithmetic Ops351361 +Node: Concatenation353867 +Ref: Concatenation-Footnote-1356714 +Node: Assignment Ops356821 +Ref: table-assign-ops361812 +Node: Increment Ops363125 +Node: Truth Values and Conditions366585 +Node: Truth Values367659 +Node: Typing and Comparison368707 +Node: Variable Typing369527 +Ref: Variable Typing-Footnote-1375990 +Ref: Variable Typing-Footnote-2376062 +Node: Comparison Operators376139 +Ref: table-relational-ops376558 +Node: POSIX String Comparison380053 +Ref: POSIX String Comparison-Footnote-1381748 +Ref: POSIX String Comparison-Footnote-2381887 +Node: Boolean Ops381971 +Ref: Boolean Ops-Footnote-1386453 +Node: Conditional Exp386545 +Node: Function Calls388281 +Node: Precedence392158 +Node: Locales395817 +Node: Expressions Summary397449 +Node: Patterns and Actions400022 +Node: Pattern Overview401142 +Node: Regexp Patterns402819 +Node: Expression Patterns403361 +Node: Ranges407142 +Node: BEGIN/END410250 +Node: Using BEGIN/END411011 +Ref: Using BEGIN/END-Footnote-1413747 +Node: I/O And BEGIN/END413853 +Node: BEGINFILE/ENDFILE416167 +Node: Empty419074 +Node: Using Shell Variables419391 +Node: Action Overview421665 +Node: Statements423990 +Node: If Statement425838 +Node: While Statement427333 +Node: Do Statement429361 +Node: For Statement430509 +Node: Switch Statement433667 +Node: Break Statement436053 +Node: Continue Statement438145 +Node: Next Statement439972 +Node: Nextfile Statement442355 +Node: Exit Statement445007 +Node: Built-in Variables447410 +Node: User-modified448543 +Node: Auto-set456310 +Ref: Auto-set-Footnote-1471038 +Ref: Auto-set-Footnote-2471244 +Node: ARGC and ARGV471300 +Node: Pattern Action Summary475513 +Node: Arrays477943 +Node: Array Basics479272 +Node: Array Intro480116 +Ref: figure-array-elements482091 +Ref: Array Intro-Footnote-1484795 +Node: Reference to Elements484923 +Node: Assigning Elements487387 +Node: Array Example487878 +Node: Scanning an Array489637 +Node: Controlling Scanning492659 +Ref: Controlling Scanning-Footnote-1498058 +Node: Numeric Array Subscripts498374 +Node: Uninitialized Subscripts500558 +Node: Delete502177 +Ref: Delete-Footnote-1504929 +Node: Multidimensional504986 +Node: Multiscanning508081 +Node: Arrays of Arrays509672 +Node: Arrays Summary514439 +Node: Functions516532 +Node: Built-in517570 +Node: Calling Built-in518651 +Node: Numeric Functions520647 +Ref: Numeric Functions-Footnote-1525480 +Ref: Numeric Functions-Footnote-2525837 +Ref: Numeric Functions-Footnote-3525885 +Node: String Functions526157 +Ref: String Functions-Footnote-1549661 +Ref: String Functions-Footnote-2549789 +Ref: String Functions-Footnote-3550037 +Node: Gory Details550124 +Ref: table-sub-escapes551915 +Ref: table-sub-proposed553434 +Ref: table-posix-sub554797 +Ref: table-gensub-escapes556338 +Ref: Gory Details-Footnote-1557161 +Node: I/O Functions557315 +Ref: table-system-return-values563897 +Ref: I/O Functions-Footnote-1565877 +Ref: I/O Functions-Footnote-2566025 +Node: Time Functions566145 +Ref: Time Functions-Footnote-1576812 +Ref: Time Functions-Footnote-2576880 +Ref: Time Functions-Footnote-3577038 +Ref: Time Functions-Footnote-4577149 +Ref: Time Functions-Footnote-5577261 +Ref: Time Functions-Footnote-6577488 +Node: Bitwise Functions577754 +Ref: table-bitwise-ops578348 +Ref: Bitwise Functions-Footnote-1584381 +Ref: Bitwise Functions-Footnote-2584554 +Node: Type Functions584745 +Node: I18N Functions587420 +Node: User-defined589071 +Node: Definition Syntax589876 +Ref: Definition Syntax-Footnote-1595563 +Node: Function Example595634 +Ref: Function Example-Footnote-1598556 +Node: Function Caveats598578 +Node: Calling A Function599096 +Node: Variable Scope600054 +Node: Pass By Value/Reference603048 +Node: Return Statement606547 +Node: Dynamic Typing609526 +Node: Indirect Calls610456 +Ref: Indirect Calls-Footnote-1620707 +Node: Functions Summary620835 +Node: Library Functions623540 +Ref: Library Functions-Footnote-1627147 +Ref: Library Functions-Footnote-2627290 +Node: Library Names627461 +Ref: Library Names-Footnote-1630921 +Ref: Library Names-Footnote-2631144 +Node: General Functions631230 +Node: Strtonum Function632333 +Node: Assert Function635355 +Node: Round Function638681 +Node: Cliff Random Function640222 +Node: Ordinal Functions641238 +Ref: Ordinal Functions-Footnote-1644301 +Ref: Ordinal Functions-Footnote-2644553 +Node: Join Function644763 +Ref: Join Function-Footnote-1646533 +Node: Getlocaltime Function646733 +Node: Readfile Function650475 +Node: Shell Quoting652447 +Node: Data File Management653848 +Node: Filetrans Function654480 +Node: Rewind Function658576 +Node: File Checking660482 +Ref: File Checking-Footnote-1661816 +Node: Empty Files662017 +Node: Ignoring Assigns663996 +Node: Getopt Function665546 +Ref: Getopt Function-Footnote-1677015 +Node: Passwd Functions677215 +Ref: Passwd Functions-Footnote-1686054 +Node: Group Functions686142 +Ref: Group Functions-Footnote-1694040 +Node: Walking Arrays694247 +Node: Library Functions Summary697255 +Node: Library Exercises698661 +Node: Sample Programs699126 +Node: Running Examples699896 +Node: Clones700624 +Node: Cut Program701848 +Node: Egrep Program711777 +Ref: Egrep Program-Footnote-1719289 +Node: Id Program719399 +Node: Split Program723079 +Ref: Split Program-Footnote-1726538 +Node: Tee Program726667 +Node: Uniq Program729457 +Node: Wc Program736883 +Ref: Wc Program-Footnote-1741138 +Node: Miscellaneous Programs741232 +Node: Dupword Program742445 +Node: Alarm Program744475 +Node: Translate Program749330 +Ref: Translate Program-Footnote-1753895 +Node: Labels Program754165 +Ref: Labels Program-Footnote-1757516 +Node: Word Sorting757600 +Node: History Sorting761672 +Node: Extract Program763507 +Node: Simple Sed771036 +Node: Igawk Program774110 +Ref: Igawk Program-Footnote-1788441 +Ref: Igawk Program-Footnote-2788643 +Ref: Igawk Program-Footnote-3788765 +Node: Anagram Program788880 +Node: Signature Program791942 +Node: Programs Summary793189 +Node: Programs Exercises794403 +Ref: Programs Exercises-Footnote-1798532 +Node: Advanced Features798623 +Node: Nondecimal Data800613 +Node: Array Sorting802204 +Node: Controlling Array Traversal802904 +Ref: Controlling Array Traversal-Footnote-1811271 +Node: Array Sorting Functions811389 +Ref: Array Sorting Functions-Footnote-1816480 +Node: Two-way I/O816676 +Ref: Two-way I/O-Footnote-1823227 +Ref: Two-way I/O-Footnote-2823414 +Node: TCP/IP Networking823496 +Node: Profiling826614 +Ref: Profiling-Footnote-1835286 +Node: Advanced Features Summary835609 +Node: Internationalization837453 +Node: I18N and L10N838933 +Node: Explaining gettext839620 +Ref: Explaining gettext-Footnote-1845512 +Ref: Explaining gettext-Footnote-2845697 +Node: Programmer i18n845862 +Ref: Programmer i18n-Footnote-1850811 +Node: Translator i18n850860 +Node: String Extraction851654 +Ref: String Extraction-Footnote-1852786 +Node: Printf Ordering852872 +Ref: Printf Ordering-Footnote-1855658 +Node: I18N Portability855722 +Ref: I18N Portability-Footnote-1858178 +Node: I18N Example858241 +Ref: I18N Example-Footnote-1861047 +Node: Gawk I18N861120 +Node: I18N Summary861765 +Node: Debugger863106 +Node: Debugging864128 +Node: Debugging Concepts864569 +Node: Debugging Terms866378 +Node: Awk Debugging868953 +Node: Sample Debugging Session869859 +Node: Debugger Invocation870393 +Node: Finding The Bug871779 +Node: List of Debugger Commands878257 +Node: Breakpoint Control879590 +Node: Debugger Execution Control883284 +Node: Viewing And Changing Data886646 +Node: Execution Stack890020 +Node: Debugger Info891657 +Node: Miscellaneous Debugger Commands895728 +Node: Readline Support900816 +Node: Limitations901712 +Node: Debugging Summary903821 +Node: Arbitrary Precision Arithmetic905100 +Node: Computer Arithmetic906516 +Ref: table-numeric-ranges910107 +Ref: Computer Arithmetic-Footnote-1910829 +Node: Math Definitions910886 +Ref: table-ieee-formats914200 +Ref: Math Definitions-Footnote-1914803 +Node: MPFR features914908 +Node: FP Math Caution916625 +Ref: FP Math Caution-Footnote-1917697 +Node: Inexactness of computations918066 +Node: Inexact representation919026 +Node: Comparing FP Values920386 +Node: Errors accumulate921468 +Node: Getting Accuracy922901 +Node: Try To Round925611 +Node: Setting precision926510 +Ref: table-predefined-precision-strings927207 +Node: Setting the rounding mode929037 +Ref: table-gawk-rounding-modes929411 +Ref: Setting the rounding mode-Footnote-1932819 +Node: Arbitrary Precision Integers932998 +Ref: Arbitrary Precision Integers-Footnote-1937915 +Node: POSIX Floating Point Problems938064 +Ref: POSIX Floating Point Problems-Footnote-1941946 +Node: Floating point summary941984 +Node: Dynamic Extensions944174 +Node: Extension Intro945727 +Node: Plugin License946993 +Node: Extension Mechanism Outline947790 +Ref: figure-load-extension948229 +Ref: figure-register-new-function949794 +Ref: figure-call-new-function950886 +Node: Extension API Description952948 +Node: Extension API Functions Introduction954590 +Node: General Data Types959924 +Ref: General Data Types-Footnote-1967129 +Node: Memory Allocation Functions967428 +Ref: Memory Allocation Functions-Footnote-1970273 +Node: Constructor Functions970372 +Node: Registration Functions973371 +Node: Extension Functions974056 +Node: Exit Callback Functions979269 +Node: Extension Version String980519 +Node: Input Parsers981182 +Node: Output Wrappers993889 +Node: Two-way processors998401 +Node: Printing Messages1000666 +Ref: Printing Messages-Footnote-11001837 +Node: Updating ERRNO1001990 +Node: Requesting Values1002729 +Ref: table-value-types-returned1003466 +Node: Accessing Parameters1004402 +Node: Symbol Table Access1005637 +Node: Symbol table by name1006149 +Node: Symbol table by cookie1007938 +Ref: Symbol table by cookie-Footnote-11012123 +Node: Cached values1012187 +Ref: Cached values-Footnote-11015723 +Node: Array Manipulation1015814 +Ref: Array Manipulation-Footnote-11016905 +Node: Array Data Types1016942 +Ref: Array Data Types-Footnote-11019600 +Node: Array Functions1019692 +Node: Flattening Arrays1024091 +Node: Creating Arrays1031032 +Node: Redirection API1035801 +Node: Extension API Variables1038643 +Node: Extension Versioning1039276 +Ref: gawk-api-version1039713 +Node: Extension API Informational Variables1041441 +Node: Extension API Boilerplate1042505 +Node: Changes from API V11046367 +Node: Finding Extensions1047027 +Node: Extension Example1047586 +Node: Internal File Description1048384 +Node: Internal File Ops1052464 +Ref: Internal File Ops-Footnote-11063864 +Node: Using Internal File Ops1064004 +Ref: Using Internal File Ops-Footnote-11066387 +Node: Extension Samples1066661 +Node: Extension Sample File Functions1068190 +Node: Extension Sample Fnmatch1075839 +Node: Extension Sample Fork1077326 +Node: Extension Sample Inplace1078544 +Node: Extension Sample Ord1081754 +Node: Extension Sample Readdir1082590 +Ref: table-readdir-file-types1083479 +Node: Extension Sample Revout1084284 +Node: Extension Sample Rev2way1084873 +Node: Extension Sample Read write array1085613 +Node: Extension Sample Readfile1087555 +Node: Extension Sample Time1088650 +Node: Extension Sample API Tests1089998 +Node: gawkextlib1090490 +Node: Extension summary1092937 +Node: Extension Exercises1096639 +Node: Language History1098137 +Node: V7/SVR3.11099793 +Node: SVR41101945 +Node: POSIX1103379 +Node: BTL1104758 +Node: POSIX/GNU1105487 +Node: Feature History1111379 +Node: Common Extensions1125749 +Node: Ranges and Locales1127032 +Ref: Ranges and Locales-Footnote-11131648 +Ref: Ranges and Locales-Footnote-21131675 +Ref: Ranges and Locales-Footnote-31131910 +Node: Contributors1132131 +Node: History summary1137691 +Node: Installation1139071 +Node: Gawk Distribution1140015 +Node: Getting1140499 +Node: Extracting1141460 +Node: Distribution contents1143098 +Node: Unix Installation1149440 +Node: Quick Installation1150122 +Node: Shell Startup Files1152536 +Node: Additional Configuration Options1153625 +Node: Configuration Philosophy1155430 +Node: Non-Unix Installation1157799 +Node: PC Installation1158259 +Node: PC Binary Installation1159097 +Node: PC Compiling1159532 +Node: PC Using1160649 +Node: Cygwin1163694 +Node: MSYS1164464 +Node: VMS Installation1164965 +Node: VMS Compilation1165756 +Ref: VMS Compilation-Footnote-11166985 +Node: VMS Dynamic Extensions1167043 +Node: VMS Installation Details1168728 +Node: VMS Running1170981 +Node: VMS GNV1175260 +Node: VMS Old Gawk1175995 +Node: Bugs1176466 +Node: Bug address1177129 +Node: Usenet1179526 +Node: Maintainers1180303 +Node: Other Versions1181679 +Node: Installation summary1188263 +Node: Notes1189298 +Node: Compatibility Mode1190163 +Node: Additions1190945 +Node: Accessing The Source1191870 +Node: Adding Code1193305 +Node: New Ports1199523 +Node: Derived Files1204011 +Ref: Derived Files-Footnote-11209496 +Ref: Derived Files-Footnote-21209531 +Ref: Derived Files-Footnote-31210129 +Node: Future Extensions1210243 +Node: Implementation Limitations1210901 +Node: Extension Design1212084 +Node: Old Extension Problems1213238 +Ref: Old Extension Problems-Footnote-11214756 +Node: Extension New Mechanism Goals1214813 +Ref: Extension New Mechanism Goals-Footnote-11218177 +Node: Extension Other Design Decisions1218366 +Node: Extension Future Growth1220479 +Node: Old Extension Mechanism1221315 +Node: Notes summary1223078 +Node: Basic Concepts1224260 +Node: Basic High Level1224941 +Ref: figure-general-flow1225223 +Ref: figure-process-flow1225908 +Ref: Basic High Level-Footnote-11229209 +Node: Basic Data Typing1229394 +Node: Glossary1232722 +Node: Copying1264669 +Node: GNU Free Documentation License1302208 +Node: Index1327326 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 658ac17e..0e376104 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -7761,6 +7761,9 @@ variable @code{FIELDWIDTHS}. Each number specifies the width of the field, @emph{including} columns between fields. If you want to ignore the columns between fields, you can specify the width as a separate field that is subsequently ignored. +Or, starting in @value{PVERSION} 4.2, each field width may optionally be +preceded by a colon-separated value specifying the number of characters to skip +before the field starts. It is a fatal error to supply a field width that has a negative value. The following data is the output of the Unix @command{w} utility. It is useful to illustrate the use of @code{FIELDWIDTHS}: @@ -7820,6 +7823,24 @@ brent ttyp0 286 dave ttyq4 1296000 @end example +Starting in @value{PVERSION} 4.2, this program could be rewritten to +specify @code{FIELDWIDTHS} like so: +@example +BEGIN @{ FIELDWIDTHS = "8 1:5 4:7 6 1:6 1:6 2:33" @} +@end example +This strips away some of the white space separating the fields. With such +a change, the program would produce the following results: + +@example +hzang ttyV3 50 +eklye ttyV5 0 +dportein ttyV6 107 +gierd ttyD3 1 +dave ttyD4 0 +brent ttyp0 286 +dave ttyq4 1296000 +@end example + Another (possibly more practical) example of fixed-width input data is the input from a deck of balloting cards. In some parts of the United States, voters mark their choices by punching holes in computer @@ -7845,8 +7866,10 @@ if (PROCINFO["FS"] == "FS") @var{regular field splitting} @dots{} else if (PROCINFO["FS"] == "FIELDWIDTHS") @var{fixed-width field splitting} @dots{} -else +else if (PROCINFO["FS"] == "FPAT") @var{content-based field splitting} @dots{} @ii{(see next @value{SECTION})} +else + @var{API input parser field splitting} @dots{} @ii{(advanced feature)} @end example This information is useful when writing a function @@ -7986,7 +8009,9 @@ To recap, @command{gawk} provides three independent methods to split input records into fields. The mechanism used is based on which of the three variables---@code{FS}, @code{FIELDWIDTHS}, or @code{FPAT}---was -last assigned to. +last assigned to. In addition, an API input parser may choose to +override the record parsing mechanism; please refer to @ref{Input Parsers} +for further information about this feature. @node Multiple Line @section Multiple-Line Records @@ -14972,6 +14997,9 @@ Its default value is @code{"%.6g"}. @item FIELDWIDTHS # A space-separated list of columns that tells @command{gawk} how to split input with fixed columnar boundaries. +Starting in @value{PVERSION} 4.2, each field width may optionally be +preceded by a colon-separated value specifying the number of characters to skip +before the field starts. Assigning a value to @code{FIELDWIDTHS} overrides the use of @code{FS} and @code{FPAT} for field splitting. @xref{Constant Size} for more information. @@ -15366,7 +15394,8 @@ The value of the @code{geteuid()} system call. This is @code{"FS"} if field splitting with @code{FS} is in effect, @code{"FIELDWIDTHS"} if field splitting with @code{FIELDWIDTHS} is in effect, -or @code{"FPAT"} if field matching with @code{FPAT} is in effect. +@code{"FPAT"} if field matching with @code{FPAT} is in effect, +or @code{"API"} if field splitting is controlled by an API input parser. @item PROCINFO["gid"] @cindex group ID of @command{gawk} user @@ -33165,7 +33194,8 @@ typedef struct awk_input @{ #define INVALID_HANDLE (-1) void *opaque; /* private data for input parsers */ int (*get_record)(char **out, struct awk_input *iobuf, - int *errcode, char **rt_start, size_t *rt_len); + int *errcode, char **rt_start, size_t *rt_len, + const awk_fieldwidth_info_t **field_width); ssize_t (*read_func)(); void (*close_func)(struct awk_input *iobuf); struct stat sbuf; /* stat buf */ @@ -33217,7 +33247,8 @@ is not required to use this pointer. @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ struct@ awk_input *iobuf, @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ int *errcode, @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ char **rt_start, -@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ size_t *rt_len); +@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ size_t *rt_len, +@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ const awk_fieldwidth_info_t **field_width); This function pointer should point to a function that creates the input records. Said function is the core of the input parser. Its behavior is described in the text following this list. @@ -33269,6 +33300,21 @@ If the concept of a ``record terminator'' makes sense, then data. Otherwise, @code{*rt_len} should be set to zero. @command{gawk} makes its own copy of this data, so the extension must manage this storage. + +@item const awk_fieldwidth_info_t **field_width +If @code{field_width} is not @code{NULL}, then @code{*field_width} will be initialized +to @code{NULL}, and the function may set it to point to a structure +supplying field width information to override the default +field parsing mechanism. Note that this structure will not +be copied by @command{gawk}; it must persist at least until the next call +to @code{get_record} or @code{close_func}. Note also that @code{field_width} is +@code{NULL} when @code{getline} is assigning the results to a variable, thus +field parsing is not needed. If the parser does set @code{*field_width}, +then @command{gawk} uses this layout to parse the input record, +and the @code{PROCINFO["FS"]} value will be @code{"API"} while this record +is active in @code{$0}. +The @code{awk_fieldwidth_info_t} data structure +is described below. @end table The return value is the length of the buffer pointed to by @@ -33327,6 +33373,50 @@ Register the input parser pointed to by @code{input_parser} with @command{gawk}. @end table +If you would like to override the default field parsing mechanism for a given +record, then you must populate an @code{awk_fieldwidth_info_t} structure, +which looks like this: + +@example +typedef struct @{ + awk_bool_t use_chars; /* false ==> use bytes */ + size_t nf; /* number of fields in record (NF) */ + struct awk_field_info @{ + size_t skip; /* amount to skip before field starts */ + size_t len; /* length of field */ + @} fields[1]; /* actual dimension should be nf */ +@} awk_fieldwidth_info_t; +@end example + +The fields are: + +@table @code +@item awk_bool_t use_chars; +Set this to @code{awk_true} if the field lengths are specified in terms +of potentially multi-byte characters, and set it to @code{awk_false} if +the lengths are in terms of bytes. +Performance will be better if the values are supplied in +terms of bytes. + +@item size_t nf; +Set this to the number of fields in the input record, i.e. @code{NF}. + +@item struct awk_field_info fields[nf]; +This is a variable-length array whose actual dimension should be @code{nf}. +For each field, the @code{skip} element should be set to the number +of characters or bytes, as controlled by the @code{use_chars} flag, +to skip before the start of this field. The @code{len} element provides +the length of the field. The values in @code{fields[0]} provide the information +for @code{$1}, and so on through the @code{fields[nf-1]} element containing the information for @code{$NF}. +@end table + +A convenience macro @code{awk_fieldwidth_info_size(NF)} is provided to +calculate the appropriate size of a variable-length +@code{awk_fieldwidth_info_t} structure containing @code{NF} fields. This can +be used as an argument to @code{malloc()} or in a union to allocate space +statically. Please refer to the @code{readdir_test} sample extension for an +example. + @node Output Wrappers @subsubsection Customized Output Wrappers @cindex customized output wrapper diff --git a/doc/gawktexi.in b/doc/gawktexi.in index d8e9654f..f4fe2596 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -7361,6 +7361,9 @@ variable @code{FIELDWIDTHS}. Each number specifies the width of the field, @emph{including} columns between fields. If you want to ignore the columns between fields, you can specify the width as a separate field that is subsequently ignored. +Or, starting in @value{PVERSION} 4.2, each field width may optionally be +preceded by a colon-separated value specifying the number of characters to skip +before the field starts. It is a fatal error to supply a field width that has a negative value. The following data is the output of the Unix @command{w} utility. It is useful to illustrate the use of @code{FIELDWIDTHS}: @@ -7420,6 +7423,24 @@ brent ttyp0 286 dave ttyq4 1296000 @end example +Starting in @value{PVERSION} 4.2, this program could be rewritten to +specify @code{FIELDWIDTHS} like so: +@example +BEGIN @{ FIELDWIDTHS = "8 1:5 4:7 6 1:6 1:6 2:33" @} +@end example +This strips away some of the white space separating the fields. With such +a change, the program would produce the following results: + +@example +hzang ttyV3 50 +eklye ttyV5 0 +dportein ttyV6 107 +gierd ttyD3 1 +dave ttyD4 0 +brent ttyp0 286 +dave ttyq4 1296000 +@end example + Another (possibly more practical) example of fixed-width input data is the input from a deck of balloting cards. In some parts of the United States, voters mark their choices by punching holes in computer @@ -7445,8 +7466,10 @@ if (PROCINFO["FS"] == "FS") @var{regular field splitting} @dots{} else if (PROCINFO["FS"] == "FIELDWIDTHS") @var{fixed-width field splitting} @dots{} -else +else if (PROCINFO["FS"] == "FPAT") @var{content-based field splitting} @dots{} @ii{(see next @value{SECTION})} +else + @var{API input parser field splitting} @dots{} @ii{(advanced feature)} @end example This information is useful when writing a function @@ -7586,7 +7609,9 @@ To recap, @command{gawk} provides three independent methods to split input records into fields. The mechanism used is based on which of the three variables---@code{FS}, @code{FIELDWIDTHS}, or @code{FPAT}---was -last assigned to. +last assigned to. In addition, an API input parser may choose to +override the record parsing mechanism; please refer to @ref{Input Parsers} +for further information about this feature. @node Multiple Line @section Multiple-Line Records @@ -14291,6 +14316,9 @@ Its default value is @code{"%.6g"}. @item FIELDWIDTHS # A space-separated list of columns that tells @command{gawk} how to split input with fixed columnar boundaries. +Starting in @value{PVERSION} 4.2, each field width may optionally be +preceded by a colon-separated value specifying the number of characters to skip +before the field starts. Assigning a value to @code{FIELDWIDTHS} overrides the use of @code{FS} and @code{FPAT} for field splitting. @xref{Constant Size} for more information. @@ -14685,7 +14713,8 @@ The value of the @code{geteuid()} system call. This is @code{"FS"} if field splitting with @code{FS} is in effect, @code{"FIELDWIDTHS"} if field splitting with @code{FIELDWIDTHS} is in effect, -or @code{"FPAT"} if field matching with @code{FPAT} is in effect. +@code{"FPAT"} if field matching with @code{FPAT} is in effect, +or @code{"API"} if field splitting is controlled by an API input parser. @item PROCINFO["gid"] @cindex group ID of @command{gawk} user @@ -32179,7 +32208,8 @@ typedef struct awk_input @{ #define INVALID_HANDLE (-1) void *opaque; /* private data for input parsers */ int (*get_record)(char **out, struct awk_input *iobuf, - int *errcode, char **rt_start, size_t *rt_len); + int *errcode, char **rt_start, size_t *rt_len, + const awk_fieldwidth_info_t **field_width); ssize_t (*read_func)(); void (*close_func)(struct awk_input *iobuf); struct stat sbuf; /* stat buf */ @@ -32231,7 +32261,8 @@ is not required to use this pointer. @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ struct@ awk_input *iobuf, @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ int *errcode, @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ char **rt_start, -@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ size_t *rt_len); +@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ size_t *rt_len, +@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ const awk_fieldwidth_info_t **field_width); This function pointer should point to a function that creates the input records. Said function is the core of the input parser. Its behavior is described in the text following this list. @@ -32283,6 +32314,21 @@ If the concept of a ``record terminator'' makes sense, then data. Otherwise, @code{*rt_len} should be set to zero. @command{gawk} makes its own copy of this data, so the extension must manage this storage. + +@item const awk_fieldwidth_info_t **field_width +If @code{field_width} is not @code{NULL}, then @code{*field_width} will be initialized +to @code{NULL}, and the function may set it to point to a structure +supplying field width information to override the default +field parsing mechanism. Note that this structure will not +be copied by @command{gawk}; it must persist at least until the next call +to @code{get_record} or @code{close_func}. Note also that @code{field_width} is +@code{NULL} when @code{getline} is assigning the results to a variable, thus +field parsing is not needed. If the parser does set @code{*field_width}, +then @command{gawk} uses this layout to parse the input record, +and the @code{PROCINFO["FS"]} value will be @code{"API"} while this record +is active in @code{$0}. +The @code{awk_fieldwidth_info_t} data structure +is described below. @end table The return value is the length of the buffer pointed to by @@ -32341,6 +32387,50 @@ Register the input parser pointed to by @code{input_parser} with @command{gawk}. @end table +If you would like to override the default field parsing mechanism for a given +record, then you must populate an @code{awk_fieldwidth_info_t} structure, +which looks like this: + +@example +typedef struct @{ + awk_bool_t use_chars; /* false ==> use bytes */ + size_t nf; /* number of fields in record (NF) */ + struct awk_field_info @{ + size_t skip; /* amount to skip before field starts */ + size_t len; /* length of field */ + @} fields[1]; /* actual dimension should be nf */ +@} awk_fieldwidth_info_t; +@end example + +The fields are: + +@table @code +@item awk_bool_t use_chars; +Set this to @code{awk_true} if the field lengths are specified in terms +of potentially multi-byte characters, and set it to @code{awk_false} if +the lengths are in terms of bytes. +Performance will be better if the values are supplied in +terms of bytes. + +@item size_t nf; +Set this to the number of fields in the input record, i.e. @code{NF}. + +@item struct awk_field_info fields[nf]; +This is a variable-length array whose actual dimension should be @code{nf}. +For each field, the @code{skip} element should be set to the number +of characters or bytes, as controlled by the @code{use_chars} flag, +to skip before the start of this field. The @code{len} element provides +the length of the field. The values in @code{fields[0]} provide the information +for @code{$1}, and so on through the @code{fields[nf-1]} element containing the information for @code{$NF}. +@end table + +A convenience macro @code{awk_fieldwidth_info_size(NF)} is provided to +calculate the appropriate size of a variable-length +@code{awk_fieldwidth_info_t} structure containing @code{NF} fields. This can +be used as an argument to @code{malloc()} or in a union to allocate space +statically. Please refer to the @code{readdir_test} sample extension for an +example. + @node Output Wrappers @subsubsection Customized Output Wrappers @cindex customized output wrapper |