← Back to branch summary

~vcs-imports/gawk/master

« back to all changes in this revision

Viewing changes to gawk.1

  • Committer: Arnold D. Robbins
  • Date: 2010-07-16 09:41:09 UTC
  • Revision ID: git-v1:8c042f99cc7465c86351d21331a129111b75345d
Tags: gawk-3.0.0
Move to gawk-3.0.0.

Show diffs side-by-side

added added

removed removed

Lines of Context:
gawk.1
1
 
.ds PX \s-1POSIX\s+1
2
 
.ds UX \s-1UNIX\s+1
3
 
.ds AN \s-1ANSI\s+1
4
 
.TH GAWK 1 "Nov 24 1994" "Free Software Foundation" "Utility Commands"
5
 
.SH NAME
6
 
gawk \- pattern scanning and processing language
7
 
.SH SYNOPSIS
8
 
.B gawk
9
 
[ POSIX or GNU style options ]
10
 
.B \-f
11
 
.I program-file
12
 
[
13
 
.B \-\^\-
14
 
] file .\^.\^.
15
 
.br
16
 
.B gawk
17
 
[ POSIX or GNU style options ]
18
 
[
19
 
.B \-\^\-
20
 
]
21
 
.I program-text
22
 
file .\^.\^.
23
 
.SH DESCRIPTION
24
 
.I Gawk
25
 
is the GNU Project's implementation of the AWK programming language.
26
 
It conforms to the definition of the language in
27
 
the \*(PX 1003.2 Command Language And Utilities Standard.
28
 
This version in turn is based on the description in
29
 
.IR "The AWK Programming Language" ,
30
 
by Aho, Kernighan, and Weinberger,
31
 
with the additional features defined in the System V Release 4 version
32
 
of \*(UX
33
 
.IR awk .
34
 
.I Gawk
35
 
also provides some GNU-specific extensions.
36
 
.PP
37
 
The command line consists of options to
38
 
.I gawk
39
 
itself, the AWK program text (if not supplied via the
40
 
.B \-f
41
 
or
42
 
.B \-\^\-file
43
 
options), and values to be made
44
 
available in the
45
 
.B ARGC
46
 
and
47
 
.B ARGV
48
 
pre-defined AWK variables.
49
 
.SH OPTIONS
50
 
.PP
51
 
.I Gawk
52
 
options may be either the traditional \*(PX one letter options,
53
 
or the GNU style long options.  \*(PX style options start with a single ``\-'',
54
 
while GNU long options start with ``\-\^\-''.
55
 
GNU style long options are provided for both GNU-specific features and
56
 
for \*(PX mandated features.  Other implementations of the AWK language
57
 
are likely to only accept the traditional one letter options.
58
 
.PP
59
 
Following the \*(PX standard,
60
 
.IR gawk -specific
61
 
options are supplied via arguments to the
62
 
.B \-W
63
 
option.  Multiple
64
 
.B \-W
65
 
options may be supplied, or multiple arguments may be supplied together
66
 
if they are separated by commas, or enclosed in quotes and separated
67
 
by white space.
68
 
Case is ignored in arguments to the
69
 
.B \-W
70
 
option.
71
 
Each
72
 
.B \-W
73
 
option has a corresponding GNU style long option, as detailed below.
74
 
Arguments to GNU style long options are either joined with the option
75
 
by an
76
 
.B =
77
 
sign, with no intervening spaces, or they may be provided in the
78
 
next command line argument.
79
 
.PP
80
 
.I Gawk
81
 
accepts the following options.
82
 
.TP
83
 
.PD 0
84
 
.BI \-F " fs"
85
 
.TP
86
 
.PD
87
 
.BI \-\^\-field-separator= fs
88
 
Use
89
 
.I fs
90
 
for the input field separator (the value of the
91
 
.B FS
92
 
predefined
93
 
variable).
94
 
.TP
95
 
.PD 0
96
 
\fB\-v\fI var\fB\^=\^\fIval\fR
97
 
.TP
98
 
.PD
99
 
\fB\-\^\-assign=\fIvar\fB\^=\^\fIval\fR
100
 
Assign the value
101
 
.IR val ,
102
 
to the variable
103
 
.IR var ,
104
 
before execution of the program begins.
105
 
Such variable values are available to the
106
 
.B BEGIN
107
 
block of an AWK program.
108
 
.TP
109
 
.PD 0
110
 
.BI \-f " program-file"
111
 
.TP
112
 
.PD
113
 
.BI \-\^\-file= program-file
114
 
Read the AWK program source from the file
115
 
.IR program-file ,
116
 
instead of from the first command line argument.
117
 
Multiple
118
 
.B \-f
119
 
(or
120
 
.BR \-\^\-file )
121
 
options may be used.
122
 
.TP
123
 
.PD 0
124
 
.BI \-mf= NNN
125
 
.TP
126
 
.BI \-mr= NNN
127
 
Set various memory limits to the value
128
 
.IR NNN .
129
 
The
130
 
.B f
131
 
flag sets the maximum number of fields, and the
132
 
.B r
133
 
flag sets the maximum record size.  These two flags and the
134
 
.B \-m
135
 
option are from the AT&T Bell Labs research version of \*(UX
136
 
.IR awk .
137
 
They are ignored by
138
 
.IR gawk ,
139
 
since
140
 
.I gawk
141
 
has no pre-defined limits.
142
 
.TP \w'\fB\-\^\-copyright\fR'u+1n
143
 
.PD 0
144
 
.B "\-W compat"
145
 
.TP
146
 
.PD
147
 
.B \-\^\-compat
148
 
Run in
149
 
.I compatibility
150
 
mode.  In compatibility mode,
151
 
.I gawk
152
 
behaves identically to \*(UX
153
 
.IR awk ;
154
 
none of the GNU-specific extensions are recognized.
155
 
See
156
 
.BR "GNU EXTENSIONS" ,
157
 
below, for more information.
158
 
.TP
159
 
.PD 0
160
 
.B "\-W copyleft"
161
 
.TP
162
 
.PD 0
163
 
.B "\-W copyright"
164
 
.TP
165
 
.PD 0
166
 
.B \-\^\-copyleft
167
 
.TP
168
 
.PD
169
 
.B \-\^\-copyright
170
 
Print the short version of the GNU copyright information message on
171
 
the error output.
172
 
.TP
173
 
.PD 0
174
 
.B "\-W help"
175
 
.TP
176
 
.PD 0
177
 
.B "\-W usage"
178
 
.TP
179
 
.PD 0
180
 
.B \-\^\-help
181
 
.TP
182
 
.PD
183
 
.B \-\^\-usage
184
 
Print a relatively short summary of the available options on
185
 
the error output.
186
 
Per the GNU Coding Standards, these options cause an immediate,
187
 
successful exit.
188
 
.TP
189
 
.PD 0
190
 
.B "\-W lint"
191
 
.TP
192
 
.PD 0
193
 
.B \-\^\-lint
194
 
Provide warnings about constructs that are
195
 
dubious or non-portable to other AWK implementations.
196
 
.ig
197
 
.\" This option is left undocumented, on purpose.
198
 
.TP
199
 
.PD 0
200
 
.B "\-W nostalgia"
201
 
.TP
202
 
.PD
203
 
.B \-\^\-nostalgia
204
 
Provide a moment of nostalgia for long time
205
 
.I awk
206
 
users.
207
 
..
208
 
.TP
209
 
.PD 0
210
 
.B "\-W posix"
211
 
.TP
212
 
.PD
213
 
.B \-\^\-posix
214
 
This turns on
215
 
.I compatibility 
216
 
mode, with the following additional restrictions:
217
 
.RS
218
 
.TP \w'\(bu'u+1n
219
 
\(bu
220
 
.B \ex
221
 
escape sequences are not recognized.
222
 
.TP
223
 
\(bu
224
 
The synonym
225
 
.B func
226
 
for the keyword
227
 
.B function
228
 
is not recognized.
229
 
.TP
230
 
\(bu
231
 
The operators
232
 
.B **
233
 
and
234
 
.B **=
235
 
cannot be used in place of
236
 
.B ^
237
 
and
238
 
.BR ^= .
239
 
.RE
240
 
.TP
241
 
.PD 0
242
 
.BI "\-W source=" program-text
243
 
.TP
244
 
.PD
245
 
.BI \-\^\-source= program-text
246
 
Use
247
 
.I program-text
248
 
as AWK program source code.
249
 
This option allows the easy intermixing of library functions (used via the 
250
 
.B \-f
251
 
and
252
 
.B \-\^\-file
253
 
options) with source code entered on the command line.
254
 
It is intended primarily for medium to large size AWK programs used
255
 
in shell scripts.
256
 
.sp .5
257
 
The
258
 
.B "\-W source="
259
 
form of this option uses the rest of the command line argument for
260
 
.IR program-text ;
261
 
no other options to
262
 
.B \-W
263
 
will be recognized in the same argument.
264
 
.TP
265
 
.PD 0
266
 
.B "\-W version"
267
 
.TP
268
 
.PD
269
 
.B \-\^\-version
270
 
Print version information for this particular copy of
271
 
.I gawk
272
 
on the error output.
273
 
This is useful mainly for knowing if the current copy of
274
 
.I gawk
275
 
on your system
276
 
is up to date with respect to whatever the Free Software Foundation
277
 
is distributing.
278
 
Per the GNU Coding Standards, these options cause an immediate,
279
 
successful exit.
280
 
.TP
281
 
.B \-\^\-
282
 
Signal the end of options. This is useful to allow further arguments to the
283
 
AWK program itself to start with a ``\-''.
284
 
This is mainly for consistency with the argument parsing convention used
285
 
by most other \*(PX programs.
286
 
.PP
287
 
In compatibility mode,
288
 
any other options are flagged as illegal, but are otherwise ignored.
289
 
In normal operation, as long as program text has been supplied, unknown
290
 
options are passed on to the AWK program in the
291
 
.B ARGV
292
 
array for processing.  This is particularly useful for running AWK
293
 
programs via the ``#!'' executable interpreter mechanism.
294
 
.SH AWK PROGRAM EXECUTION
295
 
.PP
296
 
An AWK program consists of a sequence of pattern-action statements
297
 
and optional function definitions.
298
 
.RS
299
 
.PP
300
 
\fIpattern\fB   { \fIaction statements\fB }\fR
301
 
.br
302
 
\fBfunction \fIname\fB(\fIparameter list\fB) { \fIstatements\fB }\fR
303
 
.RE
304
 
.PP
305
 
.I Gawk
306
 
first reads the program source from the
307
 
.IR program-file (s)
308
 
if specified,
309
 
from arguments to
310
 
.BR "\-W source=" ,
311
 
or from the first non-option argument on the command line.
312
 
The
313
 
.B \-f
314
 
and
315
 
.B "\-W source="
316
 
options may be used multiple times on the command line.
317
 
.I Gawk
318
 
will read the program text as if all the
319
 
.IR program-file s
320
 
and command line source texts
321
 
had been concatenated together.  This is useful for building libraries
322
 
of AWK functions, without having to include them in each new AWK
323
 
program that uses them.  It also provides the ability to mix library
324
 
functions with command line programs.
325
 
.PP
326
 
The environment variable
327
 
.B AWKPATH
328
 
specifies a search path to use when finding source files named with
329
 
the 
330
 
.B \-f
331
 
option.  If this variable does not exist, the default path is
332
 
\fB".:/usr/lib/awk:/usr/local/lib/awk"\fR.
333
 
If a file name given to the
334
 
.B \-f
335
 
option contains a ``/'' character, no path search is performed.
336
 
.PP
337
 
.I Gawk
338
 
executes AWK programs in the following order.
339
 
First,
340
 
all variable assignments specified via the
341
 
.B \-v
342
 
option are performed.
343
 
Next,
344
 
.I gawk
345
 
compiles the program into an internal form.
346
 
Then,
347
 
.I gawk
348
 
executes the code in the
349
 
.B BEGIN
350
 
block(s) (if any),
351
 
and then proceeds to read
352
 
each file named in the
353
 
.B ARGV
354
 
array.
355
 
If there are no files named on the command line,
356
 
.I gawk
357
 
reads the standard input.
358
 
.PP
359
 
If a filename on the command line has the form
360
 
.IB var = val
361
 
it is treated as a variable assignment. The variable
362
 
.I var
363
 
will be assigned the value
364
 
.IR val .
365
 
(This happens after any
366
 
.B BEGIN
367
 
block(s) have been run.)
368
 
Command line variable assignment
369
 
is most useful for dynamically assigning values to the variables
370
 
AWK uses to control how input is broken into fields and records. It
371
 
is also useful for controlling state if multiple passes are needed over
372
 
a single data file.
373
 
.PP
374
 
If the value of a particular element of
375
 
.B ARGV
376
 
is empty (\fB""\fR),
377
 
.I gawk
378
 
skips over it.
379
 
.PP
380
 
For each line in the input,
381
 
.I gawk
382
 
tests to see if it matches any
383
 
.I pattern
384
 
in the AWK program.
385
 
For each pattern that the line matches, the associated
386
 
.I action
387
 
is executed.
388
 
The patterns are tested in the order they occur in the program.
389
 
.PP
390
 
Finally, after all the input is exhausted,
391
 
.I gawk
392
 
executes the code in the
393
 
.B END
394
 
block(s) (if any).
395
 
.SH VARIABLES AND FIELDS
396
 
AWK variables are dynamic; they come into existence when they are
397
 
first used. Their values are either floating-point numbers or strings,
398
 
or both,
399
 
depending upon how they are used. AWK also has one dimensional
400
 
arrays; arrays with multiple dimensions may be simulated.
401
 
Several pre-defined variables are set as a program
402
 
runs; these will be described as needed and summarized below.
403
 
.SS Fields
404
 
.PP
405
 
As each input line is read,
406
 
.I gawk
407
 
splits the line into
408
 
.IR fields ,
409
 
using the value of the
410
 
.B FS
411
 
variable as the field separator.
412
 
If
413
 
.B FS
414
 
is a single character, fields are separated by that character.
415
 
Otherwise,
416
 
.B FS
417
 
is expected to be a full regular expression.
418
 
In the special case that
419
 
.B FS
420
 
is a single blank, fields are separated
421
 
by runs of blanks and/or tabs.
422
 
Note that the value of
423
 
.B IGNORECASE
424
 
(see below) will also affect how fields are split when
425
 
.B FS
426
 
is a regular expression.
427
 
.PP
428
 
If the
429
 
.B FIELDWIDTHS
430
 
variable is set to a space separated list of numbers, each field is
431
 
expected to have fixed width, and
432
 
.I gawk
433
 
will split up the record using the specified widths.  The value of
434
 
.B FS
435
 
is ignored.
436
 
Assigning a new value to
437
 
.B FS
438
 
overrides the use of
439
 
.BR FIELDWIDTHS ,
440
 
and restores the default behavior.
441
 
.PP
442
 
Each field in the input line may be referenced by its position,
443
 
.BR $1 ,
444
 
.BR $2 ,
445
 
and so on.
446
 
.B $0
447
 
is the whole line. The value of a field may be assigned to as well.
448
 
Fields need not be referenced by constants:
449
 
.RS
450
 
.PP
451
 
.ft B
452
 
n = 5
453
 
.br
454
 
print $n
455
 
.ft R
456
 
.RE
457
 
.PP
458
 
prints the fifth field in the input line.
459
 
The variable
460
 
.B NF
461
 
is set to the total number of fields in the input line.
462
 
.PP
463
 
References to non-existent fields (i.e. fields after
464
 
.BR $NF )
465
 
produce the null-string. However, assigning to a non-existent field
466
 
(e.g., 
467
 
.BR "$(NF+2) = 5" )
468
 
will increase the value of
469
 
.BR NF ,
470
 
create any intervening fields with the null string as their value, and
471
 
cause the value of
472
 
.B $0
473
 
to be recomputed, with the fields being separated by the value of
474
 
.BR OFS .
475
 
References to negative numbered fields cause a fatal error.
476
 
.SS Built-in Variables
477
 
.PP
478
 
AWK's built-in variables are:
479
 
.PP
480
 
.TP \w'\fBFIELDWIDTHS\fR'u+1n
481
 
.B ARGC
482
 
The number of command line arguments (does not include options to
483
 
.IR gawk ,
484
 
or the program source).
485
 
.TP
486
 
.B ARGIND
487
 
The index in
488
 
.B ARGV
489
 
of the current file being processed.
490
 
.TP
491
 
.B ARGV
492
 
Array of command line arguments. The array is indexed from
493
 
0 to
494
 
.B ARGC
495
 
\- 1.
496
 
Dynamically changing the contents of
497
 
.B ARGV
498
 
can control the files used for data.
499
 
.TP
500
 
.B CONVFMT
501
 
The conversion format for numbers, \fB"%.6g"\fR, by default.
502
 
.TP
503
 
.B ENVIRON
504
 
An array containing the values of the current environment.
505
 
The array is indexed by the environment variables, each element being
506
 
the value of that variable (e.g., \fBENVIRON["HOME"]\fP might be
507
 
.BR /u/arnold ).
508
 
Changing this array does not affect the environment seen by programs which
509
 
.I gawk
510
 
spawns via redirection or the
511
 
.B system()
512
 
function.
513
 
(This may change in a future version of
514
 
.IR gawk .)
515
 
.\" but don't hold your breath...
516
 
.TP
517
 
.B ERRNO
518
 
If a system error occurs either doing a redirection for
519
 
.BR getline ,
520
 
during a read for
521
 
.BR getline ,
522
 
or during a
523
 
.BR close() ,
524
 
then
525
 
.B ERRNO
526
 
will contain
527
 
a string describing the error.
528
 
.TP
529
 
.B FIELDWIDTHS
530
 
A white-space separated list of fieldwidths.  When set,
531
 
.I gawk
532
 
parses the input into fields of fixed width, instead of using the
533
 
value of the
534
 
.B FS
535
 
variable as the field separator.
536
 
The fixed field width facility is still experimental; expect the
537
 
semantics to change as
538
 
.I gawk
539
 
evolves over time.
540
 
.TP
541
 
.B FILENAME
542
 
The name of the current input file.
543
 
If no files are specified on the command line, the value of
544
 
.B FILENAME
545
 
is ``\-''.
546
 
However,
547
 
.B FILENAME
548
 
is undefined inside the
549
 
.B BEGIN
550
 
block.
551
 
.TP
552
 
.B FNR
553
 
The input record number in the current input file.
554
 
.TP
555
 
.B FS
556
 
The input field separator, a blank by default.
557
 
.TP
558
 
.B IGNORECASE
559
 
Controls the case-sensitivity of all regular expression operations. If
560
 
.B IGNORECASE
561
 
has a non-zero value, then pattern matching in rules,
562
 
field splitting with
563
 
.BR FS ,
564
 
regular expression
565
 
matching with
566
 
.B ~
567
 
and
568
 
.BR !~ ,
569
 
and the
570
 
.BR gsub() ,
571
 
.BR index() ,
572
 
.BR match() ,
573
 
.BR split() ,
574
 
and
575
 
.B sub()
576
 
pre-defined functions will all ignore case when doing regular expression
577
 
operations.  Thus, if
578
 
.B IGNORECASE
579
 
is not equal to zero,
580
 
.B /aB/
581
 
matches all of the strings \fB"ab"\fP, \fB"aB"\fP, \fB"Ab"\fP,
582
 
and \fB"AB"\fP.
583
 
As with all AWK variables, the initial value of
584
 
.B IGNORECASE
585
 
is zero, so all regular expression operations are normally case-sensitive.
586
 
.TP
587
 
.B NF
588
 
The number of fields in the current input record.
589
 
.TP
590
 
.B NR
591
 
The total number of input records seen so far.
592
 
.TP
593
 
.B OFMT
594
 
The output format for numbers, \fB"%.6g"\fR, by default.
595
 
.TP
596
 
.B OFS
597
 
The output field separator, a blank by default.
598
 
.TP
599
 
.B ORS
600
 
The output record separator, by default a newline.
601
 
.TP
602
 
.B RS
603
 
The input record separator, by default a newline.
604
 
.B RS
605
 
is exceptional in that only the first character of its string
606
 
value is used for separating records.
607
 
(This will probably change in a future release of
608
 
.IR gawk .)
609
 
If
610
 
.B RS
611
 
is set to the null string, then records are separated by
612
 
blank lines.
613
 
When
614
 
.B RS
615
 
is set to the null string, then the newline character always acts as
616
 
a field separator, in addition to whatever value
617
 
.B FS
618
 
may have.
619
 
.TP
620
 
.B RSTART
621
 
The index of the first character matched by
622
 
.BR match() ;
623
 
0 if no match.
624
 
.TP
625
 
.B RLENGTH
626
 
The length of the string matched by
627
 
.BR match() ;
628
 
\-1 if no match.
629
 
.TP
630
 
.B SUBSEP
631
 
The character used to separate multiple subscripts in array
632
 
elements, by default \fB"\e034"\fR.
633
 
.SS Arrays
634
 
.PP
635
 
Arrays are subscripted with an expression between square brackets
636
 
.RB ( [ " and " ] ).
637
 
If the expression is an expression list
638
 
.RI ( expr ", " expr " ...)"
639
 
then the array subscript is a string consisting of the
640
 
concatenation of the (string) value of each expression,
641
 
separated by the value of the
642
 
.B SUBSEP
643
 
variable.
644
 
This facility is used to simulate multiply dimensioned
645
 
arrays. For example:
646
 
.PP
647
 
.RS
648
 
.ft B
649
 
i = "A" ;\^ j = "B" ;\^ k = "C"
650
 
.br
651
 
x[i, j, k] = "hello, world\en"
652
 
.ft R
653
 
.RE
654
 
.PP
655
 
assigns the string \fB"hello, world\en"\fR to the element of the array
656
 
.B x
657
 
which is indexed by the string \fB"A\e034B\e034C"\fR. All arrays in AWK
658
 
are associative, i.e. indexed by string values.
659
 
.PP
660
 
The special operator
661
 
.B in
662
 
may be used in an
663
 
.B if
664
 
or
665
 
.B while
666
 
statement to see if an array has an index consisting of a particular
667
 
value.
668
 
.PP
669
 
.RS
670
 
.ft B
671
 
.nf
672
 
if (val in array)
673
 
        print array[val]
674
 
.fi
675
 
.ft
676
 
.RE
677
 
.PP
678
 
If the array has multiple subscripts, use
679
 
.BR "(i, j) in array" .
680
 
.PP
681
 
The
682
 
.B in
683
 
construct may also be used in a
684
 
.B for
685
 
loop to iterate over all the elements of an array.
686
 
.PP
687
 
An element may be deleted from an array using the
688
 
.B delete
689
 
statement.
690
 
The
691
 
.B delete
692
 
statement may also be used to delete the entire contents of an array.
693
 
.SS Variable Typing And Conversion
694
 
.PP
695
 
Variables and fields
696
 
may be (floating point) numbers, or strings, or both. How the
697
 
value of a variable is interpreted depends upon its context. If used in
698
 
a numeric expression, it will be treated as a number, if used as a string
699
 
it will be treated as a string.
700
 
.PP
701
 
To force a variable to be treated as a number, add 0 to it; to force it
702
 
to be treated as a string, concatenate it with the null string.
703
 
.PP
704
 
When a string must be converted to a number, the conversion is accomplished
705
 
using
706
 
.IR atof (3).
707
 
A number is converted to a string by using the value of
708
 
.B CONVFMT
709
 
as a format string for
710
 
.IR sprintf (3),
711
 
with the numeric value of the variable as the argument.
712
 
However, even though all numbers in AWK are floating-point,
713
 
integral values are
714
 
.I always
715
 
converted as integers.  Thus, given
716
 
.PP
717
 
.RS
718
 
.ft B
719
 
.nf
720
 
CONVFMT = "%2.2f"
721
 
a = 12
722
 
b = a ""
723
 
.fi
724
 
.ft R
725
 
.RE
726
 
.PP
727
 
the variable
728
 
.B b
729
 
has a string value of \fB"12"\fR and not \fB"12.00"\fR.
730
 
.PP
731
 
.I Gawk
732
 
performs comparisons as follows:
733
 
If two variables are numeric, they are compared numerically.
734
 
If one value is numeric and the other has a string value that is a
735
 
``numeric string,'' then comparisons are also done numerically.
736
 
Otherwise, the numeric value is converted to a string and a string
737
 
comparison is performed.
738
 
Two strings are compared, of course, as strings.
739
 
According to the \*(PX standard, even if two strings are
740
 
numeric strings, a numeric comparison is performed.  However, this is
741
 
clearly incorrect, and
742
 
.I gawk
743
 
does not do this.
744
 
.PP
745
 
Uninitialized variables have the numeric value 0 and the string value ""
746
 
(the null, or empty, string).
747
 
.SH PATTERNS AND ACTIONS
748
 
AWK is a line oriented language. The pattern comes first, and then the
749
 
action. Action statements are enclosed in
750
 
.B {
751
 
and
752
 
.BR } .
753
 
Either the pattern may be missing, or the action may be missing, but,
754
 
of course, not both. If the pattern is missing, the action will be
755
 
executed for every single line of input.
756
 
A missing action is equivalent to
757
 
.RS
758
 
.PP
759
 
.B "{ print }"
760
 
.RE
761
 
.PP
762
 
which prints the entire line.
763
 
.PP
764
 
Comments begin with the ``#'' character, and continue until the
765
 
end of the line.
766
 
Blank lines may be used to separate statements.
767
 
Normally, a statement ends with a newline, however, this is not the
768
 
case for lines ending in
769
 
a ``,'', ``{'', ``?'', ``:'', ``&&'', or ``||''.
770
 
Lines ending in
771
 
.B do
772
 
or
773
 
.B else
774
 
also have their statements automatically continued on the following line.
775
 
In other cases, a line can be continued by ending it with a ``\e'',
776
 
in which case the newline will be ignored.
777
 
.PP
778
 
Multiple statements may
779
 
be put on one line by separating them with a ``;''.
780
 
This applies to both the statements within the action part of a
781
 
pattern-action pair (the usual case),
782
 
and to the pattern-action statements themselves.
783
 
.SS Patterns
784
 
AWK patterns may be one of the following:
785
 
.PP
786
 
.RS
787
 
.nf
788
 
.B BEGIN
789
 
.B END
790
 
.BI / "regular expression" /
791
 
.I "relational expression"
792
 
.IB pattern " && " pattern
793
 
.IB pattern " || " pattern
794
 
.IB pattern " ? " pattern " : " pattern
795
 
.BI ( pattern )
796
 
.BI ! " pattern"
797
 
.IB pattern1 ", " pattern2
798
 
.fi
799
 
.RE
800
 
.PP
801
 
.B BEGIN
802
 
and
803
 
.B END
804
 
are two special kinds of patterns which are not tested against
805
 
the input.
806
 
The action parts of all
807
 
.B BEGIN
808
 
patterns are merged as if all the statements had
809
 
been written in a single
810
 
.B BEGIN
811
 
block. They are executed before any
812
 
of the input is read. Similarly, all the
813
 
.B END
814
 
blocks are merged,
815
 
and executed when all the input is exhausted (or when an
816
 
.B exit
817
 
statement is executed).
818
 
.B BEGIN
819
 
and
820
 
.B END
821
 
patterns cannot be combined with other patterns in pattern expressions.
822
 
.B BEGIN
823
 
and
824
 
.B END
825
 
patterns cannot have missing action parts.
826
 
.PP
827
 
For
828
 
.BI / "regular expression" /
829
 
patterns, the associated statement is executed for each input line that matches
830
 
the regular expression.
831
 
Regular expressions are the same as those in
832
 
.IR egrep (1),
833
 
and are summarized below.
834
 
.PP
835
 
A
836
 
.I "relational expression"
837
 
may use any of the operators defined below in the section on actions.
838
 
These generally test whether certain fields match certain regular expressions.
839
 
.PP
840
 
The
841
 
.BR && ,
842
 
.BR || ,
843
 
and
844
 
.B !
845
 
operators are logical AND, logical OR, and logical NOT, respectively, as in C.
846
 
They do short-circuit evaluation, also as in C, and are used for combining
847
 
more primitive pattern expressions. As in most languages, parentheses
848
 
may be used to change the order of evaluation.
849
 
.PP
850
 
The
851
 
.B ?\^:
852
 
operator is like the same operator in C. If the first pattern is true
853
 
then the pattern used for testing is the second pattern, otherwise it is
854
 
the third. Only one of the second and third patterns is evaluated.
855
 
.PP
856
 
The 
857
 
.IB pattern1 ", " pattern2
858
 
form of an expression is called a
859
 
.IR "range pattern" .
860
 
It matches all input records starting with a line that matches
861
 
.IR pattern1 ,
862
 
and continuing until a record that matches
863
 
.IR pattern2 ,
864
 
inclusive. It does not combine with any other sort of pattern expression.
865
 
.SS Regular Expressions
866
 
Regular expressions are the extended kind found in
867
 
.IR egrep .
868
 
They are composed of characters as follows:
869
 
.TP \w'\fB[^\fIabc...\fB]\fR'u+2n
870
 
.I c
871
 
matches the non-metacharacter
872
 
.IR c .
873
 
.TP
874
 
.I \ec
875
 
matches the literal character
876
 
.IR c .
877
 
.TP
878
 
.B .
879
 
matches any character except newline.
880
 
.TP
881
 
.B ^
882
 
matches the beginning of a line or a string.
883
 
.TP
884
 
.B $
885
 
matches the end of a line or a string.
886
 
.TP
887
 
.BI [ abc... ]
888
 
character class, matches any of the characters
889
 
.IR abc... .
890
 
.TP
891
 
.BI [^ abc... ]
892
 
negated character class, matches any character except
893
 
.I abc...
894
 
and newline.
895
 
.TP
896
 
.IB r1 | r2
897
 
alternation: matches either
898
 
.I r1
899
 
or
900
 
.IR r2 .
901
 
.TP
902
 
.I r1r2
903
 
concatenation: matches
904
 
.IR r1 ,
905
 
and then
906
 
.IR r2 .
907
 
.TP
908
 
.IB r +
909
 
matches one or more
910
 
.IR r 's. 
911
 
.TP
912
 
.IB r *
913
 
matches zero or more
914
 
.IR r 's. 
915
 
.TP
916
 
.IB r ?
917
 
matches zero or one
918
 
.IR r 's. 
919
 
.TP
920
 
.BI ( r )
921
 
grouping: matches
922
 
.IR r .
923
 
.PP
924
 
The escape sequences that are valid in string constants (see below)
925
 
are also legal in regular expressions.
926
 
.SS Actions
927
 
Action statements are enclosed in braces,
928
 
.B {
929
 
and
930
 
.BR } .
931
 
Action statements consist of the usual assignment, conditional, and looping
932
 
statements found in most languages. The operators, control statements,
933
 
and input/output statements
934
 
available are patterned after those in C.
935
 
.SS Operators
936
 
.PP
937
 
The operators in AWK, in order of increasing precedence, are
938
 
.PP
939
 
.TP "\w'\fB*= /= %= ^=\fR'u+1n"
940
 
.PD 0
941
 
.B "= += \-="
942
 
.TP
943
 
.PD
944
 
.B "*= /= %= ^="
945
 
Assignment. Both absolute assignment
946
 
.BI ( var " = " value )
947
 
and operator-assignment (the other forms) are supported.
948
 
.TP
949
 
.B ?:
950
 
The C conditional expression. This has the form
951
 
.IB expr1 " ? " expr2 " : " expr3\c
952
 
\&. If
953
 
.I expr1
954
 
is true, the value of the expression is
955
 
.IR expr2 ,
956
 
otherwise it is
957
 
.IR expr3 .
958
 
Only one of
959
 
.I expr2
960
 
and
961
 
.I expr3
962
 
is evaluated.
963
 
.TP
964
 
.B ||
965
 
Logical OR.
966
 
.TP
967
 
.B &&
968
 
Logical AND.
969
 
.TP
970
 
.B "~ !~"
971
 
Regular expression match, negated match.
972
 
.B NOTE:
973
 
Do not use a constant regular expression
974
 
.RB ( /foo/ )
975
 
on the left-hand side of a
976
 
.B ~
977
 
or
978
 
.BR !~ .
979
 
Only use one on the right-hand side.  The expression
980
 
.BI "/foo/ ~ " exp
981
 
has the same meaning as \fB(($0 ~ /foo/) ~ \fIexp\fB)\fR.
982
 
This is usually
983
 
.I not
984
 
what was intended.
985
 
.TP
986
 
.PD 0
987
 
.B "< >"
988
 
.TP
989
 
.PD 0
990
 
.B "<= >="
991
 
.TP
992
 
.PD
993
 
.B "!= =="
994
 
The regular relational operators.
995
 
.TP
996
 
.I blank
997
 
String concatenation.
998
 
.TP
999
 
.B "+ \-"
1000
 
Addition and subtraction.
1001
 
.TP
1002
 
.B "* / %"
1003
 
Multiplication, division, and modulus.
1004
 
.TP
1005
 
.B "+ \- !"
1006
 
Unary plus, unary minus, and logical negation.
1007
 
.TP
1008
 
.B ^
1009
 
Exponentiation (\fB**\fR may also be used, and \fB**=\fR for
1010
 
the assignment operator).
1011
 
.TP
1012
 
.B "++ \-\^\-"
1013
 
Increment and decrement, both prefix and postfix.
1014
 
.TP
1015
 
.B $
1016
 
Field reference.
1017
 
.SS Control Statements
1018
 
.PP
1019
 
The control statements are
1020
 
as follows:
1021
 
.PP
1022
 
.RS
1023
 
.nf
1024
 
\fBif (\fIcondition\fB) \fIstatement\fR [ \fBelse\fI statement \fR]
1025
 
\fBwhile (\fIcondition\fB) \fIstatement \fR
1026
 
\fBdo \fIstatement \fBwhile (\fIcondition\fB)\fR
1027
 
\fBfor (\fIexpr1\fB; \fIexpr2\fB; \fIexpr3\fB) \fIstatement\fR
1028
 
\fBfor (\fIvar \fBin\fI array\fB) \fIstatement\fR
1029
 
\fBbreak\fR
1030
 
\fBcontinue\fR
1031
 
\fBdelete \fIarray\^\fB[\^\fIindex\^\fB]\fR
1032
 
\fBdelete \fIarray\^\fR
1033
 
\fBexit\fR [ \fIexpression\fR ]
1034
 
\fB{ \fIstatements \fB}
1035
 
.fi
1036
 
.RE
1037
 
.SS "I/O Statements"
1038
 
.PP
1039
 
The input/output statements are as follows:
1040
 
.PP
1041
 
.TP "\w'\fBprintf \fIfmt, expr-list\fR'u+1n"
1042
 
.BI close( filename )
1043
 
Close file (or pipe, see below).
1044
 
.TP
1045
 
.B getline
1046
 
Set
1047
 
.B $0
1048
 
from next input record; set
1049
 
.BR NF ,
1050
 
.BR NR ,
1051
 
.BR FNR .
1052
 
.TP
1053
 
.BI "getline <" file
1054
 
Set
1055
 
.B $0
1056
 
from next record of
1057
 
.IR file ;
1058
 
set
1059
 
.BR NF .
1060
 
.TP
1061
 
.BI getline " var"
1062
 
Set
1063
 
.I var
1064
 
from next input record; set
1065
 
.BR NF ,
1066
 
.BR FNR .
1067
 
.TP
1068
 
.BI getline " var" " <" file
1069
 
Set
1070
 
.I var
1071
 
from next record of
1072
 
.IR file .
1073
 
.TP
1074
 
.B next
1075
 
Stop processing the current input record. The next input record
1076
 
is read and processing starts over with the first pattern in the
1077
 
AWK program. If the end of the input data is reached, the
1078
 
.B END
1079
 
block(s), if any, are executed.
1080
 
.TP
1081
 
.B "next file"
1082
 
Stop processing the current input file.  The next input record read
1083
 
comes from the next input file.
1084
 
.B FILENAME
1085
 
is updated,
1086
 
.B FNR
1087
 
is reset to 1, and processing starts over with the first pattern in the
1088
 
AWK program. If the end of the input data is reached, the
1089
 
.B END
1090
 
block(s), if any, are executed.
1091
 
.TP
1092
 
.B print
1093
 
Prints the current record.
1094
 
.TP
1095
 
.BI print " expr-list"
1096
 
Prints expressions.
1097
 
Each expression is separated by the value of the
1098
 
.B OFS
1099
 
variable. The output record is terminated with the value of the
1100
 
.B ORS
1101
 
variable.
1102
 
.TP
1103
 
.BI print " expr-list" " >" file
1104
 
Prints expressions on
1105
 
.IR file .
1106
 
Each expression is separated by the value of the
1107
 
.B OFS
1108
 
variable. The output record is terminated with the value of the
1109
 
.B ORS
1110
 
variable.
1111
 
.TP
1112
 
.BI printf " fmt, expr-list"
1113
 
Format and print.
1114
 
.TP
1115
 
.BI printf " fmt, expr-list" " >" file
1116
 
Format and print on
1117
 
.IR file .
1118
 
.TP
1119
 
.BI system( cmd-line )
1120
 
Execute the command
1121
 
.IR cmd-line ,
1122
 
and return the exit status.
1123
 
(This may not be available on non-\*(PX systems.)
1124
 
.PP
1125
 
Other input/output redirections are also allowed. For
1126
 
.B print
1127
 
and
1128
 
.BR printf ,
1129
 
.BI >> file
1130
 
appends output to the
1131
 
.IR file ,
1132
 
while
1133
 
.BI | " command"
1134
 
writes on a pipe.
1135
 
In a similar fashion,
1136
 
.IB command " | getline"
1137
 
pipes into
1138
 
.BR getline .
1139
 
The
1140
 
.BR getline
1141
 
command will return 0 on end of file, and \-1 on an error.
1142
 
.SS The \fIprintf\fP\^ Statement
1143
 
.PP
1144
 
The AWK versions of the
1145
 
.B printf
1146
 
statement and
1147
 
.B sprintf()
1148
 
function
1149
 
(see below)
1150
 
accept the following conversion specification formats:
1151
 
.TP
1152
 
.B %c
1153
 
An \s-1ASCII\s+1 character.
1154
 
If the argument used for
1155
 
.B %c
1156
 
is numeric, it is treated as a character and printed.
1157
 
Otherwise, the argument is assumed to be a string, and the only first
1158
 
character of that string is printed.
1159
 
.TP
1160
 
.B %d
1161
 
A decimal number (the integer part).
1162
 
.TP
1163
 
.B %i
1164
 
Just like
1165
 
.BR %d .
1166
 
.TP
1167
 
.B %e
1168
 
A floating point number of the form
1169
 
.BR [\-]d.ddddddE[+\^\-]dd .
1170
 
.TP
1171
 
.B %f
1172
 
A floating point number of the form
1173
 
.BR [\-]ddd.dddddd .
1174
 
.TP
1175
 
.B %g
1176
 
Use
1177
 
.B e
1178
 
or
1179
 
.B f
1180
 
conversion, whichever is shorter, with nonsignificant zeros suppressed.
1181
 
.TP
1182
 
.B %o
1183
 
An unsigned octal number (again, an integer).
1184
 
.TP
1185
 
.B %s
1186
 
A character string.
1187
 
.TP
1188
 
.B %x
1189
 
An unsigned hexadecimal number (an integer).
1190
 
.TP
1191
 
.B %X
1192
 
Like
1193
 
.BR %x ,
1194
 
but using
1195
 
.B ABCDEF
1196
 
instead of
1197
 
.BR abcdef .
1198
 
.TP
1199
 
.B %%
1200
 
A single
1201
 
.B %
1202
 
character; no argument is converted.
1203
 
.PP
1204
 
There are optional, additional parameters that may lie between the
1205
 
.B %
1206
 
and the control letter:
1207
 
.TP
1208
 
.B \-
1209
 
The expression should be left-justified within its field.
1210
 
.TP
1211
 
.I width
1212
 
The field should be padded to this width. If the number has a leading
1213
 
zero, then the field will be padded with zeros.
1214
 
Otherwise it is padded with blanks.
1215
 
This applies even to the non-numeric output formats.
1216
 
.TP
1217
 
.BI . prec
1218
 
A number indicating the maximum width of strings or digits to the right
1219
 
of the decimal point.
1220
 
.PP
1221
 
The dynamic
1222
 
.I width
1223
 
and
1224
 
.I prec
1225
 
capabilities of the \*(AN C
1226
 
.B printf()
1227
 
routines are supported.
1228
 
A
1229
 
.B *
1230
 
in place of either the
1231
 
.B width
1232
 
or
1233
 
.B prec
1234
 
specifications will cause their values to be taken from
1235
 
the argument list to
1236
 
.B printf
1237
 
or
1238
 
.BR sprintf() .
1239
 
.SS Special File Names
1240
 
.PP
1241
 
When doing I/O redirection from either
1242
 
.B print
1243
 
or
1244
 
.B printf
1245
 
into a file,
1246
 
or via
1247
 
.B getline
1248
 
from a file,
1249
 
.I gawk
1250
 
recognizes certain special filenames internally.  These filenames
1251
 
allow access to open file descriptors inherited from
1252
 
.IR gawk 's
1253
 
parent process (usually the shell).
1254
 
Other special filenames provide access information about the running
1255
 
.B gawk
1256
 
process.
1257
 
The filenames are:
1258
 
.TP \w'\fB/dev/stdout\fR'u+1n
1259
 
.B /dev/pid
1260
 
Reading this file returns the process ID of the current process,
1261
 
in decimal, terminated with a newline.
1262
 
.TP
1263
 
.B /dev/ppid
1264
 
Reading this file returns the parent process ID of the current process,
1265
 
in decimal, terminated with a newline.
1266
 
.TP
1267
 
.B /dev/pgrpid
1268
 
Reading this file returns the process group ID of the current process,
1269
 
in decimal, terminated with a newline.
1270
 
.TP
1271
 
.B /dev/user
1272
 
Reading this file returns a single record terminated with a newline.
1273
 
The fields are separated with blanks.
1274
 
.B $1
1275
 
is the value of the
1276
 
.IR getuid (2)
1277
 
system call,
1278
 
.B $2
1279
 
is the value of the
1280
 
.IR geteuid (2)
1281
 
system call,
1282
 
.B $3
1283
 
is the value of the
1284
 
.IR getgid (2)
1285
 
system call, and
1286
 
.B $4
1287
 
is the value of the
1288
 
.IR getegid (2)
1289
 
system call.
1290
 
If there are any additional fields, they are the group IDs returned by
1291
 
.IR getgroups (2).
1292
 
Multiple groups may not be supported on all systems.
1293
 
.TP
1294
 
.B /dev/stdin
1295
 
The standard input.
1296
 
.TP
1297
 
.B /dev/stdout
1298
 
The standard output.
1299
 
.TP
1300
 
.B /dev/stderr
1301
 
The standard error output.
1302
 
.TP
1303
 
.BI /dev/fd/\^ n
1304
 
The file associated with the open file descriptor
1305
 
.IR n .
1306
 
.PP
1307
 
These are particularly useful for error messages. For example:
1308
 
.PP
1309
 
.RS
1310
 
.ft B
1311
 
print "You blew it!" > "/dev/stderr"
1312
 
.ft R
1313
 
.RE
1314
 
.PP
1315
 
whereas you would otherwise have to use
1316
 
.PP
1317
 
.RS
1318
 
.ft B
1319
 
print "You blew it!" | "cat 1>&2"
1320
 
.ft R
1321
 
.RE
1322
 
.PP
1323
 
These file names may also be used on the command line to name data files.
1324
 
.SS Numeric Functions
1325
 
.PP
1326
 
AWK has the following pre-defined arithmetic functions:
1327
 
.PP
1328
 
.TP \w'\fBsrand(\^\fIexpr\^\fB)\fR'u+1n
1329
 
.BI atan2( y , " x" )
1330
 
returns the arctangent of
1331
 
.I y/x
1332
 
in radians.
1333
 
.TP
1334
 
.BI cos( expr )
1335
 
returns the cosine in radians.
1336
 
.TP
1337
 
.BI exp( expr )
1338
 
the exponential function.
1339
 
.TP
1340
 
.BI int( expr )
1341
 
truncates to integer.
1342
 
.TP
1343
 
.BI log( expr )
1344
 
the natural logarithm function.
1345
 
.TP
1346
 
.B rand()
1347
 
returns a random number between 0 and 1.
1348
 
.TP
1349
 
.BI sin( expr )
1350
 
returns the sine in radians.
1351
 
.TP
1352
 
.BI sqrt( expr )
1353
 
the square root function.
1354
 
.TP
1355
 
.BI srand( expr )
1356
 
use
1357
 
.I expr
1358
 
as a new seed for the random number generator. If no
1359
 
.I expr
1360
 
is provided, the time of day will be used.
1361
 
The return value is the previous seed for the random
1362
 
number generator.
1363
 
.SS String Functions
1364
 
.PP
1365
 
AWK has the following pre-defined string functions:
1366
 
.PP
1367
 
.TP "\w'\fBsprintf(\^\fIfmt\fB\^, \fIexpr-list\^\fB)\fR'u+1n"
1368
 
\fBgsub(\fIr\fB, \fIs\fB, \fIt\fB)\fR
1369
 
for each substring matching the regular expression
1370
 
.I r
1371
 
in the string
1372
 
.IR t ,
1373
 
substitute the string
1374
 
.IR s ,
1375
 
and return the number of substitutions.
1376
 
If
1377
 
.I t
1378
 
is not supplied, use
1379
 
.BR $0 .
1380
 
.TP
1381
 
.BI index( s , " t" )
1382
 
returns the index of the string
1383
 
.I t
1384
 
in the string
1385
 
.IR s ,
1386
 
or 0 if
1387
 
.I t
1388
 
is not present.
1389
 
.TP
1390
 
.BI length( s )
1391
 
returns the length of the string
1392
 
.IR s ,
1393
 
or the length of
1394
 
.B $0
1395
 
if
1396
 
.I s
1397
 
is not supplied.
1398
 
.TP
1399
 
.BI match( s , " r" )
1400
 
returns the position in
1401
 
.I s
1402
 
where the regular expression
1403
 
.I r
1404
 
occurs, or 0 if
1405
 
.I r
1406
 
is not present, and sets the values of
1407
 
.B RSTART
1408
 
and
1409
 
.BR RLENGTH .
1410
 
.TP
1411
 
\fBsplit(\fIs\fB, \fIa\fB, \fIr\fB)\fR
1412
 
splits the string
1413
 
.I s
1414
 
into the array
1415
 
.I a
1416
 
on the regular expression
1417
 
.IR r ,
1418
 
and returns the number of fields. If
1419
 
.I r
1420
 
is omitted,
1421
 
.B FS
1422
 
is used instead.
1423
 
The array
1424
 
.I a
1425
 
is cleared first.
1426
 
.TP
1427
 
.BI sprintf( fmt , " expr-list" )
1428
 
prints
1429
 
.I expr-list
1430
 
according to
1431
 
.IR fmt ,
1432
 
and returns the resulting string.
1433
 
.TP
1434
 
\fBsub(\fIr\fB, \fIs\fB, \fIt\fB)\fR
1435
 
just like
1436
 
.BR gsub() ,
1437
 
but only the first matching substring is replaced.
1438
 
.TP
1439
 
\fBsubstr(\fIs\fB, \fIi\fB, \fIn\fB)\fR
1440
 
returns the
1441
 
.IR n -character
1442
 
substring of
1443
 
.I s
1444
 
starting at
1445
 
.IR i .
1446
 
If
1447
 
.I n
1448
 
is omitted, the rest of
1449
 
.I s
1450
 
is used.
1451
 
.TP
1452
 
.BI tolower( str )
1453
 
returns a copy of the string
1454
 
.IR str ,
1455
 
with all the upper-case characters in
1456
 
.I str
1457
 
translated to their corresponding lower-case counterparts.
1458
 
Non-alphabetic characters are left unchanged.
1459
 
.TP
1460
 
.BI toupper( str )
1461
 
returns a copy of the string
1462
 
.IR str ,
1463
 
with all the lower-case characters in
1464
 
.I str
1465
 
translated to their corresponding upper-case counterparts.
1466
 
Non-alphabetic characters are left unchanged.
1467
 
.SS Time Functions
1468
 
.PP
1469
 
Since one of the primary uses of AWK programs is processing log files
1470
 
that contain time stamp information,
1471
 
.I gawk
1472
 
provides the following two functions for obtaining time stamps and
1473
 
formatting them.
1474
 
.PP
1475
 
.TP "\w'\fBsystime()\fR'u+1n"
1476
 
.B systime()
1477
 
returns the current time of day as the number of seconds since the Epoch
1478
 
(Midnight UTC, January 1, 1970 on \*(PX systems).
1479
 
.TP
1480
 
\fBstrftime(\fIformat\fR, \fItimestamp\fB)\fR
1481
 
formats
1482
 
.I timestamp
1483
 
according to the specification in
1484
 
.IR format.
1485
 
The
1486
 
.I timestamp
1487
 
should be of the same form as returned by
1488
 
.BR systime() .
1489
 
If
1490
 
.I timestamp
1491
 
is missing, the current time of day is used.
1492
 
See the specification for the
1493
 
.B strftime()
1494
 
function in \*(AN C for the format conversions that are
1495
 
guaranteed to be available.
1496
 
A public-domain version of
1497
 
.IR strftime (3)
1498
 
and a man page for it are shipped with
1499
 
.IR gawk ;
1500
 
if that version was used to build
1501
 
.IR gawk ,
1502
 
then all of the conversions described in that man page are available to
1503
 
.IR gawk.
1504
 
.SS String Constants
1505
 
.PP
1506
 
String constants in AWK are sequences of characters enclosed
1507
 
between double quotes (\fB"\fR). Within strings, certain
1508
 
.I "escape sequences"
1509
 
are recognized, as in C. These are:
1510
 
.PP
1511
 
.TP \w'\fB\e\^\fIddd\fR'u+1n
1512
 
.B \e\e
1513
 
A literal backslash.
1514
 
.TP
1515
 
.B \ea
1516
 
The ``alert'' character; usually the \s-1ASCII\s+1 \s-1BEL\s+1 character.
1517
 
.TP
1518
 
.B \eb
1519
 
backspace.
1520
 
.TP
1521
 
.B \ef
1522
 
form-feed.
1523
 
.TP
1524
 
.B \en
1525
 
new line.
1526
 
.TP
1527
 
.B \er
1528
 
carriage return.
1529
 
.TP
1530
 
.B \et
1531
 
horizontal tab.
1532
 
.TP
1533
 
.B \ev
1534
 
vertical tab.
1535
 
.TP
1536
 
.BI \ex "\^hex digits"
1537
 
The character represented by the string of hexadecimal digits following
1538
 
the
1539
 
.BR \ex .
1540
 
As in \*(AN C, all following hexadecimal digits are considered part of
1541
 
the escape sequence.
1542
 
(This feature should tell us something about language design by committee.)
1543
 
E.g., \fB"\ex1B"\fR is the \s-1ASCII\s+1 \s-1ESC\s+1 (escape) character.
1544
 
.TP
1545
 
.BI \e ddd
1546
 
The character represented by the 1-, 2-, or 3-digit sequence of octal
1547
 
digits. E.g. \fB"\e033"\fR is the \s-1ASCII\s+1 \s-1ESC\s+1 (escape) character.
1548
 
.TP
1549
 
.BI \e c
1550
 
The literal character
1551
 
.IR c\^ .
1552
 
.PP
1553
 
The escape sequences may also be used inside constant regular expressions
1554
 
(e.g.,
1555
 
.B "/[\ \et\ef\en\er\ev]/"
1556
 
matches whitespace characters).
1557
 
.SH FUNCTIONS
1558
 
Functions in AWK are defined as follows:
1559
 
.PP
1560
 
.RS
1561
 
\fBfunction \fIname\fB(\fIparameter list\fB) { \fIstatements \fB}\fR
1562
 
.RE
1563
 
.PP
1564
 
Functions are executed when called from within the action parts of regular
1565
 
pattern-action statements. Actual parameters supplied in the function
1566
 
call are used to instantiate the formal parameters declared in the function.
1567
 
Arrays are passed by reference, other variables are passed by value.
1568
 
.PP
1569
 
Since functions were not originally part of the AWK language, the provision
1570
 
for local variables is rather clumsy: They are declared as extra parameters
1571
 
in the parameter list. The convention is to separate local variables from
1572
 
real parameters by extra spaces in the parameter list. For example:
1573
 
.PP
1574
 
.RS
1575
 
.ft B
1576
 
.nf
1577
 
function  f(p, q,     a, b) {   # a & b are local
1578
 
                        ..... }
1579
 
 
1580
 
/abc/   { ... ; f(1, 2) ; ... }
1581
 
.fi
1582
 
.ft R
1583
 
.RE
1584
 
.PP
1585
 
The left parenthesis in a function call is required
1586
 
to immediately follow the function name,
1587
 
without any intervening white space.
1588
 
This is to avoid a syntactic ambiguity with the concatenation operator.
1589
 
This restriction does not apply to the built-in functions listed above.
1590
 
.PP
1591
 
Functions may call each other and may be recursive.
1592
 
Function parameters used as local variables are initialized
1593
 
to the null string and the number zero upon function invocation.
1594
 
.PP
1595
 
The word
1596
 
.B func
1597
 
may be used in place of
1598
 
.BR function .
1599
 
.SH EXAMPLES
1600
 
.nf
1601
 
Print and sort the login names of all users:
1602
 
 
1603
 
.ft B
1604
 
        BEGIN   { FS = ":" }
1605
 
                { print $1 | "sort" }
1606
 
 
1607
 
.ft R
1608
 
Count lines in a file:
1609
 
 
1610
 
.ft B
1611
 
                { nlines++ }
1612
 
        END     { print nlines }
1613
 
 
1614
 
.ft R
1615
 
Precede each line by its number in the file:
1616
 
 
1617
 
.ft B
1618
 
        { print FNR, $0 }
1619
 
 
1620
 
.ft R
1621
 
Concatenate and line number (a variation on a theme):
1622
 
 
1623
 
.ft B
1624
 
        { print NR, $0 }
1625
 
.ft R
1626
 
.fi
1627
 
.SH SEE ALSO
1628
 
.IR egrep (1),
1629
 
.IR getpid (2),
1630
 
.IR getppid (2),
1631
 
.IR getpgrp (2),
1632
 
.IR getuid (2),
1633
 
.IR geteuid (2),
1634
 
.IR getgid (2),
1635
 
.IR getegid (2),
1636
 
.IR getgroups (2)
1637
 
.PP
1638
 
.IR "The AWK Programming Language" ,
1639
 
Alfred V. Aho, Brian W. Kernighan, Peter J. Weinberger,
1640
 
Addison-Wesley, 1988. ISBN 0-201-07981-X.
1641
 
.PP
1642
 
.IR "The GAWK Manual" ,
1643
 
Edition 0.15, published by the Free Software Foundation, 1993.
1644
 
.SH POSIX COMPATIBILITY
1645
 
A primary goal for
1646
 
.I gawk
1647
 
is compatibility with the \*(PX standard, as well as with the
1648
 
latest version of \*(UX
1649
 
.IR awk .
1650
 
To this end,
1651
 
.I gawk
1652
 
incorporates the following user visible
1653
 
features which are not described in the AWK book,
1654
 
but are part of
1655
 
.I awk
1656
 
in System V Release 4, and are in the \*(PX standard.
1657
 
.PP
1658
 
The
1659
 
.B \-v
1660
 
option for assigning variables before program execution starts is new.
1661
 
The book indicates that command line variable assignment happens when
1662
 
.I awk
1663
 
would otherwise open the argument as a file, which is after the
1664
 
.B BEGIN
1665
 
block is executed.  However, in earlier implementations, when such an
1666
 
assignment appeared before any file names, the assignment would happen
1667
 
.I before
1668
 
the
1669
 
.B BEGIN
1670
 
block was run.  Applications came to depend on this ``feature.''
1671
 
When
1672
 
.I awk
1673
 
was changed to match its documentation, this option was added to
1674
 
accommodate applications that depended upon the old behavior.
1675
 
(This feature was agreed upon by both the AT&T and GNU developers.)
1676
 
.PP
1677
 
The
1678
 
.B \-W
1679
 
option for implementation specific features is from the \*(PX standard.
1680
 
.PP
1681
 
When processing arguments,
1682
 
.I gawk
1683
 
uses the special option ``\fB\-\^\-\fP'' to signal the end of
1684
 
arguments.
1685
 
In compatibility mode, it will warn about, but otherwise ignore,
1686
 
undefined options.
1687
 
In normal operation, such arguments are passed on to the AWK program for
1688
 
it to process.
1689
 
.PP
1690
 
The AWK book does not define the return value of
1691
 
.BR srand() .
1692
 
The System V Release 4 version of \*(UX
1693
 
.I awk
1694
 
(and the \*(PX standard)
1695
 
has it return the seed it was using, to allow keeping track
1696
 
of random number sequences. Therefore
1697
 
.B srand()
1698
 
in
1699
 
.I gawk
1700
 
also returns its current seed.
1701
 
.PP
1702
 
Other new features are:
1703
 
The use of multiple
1704
 
.B \-f
1705
 
options (from MKS
1706
 
.IR awk );
1707
 
the
1708
 
.B ENVIRON
1709
 
array; the
1710
 
.BR \ea ,
1711
 
and
1712
 
.BR \ev
1713
 
escape sequences (done originally in
1714
 
.I gawk
1715
 
and fed back into AT&T's); the
1716
 
.B tolower()
1717
 
and
1718
 
.B toupper()
1719
 
built-in functions (from AT&T); and the \*(AN C conversion specifications in
1720
 
.B printf
1721
 
(done first in AT&T's version).
1722
 
.SH GNU EXTENSIONS
1723
 
.I Gawk
1724
 
has some extensions to \*(PX
1725
 
.IR awk .
1726
 
They are described in this section.  All the extensions described here
1727
 
can be disabled by
1728
 
invoking
1729
 
.I gawk
1730
 
with the
1731
 
.B "\-W compat"
1732
 
option.
1733
 
.PP
1734
 
The following features of
1735
 
.I gawk
1736
 
are not available in
1737
 
\*(PX
1738
 
.IR awk .
1739
 
.RS
1740
 
.TP \w'\(bu'u+1n
1741
 
\(bu
1742
 
The
1743
 
.B \ex
1744
 
escape sequence.
1745
 
.TP
1746
 
\(bu
1747
 
The
1748
 
.B systime()
1749
 
and
1750
 
.B strftime()
1751
 
functions.
1752
 
.TP
1753
 
\(bu
1754
 
The special file names available for I/O redirection are not recognized.
1755
 
.TP
1756
 
\(bu
1757
 
The
1758
 
.B ARGIND
1759
 
and
1760
 
.B ERRNO
1761
 
variables are not special.
1762
 
.TP
1763
 
\(bu
1764
 
The
1765
 
.B IGNORECASE
1766
 
variable and its side-effects are not available.
1767
 
.TP
1768
 
\(bu
1769
 
The
1770
 
.B FIELDWIDTHS
1771
 
variable and fixed width field splitting.
1772
 
.TP
1773
 
\(bu
1774
 
No path search is performed for files named via the
1775
 
.B \-f
1776
 
option.  Therefore the
1777
 
.B AWKPATH
1778
 
environment variable is not special.
1779
 
.TP
1780
 
\(bu
1781
 
The use of
1782
 
.B "next file"
1783
 
to abandon processing of the current input file.
1784
 
.TP
1785
 
\(bu
1786
 
The use of
1787
 
.BI delete " array"
1788
 
to delete the entire contents of an array.
1789
 
.RE
1790
 
.PP
1791
 
The AWK book does not define the return value of the
1792
 
.B close()
1793
 
function.
1794
 
.IR Gawk\^ 's
1795
 
.B close()
1796
 
returns the value from
1797
 
.IR fclose (3),
1798
 
or
1799
 
.IR pclose (3),
1800
 
when closing a file or pipe, respectively.
1801
 
.PP
1802
 
When
1803
 
.I gawk
1804
 
is invoked with the
1805
 
.B "\-W compat"
1806
 
option,
1807
 
if the
1808
 
.I fs
1809
 
argument to the
1810
 
.B \-F
1811
 
option is ``t'', then
1812
 
.B FS
1813
 
will be set to the tab character.
1814
 
Since this is a rather ugly special case, it is not the default behavior.
1815
 
This behavior also does not occur if
1816
 
.B "\-W posix"
1817
 
has been specified.
1818
 
.ig
1819
 
.PP
1820
 
If
1821
 
.I gawk
1822
 
was compiled for debugging, it will
1823
 
accept the following additional options:
1824
 
.TP
1825
 
.PD 0
1826
 
.B \-Wparsedebug
1827
 
.TP
1828
 
.PD
1829
 
.B \-\^\-parsedebug
1830
 
Turn on
1831
 
.IR yacc (1)
1832
 
or
1833
 
.IR bison (1)
1834
 
debugging output during program parsing.
1835
 
This option should only be of interest to the
1836
 
.I gawk
1837
 
maintainers, and may not even be compiled into
1838
 
.IR gawk .
1839
 
..
1840
 
.SH HISTORICAL FEATURES
1841
 
There are two features of historical AWK implementations that
1842
 
.I gawk
1843
 
supports.
1844
 
First, it is possible to call the
1845
 
.B length()
1846
 
built-in function not only with no argument, but even without parentheses!
1847
 
Thus,
1848
 
.RS
1849
 
.PP
1850
 
.ft B
1851
 
a = length
1852
 
.ft R
1853
 
.RE
1854
 
.PP
1855
 
is the same as either of
1856
 
.RS
1857
 
.PP
1858
 
.ft B
1859
 
a = length()
1860
 
.br
1861
 
a = length($0)
1862
 
.ft R
1863
 
.RE
1864
 
.PP
1865
 
This feature is marked as ``deprecated'' in the \*(PX standard, and
1866
 
.I gawk
1867
 
will issue a warning about its use if
1868
 
.B "\-W lint"
1869
 
is specified on the command line.
1870
 
.PP
1871
 
The other feature is the use of either the
1872
 
.B continue
1873
 
or the
1874
 
.B break
1875
 
statements outside the body of a
1876
 
.BR while ,
1877
 
.BR for ,
1878
 
or
1879
 
.B do
1880
 
loop.  Traditional AWK implementations have treated such usage as
1881
 
equivalent to the
1882
 
.B next
1883
 
statement.
1884
 
.I Gawk
1885
 
will support this usage if
1886
 
.B "\-W compat"
1887
 
has been specified.
1888
 
.SH ENVIRONMENT VARIABLES
1889
 
If
1890
 
.B POSIXLY_CORRECT
1891
 
exists in the environment, then
1892
 
.I gawk
1893
 
behaves exactly as if
1894
 
.B \-\-posix
1895
 
had been specified on the command line.
1896
 
If
1897
 
.B \-\-lint
1898
 
has been specified,
1899
 
.I gawk
1900
 
will issue a warning message to this effect.
1901
 
.SH BUGS
1902
 
The
1903
 
.B \-F
1904
 
option is not necessary given the command line variable assignment feature;
1905
 
it remains only for backwards compatibility.
1906
 
.PP
1907
 
If your system actually has support for
1908
 
.B /dev/fd
1909
 
and the associated
1910
 
.BR /dev/stdin ,
1911
 
.BR /dev/stdout ,
1912
 
and
1913
 
.B /dev/stderr
1914
 
files, you may get different output from
1915
 
.I gawk
1916
 
than you would get on a system without those files.  When
1917
 
.I gawk
1918
 
interprets these files internally, it synchronizes output to the standard
1919
 
output with output to
1920
 
.BR /dev/stdout ,
1921
 
while on a system with those files, the output is actually to different
1922
 
open files.
1923
 
Caveat Emptor.
1924
 
.SH VERSION INFORMATION
1925
 
This man page documents
1926
 
.IR gawk ,
1927
 
version 2.15.
1928
 
.PP
1929
 
Starting with the 2.15 version of
1930
 
.IR gawk ,
1931
 
the
1932
 
.BR \-c ,
1933
 
.BR \-V ,
1934
 
.BR \-C ,
1935
 
.ig
1936
 
.BR \-D ,
1937
 
..
1938
 
.BR \-a ,
1939
 
and
1940
 
.B \-e
1941
 
options of the 2.11 version are no longer recognized.
1942
 
This fact will not even be documented in the manual page for the next
1943
 
major version.
1944
 
.SH AUTHORS
1945
 
The original version of \*(UX
1946
 
.I awk
1947
 
was designed and implemented by Alfred Aho,
1948
 
Peter Weinberger, and Brian Kernighan of AT&T Bell Labs. Brian Kernighan
1949
 
continues to maintain and enhance it.
1950
 
.PP
1951
 
Paul Rubin and Jay Fenlason,
1952
 
of the Free Software Foundation, wrote
1953
 
.IR gawk ,
1954
 
to be compatible with the original version of
1955
 
.I awk
1956
 
distributed in Seventh Edition \*(UX.
1957
 
John Woods contributed a number of bug fixes.
1958
 
David Trueman, with contributions
1959
 
from Arnold Robbins, made
1960
 
.I gawk
1961
 
compatible with the new version of \*(UX
1962
 
.IR awk .
1963
 
Arnold Robbins is the current maintainer.
1964
 
.PP
1965
 
The initial DOS port was done by Conrad Kwok and Scott Garfinkle.
1966
 
Scott Deifik is the current DOS maintainer.  Pat Rankin did the
1967
 
port to VMS, and Michal Jaegermann did the port to the Atari ST.
1968
 
The port to OS/2 was done by Kai Uwe Rommel, with contributions and
1969
 
help from Darrel Hankerson.
1970
 
.SH BUG REPORTS
1971
 
If you find a bug in
1972
 
.IR gawk ,
1973
 
please send electronic mail to
1974
 
.BR bug-gnu-utils@prep.ai.mit.edu ,
1975
 
.I with
1976
 
a carbon copy to
1977
 
.BR arnold@gnu.ai.mit.edu .
1978
 
Please include your operating system and its revision, the version of
1979
 
.IR gawk ,
1980
 
what C compiler you used to compile it, and a test program
1981
 
and data that are as small as possible for reproducing the problem.
1982
 
.PP
1983
 
Before sending a bug report, please do two things. First, verify that
1984
 
you have the latest version of
1985
 
.IR gawk .
1986
 
Many bugs (usually subtle ones) are fixed at each release, and if
1987
 
your's is out of date, the problem may already have been solved.
1988
 
Second, please read this man page and the reference manual carefully to
1989
 
be sure that what you think is a bug really is, instead of just a quirk
1990
 
in the language.
1991
 
.SH ACKNOWLEDGEMENTS
1992
 
Brian Kernighan of Bell Labs
1993
 
provided valuable assistance during testing and debugging.
1994
 
We thank him.