Annotation of src/usr.bin/awk/awk.1, Revision 1.52
1.52 ! millert 1: .\" $OpenBSD: awk.1,v 1.51 2020/06/13 01:19:55 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.52 ! millert 25: .Dd $Mdocdate: June 13 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)"
1.52 ! millert 498: .It Fn gensub r s h [t]
! 499: Search the target string
! 500: .Ar t
! 501: for matches of the regular expression
! 502: .Ar r .
! 503: If
! 504: .Ar h
! 505: is a string beginning with
! 506: .Ic g
! 507: or
! 508: .Ic G ,
! 509: then replace all matches of
! 510: .Ar r
! 511: with
! 512: .Ar s .
! 513: Otherwise,
! 514: .Ar h
! 515: is a number indicating which match of
! 516: .Ar r
! 517: to replace.
! 518: If no
! 519: .Ar t
! 520: is supplied,
! 521: .Va $0
! 522: is used instead.
! 523: .\"Within the replacement text
! 524: .\".Ar s ,
! 525: .\"the sequence
! 526: .\".Ar \en ,
! 527: .\"where
! 528: .\".Ar n
! 529: .\"is a digit from 1 to 9, may be used to indicate just the text that
! 530: .\"matched the
! 531: .\".Ar n Ap th
! 532: .\"parenthesized subexpression.
! 533: .\"The sequence
! 534: .\".Ic \e0
! 535: .\"represents the entire text, as does the character
! 536: .\".Ic & .
! 537: Unlike
! 538: .Fn sub
! 539: and
! 540: .Fn gsub ,
! 541: the modified string is returned as the result of the function,
! 542: and the original target is
! 543: .Em not
! 544: changed.
! 545: Note that
! 546: .Ar \en
! 547: sequences within the replacement string
! 548: .Ar s ,
! 549: as supported by GNU
! 550: .Nm ,
! 551: are
! 552: .Em not
! 553: supported at this time.
1.17 jmc 554: .It Fn gsub r t s
555: The same as
556: .Fn sub
557: except that all occurrences of the regular expression are replaced.
558: .Fn gsub
559: returns the number of replacements.
1.7 aaron 560: .It Fn index s t
1.16 jmc 561: The position in
1.7 aaron 562: .Fa s
1.1 tholo 563: where the string
1.7 aaron 564: .Fa t
1.1 tholo 565: occurs, or 0 if it does not.
1.17 jmc 566: .It Fn length s
567: The length of
568: .Fa s
569: taken as a string,
1.47 millert 570: number of elements in an array for an array argument,
571: or length of
1.17 jmc 572: .Va $0
573: if no argument is given.
1.7 aaron 574: .It Fn match s r
1.16 jmc 575: The position in
1.7 aaron 576: .Fa s
1.1 tholo 577: where the regular expression
1.7 aaron 578: .Fa r
1.1 tholo 579: occurs, or 0 if it does not.
1.17 jmc 580: The variable
1.7 aaron 581: .Va RSTART
1.17 jmc 582: is set to the starting position of the matched string
583: .Pq which is the same as the returned value
584: or zero if no match is found.
585: The variable
1.7 aaron 586: .Va RLENGTH
1.17 jmc 587: is set to the length of the matched string,
588: or \-1 if no match is found.
1.7 aaron 589: .It Fn split s a fs
1.16 jmc 590: Splits the string
1.7 aaron 591: .Fa s
1.1 tholo 592: into array elements
1.7 aaron 593: .Va a[1] , a[2] , ... , a[n]
1.1 tholo 594: and returns
1.7 aaron 595: .Va n .
1.1 tholo 596: The separation is done with the regular expression
1.7 aaron 597: .Ar fs
1.1 tholo 598: or with the field separator
1.7 aaron 599: .Va FS
1.1 tholo 600: if
1.7 aaron 601: .Ar fs
1.1 tholo 602: is not given.
603: An empty string as field separator splits the string
604: into one array element per character.
1.17 jmc 605: .It Fn sprintf fmt expr ...
606: The string resulting from formatting
607: .Fa expr , ...
608: according to the
1.28 jmc 609: .Xr printf 1
1.17 jmc 610: format
611: .Fa fmt .
1.7 aaron 612: .It Fn sub r t s
1.16 jmc 613: Substitutes
1.7 aaron 614: .Fa t
1.1 tholo 615: for the first occurrence of the regular expression
1.7 aaron 616: .Fa r
1.1 tholo 617: in the string
1.7 aaron 618: .Fa s .
1.1 tholo 619: If
1.7 aaron 620: .Fa s
1.1 tholo 621: is not given,
1.7 aaron 622: .Va $0
1.1 tholo 623: is used.
1.17 jmc 624: An ampersand
625: .Pq Sq &
626: in
627: .Fa t
628: is replaced in string
629: .Fa s
630: with regular expression
631: .Fa r .
632: A literal ampersand can be specified by preceding it with two backslashes
633: .Pq Sq \e\e .
634: A literal backslash can be specified by preceding it with another backslash
635: .Pq Sq \e\e .
1.7 aaron 636: .Fn sub
1.17 jmc 637: returns the number of replacements.
638: .It Fn substr s m n
639: Return at most the
640: .Fa n Ns -character
641: substring of
642: .Fa s
643: that begins at position
644: .Fa m
645: counted from 1.
646: If
647: .Fa n
648: is omitted, or if
649: .Fa n
650: specifies more characters than are left in the string,
651: the length of the substring is limited by the length of
652: .Fa s .
1.7 aaron 653: .It Fn tolower str
1.16 jmc 654: Returns a copy of
1.7 aaron 655: .Fa str
1.1 tholo 656: with all upper-case characters translated to their
657: corresponding lower-case equivalents.
1.7 aaron 658: .It Fn toupper str
1.16 jmc 659: Returns a copy of
1.7 aaron 660: .Fa str
1.1 tholo 661: with all lower-case characters translated to their
662: corresponding upper-case equivalents.
1.7 aaron 663: .El
1.52 ! millert 664: .Ss Time Functions
! 665: This version of
! 666: .Nm
! 667: provides the following functions for obtaining and formatting time
! 668: stamps.
! 669: .Bl -tag -width indent
! 670: .It Fn strftime "[format [, timestamp]]"
! 671: Formats
! 672: .Ar timestamp
! 673: according to the string
! 674: .Ar format .
! 675: The format string may contain any of the conversion specifications described
! 676: in the
! 677: .Xr strftime 3
! 678: manual page, as well as any arbitrary text.
! 679: The
! 680: .Ar timestamp
! 681: must be in the same form as a value returned by
! 682: .Fn systime .
! 683: If
! 684: .Ar timestamp
! 685: is not specified, the current time is used.
! 686: If
! 687: .Ar format
! 688: is not specified, a default format equivalent to the output of
! 689: .Xr date 1
! 690: is used.
! 691: .It Fn systime
! 692: Returns the value of time in seconds since 0 hours, 0 minutes,
! 693: 0 seconds, January 1, 1970, Coordinated Universal Time (UTC).
! 694: .El
1.17 jmc 695: .Ss Input/Output and General Functions
696: .Bl -tag -width "getline [var] < file"
697: .It Fn close expr
698: Closes the file or pipe
699: .Fa expr .
700: .Fa expr
701: should match the string that was used to open the file or pipe.
702: .It Ar cmd | Ic getline Op Va var
703: Read a record of input from a stream piped from the output of
704: .Ar cmd .
705: If
706: .Va var
707: is omitted, the variables
708: .Va $0
709: and
710: .Va NF
711: are set.
712: Otherwise
713: .Va var
714: is set.
715: If the stream is not open, it is opened.
716: As long as the stream remains open, subsequent calls
717: will read subsequent records from the stream.
718: The stream remains open until explicitly closed with a call to
719: .Fn close .
1.24 jmc 720: .Ic getline
721: returns 1 for a successful input, 0 for end of file, and \-1 for an error.
722: .It Fn fflush [expr]
1.39 jmc 723: Flushes any buffered output for the file or pipe
1.24 jmc 724: .Fa expr ,
725: or all open files or pipes if
726: .Fa expr
727: is omitted.
1.17 jmc 728: .Fa expr
729: should match the string that was used to open the file or pipe.
730: .It Ic getline
731: Sets
732: .Va $0
733: to the next input record from the current input file.
734: This form of
735: .Ic getline
736: sets the variables
737: .Va NF ,
738: .Va NR ,
739: and
740: .Va FNR .
1.7 aaron 741: .Ic getline
1.17 jmc 742: returns 1 for a successful input, 0 for end of file, and \-1 for an error.
743: .It Ic getline Va var
744: Sets
1.7 aaron 745: .Va $0
1.17 jmc 746: to variable
747: .Va var .
748: This form of
749: .Ic getline
750: sets the variables
751: .Va NR
752: and
753: .Va FNR .
754: .Ic getline
755: returns 1 for a successful input, 0 for end of file, and \-1 for an error.
756: .It Xo
757: .Ic getline Op Va var
1.47 millert 758: .Pf <\ \& Ar file
1.17 jmc 759: .Xc
760: Sets
1.7 aaron 761: .Va $0
1.1 tholo 762: to the next record from
1.7 aaron 763: .Ar file .
1.17 jmc 764: If
765: .Va var
766: is omitted, the variables
767: .Va $0
768: and
769: .Va NF
770: are set.
771: Otherwise
772: .Va var
773: is set.
774: If
775: .Ar file
776: is not open, it is opened.
777: As long as the stream remains open, subsequent calls will read subsequent
778: records from
779: .Ar file .
780: .Ar file
781: remains open until explicitly closed with a call to
782: .Fn close .
783: .It Fn system cmd
784: Executes
785: .Fa cmd
786: and returns its exit status.
1.47 millert 787: This will be \-1 upon error,
788: .Ar cmd Ns 's
789: exit status upon a normal exit,
790: 256 +
791: .Em sig
792: if
793: .Fa cmd
794: was terminated by a signal, where
795: .Em sig
796: is the number of the signal,
797: or 512 +
798: .Em sig
799: if there was a core dump.
1.17 jmc 800: .El
1.30 jmc 801: .Ss Bit-Operation Functions
1.29 pyr 802: .Bl -tag -width "lshift(a, b)"
803: .It Fn compl x
804: Returns the bitwise complement of integer argument x.
805: .It Fn and x y
1.30 jmc 806: Performs a bitwise AND on integer arguments x and y.
1.29 pyr 807: .It Fn or x y
1.30 jmc 808: Performs a bitwise OR on integer arguments x and y.
1.29 pyr 809: .It Fn xor x y
1.30 jmc 810: Performs a bitwise Exclusive-OR on integer arguments x and y.
1.29 pyr 811: .It Fn lshift x n
1.39 jmc 812: Returns integer argument x shifted by n bits to the left.
1.29 pyr 813: .It Fn rshift x n
1.39 jmc 814: Returns integer argument x shifted by n bits to the right.
1.29 pyr 815: .El
1.50 millert 816: .Sh ENVIRONMENT
817: The following environment variables affect the execution of
818: .Nm :
819: .Bl -tag -width POSIXLY_CORRECT
820: .It Ev POSIXLY_CORRECT
821: When set, behave in accordance with the standard, even when it conflicts
822: with historical behavior.
823: .El
1.37 jmc 824: .Sh EXIT STATUS
825: .Ex -std awk
826: .Pp
827: But note that the
828: .Ic exit
829: expression can modify the exit status.
1.7 aaron 830: .Sh EXAMPLES
1.16 jmc 831: Print lines longer than 72 characters:
832: .Pp
1.7 aaron 833: .Dl length($0) > 72
1.16 jmc 834: .Pp
835: Print first two fields in opposite order:
1.7 aaron 836: .Pp
837: .Dl { print $2, $1 }
1.16 jmc 838: .Pp
1.47 millert 839: Same, with input fields separated by comma and/or spaces and tabs:
1.7 aaron 840: .Bd -literal -offset indent
1.1 tholo 841: BEGIN { FS = ",[ \et]*|[ \et]+" }
842: { print $2, $1 }
1.7 aaron 843: .Ed
1.16 jmc 844: .Pp
845: Add up first column, print sum and average:
1.7 aaron 846: .Bd -literal -offset indent
847: { s += $1 }
848: END { print "sum is", s, " average is", s/NR }
849: .Ed
1.16 jmc 850: .Pp
851: Print all lines between start/stop pairs:
1.7 aaron 852: .Pp
853: .Dl /start/, /stop/
1.16 jmc 854: .Pp
1.45 naddy 855: Simulate
856: .Xr echo 1 :
1.7 aaron 857: .Bd -literal -offset indent
858: BEGIN { # Simulate echo(1)
859: for (i = 1; i < ARGC; i++) printf "%s ", ARGV[i]
860: printf "\en"
861: exit }
1.19 jmc 862: .Ed
863: .Pp
864: Print an error message to standard error:
865: .Bd -literal -offset indent
866: { print "error!" > "/dev/stderr" }
1.7 aaron 867: .Ed
868: .Sh SEE ALSO
1.42 tedu 869: .Xr cut 1 ,
1.52 ! millert 870: .Xr date 1 ,
1.47 millert 871: .Xr grep 1 ,
1.7 aaron 872: .Xr lex 1 ,
1.20 jmc 873: .Xr printf 1 ,
1.16 jmc 874: .Xr sed 1 ,
1.52 ! millert 875: .Xr strftime 3 ,
1.23 jmc 876: .Xr re_format 7 ,
877: .Xr script 7
1.7 aaron 878: .Rs
879: .%A A. V. Aho
880: .%A B. W. Kernighan
881: .%A P. J. Weinberger
882: .%T The AWK Programming Language
883: .%I Addison-Wesley
884: .%D 1988
885: .%O ISBN 0-201-07981-X
886: .Re
1.26 jmc 887: .Sh STANDARDS
888: The
889: .Nm
890: utility is compliant with the
1.33 jmc 891: .St -p1003.1-2008
1.50 millert 892: specification except that consecutive backslashes in the replacement
893: string argument for
894: .Fn sub
895: and
896: .Fn gsub
1.51 millert 897: are not collapsed and a slash
898: .Pq Ql /
899: does not need to be escaped in a bracket expression.
1.26 jmc 900: .Pp
901: The flags
902: .Op Fl \&dV
903: and
904: .Op Fl safe ,
1.52 ! millert 905: as well as the functions
! 906: .Fn fflush ,
! 907: .Fn gensub ,
! 908: .Fn compl ,
! 909: .Fn and ,
! 910: .Fn or ,
! 911: .Fn xor ,
! 912: .Fn lshift ,
! 913: .Fn rshift ,
! 914: .Fn strftime
! 915: and
! 916: .Fn systime
1.26 jmc 917: are extensions to that specification.
1.8 aaron 918: .Sh HISTORY
1.13 millert 919: An
1.8 aaron 920: .Nm
1.13 millert 921: utility appeared in
922: .At v7 .
1.7 aaron 923: .Sh BUGS
1.1 tholo 924: There are no explicit conversions between numbers and strings.
925: To force an expression to be treated as a number add 0 to it;
926: to force it to be treated as a string concatenate
1.7 aaron 927: .Li \&""
928: to it.
929: .Pp
1.1 tholo 930: The scope rules for variables in functions are a botch;
931: the syntax is worse.
1.47 millert 932: .Pp
933: Only eight-bit character sets are handled correctly.
![[BACK]](/icons/back.gif){kind=icon}
Return to awk.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / awk