vendor/awk: upgrade from 20121220 to 20200612
[dragonfly.git] / contrib / awk / awk.1
1 .de EX
2 .nf
3 .ft CW
4 ..
5 .de EE
6 .br
7 .fi
8 .ft 1
9 ..
10 .TH AWK 1
11 .CT 1 files prog_other
12 .SH NAME
13 awk \- pattern-directed scanning and processing language
14 .SH SYNOPSIS
15 .B awk
16 [
17 .BI \-F
18 .I fs
19 ]
20 [
21 .BI \-v
22 .I var=value
23 ]
24 [
25 .I 'prog'
26 |
27 .BI \-f
28 .I progfile
29 ]
30 [
31 .I file ...
32 ]
33 .SH DESCRIPTION
34 .I Awk
35 scans each input
36 .I file
37 for lines that match any of a set of patterns specified literally in
38 .I prog
39 or in one or more files
40 specified as
41 .B \-f
42 .IR progfile .
43 With each pattern
44 there can be an associated action that will be performed
45 when a line of a
46 .I file
47 matches the pattern.
48 Each line is matched against the
49 pattern portion of every pattern-action statement;
50 the associated action is performed for each matched pattern.
51 The file name
52 .B \-
53 means the standard input.
54 Any
55 .I file
56 of the form
57 .I var=value
58 is treated as an assignment, not a filename,
59 and is executed at the time it would have been opened if it were a filename.
60 The option
61 .B \-v
62 followed by
63 .I var=value
64 is an assignment to be done before
65 .I prog
66 is executed;
67 any number of
68 .B \-v
69 options may be present.
70 The
71 .B \-F
72 .I fs
73 option defines the input field separator to be the regular expression
74 .IR fs .
75 .PP
76 An input line is normally made up of fields separated by white space,
77 or by the regular expression
78 .BR FS .
79 The fields are denoted
80 .BR $1 ,
81 .BR $2 ,
82 \&..., while
83 .B $0
84 refers to the entire line.
85 If
86 .BR FS
87 is null, the input line is split into one field per character.
88 .PP
89 A pattern-action statement has the form:
90 .IP
91 .IB pattern " { " action " }
92 .PP
93 A missing
94 .BI { " action " }
95 means print the line;
96 a missing pattern always matches.
97 Pattern-action statements are separated by newlines or semicolons.
98 .PP
99 An action is a sequence of statements.
100 A statement can be one of the following:
101 .PP
102 .EX
103 .ta \w'\f(CWdelete array[expression]\fR'u
104 .RS
105 .nf
106 .ft CW
107 if(\fI expression \fP)\fI statement \fP\fR[ \fPelse\fI statement \fP\fR]\fP
108 while(\fI expression \fP)\fI statement\fP
109 for(\fI expression \fP;\fI expression \fP;\fI expression \fP)\fI statement\fP
110 for(\fI var \fPin\fI array \fP)\fI statement\fP
111 do\fI statement \fPwhile(\fI expression \fP)
112 break
113 continue
114 {\fR [\fP\fI statement ... \fP\fR] \fP}
115 \fIexpression\fP        #\fR commonly\fP\fI var = expression\fP
116 print\fR [ \fP\fIexpression-list \fP\fR] \fP\fR[ \fP>\fI expression \fP\fR]\fP
117 printf\fI format \fP\fR[ \fP,\fI expression-list \fP\fR] \fP\fR[ \fP>\fI expression \fP\fR]\fP
118 return\fR [ \fP\fIexpression \fP\fR]\fP
119 next    #\fR skip remaining patterns on this input line\fP
120 nextfile        #\fR skip rest of this file, open next, start at top\fP
121 delete\fI array\fP[\fI expression \fP]  #\fR delete an array element\fP
122 delete\fI array\fP      #\fR delete all elements of array\fP
123 exit\fR [ \fP\fIexpression \fP\fR]\fP   #\fR exit immediately; status is \fP\fIexpression\fP
124 .fi
125 .RE
126 .EE
127 .DT
128 .PP
129 Statements are terminated by
130 semicolons, newlines or right braces.
131 An empty
132 .I expression-list
133 stands for
134 .BR $0 .
135 String constants are quoted \&\f(CW"\ "\fR,
136 with the usual C escapes recognized within.
137 Expressions take on string or numeric values as appropriate,
138 and are built using the operators
139 .B + \- * / % ^
140 (exponentiation), and concatenation (indicated by white space).
141 The operators
142 .B
143 ! ++ \-\- += \-= *= /= %= ^= > >= < <= == != ?:
144 are also available in expressions.
145 Variables may be scalars, array elements
146 (denoted
147 .IB x  [ i ] \fR)
148 or fields.
149 Variables are initialized to the null string.
150 Array subscripts may be any string,
151 not necessarily numeric;
152 this allows for a form of associative memory.
153 Multiple subscripts such as
154 .B [i,j,k]
155 are permitted; the constituents are concatenated,
156 separated by the value of
157 .BR SUBSEP .
158 .PP
159 The
160 .B print
161 statement prints its arguments on the standard output
162 (or on a file if
163 .BI > " file
164 or
165 .BI >> " file
166 is present or on a pipe if
167 .BI | " cmd
168 is present), separated by the current output field separator,
169 and terminated by the output record separator.
170 .I file
171 and
172 .I cmd
173 may be literal names or parenthesized expressions;
174 identical string values in different statements denote
175 the same open file.
176 The
177 .B printf
178 statement formats its expression list according to the
179 .I format
180 (see
181 .IR printf (3)).
182 The built-in function
183 .BI close( expr )
184 closes the file or pipe
185 .IR expr .
186 The built-in function
187 .BI fflush( expr )
188 flushes any buffered output for the file or pipe
189 .IR expr .
190 .PP
191 The mathematical functions
192 .BR atan2 ,
193 .BR cos ,
194 .BR exp ,
195 .BR log ,
196 .BR sin ,
197 and
198 .B sqrt
199 are built in.
200 Other built-in functions:
201 .TF length
202 .TP
203 .B length
204 the length of its argument
205 taken as a string,
206 number of elements in an array for an array argument,
207 or length of
208 .B $0
209 if no argument.
210 .TP
211 .B rand
212 random number on [0,1).
213 .TP
214 .B srand
215 sets seed for
216 .B rand
217 and returns the previous seed.
218 .TP
219 .B int
220 truncates to an integer value.
221 .TP
222 \fBsubstr(\fIs\fB, \fIm\fR [\fB, \fIn\^\fR]\fB)\fR
223 the
224 .IR n -character
225 substring of
226 .I s
227 that begins at position
228 .I m
229 counted from 1.
230 If no
231 .IR n ,
232 use the rest of the string.
233 .TP
234 .BI index( s , " t" )
235 the position in
236 .I s
237 where the string
238 .I t
239 occurs, or 0 if it does not.
240 .TP
241 .BI match( s , " r" )
242 the position in
243 .I s
244 where the regular expression
245 .I r
246 occurs, or 0 if it does not.
247 The variables
248 .B RSTART
249 and
250 .B RLENGTH
251 are set to the position and length of the matched string.
252 .TP
253 \fBsplit(\fIs\fB, \fIa \fR[\fB, \fIfs\^\fR]\fB)\fR
254 splits the string
255 .I s
256 into array elements
257 .IB a [1] \fR,
258 .IB a [2] \fR,
259 \&...,
260 .IB a [ n ] \fR,
261 and returns
262 .IR n .
263 The separation is done with the regular expression
264 .I fs
265 or with the field separator
266 .B FS
267 if
268 .I fs
269 is not given.
270 An empty string as field separator splits the string
271 into one array element per character.
272 .TP
273 \fBsub(\fIr\fB, \fIt \fR[, \fIs\^\fR]\fB)
274 substitutes
275 .I t
276 for the first occurrence of the regular expression
277 .I r
278 in the string
279 .IR s .
280 If
281 .I s
282 is not given,
283 .B $0
284 is used.
285 .TP
286 \fBgsub(\fIr\fB, \fIt \fR[, \fIs\^\fR]\fB)
287 same as
288 .B sub
289 except that all occurrences of the regular expression
290 are replaced;
291 .B sub
292 and
293 .B gsub
294 return the number of replacements.
295 .TP
296 .BI sprintf( fmt , " expr" , " ...\fB)
297 the string resulting from formatting
298 .I expr ...
299 according to the
300 .IR printf (3)
301 format
302 .IR fmt .
303 .TP
304 .BI system( cmd )
305 executes
306 .I cmd
307 and returns its exit status. This will be \-1 upon error,
308 .IR cmd 's
309 exit status upon a normal exit,
310 256 +
311 .I sig
312 upon death-by-signal, where
313 .I sig
314 is the number of the murdering signal,
315 or 512 +
316 .I sig
317 if there was a core dump.
318 .TP
319 .BI tolower( str )
320 returns a copy of
321 .I str
322 with all upper-case characters translated to their
323 corresponding lower-case equivalents.
324 .TP
325 .BI toupper( str )
326 returns a copy of
327 .I str
328 with all lower-case characters translated to their
329 corresponding upper-case equivalents.
330 .PD
331 .PP
332 The ``function''
333 .B getline
334 sets
335 .B $0
336 to the next input record from the current input file;
337 .B getline
338 .BI < " file
339 sets
340 .B $0
341 to the next record from
342 .IR file .
343 .B getline
344 .I x
345 sets variable
346 .I x
347 instead.
348 Finally,
349 .IB cmd " | getline
350 pipes the output of
351 .I cmd
352 into
353 .BR getline ;
354 each call of
355 .B getline
356 returns the next line of output from
357 .IR cmd .
358 In all cases,
359 .B getline
360 returns 1 for a successful input,
361 0 for end of file, and \-1 for an error.
362 .PP
363 Patterns are arbitrary Boolean combinations
364 (with
365 .BR "! || &&" )
366 of regular expressions and
367 relational expressions.
368 Regular expressions are as in
369 .IR egrep ;
370 see
371 .IR grep (1).
372 Isolated regular expressions
373 in a pattern apply to the entire line.
374 Regular expressions may also occur in
375 relational expressions, using the operators
376 .B ~
377 and
378 .BR !~ .
379 .BI / re /
380 is a constant regular expression;
381 any string (constant or variable) may be used
382 as a regular expression, except in the position of an isolated regular expression
383 in a pattern.
384 .PP
385 A pattern may consist of two patterns separated by a comma;
386 in this case, the action is performed for all lines
387 from an occurrence of the first pattern
388 though an occurrence of the second.
389 .PP
390 A relational expression is one of the following:
391 .IP
392 .I expression matchop regular-expression
393 .br
394 .I expression relop expression
395 .br
396 .IB expression " in " array-name
397 .br
398 .BI ( expr , expr,... ") in " array-name
399 .PP
400 where a
401 .I relop
402 is any of the six relational operators in C,
403 and a
404 .I matchop
405 is either
406 .B ~
407 (matches)
408 or
409 .B !~
410 (does not match).
411 A conditional is an arithmetic expression,
412 a relational expression,
413 or a Boolean combination
414 of these.
415 .PP
416 The special patterns
417 .B BEGIN
418 and
419 .B END
420 may be used to capture control before the first input line is read
421 and after the last.
422 .B BEGIN
423 and
424 .B END
425 do not combine with other patterns.
426 They may appear multiple times in a program and execute
427 in the order they are read by
428 .IR awk .
429 .PP
430 Variable names with special meanings:
431 .TF FILENAME
432 .TP
433 .B ARGC
434 argument count, assignable.
435 .TP
436 .B ARGV
437 argument array, assignable;
438 non-null members are taken as filenames.
439 .TP
440 .B CONVFMT
441 conversion format used when converting numbers
442 (default
443 .BR "%.6g" ).
444 .TP
445 .B ENVIRON
446 array of environment variables; subscripts are names.
447 .TP
448 .B FILENAME
449 the name of the current input file.
450 .TP
451 .B FNR
452 ordinal number of the current record in the current file.
453 .TP
454 .B FS
455 regular expression used to separate fields; also settable
456 by option
457 .BI \-F fs\fR.
458 .TP
459 .BR NF
460 number of fields in the current record.
461 .TP
462 .B NR
463 ordinal number of the current record.
464 .TP
465 .B OFMT
466 output format for numbers (default
467 .BR "%.6g" ).
468 .TP
469 .B OFS
470 output field separator (default space).
471 .TP
472 .B ORS
473 output record separator (default newline).
474 .TP
475 .B RLENGTH
476 the length of a string matched by
477 .BR match .
478 .TP
479 .B RS
480 input record separator (default newline).
481 If empty, blank lines separate records.
482 If more than one character long,
483 .B RS
484 is treated as a regular expression, and records are
485 separated by text matching the expression.
486 .TP
487 .B RSTART
488 the start position of a string matched by
489 .BR match .
490 .TP
491 .B SUBSEP
492 separates multiple subscripts (default 034).
493 .PD
494 .PP
495 Functions may be defined (at the position of a pattern-action statement) thus:
496 .IP
497 .B
498 function foo(a, b, c) { ...; return x }
499 .PP
500 Parameters are passed by value if scalar and by reference if array name;
501 functions may be called recursively.
502 Parameters are local to the function; all other variables are global.
503 Thus local variables may be created by providing excess parameters in
504 the function definition.
505 .SH ENVIRONMENT VARIABLES
506 If
507 .B POSIXLY_CORRECT
508 is set in the environment, then
509 .I awk
510 follows the POSIX rules for
511 .B sub
512 and
513 .B gsub
514 with respect to consecutive backslashes and ampersands.
515 .SH EXAMPLES
516 .TP
517 .EX
518 length($0) > 72
519 .EE
520 Print lines longer than 72 characters.
521 .TP
522 .EX
523 { print $2, $1 }
524 .EE
525 Print first two fields in opposite order.
526 .PP
527 .EX
528 BEGIN { FS = ",[ \et]*|[ \et]+" }
529       { print $2, $1 }
530 .EE
531 .ns
532 .IP
533 Same, with input fields separated by comma and/or spaces and tabs.
534 .PP
535 .EX
536 .nf
537         { s += $1 }
538 END     { print "sum is", s, " average is", s/NR }
539 .fi
540 .EE
541 .ns
542 .IP
543 Add up first column, print sum and average.
544 .TP
545 .EX
546 /start/, /stop/
547 .EE
548 Print all lines between start/stop pairs.
549 .PP
550 .EX
551 .nf
552 BEGIN   {       # Simulate echo(1)
553         for (i = 1; i < ARGC; i++) printf "%s ", ARGV[i]
554         printf "\en"
555         exit }
556 .fi
557 .EE
558 .SH SEE ALSO
559 .IR grep (1),
560 .IR lex (1),
561 .IR sed (1)
562 .br
563 A. V. Aho, B. W. Kernighan, P. J. Weinberger,
564 .IR "The AWK Programming Language" ,
565 Addison-Wesley, 1988.  ISBN 0-201-07981-X.
566 .SH BUGS
567 There are no explicit conversions between numbers and strings.
568 To force an expression to be treated as a number add 0 to it;
569 to force it to be treated as a string concatenate
570 \&\f(CW""\fP to it.
571 .PP
572 The scope rules for variables in functions are a botch;
573 the syntax is worse.
574 .PP
575 Only eight-bit characters sets are handled correctly.