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