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