Annotation of src/usr.bin/awk/awk.1, Revision 1.47
1.47 ! millert 1: .\" $OpenBSD: awk.1,v 1.46 2020/01/22 03:47:38 deraadt 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.47 ! millert 25: .Dd $Mdocdate: January 22 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).
422: .It Va RSTART
423: The starting position of the string matched by the
424: .Fn match
425: function.
426: .It Va SUBSEP
427: Separates multiple subscripts (default 034).
428: .El
1.17 jmc 429: .Sh FUNCTIONS
430: The awk language has a variety of built-in functions:
1.30 jmc 431: arithmetic, string, input/output, general, and bit-operation.
432: .Pp
433: Functions may be defined (at the position of a pattern-action statement)
434: thusly:
435: .Pp
436: .Dl function foo(a, b, c) { ...; return x }
437: .Pp
438: Parameters are passed by value if scalar, and by reference if array name;
439: functions may be called recursively.
440: Parameters are local to the function; all other variables are global.
441: Thus local variables may be created by providing excess parameters in
442: the function definition.
1.17 jmc 443: .Ss Arithmetic Functions
444: .Bl -tag -width "atan2(y, x)"
445: .It Fn atan2 y x
446: Return the arctangent of
447: .Fa y Ns / Ns Fa x
448: in radians.
449: .It Fn cos x
450: Return the cosine of
451: .Fa x ,
452: where
453: .Fa x
454: is in radians.
455: .It Fn exp x
456: Return the exponential of
457: .Fa x .
458: .It Fn int x
459: Return
460: .Fa x
461: truncated to an integer value.
462: .It Fn log x
463: Return the natural logarithm of
464: .Fa x .
1.7 aaron 465: .It Fn rand
1.17 jmc 466: Return a random number,
467: .Fa n ,
468: such that
469: .Sm off
470: .Pf 0 \*(Le Fa n No \*(Lt 1 .
471: .Sm on
472: .It Fn sin x
473: Return the sine of
474: .Fa x ,
475: where
476: .Fa x
477: is in radians.
478: .It Fn sqrt x
479: Return the square root of
480: .Fa x .
481: .It Fn srand expr
1.16 jmc 482: Sets seed for
1.7 aaron 483: .Fn rand
1.17 jmc 484: to
485: .Fa expr
1.1 tholo 486: and returns the previous seed.
1.17 jmc 487: If
488: .Fa expr
489: is omitted, the time of day is used instead.
490: .El
491: .Ss String Functions
492: .Bl -tag -width "split(s, a, fs)"
493: .It Fn gsub r t s
494: The same as
495: .Fn sub
496: except that all occurrences of the regular expression are replaced.
497: .Fn gsub
498: returns the number of replacements.
1.7 aaron 499: .It Fn index s t
1.16 jmc 500: The position in
1.7 aaron 501: .Fa s
1.1 tholo 502: where the string
1.7 aaron 503: .Fa t
1.1 tholo 504: occurs, or 0 if it does not.
1.17 jmc 505: .It Fn length s
506: The length of
507: .Fa s
508: taken as a string,
1.47 ! millert 509: number of elements in an array for an array argument,
! 510: or length of
1.17 jmc 511: .Va $0
512: if no argument is given.
1.7 aaron 513: .It Fn match s r
1.16 jmc 514: The position in
1.7 aaron 515: .Fa s
1.1 tholo 516: where the regular expression
1.7 aaron 517: .Fa r
1.1 tholo 518: occurs, or 0 if it does not.
1.17 jmc 519: The variable
1.7 aaron 520: .Va RSTART
1.17 jmc 521: is set to the starting position of the matched string
522: .Pq which is the same as the returned value
523: or zero if no match is found.
524: The variable
1.7 aaron 525: .Va RLENGTH
1.17 jmc 526: is set to the length of the matched string,
527: or \-1 if no match is found.
1.7 aaron 528: .It Fn split s a fs
1.16 jmc 529: Splits the string
1.7 aaron 530: .Fa s
1.1 tholo 531: into array elements
1.7 aaron 532: .Va a[1] , a[2] , ... , a[n]
1.1 tholo 533: and returns
1.7 aaron 534: .Va n .
1.1 tholo 535: The separation is done with the regular expression
1.7 aaron 536: .Ar fs
1.1 tholo 537: or with the field separator
1.7 aaron 538: .Va FS
1.1 tholo 539: if
1.7 aaron 540: .Ar fs
1.1 tholo 541: is not given.
542: An empty string as field separator splits the string
543: into one array element per character.
1.17 jmc 544: .It Fn sprintf fmt expr ...
545: The string resulting from formatting
546: .Fa expr , ...
547: according to the
1.28 jmc 548: .Xr printf 1
1.17 jmc 549: format
550: .Fa fmt .
1.7 aaron 551: .It Fn sub r t s
1.16 jmc 552: Substitutes
1.7 aaron 553: .Fa t
1.1 tholo 554: for the first occurrence of the regular expression
1.7 aaron 555: .Fa r
1.1 tholo 556: in the string
1.7 aaron 557: .Fa s .
1.1 tholo 558: If
1.7 aaron 559: .Fa s
1.1 tholo 560: is not given,
1.7 aaron 561: .Va $0
1.1 tholo 562: is used.
1.17 jmc 563: An ampersand
564: .Pq Sq &
565: in
566: .Fa t
567: is replaced in string
568: .Fa s
569: with regular expression
570: .Fa r .
571: A literal ampersand can be specified by preceding it with two backslashes
572: .Pq Sq \e\e .
573: A literal backslash can be specified by preceding it with another backslash
574: .Pq Sq \e\e .
1.7 aaron 575: .Fn sub
1.17 jmc 576: returns the number of replacements.
577: .It Fn substr s m n
578: Return at most the
579: .Fa n Ns -character
580: substring of
581: .Fa s
582: that begins at position
583: .Fa m
584: counted from 1.
585: If
586: .Fa n
587: is omitted, or if
588: .Fa n
589: specifies more characters than are left in the string,
590: the length of the substring is limited by the length of
591: .Fa s .
1.7 aaron 592: .It Fn tolower str
1.16 jmc 593: Returns a copy of
1.7 aaron 594: .Fa str
1.1 tholo 595: with all upper-case characters translated to their
596: corresponding lower-case equivalents.
1.7 aaron 597: .It Fn toupper str
1.16 jmc 598: Returns a copy of
1.7 aaron 599: .Fa str
1.1 tholo 600: with all lower-case characters translated to their
601: corresponding upper-case equivalents.
1.7 aaron 602: .El
1.17 jmc 603: .Ss Input/Output and General Functions
604: .Bl -tag -width "getline [var] < file"
605: .It Fn close expr
606: Closes the file or pipe
607: .Fa expr .
608: .Fa expr
609: should match the string that was used to open the file or pipe.
610: .It Ar cmd | Ic getline Op Va var
611: Read a record of input from a stream piped from the output of
612: .Ar cmd .
613: If
614: .Va var
615: is omitted, the variables
616: .Va $0
617: and
618: .Va NF
619: are set.
620: Otherwise
621: .Va var
622: is set.
623: If the stream is not open, it is opened.
624: As long as the stream remains open, subsequent calls
625: will read subsequent records from the stream.
626: The stream remains open until explicitly closed with a call to
627: .Fn close .
1.24 jmc 628: .Ic getline
629: returns 1 for a successful input, 0 for end of file, and \-1 for an error.
630: .It Fn fflush [expr]
1.39 jmc 631: Flushes any buffered output for the file or pipe
1.24 jmc 632: .Fa expr ,
633: or all open files or pipes if
634: .Fa expr
635: is omitted.
1.17 jmc 636: .Fa expr
637: should match the string that was used to open the file or pipe.
638: .It Ic getline
639: Sets
640: .Va $0
641: to the next input record from the current input file.
642: This form of
643: .Ic getline
644: sets the variables
645: .Va NF ,
646: .Va NR ,
647: and
648: .Va FNR .
1.7 aaron 649: .Ic getline
1.17 jmc 650: returns 1 for a successful input, 0 for end of file, and \-1 for an error.
651: .It Ic getline Va var
652: Sets
1.7 aaron 653: .Va $0
1.17 jmc 654: to variable
655: .Va var .
656: This form of
657: .Ic getline
658: sets the variables
659: .Va NR
660: and
661: .Va FNR .
662: .Ic getline
663: returns 1 for a successful input, 0 for end of file, and \-1 for an error.
664: .It Xo
665: .Ic getline Op Va var
1.47 ! millert 666: .Pf <\ \& Ar file
1.17 jmc 667: .Xc
668: Sets
1.7 aaron 669: .Va $0
1.1 tholo 670: to the next record from
1.7 aaron 671: .Ar file .
1.17 jmc 672: If
673: .Va var
674: is omitted, the variables
675: .Va $0
676: and
677: .Va NF
678: are set.
679: Otherwise
680: .Va var
681: is set.
682: If
683: .Ar file
684: is not open, it is opened.
685: As long as the stream remains open, subsequent calls will read subsequent
686: records from
687: .Ar file .
688: .Ar file
689: remains open until explicitly closed with a call to
690: .Fn close .
691: .It Fn system cmd
692: Executes
693: .Fa cmd
694: and returns its exit status.
1.47 ! millert 695: This will be \-1 upon error,
! 696: .Ar cmd Ns 's
! 697: exit status upon a normal exit,
! 698: 256 +
! 699: .Em sig
! 700: if
! 701: .Fa cmd
! 702: was terminated by a signal, where
! 703: .Em sig
! 704: is the number of the signal,
! 705: or 512 +
! 706: .Em sig
! 707: if there was a core dump.
1.17 jmc 708: .El
1.30 jmc 709: .Ss Bit-Operation Functions
1.29 pyr 710: .Bl -tag -width "lshift(a, b)"
711: .It Fn compl x
712: Returns the bitwise complement of integer argument x.
713: .It Fn and x y
1.30 jmc 714: Performs a bitwise AND on integer arguments x and y.
1.29 pyr 715: .It Fn or x y
1.30 jmc 716: Performs a bitwise OR on integer arguments x and y.
1.29 pyr 717: .It Fn xor x y
1.30 jmc 718: Performs a bitwise Exclusive-OR on integer arguments x and y.
1.29 pyr 719: .It Fn lshift x n
1.39 jmc 720: Returns integer argument x shifted by n bits to the left.
1.29 pyr 721: .It Fn rshift x n
1.39 jmc 722: Returns integer argument x shifted by n bits to the right.
1.29 pyr 723: .El
1.37 jmc 724: .Sh EXIT STATUS
725: .Ex -std awk
726: .Pp
727: But note that the
728: .Ic exit
729: expression can modify the exit status.
1.7 aaron 730: .Sh EXAMPLES
1.16 jmc 731: Print lines longer than 72 characters:
732: .Pp
1.7 aaron 733: .Dl length($0) > 72
1.16 jmc 734: .Pp
735: Print first two fields in opposite order:
1.7 aaron 736: .Pp
737: .Dl { print $2, $1 }
1.16 jmc 738: .Pp
1.47 ! millert 739: Same, with input fields separated by comma and/or spaces and tabs:
1.7 aaron 740: .Bd -literal -offset indent
1.1 tholo 741: BEGIN { FS = ",[ \et]*|[ \et]+" }
742: { print $2, $1 }
1.7 aaron 743: .Ed
1.16 jmc 744: .Pp
745: Add up first column, print sum and average:
1.7 aaron 746: .Bd -literal -offset indent
747: { s += $1 }
748: END { print "sum is", s, " average is", s/NR }
749: .Ed
1.16 jmc 750: .Pp
751: Print all lines between start/stop pairs:
1.7 aaron 752: .Pp
753: .Dl /start/, /stop/
1.16 jmc 754: .Pp
1.45 naddy 755: Simulate
756: .Xr echo 1 :
1.7 aaron 757: .Bd -literal -offset indent
758: BEGIN { # Simulate echo(1)
759: for (i = 1; i < ARGC; i++) printf "%s ", ARGV[i]
760: printf "\en"
761: exit }
1.19 jmc 762: .Ed
763: .Pp
764: Print an error message to standard error:
765: .Bd -literal -offset indent
766: { print "error!" > "/dev/stderr" }
1.7 aaron 767: .Ed
768: .Sh SEE ALSO
1.42 tedu 769: .Xr cut 1 ,
1.47 ! millert 770: .Xr grep 1 ,
1.7 aaron 771: .Xr lex 1 ,
1.20 jmc 772: .Xr printf 1 ,
1.16 jmc 773: .Xr sed 1 ,
1.23 jmc 774: .Xr re_format 7 ,
775: .Xr script 7
1.7 aaron 776: .Rs
777: .%A A. V. Aho
778: .%A B. W. Kernighan
779: .%A P. J. Weinberger
780: .%T The AWK Programming Language
781: .%I Addison-Wesley
782: .%D 1988
783: .%O ISBN 0-201-07981-X
784: .Re
1.26 jmc 785: .Sh STANDARDS
786: The
787: .Nm
788: utility is compliant with the
1.33 jmc 789: .St -p1003.1-2008
1.41 jmc 790: specification,
791: except
792: .Nm
793: does not support {n,m} pattern matching.
1.26 jmc 794: .Pp
795: The flags
796: .Op Fl \&dV
797: and
798: .Op Fl safe ,
1.30 jmc 799: as well as the commands
800: .Cm fflush , compl , and , or ,
801: .Cm xor , lshift , rshift ,
1.26 jmc 802: are extensions to that specification.
1.8 aaron 803: .Sh HISTORY
1.13 millert 804: An
1.8 aaron 805: .Nm
1.13 millert 806: utility appeared in
807: .At v7 .
1.7 aaron 808: .Sh BUGS
1.1 tholo 809: There are no explicit conversions between numbers and strings.
810: To force an expression to be treated as a number add 0 to it;
811: to force it to be treated as a string concatenate
1.7 aaron 812: .Li \&""
813: to it.
814: .Pp
1.1 tholo 815: The scope rules for variables in functions are a botch;
816: the syntax is worse.
1.47 ! millert 817: .Pp
! 818: POSIX-standard interval expressions in regular expressions are not supported.
! 819: .Pp
! 820: Only eight-bit character sets are handled correctly.