Annotation of src/usr.bin/awk/awk.1, Revision 1.51
1.51 ! millert 1: .\" $OpenBSD: awk.1,v 1.50 2020/06/10 21:05:02 millert Exp $
1.11 jmc 2: .\"
3: .\" Copyright (C) Lucent Technologies 1997
4: .\" All Rights Reserved
1.12 jmc 5: .\"
1.11 jmc 6: .\" Permission to use, copy, modify, and distribute this software and
7: .\" its documentation for any purpose and without fee is hereby
8: .\" granted, provided that the above copyright notice appear in all
9: .\" copies and that both that the copyright notice and this
10: .\" permission notice and warranty disclaimer appear in supporting
11: .\" documentation, and that the name Lucent Technologies or any of
12: .\" its entities not be used in advertising or publicity pertaining
13: .\" to distribution of the software without specific, written prior
14: .\" permission.
1.12 jmc 15: .\"
1.11 jmc 16: .\" LUCENT DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
17: .\" INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.
18: .\" IN NO EVENT SHALL LUCENT OR ANY OF ITS ENTITIES BE LIABLE FOR ANY
19: .\" SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
20: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER
21: .\" IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
22: .\" ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
23: .\" THIS SOFTWARE.
24: .\"
1.48 millert 25: .Dd $Mdocdate: June 10 2020 $
1.7 aaron 26: .Dt AWK 1
27: .Os
28: .Sh NAME
29: .Nm awk
30: .Nd pattern-directed scanning and processing language
31: .Sh SYNOPSIS
32: .Nm awk
1.16 jmc 33: .Op Fl safe
34: .Op Fl V
35: .Op Fl d Ns Op Ar n
1.7 aaron 36: .Op Fl F Ar fs
1.38 schwarze 37: .Op Fl v Ar var Ns = Ns Ar value
1.18 jmc 38: .Op Ar prog | Fl f Ar progfile
1.7 aaron 39: .Ar
40: .Sh DESCRIPTION
41: .Nm
1.1 tholo 42: scans each input
1.7 aaron 43: .Ar file
1.1 tholo 44: for lines that match any of a set of patterns specified literally in
1.7 aaron 45: .Ar prog
1.16 jmc 46: or in one or more files specified as
1.7 aaron 47: .Fl f Ar progfile .
1.16 jmc 48: With each pattern there can be an associated action that will be performed
1.1 tholo 49: when a line of a
1.7 aaron 50: .Ar file
1.1 tholo 51: matches the pattern.
52: Each line is matched against the
53: pattern portion of every pattern-action statement;
54: the associated action is performed for each matched pattern.
1.6 aaron 55: The file name
1.16 jmc 56: .Sq -
1.1 tholo 57: means the standard input.
58: Any
1.7 aaron 59: .Ar file
1.1 tholo 60: of the form
1.16 jmc 61: .Ar var Ns = Ns Ar value
1.1 tholo 62: is treated as an assignment, not a filename,
63: and is executed at the time it would have been opened if it were a filename.
1.16 jmc 64: .Pp
65: The options are as follows:
1.20 jmc 66: .Bl -tag -width "-safe "
1.16 jmc 67: .It Fl d Ns Op Ar n
68: Debug mode.
69: Set debug level to
70: .Ar n ,
71: or 1 if
72: .Ar n
73: is not specified.
74: A value greater than 1 causes
75: .Nm
76: to dump core on fatal errors.
77: .It Fl F Ar fs
78: Define the input field separator to be the regular expression
1.7 aaron 79: .Ar fs .
1.25 jmc 80: .It Fl f Ar progfile
1.16 jmc 81: Read program code from the specified file
1.25 jmc 82: .Ar progfile
1.16 jmc 83: instead of from the command line.
84: .It Fl safe
85: Disable file output
1.17 jmc 86: .Pf ( Ic print No > ,
87: .Ic print No >> ) ,
1.7 aaron 88: process creation
89: .Po
1.17 jmc 90: .Ar cmd | Ic getline ,
1.40 jmc 91: .Ic print | ,
1.17 jmc 92: .Ic system
1.7 aaron 93: .Pc
94: and access to the environment
1.17 jmc 95: .Pf ( Va ENVIRON ;
1.18 jmc 96: see the section on variables below).
1.17 jmc 97: This is a first
1.16 jmc 98: .Pq and not very reliable
99: approximation to a
1.7 aaron 100: .Dq safe
101: version of
1.16 jmc 102: .Nm .
103: .It Fl V
104: Print the version number of
105: .Nm
106: to standard output and exit.
107: .It Fl v Ar var Ns = Ns Ar value
108: Assign
109: .Ar value
110: to variable
111: .Ar var
112: before
113: .Ar prog
114: is executed;
115: any number of
116: .Fl v
117: options may be present.
118: .El
1.7 aaron 119: .Pp
1.18 jmc 120: The input is normally made up of input lines
121: .Pq records
122: separated by newlines, or by the value of
123: .Va RS .
124: If
125: .Va RS
126: is null, then any number of blank lines are used as the record separator,
127: and newlines are used as field separators
128: (in addition to the value of
129: .Va FS ) .
130: This is convenient when working with multi-line records.
131: .Pp
1.7 aaron 132: An input line is normally made up of fields separated by whitespace,
1.18 jmc 133: or by the regular expression
1.7 aaron 134: .Va FS .
1.1 tholo 135: The fields are denoted
1.7 aaron 136: .Va $1 , $2 , ... ,
137: while
138: .Va $0
1.1 tholo 139: refers to the entire line.
140: If
1.7 aaron 141: .Va FS
1.1 tholo 142: is null, the input line is split into one field per character.
1.7 aaron 143: .Pp
1.18 jmc 144: Normally, any number of blanks separate fields.
145: In order to set the field separator to a single blank, use the
146: .Fl F
147: option with a value of
148: .Sq [\ \&] .
149: If a field separator of
150: .Sq t
151: is specified,
152: .Nm
153: treats it as if
154: .Sq \et
155: had been specified and uses
156: .Aq TAB
157: as the field separator.
158: In order to use a literal
159: .Sq t
160: as the field separator, use the
161: .Fl F
162: option with a value of
163: .Sq [t] .
164: .Pp
1.47 millert 165: A pattern-action statement has the form:
1.7 aaron 166: .Pp
167: .D1 Ar pattern Ic \&{ Ar action Ic \&}
168: .Pp
1.6 aaron 169: A missing
1.7 aaron 170: .Ic \&{ Ar action Ic \&}
1.1 tholo 171: means print the line;
172: a missing pattern always matches.
173: Pattern-action statements are separated by newlines or semicolons.
1.7 aaron 174: .Pp
1.18 jmc 175: Newlines are permitted after a terminating statement or following a comma
176: .Pq Sq ,\& ,
177: an open brace
178: .Pq Sq { ,
179: a logical AND
180: .Pq Sq && ,
181: a logical OR
182: .Pq Sq || ,
183: after the
184: .Sq do
185: or
186: .Sq else
187: keywords,
188: or after the closing parenthesis of an
189: .Sq if ,
190: .Sq for ,
191: or
192: .Sq while
193: statement.
194: Additionally, a backslash
195: .Pq Sq \e
196: can be used to escape a newline between tokens.
197: .Pp
1.1 tholo 198: An action is a sequence of statements.
199: A statement can be one of the following:
1.35 jmc 200: .Pp
201: .Bl -tag -width Ds -offset indent -compact
1.43 schwarze 202: .It Ic if Ar ( expression ) Ar statement Op Ic else Ar statement
203: .It Ic while Ar ( expression ) Ar statement
204: .It Ic for Ar ( expression ; expression ; expression ) statement
205: .It Ic for Ar ( var Ic in Ar array ) statement
206: .It Ic do Ar statement Ic while Ar ( expression )
1.35 jmc 207: .It Ic break
208: .It Ic continue
209: .It Xo Ic {
210: .Op Ar statement ...
211: .Ic }
212: .Xc
213: .It Xo Ar expression
214: .No # commonly
215: .Ar var No = Ar expression
1.7 aaron 216: .Xc
1.35 jmc 217: .It Xo Ic print
1.7 aaron 218: .Op Ar expression-list
1.17 jmc 219: .Op > Ns Ar expression
1.7 aaron 220: .Xc
1.35 jmc 221: .It Xo Ic printf Ar format
1.7 aaron 222: .Op Ar ... , expression-list
1.17 jmc 223: .Op > Ns Ar expression
1.7 aaron 224: .Xc
1.35 jmc 225: .It Ic return Op Ar expression
226: .It Xo Ic next
227: .No # skip remaining patterns on this input line
228: .Xc
229: .It Xo Ic nextfile
230: .No # skip rest of this file, open next, start at top
231: .Xc
232: .It Xo Ic delete
233: .Sm off
234: .Ar array Ic \&[ Ar expression Ic \&]
235: .Sm on
236: .No # delete an array element
1.7 aaron 237: .Xc
1.35 jmc 238: .It Xo Ic delete Ar array
239: .No # delete all elements of array
1.7 aaron 240: .Xc
1.35 jmc 241: .It Xo Ic exit
1.7 aaron 242: .Op Ar expression
1.46 deraadt 243: .No # exit processing, and perform
244: .Ic END
245: processing; status is
246: .Ar expression
1.7 aaron 247: .Xc
1.35 jmc 248: .El
1.7 aaron 249: .Pp
1.1 tholo 250: Statements are terminated by
251: semicolons, newlines or right braces.
252: An empty
1.7 aaron 253: .Ar expression-list
1.1 tholo 254: stands for
1.7 aaron 255: .Ar $0 .
256: String constants are quoted
257: .Li \&"" ,
1.20 jmc 258: with the usual C escapes recognized within
259: (see
260: .Xr printf 1
261: for a complete list of these).
1.1 tholo 262: Expressions take on string or numeric values as appropriate,
263: and are built using the operators
1.7 aaron 264: .Ic + \- * / % ^
1.20 jmc 265: .Pq exponentiation ,
266: and concatenation
267: .Pq indicated by whitespace .
1.1 tholo 268: The operators
1.16 jmc 269: .Ic \&! ++ \-\- += \-= *= /= %= ^=
270: .Ic > >= < <= == != ?:
1.1 tholo 271: are also available in expressions.
272: Variables may be scalars, array elements
273: (denoted
1.7 aaron 274: .Li x[i] )
1.1 tholo 275: or fields.
276: Variables are initialized to the null string.
277: Array subscripts may be any string,
278: not necessarily numeric;
279: this allows for a form of associative memory.
280: Multiple subscripts such as
1.7 aaron 281: .Li [i,j,k]
1.1 tholo 282: are permitted; the constituents are concatenated,
283: separated by the value of
1.17 jmc 284: .Va SUBSEP
1.31 deraadt 285: .Pq see the section on variables below .
1.7 aaron 286: .Pp
1.1 tholo 287: The
1.7 aaron 288: .Ic print
1.1 tholo 289: statement prints its arguments on the standard output
290: (or on a file if
1.47 millert 291: .Pf >\ \& Ar file
1.1 tholo 292: or
1.47 millert 293: .Pf >>\ \& Ar file
1.1 tholo 294: is present or on a pipe if
1.17 jmc 295: .Pf |\ \& Ar cmd
1.1 tholo 296: is present), separated by the current output field separator,
297: and terminated by the output record separator.
1.7 aaron 298: .Ar file
1.1 tholo 299: and
1.7 aaron 300: .Ar cmd
1.1 tholo 301: may be literal names or parenthesized expressions;
302: identical string values in different statements denote
303: the same open file.
304: The
1.7 aaron 305: .Ic printf
1.47 millert 306: statement formats its expression list according to the
307: .Ar format
1.1 tholo 308: (see
1.28 jmc 309: .Xr printf 1 ) .
1.18 jmc 310: .Pp
311: Patterns are arbitrary Boolean combinations
312: (with
313: .Ic "\&! || &&" )
314: of regular expressions and
315: relational expressions.
1.22 jmc 316: .Nm
317: supports extended regular expressions
318: .Pq EREs .
319: See
320: .Xr re_format 7
321: for more information on regular expressions.
1.18 jmc 322: Isolated regular expressions
323: in a pattern apply to the entire line.
324: Regular expressions may also occur in
325: relational expressions, using the operators
326: .Ic ~
327: and
328: .Ic !~ .
1.44 schwarze 329: .Pf / Ar re Ns /
1.18 jmc 330: is a constant regular expression;
331: any string (constant or variable) may be used
332: as a regular expression, except in the position of an isolated regular expression
333: in a pattern.
334: .Pp
335: A pattern may consist of two patterns separated by a comma;
336: in this case, the action is performed for all lines
337: from an occurrence of the first pattern
338: through an occurrence of the second.
339: .Pp
340: A relational expression is one of the following:
1.35 jmc 341: .Pp
342: .Bl -tag -width Ds -offset indent -compact
343: .It Ar expression matchop regular-expression
344: .It Ar expression relop expression
345: .It Ar expression Ic in Ar array-name
346: .It Xo Ic \&( Ns
1.18 jmc 347: .Ar expr , expr , \&... Ns Ic \&) in
1.35 jmc 348: .Ar array-name
1.18 jmc 349: .Xc
1.35 jmc 350: .El
1.18 jmc 351: .Pp
352: where a
353: .Ar relop
354: is any of the six relational operators in C, and a
355: .Ar matchop
356: is either
357: .Ic ~
358: (matches)
359: or
360: .Ic !~
361: (does not match).
362: A conditional is an arithmetic expression,
363: a relational expression,
364: or a Boolean combination
365: of these.
366: .Pp
1.46 deraadt 367: The special pattern
1.18 jmc 368: .Ic BEGIN
1.46 deraadt 369: may be used to capture control before the first input line is read.
370: The special pattern
1.18 jmc 371: .Ic END
1.46 deraadt 372: may be used to capture control after processing is finished.
1.18 jmc 373: .Ic BEGIN
374: and
375: .Ic END
376: do not combine with other patterns.
1.47 millert 377: They may appear multiple times in a program and execute
378: in the order they are read by
379: .Nm .
1.18 jmc 380: .Pp
381: Variable names with special meanings:
382: .Pp
1.20 jmc 383: .Bl -tag -width "FILENAME " -compact
1.18 jmc 384: .It Va ARGC
385: Argument count, assignable.
386: .It Va ARGV
387: Argument array, assignable;
388: non-null members are taken as filenames.
389: .It Va CONVFMT
390: Conversion format when converting numbers
391: (default
392: .Qq Li %.6g ) .
393: .It Va ENVIRON
394: Array of environment variables; subscripts are names.
395: .It Va FILENAME
396: The name of the current input file.
397: .It Va FNR
398: Ordinal number of the current record in the current file.
399: .It Va FS
400: Regular expression used to separate fields; also settable
401: by option
402: .Fl F Ar fs .
403: .It Va NF
404: Number of fields in the current record.
405: .Va $NF
406: can be used to obtain the value of the last field in the current record.
407: .It Va NR
408: Ordinal number of the current record.
409: .It Va OFMT
410: Output format for numbers (default
411: .Qq Li %.6g ) .
412: .It Va OFS
413: Output field separator (default blank).
414: .It Va ORS
415: Output record separator (default newline).
416: .It Va RLENGTH
417: The length of the string matched by the
418: .Fn match
419: function.
420: .It Va RS
421: Input record separator (default newline).
1.49 millert 422: If empty, blank lines separate records.
423: If more than one character long,
424: .Va RS
425: is treated as a regular expression, and records are
426: separated by text matching the expression.
1.18 jmc 427: .It Va RSTART
428: The starting position of the string matched by the
429: .Fn match
430: function.
431: .It Va SUBSEP
432: Separates multiple subscripts (default 034).
433: .El
1.17 jmc 434: .Sh FUNCTIONS
435: The awk language has a variety of built-in functions:
1.30 jmc 436: arithmetic, string, input/output, general, and bit-operation.
437: .Pp
438: Functions may be defined (at the position of a pattern-action statement)
439: thusly:
440: .Pp
441: .Dl function foo(a, b, c) { ...; return x }
442: .Pp
443: Parameters are passed by value if scalar, and by reference if array name;
444: functions may be called recursively.
445: Parameters are local to the function; all other variables are global.
446: Thus local variables may be created by providing excess parameters in
447: the function definition.
1.17 jmc 448: .Ss Arithmetic Functions
449: .Bl -tag -width "atan2(y, x)"
450: .It Fn atan2 y x
451: Return the arctangent of
452: .Fa y Ns / Ns Fa x
453: in radians.
454: .It Fn cos x
455: Return the cosine of
456: .Fa x ,
457: where
458: .Fa x
459: is in radians.
460: .It Fn exp x
461: Return the exponential of
462: .Fa x .
463: .It Fn int x
464: Return
465: .Fa x
466: truncated to an integer value.
467: .It Fn log x
468: Return the natural logarithm of
469: .Fa x .
1.7 aaron 470: .It Fn rand
1.17 jmc 471: Return a random number,
472: .Fa n ,
473: such that
474: .Sm off
475: .Pf 0 \*(Le Fa n No \*(Lt 1 .
476: .Sm on
477: .It Fn sin x
478: Return the sine of
479: .Fa x ,
480: where
481: .Fa x
482: is in radians.
483: .It Fn sqrt x
484: Return the square root of
485: .Fa x .
486: .It Fn srand expr
1.16 jmc 487: Sets seed for
1.7 aaron 488: .Fn rand
1.17 jmc 489: to
490: .Fa expr
1.1 tholo 491: and returns the previous seed.
1.17 jmc 492: If
493: .Fa expr
494: is omitted, the time of day is used instead.
495: .El
496: .Ss String Functions
497: .Bl -tag -width "split(s, a, fs)"
498: .It Fn gsub r t s
499: The same as
500: .Fn sub
501: except that all occurrences of the regular expression are replaced.
502: .Fn gsub
503: returns the number of replacements.
1.7 aaron 504: .It Fn index s t
1.16 jmc 505: The position in
1.7 aaron 506: .Fa s
1.1 tholo 507: where the string
1.7 aaron 508: .Fa t
1.1 tholo 509: occurs, or 0 if it does not.
1.17 jmc 510: .It Fn length s
511: The length of
512: .Fa s
513: taken as a string,
1.47 millert 514: number of elements in an array for an array argument,
515: or length of
1.17 jmc 516: .Va $0
517: if no argument is given.
1.7 aaron 518: .It Fn match s r
1.16 jmc 519: The position in
1.7 aaron 520: .Fa s
1.1 tholo 521: where the regular expression
1.7 aaron 522: .Fa r
1.1 tholo 523: occurs, or 0 if it does not.
1.17 jmc 524: The variable
1.7 aaron 525: .Va RSTART
1.17 jmc 526: is set to the starting position of the matched string
527: .Pq which is the same as the returned value
528: or zero if no match is found.
529: The variable
1.7 aaron 530: .Va RLENGTH
1.17 jmc 531: is set to the length of the matched string,
532: or \-1 if no match is found.
1.7 aaron 533: .It Fn split s a fs
1.16 jmc 534: Splits the string
1.7 aaron 535: .Fa s
1.1 tholo 536: into array elements
1.7 aaron 537: .Va a[1] , a[2] , ... , a[n]
1.1 tholo 538: and returns
1.7 aaron 539: .Va n .
1.1 tholo 540: The separation is done with the regular expression
1.7 aaron 541: .Ar fs
1.1 tholo 542: or with the field separator
1.7 aaron 543: .Va FS
1.1 tholo 544: if
1.7 aaron 545: .Ar fs
1.1 tholo 546: is not given.
547: An empty string as field separator splits the string
548: into one array element per character.
1.17 jmc 549: .It Fn sprintf fmt expr ...
550: The string resulting from formatting
551: .Fa expr , ...
552: according to the
1.28 jmc 553: .Xr printf 1
1.17 jmc 554: format
555: .Fa fmt .
1.7 aaron 556: .It Fn sub r t s
1.16 jmc 557: Substitutes
1.7 aaron 558: .Fa t
1.1 tholo 559: for the first occurrence of the regular expression
1.7 aaron 560: .Fa r
1.1 tholo 561: in the string
1.7 aaron 562: .Fa s .
1.1 tholo 563: If
1.7 aaron 564: .Fa s
1.1 tholo 565: is not given,
1.7 aaron 566: .Va $0
1.1 tholo 567: is used.
1.17 jmc 568: An ampersand
569: .Pq Sq &
570: in
571: .Fa t
572: is replaced in string
573: .Fa s
574: with regular expression
575: .Fa r .
576: A literal ampersand can be specified by preceding it with two backslashes
577: .Pq Sq \e\e .
578: A literal backslash can be specified by preceding it with another backslash
579: .Pq Sq \e\e .
1.7 aaron 580: .Fn sub
1.17 jmc 581: returns the number of replacements.
582: .It Fn substr s m n
583: Return at most the
584: .Fa n Ns -character
585: substring of
586: .Fa s
587: that begins at position
588: .Fa m
589: counted from 1.
590: If
591: .Fa n
592: is omitted, or if
593: .Fa n
594: specifies more characters than are left in the string,
595: the length of the substring is limited by the length of
596: .Fa s .
1.7 aaron 597: .It Fn tolower str
1.16 jmc 598: Returns a copy of
1.7 aaron 599: .Fa str
1.1 tholo 600: with all upper-case characters translated to their
601: corresponding lower-case equivalents.
1.7 aaron 602: .It Fn toupper str
1.16 jmc 603: Returns a copy of
1.7 aaron 604: .Fa str
1.1 tholo 605: with all lower-case characters translated to their
606: corresponding upper-case equivalents.
1.7 aaron 607: .El
1.17 jmc 608: .Ss Input/Output and General Functions
609: .Bl -tag -width "getline [var] < file"
610: .It Fn close expr
611: Closes the file or pipe
612: .Fa expr .
613: .Fa expr
614: should match the string that was used to open the file or pipe.
615: .It Ar cmd | Ic getline Op Va var
616: Read a record of input from a stream piped from the output of
617: .Ar cmd .
618: If
619: .Va var
620: is omitted, the variables
621: .Va $0
622: and
623: .Va NF
624: are set.
625: Otherwise
626: .Va var
627: is set.
628: If the stream is not open, it is opened.
629: As long as the stream remains open, subsequent calls
630: will read subsequent records from the stream.
631: The stream remains open until explicitly closed with a call to
632: .Fn close .
1.24 jmc 633: .Ic getline
634: returns 1 for a successful input, 0 for end of file, and \-1 for an error.
635: .It Fn fflush [expr]
1.39 jmc 636: Flushes any buffered output for the file or pipe
1.24 jmc 637: .Fa expr ,
638: or all open files or pipes if
639: .Fa expr
640: is omitted.
1.17 jmc 641: .Fa expr
642: should match the string that was used to open the file or pipe.
643: .It Ic getline
644: Sets
645: .Va $0
646: to the next input record from the current input file.
647: This form of
648: .Ic getline
649: sets the variables
650: .Va NF ,
651: .Va NR ,
652: and
653: .Va FNR .
1.7 aaron 654: .Ic getline
1.17 jmc 655: returns 1 for a successful input, 0 for end of file, and \-1 for an error.
656: .It Ic getline Va var
657: Sets
1.7 aaron 658: .Va $0
1.17 jmc 659: to variable
660: .Va var .
661: This form of
662: .Ic getline
663: sets the variables
664: .Va NR
665: and
666: .Va FNR .
667: .Ic getline
668: returns 1 for a successful input, 0 for end of file, and \-1 for an error.
669: .It Xo
670: .Ic getline Op Va var
1.47 millert 671: .Pf <\ \& Ar file
1.17 jmc 672: .Xc
673: Sets
1.7 aaron 674: .Va $0
1.1 tholo 675: to the next record from
1.7 aaron 676: .Ar file .
1.17 jmc 677: If
678: .Va var
679: is omitted, the variables
680: .Va $0
681: and
682: .Va NF
683: are set.
684: Otherwise
685: .Va var
686: is set.
687: If
688: .Ar file
689: is not open, it is opened.
690: As long as the stream remains open, subsequent calls will read subsequent
691: records from
692: .Ar file .
693: .Ar file
694: remains open until explicitly closed with a call to
695: .Fn close .
696: .It Fn system cmd
697: Executes
698: .Fa cmd
699: and returns its exit status.
1.47 millert 700: This will be \-1 upon error,
701: .Ar cmd Ns 's
702: exit status upon a normal exit,
703: 256 +
704: .Em sig
705: if
706: .Fa cmd
707: was terminated by a signal, where
708: .Em sig
709: is the number of the signal,
710: or 512 +
711: .Em sig
712: if there was a core dump.
1.17 jmc 713: .El
1.30 jmc 714: .Ss Bit-Operation Functions
1.29 pyr 715: .Bl -tag -width "lshift(a, b)"
716: .It Fn compl x
717: Returns the bitwise complement of integer argument x.
718: .It Fn and x y
1.30 jmc 719: Performs a bitwise AND on integer arguments x and y.
1.29 pyr 720: .It Fn or x y
1.30 jmc 721: Performs a bitwise OR on integer arguments x and y.
1.29 pyr 722: .It Fn xor x y
1.30 jmc 723: Performs a bitwise Exclusive-OR on integer arguments x and y.
1.29 pyr 724: .It Fn lshift x n
1.39 jmc 725: Returns integer argument x shifted by n bits to the left.
1.29 pyr 726: .It Fn rshift x n
1.39 jmc 727: Returns integer argument x shifted by n bits to the right.
1.29 pyr 728: .El
1.50 millert 729: .Sh ENVIRONMENT
730: The following environment variables affect the execution of
731: .Nm :
732: .Bl -tag -width POSIXLY_CORRECT
733: .It Ev POSIXLY_CORRECT
734: When set, behave in accordance with the standard, even when it conflicts
735: with historical behavior.
736: .El
1.37 jmc 737: .Sh EXIT STATUS
738: .Ex -std awk
739: .Pp
740: But note that the
741: .Ic exit
742: expression can modify the exit status.
1.7 aaron 743: .Sh EXAMPLES
1.16 jmc 744: Print lines longer than 72 characters:
745: .Pp
1.7 aaron 746: .Dl length($0) > 72
1.16 jmc 747: .Pp
748: Print first two fields in opposite order:
1.7 aaron 749: .Pp
750: .Dl { print $2, $1 }
1.16 jmc 751: .Pp
1.47 millert 752: Same, with input fields separated by comma and/or spaces and tabs:
1.7 aaron 753: .Bd -literal -offset indent
1.1 tholo 754: BEGIN { FS = ",[ \et]*|[ \et]+" }
755: { print $2, $1 }
1.7 aaron 756: .Ed
1.16 jmc 757: .Pp
758: Add up first column, print sum and average:
1.7 aaron 759: .Bd -literal -offset indent
760: { s += $1 }
761: END { print "sum is", s, " average is", s/NR }
762: .Ed
1.16 jmc 763: .Pp
764: Print all lines between start/stop pairs:
1.7 aaron 765: .Pp
766: .Dl /start/, /stop/
1.16 jmc 767: .Pp
1.45 naddy 768: Simulate
769: .Xr echo 1 :
1.7 aaron 770: .Bd -literal -offset indent
771: BEGIN { # Simulate echo(1)
772: for (i = 1; i < ARGC; i++) printf "%s ", ARGV[i]
773: printf "\en"
774: exit }
1.19 jmc 775: .Ed
776: .Pp
777: Print an error message to standard error:
778: .Bd -literal -offset indent
779: { print "error!" > "/dev/stderr" }
1.7 aaron 780: .Ed
781: .Sh SEE ALSO
1.42 tedu 782: .Xr cut 1 ,
1.47 millert 783: .Xr grep 1 ,
1.7 aaron 784: .Xr lex 1 ,
1.20 jmc 785: .Xr printf 1 ,
1.16 jmc 786: .Xr sed 1 ,
1.23 jmc 787: .Xr re_format 7 ,
788: .Xr script 7
1.7 aaron 789: .Rs
790: .%A A. V. Aho
791: .%A B. W. Kernighan
792: .%A P. J. Weinberger
793: .%T The AWK Programming Language
794: .%I Addison-Wesley
795: .%D 1988
796: .%O ISBN 0-201-07981-X
797: .Re
1.26 jmc 798: .Sh STANDARDS
799: The
800: .Nm
801: utility is compliant with the
1.33 jmc 802: .St -p1003.1-2008
1.50 millert 803: specification except that consecutive backslashes in the replacement
804: string argument for
805: .Fn sub
806: and
807: .Fn gsub
1.51 ! millert 808: are not collapsed and a slash
! 809: .Pq Ql /
! 810: does not need to be escaped in a bracket expression.
1.26 jmc 811: .Pp
812: The flags
813: .Op Fl \&dV
814: and
815: .Op Fl safe ,
1.30 jmc 816: as well as the commands
817: .Cm fflush , compl , and , or ,
818: .Cm xor , lshift , rshift ,
1.26 jmc 819: are extensions to that specification.
1.8 aaron 820: .Sh HISTORY
1.13 millert 821: An
1.8 aaron 822: .Nm
1.13 millert 823: utility appeared in
824: .At v7 .
1.7 aaron 825: .Sh BUGS
1.1 tholo 826: There are no explicit conversions between numbers and strings.
827: To force an expression to be treated as a number add 0 to it;
828: to force it to be treated as a string concatenate
1.7 aaron 829: .Li \&""
830: to it.
831: .Pp
1.1 tholo 832: The scope rules for variables in functions are a botch;
833: the syntax is worse.
1.47 millert 834: .Pp
835: Only eight-bit character sets are handled correctly.