/contrib/one-true-awk/awk.1

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