1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1989 AT&T
44 .\" Copyright 1992, X/Open Company Limited All Rights Reserved
45 .\" Portions Copyright (c) 2005, 2006 Sun Microsystems, Inc. All Rights Reserved
46 .\" Copyright 2018, Joyent, Inc.
47 .\"
48 .TH NAWK 1 "Nov 9, 2018"
49 .SH NAME
50 nawk \- pattern scanning and processing language
51 .SH SYNOPSIS
52 .LP
53 .nf
54 \fB/usr/bin/nawk\fR [\fB-F\fR \fIERE\fR] [\fB-v\fR \fIassignment\fR] \fI\&'program'\fR | \fB-f\fR \fIprogfile\fR...
55 [\fIargument\fR]...
56 .fi
57
58 .LP
59 .nf
60 \fB/usr/xpg4/bin/awk\fR [\fB-F\fR \fIERE\fR] [\fB-v\fR \fIassignment\fR]... \fI\&'program'\fR | \fB-f\fR \fIprogfile\fR...
61 [\fIargument\fR]...
62 .fi
63
64 .SH DESCRIPTION
65 .LP
66 The \fB/usr/bin/nawk\fR and \fB/usr/xpg4/bin/awk\fR utilities execute
67 \fIprogram\fRs written in the \fBnawk\fR programming language, which is
68 specialized for textual data manipulation. A \fBnawk\fR \fIprogram\fR is a
69 sequence of patterns and corresponding actions. The string specifying
70 \fIprogram\fR must be enclosed in single quotes (') to protect it from
71 interpretation by the shell. The sequence of pattern - action statements can be
72 specified in the command line as \fIprogram\fR or in one, or more, file(s)
73 specified by the \fB-f\fR\fIprogfile\fR option. When input is read that matches
74 a pattern, the action associated with the pattern is performed.
75 .sp
76 .LP
77 Input is interpreted as a sequence of records. By default, a record is a line,
78 but this can be changed by using the \fBRS\fR built-in variable. Each record of
79 input is matched to each pattern in the \fIprogram\fR. For each pattern
80 matched, the associated action is executed.
81 .sp
82 .LP
83 The \fBnawk\fR utility interprets each input record as a sequence of fields
84 where, by default, a field is a string of non-blank characters. This default
85 white-space field delimiter (blanks and/or tabs) can be changed by using the
86 \fBFS\fR built-in variable or the \fB-F\fR\fIERE\fR option. The \fBnawk\fR
87 utility denotes the first field in a record \fB$1\fR, the second \fB$2\fR, and
88 so forth. The symbol \fB$0\fR refers to the entire record; setting any other
89 field causes the reevaluation of \fB$0\fR. Assigning to \fB$0\fR resets the
90 values of all fields and the \fBNF\fR built-in variable.
91
92 .SH OPTIONS
93 .LP
94 The following options are supported:
95 .sp
96 .ne 2
97 .na
98 \fB\fB-F\fR \fIERE\fR\fR
99 .ad
100 .RS 17n
101 Define the input field separator to be the extended regular expression
102 \fIERE\fR, before any input is read (can be a character).
103 .RE
104
105 .sp
106 .ne 2
107 .na
108 \fB\fB-f\fR \fIprogfile\fR\fR
109 .ad
110 .RS 17n
111 Specifies the pathname of the file \fIprogfile\fR containing a \fBnawk\fR
112 program. If multiple instances of this option are specified, the concatenation
113 of the files specified as \fIprogfile\fR in the order specified is the
114 \fBnawk\fR program. The \fBnawk\fR program can alternatively be specified in
115 the command line as a single argument.
116 .RE
117
118 .sp
119 .ne 2
120 .na
121 \fB\fB-v\fR \fIassignment\fR\fR
122 .ad
123 .RS 17n
124 The \fIassignment\fR argument must be in the same form as an \fIassignment\fR
125 operand. The assignment is of the form \fIvar=value\fR, where \fIvar\fR is the
126 name of one of the variables described below. The specified assignment occurs
127 before executing the \fBnawk\fR program, including the actions associated with
128 \fBBEGIN\fR patterns (if any). Multiple occurrences of this option can be
129 specified.
130 .RE
131
132 .sp
133 .ne 2
134 .na
135 \fB\fB-safe\fR\fR
136 .ad
137 .RS 17n
138 When passed to \fBnawk\fR, this flag will prevent the program from opening new
139 files or running child processes. The \fBENVIRON\fR array will also not be
140 initialized.
141 .RE
142
143 .SH OPERANDS
144 .LP
145 The following operands are supported:
146 .sp
147 .ne 2
148 .na
149 \fB\fIprogram\fR\fR
150 .ad
151 .RS 12n
152 If no \fB-f\fR option is specified, the first operand to \fBnawk\fR is the text
153 of the \fBnawk\fR program. The application supplies the \fIprogram\fR operand
154 as a single argument to \fBnawk.\fR If the text does not end in a newline
155 character, \fBnawk\fR interprets the text as if it did.
156 .RE
157
158 .sp
159 .ne 2
160 .na
161 \fB\fIargument\fR\fR
162 .ad
163 .RS 12n
164 Either of the following two types of \fIargument\fR can be intermixed:
165 .sp
166 .ne 2
167 .na
168 \fB\fIfile\fR\fR
169 .ad
170 .RS 14n
171 A pathname of a file that contains the input to be read, which is matched
172 against the set of patterns in the program. If no \fIfile\fR operands are
173 specified, or if a \fIfile\fR operand is \fB\(mi\fR, the standard input is
174 used.
175 .RE
176
177 .sp
178 .ne 2
179 .na
180 \fB\fIassignment\fR\fR
181 .ad
182 .RS 14n
183 An operand that begins with an underscore or alphabetic character from the
184 portable character set, followed by a sequence of underscores, digits and
185 alphabetics from the portable character set, followed by the \fB=\fR character
186 specifies a variable assignment rather than a pathname. The characters before
187 the \fB=\fR represent the name of a \fBnawk\fR variable. If that name is a
188 \fBnawk\fR reserved word, the behavior is undefined. The characters following
189 the equal sign is interpreted as if they appeared in the \fBnawk\fR program
190 preceded and followed by a double-quote (\fB"\fR) character, as a \fBSTRING\fR
191 token , except that if the last character is an unescaped backslash, it is
192 interpreted as a literal backslash rather than as the first character of the
193 sequence \fB\e\fR\&.. The variable is assigned the value of that \fBSTRING\fR
194 token. If the value is considered a \fInumeric\fRstring\fI,\fR the variable is
195 assigned its numeric value. Each such variable assignment is performed just
196 before the processing of the following \fIfile\fR, if any. Thus, an assignment
197 before the first \fBfile\fR argument is executed after the \fBBEGIN\fR actions
198 (if any), while an assignment after the last \fIfile\fR argument is executed
199 before the \fBEND\fR actions (if any). If there are no \fIfile\fR arguments,
200 assignments are executed before processing the standard input.
201 .RE
202
203 .RE
204
205 .SH INPUT FILES
206 .LP
207 Input files to the \fBnawk\fR program from any of the following sources:
208 .RS +4
209 .TP
210 .ie t \(bu
211 .el o
212 any \fIfile\fR operands or their equivalents, achieved by modifying the
213 \fBnawk\fR variables \fBARGV\fR and \fBARGC\fR
214 .RE
215 .RS +4
216 .TP
217 .ie t \(bu
218 .el o
219 standard input in the absence of any \fIfile\fR operands
220 .RE
221 .RS +4
222 .TP
223 .ie t \(bu
224 .el o
225 arguments to the \fBgetline\fR function
226 .RE
227 .sp
228 .LP
229 must be text files. Whether the variable \fBRS\fR is set to a value other than
230 a newline character or not, for these files, implementations support records
231 terminated with the specified separator up to \fB{LINE_MAX}\fR bytes and can
232 support longer records.
233 .sp
234 .LP
235 If \fB-\fR\fBf\fR \fIprogfile\fR is specified, the files named by each of the
236 \fIprogfile\fR option-arguments must be text files containing an \fBnawk\fR
237 program.
238 .sp
239 .LP
240 The standard input are used only if no \fIfile\fR operands are specified, or if
241 a \fIfile\fR operand is \fB\(mi\fR\&.
242
243 .SH EXTENDED DESCRIPTION
244 .LP
245 A \fBnawk\fR program is composed of pairs of the form:
246 .sp
247 .in +2
248 .nf
249 pattern { \fIaction\fR }
250 .fi
251 .in -2
252
253 .sp
254 .LP
255 Either the pattern or the action (including the enclosing brace characters) can
256 be omitted. Pattern-action statements are separated by a semicolon or by a
257 newline.
258 .sp
259 .LP
260 A missing pattern matches any record of input, and a missing action is
261 equivalent to an action that writes the matched record of input to standard
262 output.
263 .sp
264 .LP
265 Execution of the \fBnawk\fR program starts by first executing the actions
266 associated with all \fBBEGIN\fR patterns in the order they occur in the
267 program. Then each \fIfile\fR operand (or standard input if no files were
268 specified) is processed by reading data from the file until a record separator
269 is seen (a newline character by default), splitting the current record into
270 fields using the current value of \fBFS\fR, evaluating each pattern in the
271 program in the order of occurrence, and executing the action associated with
272 each pattern that matches the current record. The action for a matching pattern
273 is executed before evaluating subsequent patterns. Last, the actions associated
274 with all \fBEND\fR patterns is executed in the order they occur in the program.
275
276 .SS "Expressions in nawk"
277 .LP
278 Expressions describe computations used in \fIpatterns\fR and \fIactions\fR. In
279 the following table, valid expression operations are given in groups from
280 highest precedence first to lowest precedence last, with equal-precedence
281 operators grouped between horizontal lines. In expression evaluation, where the
282 grammar is formally ambiguous, higher precedence operators are evaluated before
283 lower precedence operators. In this table \fIexpr,\fR \fIexpr1,\fR
284 \fIexpr2,\fR and \fIexpr3\fR represent any expression, while \fIlvalue\fR
285 represents any entity that can be assigned to (that is, on the left side of an
286 assignment operator).
287 .sp
288
289 .sp
290 .TS
291 c c c c
292 l l l l .
293 \fBSyntax\fR \fBName\fR \fBType of Result\fR \fBAssociativity\fR
294 _
295 ( \fIexpr\fR ) Grouping type of \fIexpr\fR n/a
296 _
297 $\fIexpr\fR Field reference string n/a
298 _
299 ++ \fIlvalue\fR Pre-increment numeric n/a
300 \(mi\(mi \fIlvalue\fR Pre-decrement numeric n/a
301 \fIlvalue\fR ++ Post-increment numeric n/a
302 \fIlvalue\fR \(mi\(mi Post-decrement numeric n/a
303 _
304 \fIexpr\fR ^ \fIexpr\fR Exponentiation numeric right
305 _
306 ! \fIexpr\fR Logical not numeric n/a
307 + \fIexpr\fR Unary plus numeric n/a
308 \(mi \fIexpr\fR Unary minus numeric n/a
309 _
310 \fIexpr\fR * \fIexpr\fR Multiplication numeric left
311 \fIexpr\fR / \fIexpr\fR Division numeric left
312 \fIexpr\fR % \fIexpr\fR Modulus numeric left
313 _
314 \fIexpr\fR + \fIexpr\fR Addition numeric left
315 \fIexpr\fR \(mi \fIexpr\fR Subtraction numeric left
316 _
317 \fIexpr\fR \fIexpr\fR String concatenation string left
318 _
319 \fIexpr\fR < \fIexpr\fR Less than numeric none
320 \fIexpr\fR <= \fIexpr\fR Less than or equal to numeric none
321 \fIexpr\fR != \fIexpr\fR Not equal to numeric none
322 \fIexpr\fR == \fIexpr\fR Equal to numeric none
323 \fIexpr\fR > \fIexpr\fR Greater than numeric none
324 \fIexpr\fR >= \fIexpr\fR Greater than or equal to numeric none
325 _
326 \fIexpr\fR ~ \fIexpr\fR ERE match numeric none
327 \fIexpr\fR !~ \fIexpr\fR ERE non-match numeric none
328 _
329 \fIexpr\fR in array Array membership numeric left
330 ( \fIindex\fR ) in Multi-dimension array numeric left
331 \fIarray\fR membership
332 _
333 \fBexpr\fR && \fIexpr\fR Logical AND numeric left
334 _
335 \fBexpr\fR |\|| \fIexpr\fR Logical OR numeric left
336 _
337 \fIexpr1\fR ? \fIexpr2\fR Conditional expression type of selected right
338 : \fIexpr3\fR \fIexpr2\fR or \fIexpr3\fR
339 _
340 \fIlvalue\fR ^= \fIexpr\fR Exponentiation numeric right
341 assignment
342 \fIlvalue\fR %= \fIexpr\fR Modulus assignment numeric right
343 \fIlvalue\fR *= \fIexpr\fR Multiplication numeric right
344 assignment
345 \fIlvalue\fR /= \fIexpr\fR Division assignment numeric right
346 \fIlvalue\fR += \fIexpr\fR Addition assignment numeric right
347 \fIlvalue\fR \(mi= \fIexpr\fR Subtraction assignment numeric right
348 \fIlvalue\fR = \fIexpr\fR Assignment type of \fIexpr\fR right
349 .TE
350
351 .sp
352 .LP
353 Each expression has either a string value, a numeric value or both. Except as
354 stated for specific contexts, the value of an expression is implicitly
355 converted to the type needed for the context in which it is used. A string
356 value is converted to a numeric value by the equivalent of the following calls:
357 .sp
358 .in +2
359 .nf
360 setlocale(LC_NUMERIC, "");
361 \fInumeric_value\fR = atof(\fIstring_value\fR);
362 .fi
363 .in -2
364
365 .sp
366 .LP
367 A numeric value that is exactly equal to the value of an integer is converted
368 to a string by the equivalent of a call to the \fBsprintf\fR function with the
369 string \fB%d\fR as the \fBfmt\fR argument and the numeric value being converted
370 as the first and only \fIexpr\fR argument. Any other numeric value is
371 converted to a string by the equivalent of a call to the \fBsprintf\fR function
372 with the value of the variable \fBCONVFMT\fR as the \fBfmt\fR argument and the
373 numeric value being converted as the first and only \fIexpr\fR argument.
374 .sp
375 .LP
376 A string value is considered to be a \fInumeric string\fR in the following
377 case:
378 .RS +4
379 .TP
380 1.
381 Any leading and trailing blank characters is ignored.
382 .RE
383 .RS +4
384 .TP
385 2.
386 If the first unignored character is a \fB+\fR or \fB\(mi\fR, it is ignored.
387 .RE
388 .RS +4
389 .TP
390 3.
391 If the remaining unignored characters would be lexically recognized as a
392 \fBNUMBER\fR token, the string is considered a \fInumeric string\fR.
393 .RE
394 .sp
395 .LP
396 If a \fB\(mi\fR character is ignored in the above steps, the numeric value of
397 the \fInumeric string\fR is the negation of the numeric value of the recognized
398 \fBNUMBER\fR token. Otherwise the numeric value of the \fInumeric string\fR is
399 the numeric value of the recognized \fBNUMBER\fR token. Whether or not a string
400 is a \fInumeric string\fR is relevant only in contexts where that term is used
401 in this section.
402 .sp
403 .LP
404 When an expression is used in a Boolean context, if it has a numeric value, a
405 value of zero is treated as false and any other value is treated as true.
406 Otherwise, a string value of the null string is treated as false and any other
407 value is treated as true. A Boolean context is one of the following:
408 .RS +4
409 .TP
410 .ie t \(bu
411 .el o
412 the first subexpression of a conditional expression.
413 .RE
414 .RS +4
415 .TP
416 .ie t \(bu
417 .el o
418 an expression operated on by logical NOT, logical \fBAND,\fR or logical OR.
419 .RE
420 .RS +4
421 .TP
422 .ie t \(bu
423 .el o
424 the second expression of a \fBfor\fR statement.
425 .RE
426 .RS +4
427 .TP
428 .ie t \(bu
429 .el o
430 the expression of an \fBif\fR statement.
431 .RE
432 .RS +4
433 .TP
434 .ie t \(bu
435 .el o
436 the expression of the \fBwhile\fR clause in either a \fBwhile\fR or \fBdo\fR
437 \fB\&.\|.\|.\fR \fBwhile\fR statement.
438 .RE
439 .RS +4
440 .TP
441 .ie t \(bu
442 .el o
443 an expression used as a pattern (as in Overall Program Structure).
444 .RE
445 .sp
446 .LP
447 The \fBnawk\fR language supplies arrays that are used for storing numbers or
448 strings. Arrays need not be declared. They are initially empty, and their sizes
449 changes dynamically. The subscripts, or element identifiers, are strings,
450 providing a type of associative array capability. An array name followed by a
451 subscript within square brackets can be used as an \fIlvalue\fR and as an
452 expression, as described in the grammar. Unsubscripted array names are used in
453 only the following contexts:
454 .RS +4
455 .TP
456 .ie t \(bu
457 .el o
458 a parameter in a function definition or function call.
459 .RE
460 .RS +4
461 .TP
462 .ie t \(bu
463 .el o
464 the \fBNAME\fR token following any use of the keyword \fBin\fR.
465 .RE
466 .sp
467 .LP
468 A valid array \fIindex\fR consists of one or more comma-separated expressions,
469 similar to the way in which multi-dimensional arrays are indexed in some
470 programming languages. Because \fBnawk\fR arrays are really one-dimensional,
471 such a comma-separated list is converted to a single string by concatenating
472 the string values of the separate expressions, each separated from the other by
473 the value of the \fBSUBSEP\fR variable.
474 .sp
475 .LP
476 Thus, the following two index operations are equivalent:
477 .sp
478 .in +2
479 .nf
480 var[expr1, expr2, ... exprn]
481 var[expr1 SUBSEP expr2 SUBSEP ... SUBSEP exprn]
482 .fi
483 .in -2
484
485 .sp
486 .LP
487 A multi-dimensioned \fIindex\fR used with the \fBin\fR operator must be put in
488 parentheses. The \fBin\fR operator, which tests for the existence of a
489 particular array element, does not create the element if it does not exist.
490 Any other reference to a non-existent array element automatically creates it.
491
492 .SS "Variables and Special Variables"
493 .LP
494 Variables can be used in an \fBnawk\fR program by referencing them. With the
495 exception of function parameters, they are not explicitly declared.
496 Uninitialized scalar variables and array elements have both a numeric value of
497 zero and a string value of the empty string.
498 .sp
499 .LP
500 Field variables are designated by a \fB$\fR followed by a number or numerical
501 expression. The effect of the field number \fIexpression\fR evaluating to
502 anything other than a non-negative integer is unspecified. Uninitialized
503 variables or string values need not be converted to numeric values in this
504 context. New field variables are created by assigning a value to them.
505 References to non-existent fields (that is, fields after \fB$NF\fR) produce the
506 null string. However, assigning to a non-existent field (for example,
507 \fB$(NF+2) = 5\fR) increases the value of \fBNF\fR, create any intervening
508 fields with the null string as their values and cause the value of \fB$0\fR to
509 be recomputed, with the fields being separated by the value of \fBOFS\fR. Each
510 field variable has a string value when created. If the string, with any
511 occurrence of the decimal-point character from the current locale changed to a
512 period character, is considered a \fInumeric string\fR (see \fBExpressions in
513 nawk\fR above), the field variable also has the numeric value of the \fInumeric
514 string\fR.
515
516 .SS "/usr/bin/nawk, /usr/xpg4/bin/awk"
517 .LP
518 \fBnawk\fR sets the following special variables that are supported by both
519 \fB/usr/bin/nawk\fR and \fB/usr/xpg4/bin/awk\fR:
520 .sp
521 .ne 2
522 .na
523 \fB\fBARGC\fR\fR
524 .ad
525 .RS 12n
526 The number of elements in the \fBARGV\fR array.
527 .RE
528
529 .sp
530 .ne 2
531 .na
532 \fB\fBARGV\fR\fR
533 .ad
534 .RS 12n
535 An array of command line arguments, excluding options and the \fIprogram\fR
536 argument, numbered from zero to \fBARGC\fR\(mi1.
537 .sp
538 The arguments in \fBARGV\fR can be modified or added to; \fBARGC\fR can be
539 altered. As each input file ends, \fBnawk\fR treats the next non-null element
540 of \fBARGV\fR, up to the current value of \fBARGC\fR\(mi1, inclusive, as the
541 name of the next input file. Setting an element of \fBARGV\fR to null means
542 that it is not treated as an input file. The name \fB\(mi\fR indicates the
543 standard input. If an argument matches the format of an \fIassignment\fR
544 operand, this argument is treated as an assignment rather than a \fIfile\fR
545 argument.
546 .RE
547
548 .sp
549 .ne 2
550 .na
551 \fB\fBCONVFMT\fR\fR
552 .ad
553 .RS 12n
554 The \fBprintf\fR format for converting numbers to strings (except for output
555 statements, where \fBOFMT\fR is used). The default is \fB%.6g\fR.
556 .RE
557
558 .sp
559 .ne 2
560 .na
561 \fB\fBENVIRON\fR\fR
562 .ad
563 .RS 12n
564 The variable \fBENVIRON\fR is an array representing the value of the
565 environment. The indices of the array are strings consisting of the names of
566 the environment variables, and the value of each array element is a string
567 consisting of the value of that variable. If the value of an environment
568 variable is considered a \fInumeric string\fR, the array element also has its
569 numeric value.
570 .sp
571 In all cases where \fBnawk\fR behavior is affected by environment variables
572 (including the environment of any commands that \fBnawk\fR executes via the
573 \fBsystem\fR function or via pipeline redirections with the \fBprint\fR
574 statement, the \fBprintf\fR statement, or the \fBgetline\fR function), the
575 environment used is the environment at the time \fBnawk\fR began executing.
576 .RE
577
578 .sp
579 .ne 2
580 .na
581 \fB\fBFILENAME\fR\fR
582 .ad
583 .RS 12n
584 A pathname of the current input file. Inside a \fBBEGIN\fR action the value is
585 undefined. Inside an \fBEND\fR action the value is the name of the last input
586 file processed.
587 .RE
588
589 .sp
590 .ne 2
591 .na
592 \fB\fBFNR\fR\fR
593 .ad
594 .RS 12n
595 The ordinal number of the current record in the current file. Inside a
596 \fBBEGIN\fR action the value is zero. Inside an \fBEND\fR action the value is
597 the number of the last record processed in the last file processed.
598 .RE
599
600 .sp
601 .ne 2
602 .na
603 \fB\fBFS\fR\fR
604 .ad
605 .RS 12n
606 Input field separator regular expression; a space character by default.
607 .RE
608
609 .sp
610 .ne 2
611 .na
612 \fB\fBNF\fR\fR
613 .ad
614 .RS 12n
615 The number of fields in the current record. Inside a \fBBEGIN\fR action, the
616 use of \fBNF\fR is undefined unless a \fBgetline\fR function without a
617 \fIvar\fR argument is executed previously. Inside an \fBEND\fR action, \fBNF\fR
618 retains the value it had for the last record read, unless a subsequent,
619 redirected, \fBgetline\fR function without a \fIvar\fR argument is performed
620 prior to entering the \fBEND\fR action.
621 .RE
622
623 .sp
624 .ne 2
625 .na
626 \fB\fBNR\fR\fR
627 .ad
628 .RS 12n
629 The ordinal number of the current record from the start of input. Inside a
630 \fBBEGIN\fR action the value is zero. Inside an \fBEND\fR action the value is
631 the number of the last record processed.
632 .RE
633
634 .sp
635 .ne 2
636 .na
637 \fB\fBOFMT\fR\fR
638 .ad
639 .RS 12n
640 The \fBprintf\fR format for converting numbers to strings in output statements
641 \fB"%.6g"\fR by default. The result of the conversion is unspecified if the
642 value of \fBOFMT\fR is not a floating-point format specification.
643 .RE
644
645 .sp
646 .ne 2
647 .na
648 \fB\fBOFS\fR\fR
649 .ad
650 .RS 12n
651 The \fBprint\fR statement output field separator; a space character by default.
652 .RE
653
654 .sp
655 .ne 2
656 .na
657 \fB\fBORS\fR\fR
658 .ad
659 .RS 12n
660 The \fBprint\fR output record separator; a newline character by default.
661 .RE
662
663 .sp
664 .ne 2
665 .na
666 \fB\fBRLENGTH\fR\fR
667 .ad
668 .RS 12n
669 The length of the string matched by the \fBmatch\fR function.
670 .RE
671
672 .sp
673 .ne 2
674 .na
675 \fB\fBRS\fR\fR
676 .ad
677 .RS 12n
678 The first character of the string value of \fBRS\fR is the input record
679 separator; a newline character by default. If \fBRS\fR contains more than one
680 character, the results are unspecified. If \fBRS\fR is null, then records are
681 separated by sequences of one or more blank lines. Leading or trailing blank
682 lines do not produce empty records at the beginning or end of input, and the
683 field separator is always newline, no matter what the value of \fBFS\fR.
684 .RE
685
686 .sp
687 .ne 2
688 .na
689 \fB\fBRSTART\fR\fR
690 .ad
691 .RS 12n
692 The starting position of the string matched by the \fBmatch\fR function,
693 numbering from 1. This is always equivalent to the return value of the
694 \fBmatch\fR function.
695 .RE
696
697 .sp
698 .ne 2
699 .na
700 \fB\fBSUBSEP\fR\fR
701 .ad
702 .RS 12n
703 The subscript separator string for multi-dimensional arrays. The default value
704 is \fB\e034\fR\&.
705 .RE
706
707 .SS "/usr/bin/nawk"
708 .LP
709 The following variable is supported for \fB/usr/bin/nawk\fR only:
710 .sp
711 .ne 2
712 .na
713 \fB\fBRT\fR\fR
714 .ad
715 .RS 12n
716 The record terminator for the most recent record read. For most records this
717 will be the same value as \fBRS\fR. At the end of a file with no trailing
718 separator value, though, this will be set to the empty string (\fB""\fR).
719 .RE
720
721 .SS "Regular Expressions"
722 .LP
723 The \fBnawk\fR utility makes use of the extended regular expression notation
724 (see \fBregex\fR(5)) except that it allows the use of C-language conventions to
725 escape special characters within the EREs, namely \fB\e\e\fR, \fB\ea\fR,
726 \fB\eb\fR, \fB\ef\fR, \fB\en\fR, \fB\er\fR, \fB\et\fR, \fB\ev\fR, and those
727 specified in the following table. These escape sequences are recognized both
728 inside and outside bracket expressions. Note that records need not be
729 separated by newline characters and string constants can contain newline
730 characters, so even the \fB\en\fR sequence is valid in \fBnawk\fR EREs. Using
731 a slash character within the regular expression requires escaping as shown in
732 the table below:
733 .sp
734
735 .sp
736 .TS
737 l l l
738 l l l .
739 \fBEscape Sequence\fR \fBDescription\fR \fBMeaning\fR
740 _
741 \fB\e"\fR Backslash quotation-mark Quotation-mark character
742 _
743 \fB\e/\fR Backslash slash Slash character
744 _
745 \fB\e\fR\fIddd\fR T{
746 A backslash character followed by the longest sequence of one, two, or three octal-digit characters (01234567). If all of the digits are 0, (that is, representation of the NULL character), the behavior is undefined.
747 T} T{
748 The character encoded by the one-, two- or three-digit octal integer. Multi-byte characters require multiple, concatenated escape sequences, including the leading \e for each byte.
749 T}
750 _
751 \fB\e\fR\fIc\fR T{
752 A backslash character followed by any character not described in this table or special characters (\fB\e\e\fR, \fB\ea\fR, \fB\eb\fR, \fB\ef\fR, \fB\en\fR, \fB\er\fR, \fB\et\fR, \fB\ev\fR).
753 T} Undefined
754 .TE
755
756 .sp
757 .LP
758 A regular expression can be matched against a specific field or string by using
759 one of the two regular expression matching operators, \fB~\fR and \fB!\|~\fR.
760 These operators interpret their right-hand operand as a regular expression and
761 their left-hand operand as a string. If the regular expression matches the
762 string, the \fB~\fR expression evaluates to the value \fB1\fR, and the
763 \fB!\|~\fR expression evaluates to the value \fB0\fR. If the regular expression
764 does not match the string, the \fB~\fR expression evaluates to the value
765 \fB0\fR, and the \fB!\|~\fR expression evaluates to the value \fB1\fR. If the
766 right-hand operand is any expression other than the lexical token \fBERE\fR,
767 the string value of the expression is interpreted as an extended regular
768 expression, including the escape conventions described above. Notice that these
769 same escape conventions also are applied in the determining the value of a
770 string literal (the lexical token \fBSTRING\fR), and is applied a second time
771 when a string literal is used in this context.
772 .sp
773 .LP
774 When an \fBERE\fR token appears as an expression in any context other than as
775 the right-hand of the \fB~\fR or \fB!\|~\fR operator or as one of the built-in
776 function arguments described below, the value of the resulting expression is
777 the equivalent of:
778 .sp
779 .in +2
780 .nf
781 $0 ~ /\fIere\fR/
782 .fi
783 .in -2
784
785 .sp
786 .LP
787 The \fIere\fR argument to the \fBgsub,\fR \fBmatch,\fR \fBsub\fR functions, and
788 the \fIfs\fR argument to the \fBsplit\fR function (see \fBString Functions\fR)
789 is interpreted as extended regular expressions. These can be either \fBERE\fR
790 tokens or arbitrary expressions, and are interpreted in the same manner as the
791 right-hand side of the \fB~\fR or \fB!\|~\fR operator.
792 .sp
793 .LP
794 An extended regular expression can be used to separate fields by using the
795 \fB-F\fR \fIERE\fR option or by assigning a string containing the expression to
796 the built-in variable \fBFS\fR. The default value of the \fBFS\fR variable is a
797 single space character. The following describes \fBFS\fR behavior:
798 .RS +4
799 .TP
800 1.
801 If \fBFS\fR is a single character:
802 .RS +4
803 .TP
804 .ie t \(bu
805 .el o
806 If \fBFS\fR is the space character, skip leading and trailing blank characters;
807 fields are delimited by sets of one or more blank characters.
808 .RE
809 .RS +4
810 .TP
811 .ie t \(bu
812 .el o
813 Otherwise, if \fBFS\fR is any other character \fIc\fR, fields are delimited by
814 each single occurrence of \fIc\fR.
815 .RE
816 .RE
817 .RS +4
818 .TP
819 2.
820 Otherwise, the string value of \fBFS\fR is considered to be an extended
821 regular expression. Each occurrence of a sequence matching the extended regular
822 expression delimits fields.
823 .RE
824 .sp
825 .LP
826 Except in the \fBgsub\fR, \fBmatch\fR, \fBsplit\fR, and \fBsub\fR built-in
827 functions, regular expression matching is based on input records. That is,
828 record separator characters (the first character of the value of the variable
829 \fBRS\fR, a newline character by default) cannot be embedded in the expression,
830 and no expression matches the record separator character. If the record
831 separator is not a newline character, newline characters embedded in the
832 expression can be matched. In those four built-in functions, regular expression
833 matching are based on text strings. So, any character (including the newline
834 character and the record separator) can be embedded in the pattern and an
835 appropriate pattern matches any character. However, in all \fBnawk\fR regular
836 expression matching, the use of one or more NULL characters in the pattern,
837 input record or text string produces undefined results.
838
839 .SS "Patterns"
840 .LP
841 A \fIpattern\fR is any valid \fIexpression,\fR a range specified by two
842 expressions separated by comma, or one of the two special patterns \fBBEGIN\fR
843 or \fBEND\fR.
844
845 .SS "Special Patterns"
846 .LP
847 The \fBnawk\fR utility recognizes two special patterns, \fBBEGIN\fR and
848 \fBEND\fR. Each \fBBEGIN\fR pattern is matched once and its associated action
849 executed before the first record of input is read (except possibly by use of
850 the \fBgetline\fR function in a prior \fBBEGIN\fR action) and before command
851 line assignment is done. Each \fBEND\fR pattern is matched once and its
852 associated action executed after the last record of input has been read. These
853 two patterns have associated actions.
854 .sp
855 .LP
856 \fBBEGIN\fR and \fBEND\fR do not combine with other patterns. Multiple
857 \fBBEGIN\fR and \fBEND\fR patterns are allowed. The actions associated with the
858 \fBBEGIN\fR patterns are executed in the order specified in the program, as are
859 the \fBEND\fR actions. An \fBEND\fR pattern can precede a \fBBEGIN\fR pattern
860 in a program.
861 .sp
862 .LP
863 If an \fBnawk\fR program consists of only actions with the pattern \fBBEGIN\fR,
864 and the \fBBEGIN\fR action contains no \fBgetline\fR function, \fBnawk\fR exits
865 without reading its input when the last statement in the last \fBBEGIN\fR
866 action is executed. If an \fBnawk\fR program consists of only actions with the
867 pattern \fBEND\fR or only actions with the patterns \fBBEGIN\fR and \fBEND\fR,
868 the input is read before the statements in the \fBEND\fR actions are executed.
869
870 .SS "Expression Patterns"
871 .LP
872 An expression pattern is evaluated as if it were an expression in a Boolean
873 context. If the result is true, the pattern is considered to match, and the
874 associated action (if any) is executed. If the result is false, the action is
875 not executed.
876
877 .SS "Pattern Ranges"
878 .LP
879 A pattern range consists of two expressions separated by a comma. In this case,
880 the action is performed for all records between a match of the first expression
881 and the following match of the second expression, inclusive. At this point, the
882 pattern range can be repeated starting at input records subsequent to the end
883 of the matched range.
884
885 .SS "Actions"
886 .LP
887 An action is a sequence of statements. A statement can be one of the following:
888 .sp
889 .in +2
890 .nf
891 if ( \fIexpression\fR ) \fIstatement\fR [ else \fIstatement\fR ]
892 while ( \fIexpression\fR ) \fIstatement\fR
893 do \fIstatement\fR while ( \fIexpression\fR )
894 for ( \fIexpression\fR ; \fIexpression\fR ; \fIexpression\fR ) \fIstatement\fR
895 for ( \fIvar\fR in \fIarray\fR ) \fIstatement\fR
896 delete \fIarray\fR[\fIsubscript\fR] #delete an array element
897 delete \fIarray\fR #delete all elements within an array
898 break
899 continue
900 { [ \fIstatement\fR ] .\|.\|. }
901 \fIexpression\fR # commonly variable = expression
902 print [ \fIexpression-list\fR ] [ >\fIexpression\fR ]
903 printf format [ ,\fIexpression-list\fR ] [ >\fIexpression\fR ]
904 next # skip remaining patterns on this input line
905 nextfile # skip remaining patterns on this input file
906 exit [expr] # skip the rest of the input; exit status is expr
907 return [expr]
908 .fi
909 .in -2
910
911 .sp
912 .LP
913 Any single statement can be replaced by a statement list enclosed in braces.
914 The statements are terminated by newline characters or semicolons, and are
915 executed sequentially in the order that they appear.
916 .sp
917 .LP
918 The \fBnext\fR statement causes all further processing of the current input
919 record to be abandoned. The behavior is undefined if a \fBnext\fR statement
920 appears or is invoked in a \fBBEGIN\fR or \fBEND\fR action.
921 .sp
922 .LP
923 The \fBnextfile\fR statement is similar to \fBnext\fR, but also skips all other
924 records in the current file, and moves on to processing the next input file if
925 available (or exits the program if there are none). (Note that this keyword is
926 not supported by \fB/usr/xpg4/bin/awk\fR.)
927 .sp
928 .LP
929 The \fBexit\fR statement invokes all \fBEND\fR actions in the order in which
930 they occur in the program source and then terminate the program without reading
931 further input. An \fBexit\fR statement inside an \fBEND\fR action terminates
932 the program without further execution of \fBEND\fR actions. If an expression
933 is specified in an \fBexit\fR statement, its numeric value is the exit status
934 of \fBnawk\fR, unless subsequent errors are encountered or a subsequent
935 \fBexit\fR statement with an expression is executed.
936
937 .SS "Output Statements"
938 .LP
939 Both \fBprint\fR and \fBprintf\fR statements write to standard output by
940 default. The output is written to the location specified by
941 \fIoutput_redirection\fR if one is supplied, as follows:
942 .sp
943 .in +2
944 .nf
945 \fB>\fR \fIexpression\fR\fB>>\fR \fIexpression\fR\fB|\fR \fIexpression\fR
946 .fi
947 .in -2
948
949 .sp
950 .LP
951 In all cases, the \fIexpression\fR is evaluated to produce a string that is
952 used as a full pathname to write into (for \fB>\fR or \fB>>\fR) or as a command
953 to be executed (for \fB|\fR). Using the first two forms, if the file of that
954 name is not currently open, it is opened, creating it if necessary and using
955 the first form, truncating the file. The output then is appended to the file.
956 As long as the file remains open, subsequent calls in which \fIexpression\fR
957 evaluates to the same string value simply appends output to the file. The file
958 remains open until the \fBclose\fR function, which is called with an expression
959 that evaluates to the same string value.
960 .sp
961 .LP
962 The third form writes output onto a stream piped to the input of a command. The
963 stream is created if no stream is currently open with the value of
964 \fIexpression\fR as its command name. The stream created is equivalent to one
965 created by a call to the \fBpopen\fR(3C) function with the value of
966 \fIexpression\fR as the \fIcommand\fR argument and a value of \fBw\fR as the
967 \fImode\fR argument. As long as the stream remains open, subsequent calls in
968 which \fIexpression\fR evaluates to the same string value writes output to the
969 existing stream. The stream remains open until the \fBclose\fR function is
970 called with an expression that evaluates to the same string value. At that
971 time, the stream is closed as if by a call to the \fBpclose\fR function.
972 .sp
973 .LP
974 These output statements take a comma-separated list of \fIexpression\fR \fIs\fR
975 referred in the grammar by the non-terminal symbols \fBexpr_list,\fR
976 \fBprint_expr_list\fR or \fBprint_expr_list_opt.\fR This list is referred to
977 here as the \fIexpression list\fR, and each member is referred to as an
978 \fIexpression argument\fR.
979 .sp
980 .LP
981 The \fBprint\fR statement writes the value of each expression argument onto the
982 indicated output stream separated by the current output field separator (see
983 variable \fBOFS\fR above), and terminated by the output record separator (see
984 variable \fBORS\fR above). All expression arguments is taken as strings, being
985 converted if necessary; with the exception that the \fBprintf\fR format in
986 \fBOFMT\fR is used instead of the value in \fBCONVFMT\fR. An empty expression
987 list stands for the whole input record \fB(\fR$0\fB)\fR.
988 .sp
989 .LP
990 The \fBprintf\fR statement produces output based on a notation similar to the
991 File Format Notation used to describe file formats in this document Output is
992 produced as specified with the first expression argument as the string
993 \fBformat\fR and subsequent expression arguments as the strings \fBarg1\fR to
994 \fBargn,\fR inclusive, with the following exceptions:
995 .RS +4
996 .TP
997 1.
998 The \fIformat\fR is an actual character string rather than a graphical
999 representation. Therefore, it cannot contain empty character positions. The
1000 space character in the \fIformat\fR string, in any context other than a
1001 \fIflag\fR of a conversion specification, is treated as an ordinary character
1002 that is copied to the output.
1003 .RE
1004 .RS +4
1005 .TP
1006 2.
1007 If the character set contains a Delta character and that character appears
1008 in the \fIformat\fR string, it is treated as an ordinary character that is
1009 copied to the output.
1010 .RE
1011 .RS +4
1012 .TP
1013 3.
1014 The \fIescape sequences\fR beginning with a backslash character is treated
1015 as sequences of ordinary characters that are copied to the output. Note that
1016 these same sequences is interpreted lexically by \fBnawk\fR when they appear in
1017 literal strings, but they is not treated specially by the \fBprintf\fR
1018 statement.
1019 .RE
1020 .RS +4
1021 .TP
1022 4.
1023 A \fIfield width\fR or \fIprecision\fR can be specified as the \fB*\fR
1024 character instead of a digit string. In this case the next argument from the
1025 expression list is fetched and its numeric value taken as the field width or
1026 precision.
1027 .RE
1028 .RS +4
1029 .TP
1030 5.
1031 The implementation does not precede or follow output from the \fBd\fR or
1032 \fBu\fR conversion specifications with blank characters not specified by the
1033 \fIformat\fR string.
1034 .RE
1035 .RS +4
1036 .TP
1037 6.
1038 The implementation does not precede output from the \fBo\fR conversion
1039 specification with leading zeros not specified by the \fIformat\fR string.
1040 .RE
1041 .RS +4
1042 .TP
1043 7.
1044 For the \fBc\fR conversion specification: if the argument has a numeric
1045 value, the character whose encoding is that value is output. If the value is
1046 zero or is not the encoding of any character in the character set, the behavior
1047 is undefined. If the argument does not have a numeric value, the first
1048 character of the string value is output; if the string does not contain any
1049 characters the behavior is undefined.
1050 .RE
1051 .RS +4
1052 .TP
1053 8.
1054 For each conversion specification that consumes an argument, the next
1055 expression argument is evaluated. With the exception of the \fBc\fR conversion,
1056 the value is converted to the appropriate type for the conversion
1057 specification.
1058 .RE
1059 .RS +4
1060 .TP
1061 9.
1062 If there are insufficient expression arguments to satisfy all the conversion
1063 specifications in the \fIformat\fR string, the behavior is undefined.
1064 .RE
1065 .RS +4
1066 .TP
1067 10.
1068 If any character sequence in the \fIformat\fR string begins with a %
1069 character, but does not form a valid conversion specification, the behavior is
1070 unspecified.
1071 .RE
1072 .sp
1073 .LP
1074 Both \fBprint\fR and \fBprintf\fR can output at least \fB{LINE_MAX}\fR bytes.
1075
1076 .SS "Functions"
1077 .LP
1078 The \fBnawk\fR language has a variety of built-in functions: arithmetic,
1079 string, input/output and general.
1080
1081 .SS "Arithmetic Functions"
1082 .LP
1083 The arithmetic functions, except for \fBint\fR, are based on the \fBISO\fR
1084 \fBC\fR standard. The behavior is undefined in cases where the \fBISO\fR
1085 \fBC\fR standard specifies that an error be returned or that the behavior is
1086 undefined. Although the grammar permits built-in functions to appear with no
1087 arguments or parentheses, unless the argument or parentheses are indicated as
1088 optional in the following list (by displaying them within the \fB[ ]\fR
1089 brackets), such use is undefined.
1090 .sp
1091 .ne 2
1092 .na
1093 \fB\fBatan2(\fR\fIy\fR,\fIx\fR\fB)\fR\fR
1094 .ad
1095 .RS 17n
1096 Return arctangent of \fIy\fR/\fIx\fR.
1097 .RE
1098
1099 .sp
1100 .ne 2
1101 .na
1102 \fB\fBcos\fR(\fIx\fR)\fR
1103 .ad
1104 .RS 17n
1105 Return cosine of \fIx,\fR where \fIx\fR is in radians.
1106 .RE
1107
1108 .sp
1109 .ne 2
1110 .na
1111 \fB\fBsin\fR(\fIx\fR)\fR
1112 .ad
1113 .RS 17n
1114 Return sine of \fIx,\fR where \fIx\fR is in radians.
1115 .RE
1116
1117 .sp
1118 .ne 2
1119 .na
1120 \fB\fBexp\fR(\fIx\fR)\fR
1121 .ad
1122 .RS 17n
1123 Return the exponential function of \fIx\fR.
1124 .RE
1125
1126 .sp
1127 .ne 2
1128 .na
1129 \fB\fBlog\fR(\fIx\fR)\fR
1130 .ad
1131 .RS 17n
1132 Return the natural logarithm of \fIx\fR.
1133 .RE
1134
1135 .sp
1136 .ne 2
1137 .na
1138 \fB\fBsqrt\fR(\fIx\fR)\fR
1139 .ad
1140 .RS 17n
1141 Return the square root of \fIx\fR.
1142 .RE
1143
1144 .sp
1145 .ne 2
1146 .na
1147 \fB\fBint\fR(\fIx\fR)\fR
1148 .ad
1149 .RS 17n
1150 Truncate its argument to an integer. It is truncated toward 0 when \fIx\fR > 0.
1151 .RE
1152
1153 .sp
1154 .ne 2
1155 .na
1156 \fB\fBrand()\fR\fR
1157 .ad
1158 .RS 17n
1159 Return a random number \fIn\fR, such that 0 \(<= \fIn\fR < 1.
1160 .RE
1161
1162 .sp
1163 .ne 2
1164 .na
1165 \fB\fBsrand\fR([\fBexpr\fR])\fR
1166 .ad
1167 .RS 17n
1168 Set the seed value for \fBrand\fR to \fIexpr\fR or use the time of day if
1169 \fIexpr\fR is omitted. The previous seed value is returned.
1170 .RE
1171
1172 .SS "String Functions"
1173 .LP
1174 The string functions in the following list shall be supported. Although the
1175 grammar permits built-in functions to appear with no arguments or parentheses,
1176 unless the argument or parentheses are indicated as optional in the following
1177 list (by displaying them within the \fB[ ]\fR brackets), such use is undefined.
1178 .sp
1179 .ne 2
1180 .na
1181 \fB\fBgsub\fR(\fIere\fR,\fIrepl\fR[,\|\fIin\fR])\fR
1182 .ad
1183 .sp .6
1184 .RS 4n
1185 Behave like \fBsub\fR (see below), except that it replaces all occurrences of
1186 the regular expression (like the \fBed\fR utility global substitute) in
1187 \fB$0\fR or in the \fIin\fR argument, when specified.
1188 .RE
1189
1190 .sp
1191 .ne 2
1192 .na
1193 \fB\fBindex\fR(\fIs\fR,\fIt\fR)\fR
1194 .ad
1195 .sp .6
1196 .RS 4n
1197 Return the position, in characters, numbering from 1, in string \fIs\fR where
1198 string \fIt\fR first occurs, or zero if it does not occur at all.
1199 .RE
1200
1201 .sp
1202 .ne 2
1203 .na
1204 \fB\fBlength\fR[([\fIv\fR])]\fR
1205 .ad
1206 .sp .6
1207 .RS 4n
1208 Given no argument, this function returns the length of the whole record,
1209 \fB$0\fR. If given an array as an argument (and using \fB/usr/bin/nawk\fR),
1210 then this returns the number of elements it contains. Otherwise, this function
1211 interprets the argument as a string (performing any needed conversions) and
1212 returns its length in characters.
1213 .RE
1214
1215 .sp
1216 .ne 2
1217 .na
1218 \fB\fBmatch\fR(\fIs\fR,\fIere\fR)\fR
1219 .ad
1220 .sp .6
1221 .RS 4n
1222 Return the position, in characters, numbering from 1, in string \fIs\fR where
1223 the extended regular expression \fIere\fR occurs, or zero if it does not occur
1224 at all. \fBRSTART\fR is set to the starting position (which is the same as the
1225 returned value), zero if no match is found; \fBRLENGTH\fR is set to the length
1226 of the matched string, \(mi1 if no match is found.
1227 .RE
1228
1229 .sp
1230 .ne 2
1231 .na
1232 \fB\fBsplit\fR(\fIs\fR,\fIa\fR[,\|\fIfs\fR])\fR
1233 .ad
1234 .sp .6
1235 .RS 4n
1236 Split the string \fIs\fR into array elements \fIa\fR[1], \fIa\fR[2],
1237 \fB\&...,\fR \fIa\fR[\fIn\fR], and return \fIn\fR. The separation is done with
1238 the extended regular expression \fIfs\fR or with the field separator \fBFS\fR
1239 if \fIfs\fR is not given. Each array element has a string value when created.
1240 If the string assigned to any array element, with any occurrence of the
1241 decimal-point character from the current locale changed to a period character,
1242 would be considered a \fInumeric string\fR; the array element also has the
1243 numeric value of the \fInumeric string\fR. The effect of a null string as the
1244 value of \fIfs\fR is unspecified.
1245 .RE
1246
1247 .sp
1248 .ne 2
1249 .na
1250 \fB\fBsprintf\fR(\fBfmt\fR,\fIexpr\fR,\fIexpr\fR,\fB\&...\fR)\fR
1251 .ad
1252 .sp .6
1253 .RS 4n
1254 Format the expressions according to the \fBprintf\fR format given by \fIfmt\fR
1255 and return the resulting string.
1256 .RE
1257
1258 .sp
1259 .ne 2
1260 .na
1261 \fB\fBsub\fR(\fIere\fR,\fIrepl\fR[,\|\fIin\fR])\fR
1262 .ad
1263 .sp .6
1264 .RS 4n
1265 Substitute the string \fIrepl\fR in place of the first instance of the extended
1266 regular expression \fBERE\fR in string in and return the number of
1267 substitutions. An ampersand ( \fB&\fR ) appearing in the string \fIrepl\fR is
1268 replaced by the string from in that matches the regular expression. An
1269 ampersand preceded with a backslash ( \fB\e\fR ) is interpreted as the literal
1270 ampersand character. An occurrence of two consecutive backslashes is
1271 interpreted as just a single literal backslash character. Any other occurrence
1272 of a backslash (for example, preceding any other character) is treated as a
1273 literal backslash character. If \fIrepl\fR is a string literal, the handling of
1274 the ampersand character occurs after any lexical processing, including any
1275 lexical backslash escape sequence processing. If \fBin\fR is specified and it
1276 is not an \fBlvalue\fR the behavior is undefined. If in is omitted, \fBnawk\fR
1277 uses the current record (\fB$0\fR) in its place.
1278 .RE
1279
1280 .sp
1281 .ne 2
1282 .na
1283 \fB\fBsubstr\fR(\fIs\fR,\fIm\fR[,\|\fIn\fR])\fR
1284 .ad
1285 .sp .6
1286 .RS 4n
1287 Return the at most \fIn\fR-character substring of \fIs\fR that begins at
1288 position \fIm,\fR numbering from 1. If \fIn\fR is missing, the length of the
1289 substring is limited by the length of the string \fIs\fR.
1290 .RE
1291
1292 .sp
1293 .ne 2
1294 .na
1295 \fB\fBtolower\fR(\fIs\fR)\fR
1296 .ad
1297 .sp .6
1298 .RS 4n
1299 Return a string based on the string \fIs\fR. Each character in \fIs\fR that is
1300 an upper-case letter specified to have a \fBtolower\fR mapping by the
1301 \fBLC_CTYPE\fR category of the current locale is replaced in the returned
1302 string by the lower-case letter specified by the mapping. Other characters in
1303 \fIs\fR are unchanged in the returned string.
1304 .RE
1305
1306 .sp
1307 .ne 2
1308 .na
1309 \fB\fBtoupper\fR(\fIs\fR)\fR
1310 .ad
1311 .sp .6
1312 .RS 4n
1313 Return a string based on the string \fIs\fR. Each character in \fIs\fR that is
1314 a lower-case letter specified to have a \fBtoupper\fR mapping by the
1315 \fBLC_CTYPE\fR category of the current locale is replaced in the returned
1316 string by the upper-case letter specified by the mapping. Other characters in
1317 \fIs\fR are unchanged in the returned string.
1318 .RE
1319
1320 .sp
1321 .LP
1322 All of the preceding functions that take \fIERE\fR as a parameter expect a
1323 pattern or a string valued expression that is a regular expression as defined
1324 below.
1325
1326 .SS "Input/Output and General Functions"
1327 .LP
1328 The input/output and general functions are:
1329 .sp
1330 .ne 2
1331 .na
1332 \fB\fBclose(\fR\fIexpression\fR)\fR
1333 .ad
1334 .RS 27n
1335 Close the file or pipe opened by a \fBprint\fR or \fBprintf\fR statement or a
1336 call to \fBgetline\fR with the same string-valued \fIexpression\fR. If the
1337 close was successful, the function returns \fB0\fR; otherwise, it returns
1338 non-zero.
1339 .RE
1340
1341 .sp
1342 .ne 2
1343 .na
1344 \fB\fBfflush(\fR\fIexpression\fR)\fR
1345 .ad
1346 .RS 27n
1347 Flush any buffered output for the file or pipe opened by a \fBprint\fR or
1348 \fBprintf\fR statement or a call to \fBgetline\fR with the same string-valued
1349 \fIexpression\fR. If the flush was successful, the function returns \fB0\fR;
1350 otherwise, it returns \fBEOF\fR. If no arguments or the empty string
1351 (\fB""\fR) are given, then all open files will be flushed. (Note that
1352 \fBfflush\fR is supported in \fB/usr/bin/nawk\fR only.)
1353 .RE
1354
1355 .sp
1356 .ne 2
1357 .na
1358 \fB\fIexpression\fR|\fBgetline\fR[\fIvar\fR]\fR
1359 .ad
1360 .RS 27n
1361 Read a record of input from a stream piped from the output of a command. The
1362 stream is created if no stream is currently open with the value of
1363 \fIexpression\fR as its command name. The stream created is equivalent to one
1364 created by a call to the \fBpopen\fR function with the value of
1365 \fIexpression\fR as the \fIcommand\fR argument and a value of \fBr\fR as the
1366 \fImode\fR argument. As long as the stream remains open, subsequent calls in
1367 which \fIexpression\fR evaluates to the same string value reads subsequent
1368 records from the file. The stream remains open until the \fBclose\fR function
1369 is called with an expression that evaluates to the same string value. At that
1370 time, the stream is closed as if by a call to the \fBpclose\fR function. If
1371 \fIvar\fR is missing, \fB$0\fR and \fBNF\fR is set. Otherwise, \fIvar\fR is
1372 set.
1373 .sp
1374 The \fBgetline\fR operator can form ambiguous constructs when there are
1375 operators that are not in parentheses (including concatenate) to the left of
1376 the \fB|\fR (to the beginning of the expression containing \fBgetline\fR). In
1377 the context of the \fB$\fR operator, \fB|\fR behaves as if it had a lower
1378 precedence than \fB$\fR. The result of evaluating other operators is
1379 unspecified, and all such uses of portable applications must be put in
1380 parentheses properly.
1381 .RE
1382
1383 .sp
1384 .ne 2
1385 .na
1386 \fB\fBgetline\fR\fR
1387 .ad
1388 .RS 27n
1389 Set \fB$0\fR to the next input record from the current input file. This form of
1390 \fBgetline\fR sets the \fBNF\fR, \fBNR\fR, and \fBFNR\fR variables.
1391 .RE
1392
1393 .sp
1394 .ne 2
1395 .na
1396 \fB\fBgetline\fR \fIvar\fR\fR
1397 .ad
1398 .RS 27n
1399 Set variable \fIvar\fR to the next input record from the current input file.
1400 This form of \fBgetline\fR sets the \fBFNR\fR and \fBNR\fR variables.
1401 .RE
1402
1403 .sp
1404 .ne 2
1405 .na
1406 \fB\fBgetline\fR [\fIvar\fR] \fB<\fR \fIexpression\fR\fR
1407 .ad
1408 .RS 27n
1409 Read the next record of input from a named file. The \fIexpression\fR is
1410 evaluated to produce a string that is used as a full pathname. If the file of
1411 that name is not currently open, it is opened. As long as the stream remains
1412 open, subsequent calls in which \fIexpression\fR evaluates to the same string
1413 value reads subsequent records from the file. The file remains open until the
1414 \fBclose\fR function is called with an expression that evaluates to the same
1415 string value. If \fIvar\fR is missing, \fB$0\fR and \fBNF\fR is set. Otherwise,
1416 \fIvar\fR is set.
1417 .sp
1418 The \fBgetline\fR operator can form ambiguous constructs when there are binary
1419 operators that are not in parentheses (including concatenate) to the right of
1420 the \fB<\fR (up to the end of the expression containing the \fBgetline\fR). The
1421 result of evaluating such a construct is unspecified, and all such uses of
1422 portable applications must be put in parentheses properly.
1423 .RE
1424
1425 .sp
1426 .ne 2
1427 .na
1428 \fB\fBsystem\fR(\fIexpression\fR)\fR
1429 .ad
1430 .RS 27n
1431 Execute the command given by \fIexpression\fR in a manner equivalent to the
1432 \fBsystem\fR(3C) function and return the exit status of the command.
1433 .RE
1434
1435 .sp
1436 .LP
1437 All forms of \fBgetline\fR return \fB1\fR for successful input, \fB0\fR for end
1438 of file, and \fB\(mi1\fR for an error.
1439 .sp
1440 .LP
1441 Where strings are used as the name of a file or pipeline, the strings must be
1442 textually identical. The terminology ``same string value'' implies that
1443 ``equivalent strings'', even those that differ only by space characters,
1444 represent different files.
1445
1446 .SS "User-defined Functions"
1447 .LP
1448 The \fBnawk\fR language also provides user-defined functions. Such functions
1449 can be defined as:
1450 .sp
1451 .in +2
1452 .nf
1453 \fBfunction\fR \fIname\fR(\fIargs\fR,\|.\|.\|.) { \fIstatements\fR }
1454 .fi
1455 .in -2
1456
1457 .sp
1458 .LP
1459 A function can be referred to anywhere in an \fBnawk\fR program; in particular,
1460 its use can precede its definition. The scope of a function is global.
1461 .sp
1462 .LP
1463 Function arguments can be either scalars or arrays; the behavior is undefined
1464 if an array name is passed as an argument that the function uses as a scalar,
1465 or if a scalar expression is passed as an argument that the function uses as an
1466 array. Function arguments are passed by value if scalar and by reference if
1467 array name. Argument names are local to the function; all other variable names
1468 are global. The same name is not used as both an argument name and as the name
1469 of a function or a special \fBnawk\fR variable. The same name must not be used
1470 both as a variable name with global scope and as the name of a function. The
1471 same name must not be used within the same scope both as a scalar variable and
1472 as an array.
1473 .sp
1474 .LP
1475 The number of parameters in the function definition need not match the number
1476 of parameters in the function call. Excess formal parameters can be used as
1477 local variables. If fewer arguments are supplied in a function call than are in
1478 the function definition, the extra parameters that are used in the function
1479 body as scalars are initialized with a string value of the null string and a
1480 numeric value of zero, and the extra parameters that are used in the function
1481 body as arrays are initialized as empty arrays. If more arguments are supplied
1482 in a function call than are in the function definition, the behavior is
1483 undefined.
1484 .sp
1485 .LP
1486 When invoking a function, no white space can be placed between the function
1487 name and the opening parenthesis. Function calls can be nested and recursive
1488 calls can be made upon functions. Upon return from any nested or recursive
1489 function call, the values of all of the calling function's parameters are
1490 unchanged, except for array parameters passed by reference. The \fBreturn\fR
1491 statement can be used to return a value. If a \fBreturn\fR statement appears
1492 outside of a function definition, the behavior is undefined.
1493 .sp
1494 .LP
1495 In the function definition, newline characters are optional before the opening
1496 brace and after the closing brace. Function definitions can appear anywhere in
1497 the program where a \fIpattern-action\fR pair is allowed.
1498
1499 .SH USAGE
1500 .LP
1501 The \fBindex\fR, \fBlength\fR, \fBmatch\fR, and \fBsubstr\fR functions should
1502 not be confused with similar functions in the \fBISO C\fR standard; the
1503 \fBnawk\fR versions deal with characters, while the \fBISO C\fR standard deals
1504 with bytes.
1505 .sp
1506 .LP
1507 Because the concatenation operation is represented by adjacent expressions
1508 rather than an explicit operator, it is often necessary to use parentheses to
1509 enforce the proper evaluation precedence.
1510 .sp
1511 .LP
1512 See \fBlargefile\fR(5) for the description of the behavior of \fBnawk\fR when
1513 encountering files greater than or equal to 2 Gbyte (2^31 bytes).
1514
1515 .SH EXAMPLES
1516 .LP
1517 The \fBnawk\fR program specified in the command line is most easily specified
1518 within single-quotes (for example, \fB\&'\fR\fIprogram\fR\fB\&'\fR) for
1519 applications using \fBsh\fR, because \fBnawk\fR programs commonly contain
1520 characters that are special to the shell, including double-quotes. In the cases
1521 where a \fBnawk\fR program contains single-quote characters, it is usually
1522 easiest to specify most of the program as strings within single-quotes
1523 concatenated by the shell with quoted single-quote characters. For example:
1524 .sp
1525 .in +2
1526 .nf
1527 nawk '/'\e''/ { print "quote:", $0 }'
1528 .fi
1529 .in -2
1530
1531 .sp
1532 .LP
1533 prints all lines from the standard input containing a single-quote character,
1534 prefixed with \fBquote:\fR.
1535 .sp
1536 .LP
1537 The following are examples of simple \fBnawk\fR programs:
1538 .LP
1539 \fBExample 1 \fRWrite to the standard output all input lines for which field 3
1540 is greater than 5:
1541 .sp
1542 .in +2
1543 .nf
1544 \fB$3 > 5\fR
1545 .fi
1546 .in -2
1547 .sp
1548
1549 .LP
1550 \fBExample 2 \fRWrite every tenth line:
1551 .sp
1552 .in +2
1553 .nf
1554 \fB(NR % 10) == 0\fR
1555 .fi
1556 .in -2
1557 .sp
1558
1559 .LP
1560 \fBExample 3 \fRWrite any line with a substring matching the regular
1561 expression:
1562 .sp
1563 .in +2
1564 .nf
1565 \fB/(G|D)(2[0-9][[:alpha:]]*)/\fR
1566 .fi
1567 .in -2
1568 .sp
1569
1570 .LP
1571 \fBExample 4 \fRPrint any line with a substring containing a G or D, followed
1572 by a sequence of digits and characters:
1573 .sp
1574 .LP
1575 This example uses character classes \fBdigit\fR and \fBalpha\fR to match
1576 language-independent digit and alphabetic characters, respectively.
1577
1578 .sp
1579 .in +2
1580 .nf
1581 \fB/(G|D)([[:digit:][:alpha:]]*)/\fR
1582 .fi
1583 .in -2
1584 .sp
1585
1586 .LP
1587 \fBExample 5 \fRWrite any line in which the second field matches the regular
1588 expression and the fourth field does not:
1589 .sp
1590 .in +2
1591 .nf
1592 \fB$2 ~ /xyz/ && $4 !~ /xyz/\fR
1593 .fi
1594 .in -2
1595 .sp
1596
1597 .LP
1598 \fBExample 6 \fRWrite any line in which the second field contains a backslash:
1599 .sp
1600 .in +2
1601 .nf
1602 \fB$2 ~ /\e\e/\fR
1603 .fi
1604 .in -2
1605 .sp
1606
1607 .LP
1608 \fBExample 7 \fRWrite any line in which the second field contains a backslash
1609 (alternate method):
1610 .sp
1611 .LP
1612 Notice that backslash escapes are interpreted twice, once in lexical processing
1613 of the string and once in processing the regular expression.
1614
1615 .sp
1616 .in +2
1617 .nf
1618 \fB$2 ~ "\e\e\e\e"\fR
1619 .fi
1620 .in -2
1621 .sp
1622
1623 .LP
1624 \fBExample 8 \fRWrite the second to the last and the last field in each line,
1625 separating the fields by a colon:
1626 .sp
1627 .in +2
1628 .nf
1629 \fB{OFS=":";print $(NF-1), $NF}\fR
1630 .fi
1631 .in -2
1632 .sp
1633
1634 .LP
1635 \fBExample 9 \fRWrite the line number and number of fields in each line:
1636 .sp
1637 .LP
1638 The three strings representing the line number, the colon and the number of
1639 fields are concatenated and that string is written to standard output.
1640
1641 .sp
1642 .in +2
1643 .nf
1644 \fB{print NR ":" NF}\fR
1645 .fi
1646 .in -2
1647 .sp
1648
1649 .LP
1650 \fBExample 10 \fRWrite lines longer than 72 characters:
1651 .sp
1652 .in +2
1653 .nf
1654 \fB{length($0) > 72}\fR
1655 .fi
1656 .in -2
1657 .sp
1658
1659 .LP
1660 \fBExample 11 \fRWrite first two fields in opposite order separated by the OFS:
1661 .sp
1662 .in +2
1663 .nf
1664 \fB{ print $2, $1 }\fR
1665 .fi
1666 .in -2
1667 .sp
1668
1669 .LP
1670 \fBExample 12 \fRSame, with input fields separated by comma or space and tab
1671 characters, or both:
1672 .sp
1673 .in +2
1674 .nf
1675 \fBBEGIN { FS = ",[\et]*|[\et]+" }
1676 { print $2, $1 }\fR
1677 .fi
1678 .in -2
1679 .sp
1680
1681 .LP
1682 \fBExample 13 \fRAdd up first column, print sum and average:
1683 .sp
1684 .in +2
1685 .nf
1686 \fB{s += $1 }
1687 END {print "sum is ", s, " average is", s/NR}\fR
1688 .fi
1689 .in -2
1690 .sp
1691
1692 .LP
1693 \fBExample 14 \fRWrite fields in reverse order, one per line (many lines out
1694 for each line in):
1695 .sp
1696 .in +2
1697 .nf
1698 \fB{ for (i = NF; i > 0; --i) print $i }\fR
1699 .fi
1700 .in -2
1701 .sp
1702
1703 .LP
1704 \fBExample 15 \fRWrite all lines between occurrences of the strings "start" and
1705 "stop":
1706 .sp
1707 .in +2
1708 .nf
1709 \fB/start/, /stop/\fR
1710 .fi
1711 .in -2
1712 .sp
1713
1714 .LP
1715 \fBExample 16 \fRWrite all lines whose first field is different from the
1716 previous one:
1717 .sp
1718 .in +2
1719 .nf
1720 \fB$1 != prev { print; prev = $1 }\fR
1721 .fi
1722 .in -2
1723 .sp
1724
1725 .LP
1726 \fBExample 17 \fRSimulate the echo command:
1727 .sp
1728 .in +2
1729 .nf
1730 \fBBEGIN {
1731 for (i = 1; i < ARGC; ++i)
1732 printf "%s%s", ARGV[i], i==ARGC-1?"\en":""
1733 }\fR
1734 .fi
1735 .in -2
1736 .sp
1737
1738 .LP
1739 \fBExample 18 \fRWrite the path prefixes contained in the PATH environment
1740 variable, one per line:
1741 .sp
1742 .in +2
1743 .nf
1744 \fBBEGIN {
1745 n = split (ENVIRON["PATH"], path, ":")
1746 for (i = 1; i <= n; ++i)
1747 print path[i]
1748 }\fR
1749 .fi
1750 .in -2
1751 .sp
1752
1753 .LP
1754 \fBExample 19 \fRPrint the file "input", filling in page numbers starting at 5:
1755 .sp
1756 .LP
1757 If there is a file named \fBinput\fR containing page headers of the form
1758
1759 .sp
1760 .in +2
1761 .nf
1762 Page#
1763 .fi
1764 .in -2
1765
1766 .sp
1767 .LP
1768 and a file named \fBprogram\fR that contains
1769
1770 .sp
1771 .in +2
1772 .nf
1773 /Page/{ $2 = n++; }
1774 { print }
1775 .fi
1776 .in -2
1777
1778 .sp
1779 .LP
1780 then the command line
1781
1782 .sp
1783 .in +2
1784 .nf
1785 \fBnawk -f program n=5 input\fR
1786 .fi
1787 .in -2
1788 .sp
1789
1790 .sp
1791 .LP
1792 prints the file \fBinput\fR, filling in page numbers starting at 5.
1793
1794 .SH ENVIRONMENT VARIABLES
1795 .LP
1796 See \fBenviron\fR(5) for descriptions of the following environment variables
1797 that affect execution: \fBLC_COLLATE\fR, \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and
1798 \fBNLSPATH\fR.
1799 .sp
1800 .ne 2
1801 .na
1802 \fB\fBLC_NUMERIC\fR\fR
1803 .ad
1804 .RS 14n
1805 Determine the radix character used when interpreting numeric input, performing
1806 conversions between numeric and string values and formatting numeric output.
1807 Regardless of locale, the period character (the decimal-point character of the
1808 POSIX locale) is the decimal-point character recognized in processing \fBawk\fR
1809 programs (including assignments in command-line arguments).
1810 .RE
1811
1812 .SH EXIT STATUS
1813 .LP
1814 The following exit values are returned:
1815 .sp
1816 .ne 2
1817 .na
1818 \fB\fB0\fR\fR
1819 .ad
1820 .RS 6n
1821 All input files were processed successfully.
1822 .RE
1823
1824 .sp
1825 .ne 2
1826 .na
1827 \fB\fB>0\fR\fR
1828 .ad
1829 .RS 6n
1830 An error occurred.
1831 .RE
1832
1833 .sp
1834 .LP
1835 The exit status can be altered within the program by using an \fBexit\fR
1836 expression.
1837
1838 .SH SEE ALSO
1839 .LP
1840 \fBawk\fR(1), \fBed\fR(1), \fBegrep\fR(1), \fBgrep\fR(1), \fBlex\fR(1),
1841 \fBsed\fR(1), \fBpopen\fR(3C), \fBprintf\fR(3C), \fBsystem\fR(3C),
1842 \fBattributes\fR(5), \fBenviron\fR(5), \fBlargefile\fR(5), \fBregex\fR(5),
1843 \fBXPG4\fR(5)
1844 .sp
1845 .LP
1846 Aho, A. V., B. W. Kernighan, and P. J. Weinberger, \fIThe AWK Programming
1847 Language\fR, Addison-Wesley, 1988.
1848
1849 .SH DIAGNOSTICS
1850 .LP
1851 If any \fIfile\fR operand is specified and the named file cannot be accessed,
1852 \fBnawk\fR writes a diagnostic message to standard error and terminate without
1853 any further action.
1854 .sp
1855 .LP
1856 If the program specified by either the \fIprogram\fR operand or a
1857 \fIprogfile\fR operand is not a valid \fBnawk\fR program (as specified in
1858 \fBEXTENDED DESCRIPTION\fR), the behavior is undefined.
1859
1860 .SH NOTES
1861 .LP
1862 Input white space is not preserved on output if fields are involved.
1863 .sp
1864 .LP
1865 There are no explicit conversions between numbers and strings. To force an
1866 expression to be treated as a number add 0 to it; to force it to be treated as
1867 a string concatenate the null string (\fB""\fR) to it.