diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ChangeLog | 17 | ||||
| -rw-r--r-- | doc/awkcard.in | 8 | ||||
| -rw-r--r-- | doc/gawk.1 | 15 | ||||
| -rw-r--r-- | doc/gawk.info | 1201 | ||||
| -rw-r--r-- | doc/gawk.texi | 100 | ||||
| -rw-r--r-- | doc/gawktexi.in | 100 |
6 files changed, 866 insertions, 575 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index 0a04a64b..7b956c44 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,10 @@ +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 +16,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..d33e0180 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 ... (*note Input Parsers::) 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' will be + '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' will use 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,47 @@ 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 the '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. And the 'len' + element provides the length of the field. The values in + 'fields[0]' provide the information for the '$1' field, 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 sample extension 'readdir_test' for an +example. + File: gawk.info, Node: Output Wrappers, Next: Two-way processors, Prev: Input Parsers, Up: Registration Functions @@ -33052,8 +33135,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 +33325,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 +33524,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 +33543,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 +33560,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 +33568,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 +33731,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 +33782,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 +33883,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 +33907,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 +33917,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 +33987,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 +34014,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 +34022,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 +34045,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 +34063,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 +34165,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 +34205,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 +34280,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 +34393,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 +34403,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 +34465,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 +34478,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 +34536,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 +34562,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 +34576,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 +34636,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 +34656,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 +34779,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 +34794,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 +34825,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 +34841,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 +34910,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 +34952,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 +35002,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 +35023,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 +35050,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 +35077,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 +35136,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 +35221,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 +35267,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 +35284,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 +35292,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 +35330,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 +35483,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 +35643,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 Content235768 +Ref: Splitting By Content-Footnote-1239908 +Node: Multiple Line240071 +Ref: Multiple Line-Footnote-1245953 +Node: Getline246132 +Node: Plain Getline248599 +Node: Getline/Variable251238 +Node: Getline/File252387 +Node: Getline/Variable/File253773 +Ref: Getline/Variable/File-Footnote-1255376 +Node: Getline/Pipe255464 +Node: Getline/Variable/Pipe258169 +Node: Getline/Coprocess259302 +Node: Getline/Variable/Coprocess260567 +Node: Getline Notes261307 +Node: Getline Summary264102 +Ref: table-getline-variants264524 +Node: Read Timeout265272 +Ref: Read Timeout-Footnote-1269178 +Node: Retrying Input269236 +Node: Command-line directories270435 +Node: Input Summary271341 +Node: Input Exercises274513 +Node: Printing275241 +Node: Print277075 +Node: Print Examples278532 +Node: Output Separators281312 +Node: OFMT283329 +Node: Printf284685 +Node: Basic Printf285470 +Node: Control Letters287044 +Node: Format Modifiers291032 +Node: Printf Examples297047 +Node: Redirection299533 +Node: Special FD306374 +Ref: Special FD-Footnote-1309542 +Node: Special Files309616 +Node: Other Inherited Files310233 +Node: Special Network311234 +Node: Special Caveats312094 +Node: Close Files And Pipes313043 +Ref: table-close-pipe-return-values319950 +Ref: Close Files And Pipes-Footnote-1320733 +Ref: Close Files And Pipes-Footnote-2320881 +Node: Nonfatal321033 +Node: Output Summary323358 +Node: Output Exercises324580 +Node: Expressions325259 +Node: Values326447 +Node: Constants327125 +Node: Scalar Constants327816 +Ref: Scalar Constants-Footnote-1328680 +Node: Nondecimal-numbers328930 +Node: Regexp Constants331931 +Node: Using Constant Regexps332457 +Node: Standard Regexp Constants333079 +Node: Strong Regexp Constants336267 +Node: Variables339225 +Node: Using Variables339882 +Node: Assignment Options341792 +Node: Conversion343665 +Node: Strings And Numbers344189 +Ref: Strings And Numbers-Footnote-1347252 +Node: Locale influences conversions347361 +Ref: table-locale-affects350119 +Node: All Operators350737 +Node: Arithmetic Ops351366 +Node: Concatenation353872 +Ref: Concatenation-Footnote-1356719 +Node: Assignment Ops356826 +Ref: table-assign-ops361817 +Node: Increment Ops363130 +Node: Truth Values and Conditions366590 +Node: Truth Values367664 +Node: Typing and Comparison368712 +Node: Variable Typing369532 +Ref: Variable Typing-Footnote-1375995 +Ref: Variable Typing-Footnote-2376067 +Node: Comparison Operators376144 +Ref: table-relational-ops376563 +Node: POSIX String Comparison380058 +Ref: POSIX String Comparison-Footnote-1381753 +Ref: POSIX String Comparison-Footnote-2381892 +Node: Boolean Ops381976 +Ref: Boolean Ops-Footnote-1386458 +Node: Conditional Exp386550 +Node: Function Calls388286 +Node: Precedence392163 +Node: Locales395822 +Node: Expressions Summary397454 +Node: Patterns and Actions400027 +Node: Pattern Overview401147 +Node: Regexp Patterns402824 +Node: Expression Patterns403366 +Node: Ranges407147 +Node: BEGIN/END410255 +Node: Using BEGIN/END411016 +Ref: Using BEGIN/END-Footnote-1413752 +Node: I/O And BEGIN/END413858 +Node: BEGINFILE/ENDFILE416172 +Node: Empty419079 +Node: Using Shell Variables419396 +Node: Action Overview421670 +Node: Statements423995 +Node: If Statement425843 +Node: While Statement427338 +Node: Do Statement429366 +Node: For Statement430514 +Node: Switch Statement433672 +Node: Break Statement436058 +Node: Continue Statement438150 +Node: Next Statement439977 +Node: Nextfile Statement442360 +Node: Exit Statement445012 +Node: Built-in Variables447415 +Node: User-modified448548 +Node: Auto-set456315 +Ref: Auto-set-Footnote-1471043 +Ref: Auto-set-Footnote-2471249 +Node: ARGC and ARGV471305 +Node: Pattern Action Summary475518 +Node: Arrays477948 +Node: Array Basics479277 +Node: Array Intro480121 +Ref: figure-array-elements482096 +Ref: Array Intro-Footnote-1484800 +Node: Reference to Elements484928 +Node: Assigning Elements487392 +Node: Array Example487883 +Node: Scanning an Array489642 +Node: Controlling Scanning492664 +Ref: Controlling Scanning-Footnote-1498063 +Node: Numeric Array Subscripts498379 +Node: Uninitialized Subscripts500563 +Node: Delete502182 +Ref: Delete-Footnote-1504934 +Node: Multidimensional504991 +Node: Multiscanning508086 +Node: Arrays of Arrays509677 +Node: Arrays Summary514444 +Node: Functions516537 +Node: Built-in517575 +Node: Calling Built-in518656 +Node: Numeric Functions520652 +Ref: Numeric Functions-Footnote-1525485 +Ref: Numeric Functions-Footnote-2525842 +Ref: Numeric Functions-Footnote-3525890 +Node: String Functions526162 +Ref: String Functions-Footnote-1549666 +Ref: String Functions-Footnote-2549794 +Ref: String Functions-Footnote-3550042 +Node: Gory Details550129 +Ref: table-sub-escapes551920 +Ref: table-sub-proposed553439 +Ref: table-posix-sub554802 +Ref: table-gensub-escapes556343 +Ref: Gory Details-Footnote-1557166 +Node: I/O Functions557320 +Ref: table-system-return-values563902 +Ref: I/O Functions-Footnote-1565882 +Ref: I/O Functions-Footnote-2566030 +Node: Time Functions566150 +Ref: Time Functions-Footnote-1576817 +Ref: Time Functions-Footnote-2576885 +Ref: Time Functions-Footnote-3577043 +Ref: Time Functions-Footnote-4577154 +Ref: Time Functions-Footnote-5577266 +Ref: Time Functions-Footnote-6577493 +Node: Bitwise Functions577759 +Ref: table-bitwise-ops578353 +Ref: Bitwise Functions-Footnote-1584386 +Ref: Bitwise Functions-Footnote-2584559 +Node: Type Functions584750 +Node: I18N Functions587425 +Node: User-defined589076 +Node: Definition Syntax589881 +Ref: Definition Syntax-Footnote-1595568 +Node: Function Example595639 +Ref: Function Example-Footnote-1598561 +Node: Function Caveats598583 +Node: Calling A Function599101 +Node: Variable Scope600059 +Node: Pass By Value/Reference603053 +Node: Return Statement606552 +Node: Dynamic Typing609531 +Node: Indirect Calls610461 +Ref: Indirect Calls-Footnote-1620712 +Node: Functions Summary620840 +Node: Library Functions623545 +Ref: Library Functions-Footnote-1627152 +Ref: Library Functions-Footnote-2627295 +Node: Library Names627466 +Ref: Library Names-Footnote-1630926 +Ref: Library Names-Footnote-2631149 +Node: General Functions631235 +Node: Strtonum Function632338 +Node: Assert Function635360 +Node: Round Function638686 +Node: Cliff Random Function640227 +Node: Ordinal Functions641243 +Ref: Ordinal Functions-Footnote-1644306 +Ref: Ordinal Functions-Footnote-2644558 +Node: Join Function644768 +Ref: Join Function-Footnote-1646538 +Node: Getlocaltime Function646738 +Node: Readfile Function650480 +Node: Shell Quoting652452 +Node: Data File Management653853 +Node: Filetrans Function654485 +Node: Rewind Function658581 +Node: File Checking660487 +Ref: File Checking-Footnote-1661821 +Node: Empty Files662022 +Node: Ignoring Assigns664001 +Node: Getopt Function665551 +Ref: Getopt Function-Footnote-1677020 +Node: Passwd Functions677220 +Ref: Passwd Functions-Footnote-1686059 +Node: Group Functions686147 +Ref: Group Functions-Footnote-1694045 +Node: Walking Arrays694252 +Node: Library Functions Summary697260 +Node: Library Exercises698666 +Node: Sample Programs699131 +Node: Running Examples699901 +Node: Clones700629 +Node: Cut Program701853 +Node: Egrep Program711782 +Ref: Egrep Program-Footnote-1719294 +Node: Id Program719404 +Node: Split Program723084 +Ref: Split Program-Footnote-1726543 +Node: Tee Program726672 +Node: Uniq Program729462 +Node: Wc Program736888 +Ref: Wc Program-Footnote-1741143 +Node: Miscellaneous Programs741237 +Node: Dupword Program742450 +Node: Alarm Program744480 +Node: Translate Program749335 +Ref: Translate Program-Footnote-1753900 +Node: Labels Program754170 +Ref: Labels Program-Footnote-1757521 +Node: Word Sorting757605 +Node: History Sorting761677 +Node: Extract Program763512 +Node: Simple Sed771041 +Node: Igawk Program774115 +Ref: Igawk Program-Footnote-1788446 +Ref: Igawk Program-Footnote-2788648 +Ref: Igawk Program-Footnote-3788770 +Node: Anagram Program788885 +Node: Signature Program791947 +Node: Programs Summary793194 +Node: Programs Exercises794408 +Ref: Programs Exercises-Footnote-1798537 +Node: Advanced Features798628 +Node: Nondecimal Data800618 +Node: Array Sorting802209 +Node: Controlling Array Traversal802909 +Ref: Controlling Array Traversal-Footnote-1811276 +Node: Array Sorting Functions811394 +Ref: Array Sorting Functions-Footnote-1816485 +Node: Two-way I/O816681 +Ref: Two-way I/O-Footnote-1823232 +Ref: Two-way I/O-Footnote-2823419 +Node: TCP/IP Networking823501 +Node: Profiling826619 +Ref: Profiling-Footnote-1835291 +Node: Advanced Features Summary835614 +Node: Internationalization837458 +Node: I18N and L10N838938 +Node: Explaining gettext839625 +Ref: Explaining gettext-Footnote-1845517 +Ref: Explaining gettext-Footnote-2845702 +Node: Programmer i18n845867 +Ref: Programmer i18n-Footnote-1850816 +Node: Translator i18n850865 +Node: String Extraction851659 +Ref: String Extraction-Footnote-1852791 +Node: Printf Ordering852877 +Ref: Printf Ordering-Footnote-1855663 +Node: I18N Portability855727 +Ref: I18N Portability-Footnote-1858183 +Node: I18N Example858246 +Ref: I18N Example-Footnote-1861052 +Node: Gawk I18N861125 +Node: I18N Summary861770 +Node: Debugger863111 +Node: Debugging864133 +Node: Debugging Concepts864574 +Node: Debugging Terms866383 +Node: Awk Debugging868958 +Node: Sample Debugging Session869864 +Node: Debugger Invocation870398 +Node: Finding The Bug871784 +Node: List of Debugger Commands878262 +Node: Breakpoint Control879595 +Node: Debugger Execution Control883289 +Node: Viewing And Changing Data886651 +Node: Execution Stack890025 +Node: Debugger Info891662 +Node: Miscellaneous Debugger Commands895733 +Node: Readline Support900821 +Node: Limitations901717 +Node: Debugging Summary903826 +Node: Arbitrary Precision Arithmetic905105 +Node: Computer Arithmetic906521 +Ref: table-numeric-ranges910112 +Ref: Computer Arithmetic-Footnote-1910834 +Node: Math Definitions910891 +Ref: table-ieee-formats914205 +Ref: Math Definitions-Footnote-1914808 +Node: MPFR features914913 +Node: FP Math Caution916630 +Ref: FP Math Caution-Footnote-1917702 +Node: Inexactness of computations918071 +Node: Inexact representation919031 +Node: Comparing FP Values920391 +Node: Errors accumulate921473 +Node: Getting Accuracy922906 +Node: Try To Round925616 +Node: Setting precision926515 +Ref: table-predefined-precision-strings927212 +Node: Setting the rounding mode929042 +Ref: table-gawk-rounding-modes929416 +Ref: Setting the rounding mode-Footnote-1932824 +Node: Arbitrary Precision Integers933003 +Ref: Arbitrary Precision Integers-Footnote-1937920 +Node: POSIX Floating Point Problems938069 +Ref: POSIX Floating Point Problems-Footnote-1941951 +Node: Floating point summary941989 +Node: Dynamic Extensions944179 +Node: Extension Intro945732 +Node: Plugin License946998 +Node: Extension Mechanism Outline947795 +Ref: figure-load-extension948234 +Ref: figure-register-new-function949799 +Ref: figure-call-new-function950891 +Node: Extension API Description952953 +Node: Extension API Functions Introduction954595 +Node: General Data Types959929 +Ref: General Data Types-Footnote-1967134 +Node: Memory Allocation Functions967433 +Ref: Memory Allocation Functions-Footnote-1970278 +Node: Constructor Functions970377 +Node: Registration Functions973376 +Node: Extension Functions974061 +Node: Exit Callback Functions979274 +Node: Extension Version String980524 +Node: Input Parsers981187 +Node: Output Wrappers993921 +Node: Two-way processors998433 +Node: Printing Messages1000698 +Ref: Printing Messages-Footnote-11001869 +Node: Updating ERRNO1002022 +Node: Requesting Values1002761 +Ref: table-value-types-returned1003498 +Node: Accessing Parameters1004434 +Node: Symbol Table Access1005669 +Node: Symbol table by name1006181 +Node: Symbol table by cookie1007970 +Ref: Symbol table by cookie-Footnote-11012155 +Node: Cached values1012219 +Ref: Cached values-Footnote-11015755 +Node: Array Manipulation1015846 +Ref: Array Manipulation-Footnote-11016937 +Node: Array Data Types1016974 +Ref: Array Data Types-Footnote-11019632 +Node: Array Functions1019724 +Node: Flattening Arrays1024123 +Node: Creating Arrays1031064 +Node: Redirection API1035833 +Node: Extension API Variables1038675 +Node: Extension Versioning1039308 +Ref: gawk-api-version1039745 +Node: Extension API Informational Variables1041473 +Node: Extension API Boilerplate1042537 +Node: Changes from API V11046399 +Node: Finding Extensions1047059 +Node: Extension Example1047618 +Node: Internal File Description1048416 +Node: Internal File Ops1052496 +Ref: Internal File Ops-Footnote-11063896 +Node: Using Internal File Ops1064036 +Ref: Using Internal File Ops-Footnote-11066419 +Node: Extension Samples1066693 +Node: Extension Sample File Functions1068222 +Node: Extension Sample Fnmatch1075871 +Node: Extension Sample Fork1077358 +Node: Extension Sample Inplace1078576 +Node: Extension Sample Ord1081786 +Node: Extension Sample Readdir1082622 +Ref: table-readdir-file-types1083511 +Node: Extension Sample Revout1084316 +Node: Extension Sample Rev2way1084905 +Node: Extension Sample Read write array1085645 +Node: Extension Sample Readfile1087587 +Node: Extension Sample Time1088682 +Node: Extension Sample API Tests1090030 +Node: gawkextlib1090522 +Node: Extension summary1092969 +Node: Extension Exercises1096671 +Node: Language History1098169 +Node: V7/SVR3.11099825 +Node: SVR41101977 +Node: POSIX1103411 +Node: BTL1104790 +Node: POSIX/GNU1105519 +Node: Feature History1111411 +Node: Common Extensions1125781 +Node: Ranges and Locales1127064 +Ref: Ranges and Locales-Footnote-11131680 +Ref: Ranges and Locales-Footnote-21131707 +Ref: Ranges and Locales-Footnote-31131942 +Node: Contributors1132163 +Node: History summary1137723 +Node: Installation1139103 +Node: Gawk Distribution1140047 +Node: Getting1140531 +Node: Extracting1141492 +Node: Distribution contents1143130 +Node: Unix Installation1149472 +Node: Quick Installation1150154 +Node: Shell Startup Files1152568 +Node: Additional Configuration Options1153657 +Node: Configuration Philosophy1155462 +Node: Non-Unix Installation1157831 +Node: PC Installation1158291 +Node: PC Binary Installation1159129 +Node: PC Compiling1159564 +Node: PC Using1160681 +Node: Cygwin1163726 +Node: MSYS1164496 +Node: VMS Installation1164997 +Node: VMS Compilation1165788 +Ref: VMS Compilation-Footnote-11167017 +Node: VMS Dynamic Extensions1167075 +Node: VMS Installation Details1168760 +Node: VMS Running1171013 +Node: VMS GNV1175292 +Node: VMS Old Gawk1176027 +Node: Bugs1176498 +Node: Bug address1177161 +Node: Usenet1179558 +Node: Maintainers1180335 +Node: Other Versions1181711 +Node: Installation summary1188295 +Node: Notes1189330 +Node: Compatibility Mode1190195 +Node: Additions1190977 +Node: Accessing The Source1191902 +Node: Adding Code1193337 +Node: New Ports1199555 +Node: Derived Files1204043 +Ref: Derived Files-Footnote-11209528 +Ref: Derived Files-Footnote-21209563 +Ref: Derived Files-Footnote-31210161 +Node: Future Extensions1210275 +Node: Implementation Limitations1210933 +Node: Extension Design1212116 +Node: Old Extension Problems1213270 +Ref: Old Extension Problems-Footnote-11214788 +Node: Extension New Mechanism Goals1214845 +Ref: Extension New Mechanism Goals-Footnote-11218209 +Node: Extension Other Design Decisions1218398 +Node: Extension Future Growth1220511 +Node: Old Extension Mechanism1221347 +Node: Notes summary1223110 +Node: Basic Concepts1224292 +Node: Basic High Level1224973 +Ref: figure-general-flow1225255 +Ref: figure-process-flow1225940 +Ref: Basic High Level-Footnote-11229241 +Node: Basic Data Typing1229426 +Node: Glossary1232754 +Node: Copying1264701 +Node: GNU Free Documentation License1302240 +Node: Index1327358 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 658ac17e..f2d1751c 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{(@pxref{Input Parsers})} @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 @pxref{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} will +be @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} will use 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 the @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. And the @code{len} element provides +the length of the field. The values in @code{fields[0]} provide the information +for the @code{$1} field, 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 sample extension @code{readdir_test} 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..78a28230 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{(@pxref{Input Parsers})} @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 @pxref{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} will +be @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} will use 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 the @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. And the @code{len} element provides +the length of the field. The values in @code{fields[0]} provide the information +for the @code{$1} field, 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 sample extension @code{readdir_test} for an +example. + @node Output Wrappers @subsubsection Customized Output Wrappers @cindex customized output wrapper |