| blob | b32c4d84ee758607bf27a1af82826e6c72a18aaa |
1 '\" te
2 .\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved
3 .\" Copyright 1989 AT&T
4 .\" Portions Copyright (c) 1992, X/Open Company Limited. 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 AWK 1 "Jun 22, 2005"
13 .SH NAME
14 awk \- pattern scanning and processing language
15 .SH SYNOPSIS
16 .LP
17 .nf
18 \fB/usr/bin/awk\fR [\fB-f\fR \fIprogfile\fR] [\fB-F\fIc\fR\fR] [' \fIprog\fR '] [\fIparameters\fR]
19 [\fIfilename\fR]...
20 .fi
22 .LP
23 .nf
24 \fB/usr/xpg4/bin/awk\fR [\fB-F\fR\fIcERE\fR] [\fB-v\fR \fIassignment\fR]... \fI\&'program'\fR \fB-f\fR \fIprogfile\fR...
25 [\fIargument\fR]...
26 .fi
28 .SH DESCRIPTION
29 .sp
30 .LP
31 The \fB/usr/xpg4/bin/awk\fR utility is described on the \fBnawk\fR(1) manual
32 page.
33 .sp
34 .LP
35 The \fB/usr/bin/awk\fR utility scans each input \fIfilename\fR for lines that
36 match any of a set of patterns specified in \fIprog\fR. The \fIprog\fR string
37 must be enclosed in single quotes (\fB a\'\fR) to protect it from the shell.
38 For each pattern in \fIprog\fR there can be an associated action performed when
39 a line of a \fIfilename\fR matches the pattern. The set of pattern-action
40 statements can appear literally as \fIprog\fR or in a file specified with the
41 \fB-f\fR\fI progfile\fR option. Input files are read in order; if there are no
42 files, the standard input is read. The file name \fB\&'\(mi'\fR means the
43 standard input.
44 .SH OPTIONS
45 .sp
46 .LP
47 The following options are supported:
48 .sp
49 .ne 2
50 .na
51 \fB\fB-f\fR\fI progfile\fR \fR
52 .ad
53 .RS 16n
54 \fBawk\fR uses the set of patterns it reads from \fIprogfile\fR.
55 .RE
57 .sp
58 .ne 2
59 .na
60 \fB\fB-F\fR\fIc\fR \fR
61 .ad
62 .RS 16n
63 Uses the character \fIc\fR as the field separator (FS) character. See the
64 discussion of \fBFS\fR below.
65 .RE
67 .SH USAGE
68 .SS "Input Lines"
69 .sp
70 .LP
71 Each input line is matched against the pattern portion of every pattern-action
72 statement; the associated action is performed for each matched pattern. Any
73 \fIfilename\fR of the form \fIvar=value\fR is treated as an assignment, not a
74 filename, and is executed at the time it would have been opened if it were a
75 filename. \fIVariables\fR assigned in this manner are not available inside a
76 \fBBEGIN\fR rule, and are assigned after previously specified files have been
77 read.
78 .sp
79 .LP
80 An input line is normally made up of fields separated by white spaces. (This
81 default can be changed by using the \fBFS\fR built-in variable or the
82 \fB-F\fR\fIc\fR option.) The default is to ignore leading blanks and to
83 separate fields by blanks and/or tab characters. However, if \fBFS\fR is
84 assigned a value that does not include any of the white spaces, then leading
85 blanks are not ignored. The fields are denoted \fB$1\fR, \fB$2\fR,
86 \fB\&.\|.\|.\fR\|; \fB$0\fR refers to the entire line.
87 .SS "Pattern-action Statements"
88 .sp
89 .LP
90 A pattern-action statement has the form:
91 .sp
92 .in +2
93 .nf
94 \fIpattern\fR\fB { \fR\fIaction\fR\fB } \fR
95 .fi
96 .in -2
97 .sp
99 .sp
100 .LP
101 Either pattern or action can be omitted. If there is no action, the matching
102 line is printed. If there is no pattern, the action is performed on every input
103 line. Pattern-action statements are separated by newlines or semicolons.
104 .sp
105 .LP
106 Patterns are arbitrary Boolean combinations ( \fB!\fR, ||, \fB&&\fR, and
107 parentheses) of relational expressions and regular expressions. A relational
108 expression is one of the following:
109 .sp
110 .in +2
111 .nf
112 \fIexpression relop expression
113 expression matchop regular_expression\fR
114 .fi
115 .in -2
117 .sp
118 .LP
119 where a \fIrelop\fR is any of the six relational operators in C, and a
120 \fImatchop\fR is either \fB~\fR (contains) or \fB!~\fR (does not contain). An
121 \fIexpression\fR is an arithmetic expression, a relational expression, the
122 special expression
123 .sp
124 .in +2
125 .nf
126 \fIvar \fRin \fIarray\fR
127 .fi
128 .in -2
130 .sp
131 .LP
132 or a Boolean combination of these.
133 .sp
134 .LP
135 Regular expressions are as in \fBegrep\fR(1). In patterns they must be
136 surrounded by slashes. Isolated regular expressions in a pattern apply to the
137 entire line. Regular expressions can also occur in relational expressions. A
138 pattern can consist of two patterns separated by a comma; in this case, the
139 action is performed for all lines between the occurrence of the first pattern
140 to the occurrence of the second pattern.
141 .sp
142 .LP
143 The special patterns \fBBEGIN\fR and \fBEND\fR can be used to capture control
144 before the first input line has been read and after the last input line has
145 been read respectively. These keywords do not combine with any other patterns.
146 .SS "Built-in Variables"
147 .sp
148 .LP
149 Built-in variables include:
150 .sp
151 .ne 2
152 .na
153 \fB\fBFILENAME\fR \fR
154 .ad
155 .RS 13n
156 name of the current input file
157 .RE
159 .sp
160 .ne 2
161 .na
162 \fB\fBFS\fR \fR
163 .ad
164 .RS 13n
165 input field separator regular expression (default blank and tab)
166 .RE
168 .sp
169 .ne 2
170 .na
171 \fB\fBNF\fR \fR
172 .ad
173 .RS 13n
174 number of fields in the current record
175 .RE
177 .sp
178 .ne 2
179 .na
180 \fB\fBNR\fR \fR
181 .ad
182 .RS 13n
183 ordinal number of the current record
184 .RE
186 .sp
187 .ne 2
188 .na
189 \fB\fBOFMT\fR \fR
190 .ad
191 .RS 13n
192 output format for numbers (default \fB%.6g\fR)
193 .RE
195 .sp
196 .ne 2
197 .na
198 \fB\fBOFS\fR \fR
199 .ad
200 .RS 13n
201 output field separator (default blank)
202 .RE
204 .sp
205 .ne 2
206 .na
207 \fB\fBORS\fR \fR
208 .ad
209 .RS 13n
210 output record separator (default new-line)
211 .RE
213 .sp
214 .ne 2
215 .na
216 \fB\fBRS\fR \fR
217 .ad
218 .RS 13n
219 input record separator (default new-line)
220 .RE
222 .sp
223 .LP
224 An action is a sequence of statements. A statement can be one of the following:
225 .sp
226 .in +2
227 .nf
228 if ( \fIexpression\fR ) \fIstatement\fR [ else \fIstatement\fR ]
229 while ( \fIexpression\fR ) \fIstatement\fR
230 do \fIstatement\fR while ( \fIexpression\fR )
231 for ( \fIexpression\fR ; \fIexpression\fR ; \fIexpression\fR ) \fIstatement\fR
232 for ( \fIvar\fR in \fIarray\fR ) \fIstatement\fR
233 break
234 continue
235 { [ \fIstatement\fR ] .\|.\|. }
236 \fIexpression\fR # commonly variable = expression
237 print [ \fIexpression-list\fR ] [ >\fIexpression\fR ]
238 printf format [ ,\fIexpression-list\fR ] [ >\fIexpression\fR ]
239 next # skip remaining patterns on this input line
240 exit [expr] # skip the rest of the input; exit status is expr
241 .fi
242 .in -2
244 .sp
245 .LP
246 Statements are terminated by semicolons, newlines, or right braces. An empty
247 expression-list stands for the whole input line. Expressions take on string or
248 numeric values as appropriate, and are built using the operators \fB+\fR,
249 \fB\(mi\fR, \fB*\fR, \fB/\fR, \fB%\fR, \fB^\fR and concatenation (indicated by
250 a blank). The operators \fB++\fR, \fB\(mi\(mi\fR, \fB+=\fR, \fB\(mi=\fR,
251 \fB*=\fR, \fB/=\fR, \fB%=\fR, \fB^=\fR, \fB>\fR, \fB>=\fR, \fB<\fR, \fB<=\fR,
252 \fB==\fR, \fB!=\fR, and \fB?:\fR are also available in expressions. Variables
253 can be scalars, array elements (denoted x[i]), or fields. Variables are
254 initialized to the null string or zero. Array subscripts can be any string, not
255 necessarily numeric; this allows for a form of associative memory. String
256 constants are quoted (\fB""\fR), with the usual C escapes recognized within.
257 .sp
258 .LP
259 The \fBprint\fR statement prints its arguments on the standard output, or on a
260 file if \fB>\fR\fIexpression\fR is present, or on a pipe if '\fB|\fR\fIcmd\fR'
261 is present. The output resulted from the print statement is terminated by the
262 output record separator with each argument separated by the current output
263 field separator. The \fBprintf\fR statement formats its expression list
264 according to the format (see \fBprintf\fR(3C)).
265 .SS "Built-in Functions"
266 .sp
267 .LP
268 The arithmetic functions are as follows:
269 .sp
270 .ne 2
271 .na
272 \fB\fBcos\fR(\fIx\fR)\fR
273 .ad
274 .RS 11n
275 Return cosine of \fIx\fR, where \fIx\fR is in radians. (In
276 \fB/usr/xpg4/bin/awk\fR only. See \fBnawk\fR(1).)
277 .RE
279 .sp
280 .ne 2
281 .na
282 \fB\fBsin\fR(\fIx\fR)\fR
283 .ad
284 .RS 11n
285 Return sine of \fIx\fR, where \fIx\fR is in radians. (In
286 \fB/usr/xpg4/bin/awk\fR only. See \fBnawk\fR(1).)
287 .RE
289 .sp
290 .ne 2
291 .na
292 \fB\fBexp\fR(\fIx\fR)\fR
293 .ad
294 .RS 11n
295 Return the exponential function of \fIx\fR.
296 .RE
298 .sp
299 .ne 2
300 .na
301 \fB\fBlog\fR(\fIx\fR)\fR
302 .ad
303 .RS 11n
304 Return the natural logarithm of \fIx\fR.
305 .RE
307 .sp
308 .ne 2
309 .na
310 \fB\fBsqrt\fR(\fIx\fR)\fR
311 .ad
312 .RS 11n
313 Return the square root of \fIx\fR.
314 .RE
316 .sp
317 .ne 2
318 .na
319 \fB\fBint\fR(\fIx\fR)\fR
320 .ad
321 .RS 11n
322 Truncate its argument to an integer. It is truncated toward \fB0\fR when
323 \fIx\fR >\fB 0\fR.
324 .RE
326 .sp
327 .LP
328 The string functions are as follows:
329 .sp
330 .ne 2
331 .na
332 \fB\fBindex(\fR\fIs\fR\fB, \fR\fIt\fR\fB)\fR\fR
333 .ad
334 .sp .6
335 .RS 4n
336 Return the position in string \fIs\fR where string \fIt\fR first occurs, or
337 \fB0\fR if it does not occur at all.
338 .RE
340 .sp
341 .ne 2
342 .na
343 \fB\fBint(\fR\fIs\fR\fB)\fR\fR
344 .ad
345 .sp .6
346 .RS 4n
347 truncates \fIs\fR to an integer value. If \fIs\fR is not specified, $0 is used.
348 .RE
350 .sp
351 .ne 2
352 .na
353 \fB\fBlength(\fR\fIs\fR\fB)\fR\fR
354 .ad
355 .sp .6
356 .RS 4n
357 Return the length of its argument taken as a string, or of the whole line if
358 there is no argument.
359 .RE
361 .sp
362 .ne 2
363 .na
364 \fB\fBsplit(\fR\fIs\fR, \fIa\fR, \fIfs\fR\fB)\fR\fR
365 .ad
366 .sp .6
367 .RS 4n
368 Split the string \fIs\fR into array elements \fIa\fR[\fI1\fR],
369 \fIa\fR[\fI2\fR], \|.\|.\|. \fIa\fR[\fIn\fR], and returns \fIn\fR. The
370 separation is done with the regular expression \fIfs\fR or with the field
371 separator \fBFS\fR if \fIfs\fR is not given.
372 .RE
374 .sp
375 .ne 2
376 .na
377 \fB\fBsprintf(\fR\fIfmt\fR, \fIexpr\fR, \fIexpr\fR,\|.\|.\|.\|\fB)\fR\fR
378 .ad
379 .sp .6
380 .RS 4n
381 Format the expressions according to the \fBprintf\fR(3C) format given by
382 \fIfmt\fR and returns the resulting string.
383 .RE
385 .sp
386 .ne 2
387 .na
388 \fB\fBsubstr(\fR\fIs\fR, \fIm\fR, \fIn\fR\fB)\fR\fR
389 .ad
390 .sp .6
391 .RS 4n
392 returns the \fIn\fR-character substring of \fIs\fR that begins at position
393 \fIm\fR.
394 .RE
396 .sp
397 .LP
398 The input/output function is as follows:
399 .sp
400 .ne 2
401 .na
402 \fB\fBgetline\fR\fR
403 .ad
404 .RS 11n
405 Set \fB$0\fR to the next input record from the current input file.
406 \fBgetline\fR returns \fB1\fR for successful input, \fB0\fR for end of file,
407 and \fB\(mi1\fR for an error.
408 .RE
410 .SS "Large File Behavior"
411 .sp
412 .LP
413 See \fBlargefile\fR(5) for the description of the behavior of \fBawk\fR when
414 encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
415 .SH EXAMPLES
416 .LP
417 \fBExample 1 \fRPrinting Lines Longer Than 72 Characters
418 .sp
419 .LP
420 The following example is an \fBawk\fR script that can be executed by an \fBawk
421 -f examplescript\fR style command. It prints lines longer than seventy two
422 characters:
424 .sp
425 .in +2
426 .nf
427 \fBlength > 72\fR
428 .fi
429 .in -2
430 .sp
432 .LP
433 \fBExample 2 \fRPrinting Fields in Opposite Order
434 .sp
435 .LP
436 The following example is an \fBawk\fR script that can be executed by an \fBawk
437 -f examplescript\fR style command. It prints the first two fields in opposite
438 order:
440 .sp
441 .in +2
442 .nf
443 \fB{ print $2, $1 }\fR
444 .fi
445 .in -2
446 .sp
448 .LP
449 \fBExample 3 \fRPrinting Fields in Opposite Order with the Input Fields
450 Separated
451 .sp
452 .LP
453 The following example is an \fBawk\fR script that can be executed by an \fBawk
454 -f examplescript\fR style command. It prints the first two input fields in
455 opposite order, separated by a comma, blanks or tabs:
457 .sp
458 .in +2
459 .nf
460 \fBBEGIN { FS = ",[ \et]*|[ \et]+" }
461 { print $2, $1 }\fR
462 .fi
463 .in -2
464 .sp
466 .LP
467 \fBExample 4 \fRAdding Up the First Column, Printing the Sum and Average
468 .sp
469 .LP
470 The following example is an \fBawk\fR script that can be executed by an \fBawk
471 -f examplescript\fR style command. It adds up the first column, and prints the
472 sum and average:
474 .sp
475 .in +2
476 .nf
477 \fB{ s += $1 }
478 END { print "sum is", s, " average is", s/NR }\fR
479 .fi
480 .in -2
481 .sp
483 .LP
484 \fBExample 5 \fRPrinting Fields in Reverse Order
485 .sp
486 .LP
487 The following example is an \fBawk\fR script that can be executed by an \fBawk
488 -f examplescript\fR style command. It prints fields in reverse order:
490 .sp
491 .in +2
492 .nf
493 \fB{ for (i = NF; i > 0; \(mi\(mii) print $i }\fR
494 .fi
495 .in -2
496 .sp
498 .LP
499 \fBExample 6 \fRPrinting All lines Between \fBstart/stop\fR Pairs
500 .sp
501 .LP
502 The following example is an \fBawk\fR script that can be executed by an \fBawk
503 -f examplescript\fR style command. It prints all lines between start/stop
504 pairs.
506 .sp
507 .in +2
508 .nf
509 \fB/start/, /stop/\fR
510 .fi
511 .in -2
512 .sp
514 .LP
515 \fBExample 7 \fRPrinting All Lines Whose First Field is Different from the
516 Previous One
517 .sp
518 .LP
519 The following example is an \fBawk\fR script that can be executed by an \fBawk
520 -f examplescript\fR style command. It prints all lines whose first field is
521 different from the previous one.
523 .sp
524 .in +2
525 .nf
526 \fB$1 != prev { print; prev = $1 }\fR
527 .fi
528 .in -2
529 .sp
531 .LP
532 \fBExample 8 \fRPrinting a File and Filling in Page numbers
533 .sp
534 .LP
535 The following example is an \fBawk\fR script that can be executed by an \fBawk
536 -f examplescript\fR style command. It prints a file and fills in page numbers
537 starting at 5:
539 .sp
540 .in +2
541 .nf
542 \fB/Page/ { $2 = n++; }
543 { print }\fR
544 .fi
545 .in -2
546 .sp
548 .LP
549 \fBExample 9 \fRPrinting a File and Numbering Its Pages
550 .sp
551 .LP
552 Assuming this program is in a file named \fBprog\fR, the following example
553 prints the file \fBinput\fR numbering its pages starting at \fB5\fR:
555 .sp
556 .in +2
557 .nf
558 example% \fBawk -f prog n=5 input\fR
559 .fi
560 .in -2
561 .sp
563 .SH ENVIRONMENT VARIABLES
564 .sp
565 .LP
566 See \fBenviron\fR(5) for descriptions of the following environment variables
567 that affect the execution of \fBawk\fR: \fBLANG\fR, \fBLC_ALL\fR,
568 \fBLC_COLLATE\fR, \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, \fBNLSPATH\fR, and
569 \fBPATH\fR.
570 .sp
571 .ne 2
572 .na
573 \fB\fBLC_NUMERIC\fR\fR
574 .ad
575 .RS 14n
576 Determine the radix character used when interpreting numeric input, performing
577 conversions between numeric and string values and formatting numeric output.
578 Regardless of locale, the period character (the decimal-point character of the
579 POSIX locale) is the decimal-point character recognized in processing \fBawk\fR
580 programs (including assignments in command-line arguments).
581 .RE
583 .SH ATTRIBUTES
584 .sp
585 .LP
586 See \fBattributes\fR(5) for descriptions of the following attributes:
587 .SS "/usr/bin/awk"
588 .sp
590 .sp
591 .TS
592 box;
593 c | c
594 l | l .
595 ATTRIBUTE TYPE ATTRIBUTE VALUE
596 _
597 CSI Not Enabled
598 .TE
600 .SS "/usr/xpg4/bin/awk"
601 .sp
603 .sp
604 .TS
605 box;
606 c | c
607 l | l .
608 ATTRIBUTE TYPE ATTRIBUTE VALUE
609 _
610 CSI Enabled
611 _
612 Interface Stability Standard
613 .TE
615 .SH SEE ALSO
616 .sp
617 .LP
618 \fBegrep\fR(1), \fBgrep\fR(1), \fBnawk\fR(1), \fBsed\fR(1), \fBprintf\fR(3C),
619 \fBattributes\fR(5), \fBenviron\fR(5), \fBlargefile\fR(5), \fBstandards\fR(5)
620 .SH NOTES
621 .sp
622 .LP
623 Input white space is not preserved on output if fields are involved.
624 .sp
625 .LP
626 There are no explicit conversions between numbers and strings. To force an
627 expression to be treated as a number, add \fB0\fR to it. To force an expression
628 to be treated as a string, concatenate the null string (\fB""\fR) to it.