« back to all changes in this revision
Viewing changes to doc/gawk.1
- browse files at revision 21
- compare with another revision
- compare with revision 28
- download diff
- download tarball
- view history from revision 21
- 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.
- files added:
- ChangeLog
- README_d
- amiga
- awklib
- awklib/eg
- awklib/eg/data
- awklib/eg/lib
- awklib/eg/misc
- awklib/eg/prog
- doc
- pc/awklib
- pc/include
- pc/include/sys
- posix
- files removed:
- Makefile.bsd44
- config
- support
- files modified:
- ACKNOWLEDGMENT
added
removed
doc/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 "Dec 28 1995" "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 found in the System V Release 4 version
32
of \*(UX
33
.IR awk .
34
.I Gawk
35
also provides more recent Bell Labs
36
.I awk
37
extensions, and some GNU-specific extensions.
38
.PP
39
The command line consists of options to
40
.I gawk
41
itself, the AWK program text (if not supplied via the
42
.B \-f
43
or
44
.B \-\^\-file
45
options), and values to be made
46
available in the
47
.B ARGC
48
and
49
.B ARGV
50
pre-defined AWK variables.
51
.SH OPTION FORMAT
52
.PP
53
.I Gawk
54
options may be either the traditional \*(PX one letter options,
55
or the GNU style long options. \*(PX options start with a single ``\-'',
56
while long options start with ``\-\^\-''.
57
Long options are provided for both GNU-specific features and
58
for \*(PX mandated features.
59
.PP
60
Following the \*(PX standard,
61
.IR gawk -specific
62
options are supplied via arguments to the
63
.B \-W
64
option. Multiple
65
.B \-W
66
options may be supplied, or multiple arguments may be supplied together
67
if they are separated by commas, or enclosed in quotes and separated
68
by white space.
69
Case is ignored in arguments to the
70
.B \-W
71
option.
72
Each
73
.B \-W
74
option has a corresponding long option, as detailed below.
75
Arguments to long options are either joined with the option
76
by an
77
.B =
78
sign, with no intervening spaces, or they may be provided in the
79
next command line argument.
80
Long options may be abbreviated, as long as the abbreviation
81
remains unique.
82
.SH OPTIONS
83
.PP
84
.I Gawk
85
accepts the following options.
86
.TP
87
.PD 0
88
.BI \-F " fs"
89
.TP
90
.PD
91
.BI \-\^\-field-separator " fs"
92
Use
93
.I fs
94
for the input field separator (the value of the
95
.B FS
96
predefined
97
variable).
98
.TP
99
.PD 0
100
\fB\-v\fI var\fB\^=\^\fIval\fR
101
.TP
102
.PD
103
\fB\-\^\-assign \fIvar\fB\^=\^\fIval\fR
104
Assign the value
105
.IR val ,
106
to the variable
107
.IR var ,
108
before execution of the program begins.
109
Such variable values are available to the
110
.B BEGIN
111
block of an AWK program.
112
.TP
113
.PD 0
114
.BI \-f " program-file"
115
.TP
116
.PD
117
.BI \-\^\-file " program-file"
118
Read the AWK program source from the file
119
.IR program-file ,
120
instead of from the first command line argument.
121
Multiple
122
.B \-f
123
(or
124
.BR \-\^\-file )
125
options may be used.
126
.TP
127
.PD 0
128
.BI \-mf= NNN
129
.TP
130
.PD
131
.BI \-mr= NNN
132
Set various memory limits to the value
133
.IR NNN .
134
The
135
.B f
136
flag sets the maximum number of fields, and the
137
.B r
138
flag sets the maximum record size. These two flags and the
139
.B \-m
140
option are from the Bell Labs research version of \*(UX
141
.IR awk .
142
They are ignored by
143
.IR gawk ,
144
since
145
.I gawk
146
has no pre-defined limits.
147
.TP
148
.PD 0
149
.B "\-W traditional"
150
.TP
151
.PD 0
152
.B "\-W compat"
153
.TP
154
.PD 0
155
.B \-\^\-traditional
156
.TP
157
.PD
158
.B \-\^\-compat
159
Run in
160
.I compatibility
161
mode. In compatibility mode,
162
.I gawk
163
behaves identically to \*(UX
164
.IR awk ;
165
none of the GNU-specific extensions are recognized.
166
The use of
167
.B \-\^\-traditional
168
is preferred over the other forms of this option.
169
See
170
.BR "GNU EXTENSIONS" ,
171
below, for more information.
172
.TP
173
.PD 0
174
.B "\-W copyleft"
175
.TP
176
.PD 0
177
.B "\-W copyright"
178
.TP
179
.PD 0
180
.B \-\^\-copyleft
181
.TP
182
.PD
183
.B \-\^\-copyright
184
Print the short version of the GNU copyright information message on
185
the error output.
186
.TP
187
.PD 0
188
.B "\-W help"
189
.TP
190
.PD 0
191
.B "\-W usage"
192
.TP
193
.PD 0
194
.B \-\^\-help
195
.TP
196
.PD
197
.B \-\^\-usage
198
Print a relatively short summary of the available options on
199
the error output.
200
(Per the
201
.IR "GNU Coding Standards" ,
202
these options cause an immediate, successful exit.)
203
.TP
204
.PD 0
205
.B "\-W lint"
206
.TP
207
.PD
208
.B \-\^\-lint
209
Provide warnings about constructs that are
210
dubious or non-portable to other AWK implementations.
211
.TP
212
.PD 0
213
.B "\-W lint\-old"
214
.TP
215
.PD
216
.B \-\^\-lint\-old
217
Provide warnings about constructs that are
218
not portable to the original version of Unix
219
.IR awk .
220
.ig
221
.\" This option is left undocumented, on purpose.
222
.TP
223
.PD 0
224
.B "\-W nostalgia"
225
.TP
226
.PD
227
.B \-\^\-nostalgia
228
Provide a moment of nostalgia for long time
229
.I awk
230
users.
231
..
232
.TP
233
.PD 0
234
.B "\-W posix"
235
.TP
236
.PD
237
.B \-\^\-posix
238
This turns on
239
.I compatibility
240
mode, with the following additional restrictions:
241
.RS
242
.TP \w'\(bu'u+1n
243
\(bu
244
.B \ex
245
escape sequences are not recognized.
246
.TP
247
\(bu
248
The synonym
249
.B func
250
for the keyword
251
.B function
252
is not recognized.
253
.TP
254
\(bu
255
The operators
256
.B **
257
and
258
.B **=
259
cannot be used in place of
260
.B ^
261
and
262
.BR ^= .
263
.TP
264
\(bu
265
The
266
.B fflush()
267
function is not available.
268
.RE
269
.TP
270
.PD 0
271
.B "\-W re\-interval"
272
.TP
273
.PD
274
.B \-\^\-re\-interval
275
Enable the use of
276
.I "interval expressions"
277
in regular expression matching
278
(see
279
.BR "Regular Expressions" ,
280
below).
281
Interval expressions were not traditionally available in the
282
AWK language. The POSIX standard added them, to make
283
.I awk
284
and
285
.I egrep
286
consistent with each other.
287
However, their use is likely
288
to break old AWK programs, so
289
.I gawk
290
only provides them if they are requested with this option, or when
291
.B \-\^\-posix
292
is specified.
293
.TP
294
.PD 0
295
.BI "\-W source " program-text
296
.TP
297
.PD
298
.BI \-\^\-source " program-text"
299
Use
300
.I program-text
301
as AWK program source code.
302
This option allows the easy intermixing of library functions (used via the
303
.B \-f
304
and
305
.B \-\^\-file
306
options) with source code entered on the command line.
307
It is intended primarily for medium to large AWK programs used
308
in shell scripts.
309
.sp .5
310
The
311
.B "\-W source="
312
form of this option uses the rest of the command line argument for
313
.IR program-text ;
314
no other options to
315
.B \-W
316
will be recognized in the same argument.
317
.TP
318
.PD 0
319
.B "\-W version"
320
.TP
321
.PD
322
.B \-\^\-version
323
Print version information for this particular copy of
324
.I gawk
325
on the error output.
326
This is useful mainly for knowing if the current copy of
327
.I gawk
328
on your system
329
is up to date with respect to whatever the Free Software Foundation
330
is distributing.
331
This is also useful when reporting bugs.
332
(Per the
333
.IR "GNU Coding Standards" ,
334
these options cause an immediate, successful exit.)
335
.TP
336
.B \-\^\-
337
Signal the end of options. This is useful to allow further arguments to the
338
AWK program itself to start with a ``\-''.
339
This is mainly for consistency with the argument parsing convention used
340
by most other \*(PX programs.
341
.PP
342
In compatibility mode,
343
any other options are flagged as illegal, but are otherwise ignored.
344
In normal operation, as long as program text has been supplied, unknown
345
options are passed on to the AWK program in the
346
.B ARGV
347
array for processing. This is particularly useful for running AWK
348
programs via the ``#!'' executable interpreter mechanism.
349
.SH AWK PROGRAM EXECUTION
350
.PP
351
An AWK program consists of a sequence of pattern-action statements
352
and optional function definitions.
353
.RS
354
.PP
355
\fIpattern\fB { \fIaction statements\fB }\fR
356
.br
357
\fBfunction \fIname\fB(\fIparameter list\fB) { \fIstatements\fB }\fR
358
.RE
359
.PP
360
.I Gawk
361
first reads the program source from the
362
.IR program-file (s)
363
if specified,
364
from arguments to
365
.BR \-\^\-source ,
366
or from the first non-option argument on the command line.
367
The
368
.B \-f
369
and
370
.B \-\^\-source
371
options may be used multiple times on the command line.
372
.I Gawk
373
will read the program text as if all the
374
.IR program-file s
375
and command line source texts
376
had been concatenated together. This is useful for building libraries
377
of AWK functions, without having to include them in each new AWK
378
program that uses them. It also provides the ability to mix library
379
functions with command line programs.
380
.PP
381
The environment variable
382
.B AWKPATH
383
specifies a search path to use when finding source files named with
384
the
385
.B \-f
386
option. If this variable does not exist, the default path is
387
\fB".:/usr/local/share/awk"\fR.
388
(The actual directory may vary, depending upon how
389
.I gawk
390
was built and installed.)
391
If a file name given to the
392
.B \-f
393
option contains a ``/'' character, no path search is performed.
394
.PP
395
.I Gawk
396
executes AWK programs in the following order.
397
First,
398
all variable assignments specified via the
399
.B \-v
400
option are performed.
401
Next,
402
.I gawk
403
compiles the program into an internal form.
404
Then,
405
.I gawk
406
executes the code in the
407
.B BEGIN
408
block(s) (if any),
409
and then proceeds to read
410
each file named in the
411
.B ARGV
412
array.
413
If there are no files named on the command line,
414
.I gawk
415
reads the standard input.
416
.PP
417
If a filename on the command line has the form
418
.IB var = val
419
it is treated as a variable assignment. The variable
420
.I var
421
will be assigned the value
422
.IR val .
423
(This happens after any
424
.B BEGIN
425
block(s) have been run.)
426
Command line variable assignment
427
is most useful for dynamically assigning values to the variables
428
AWK uses to control how input is broken into fields and records. It
429
is also useful for controlling state if multiple passes are needed over
430
a single data file.
431
.PP
432
If the value of a particular element of
433
.B ARGV
434
is empty (\fB""\fR),
435
.I gawk
436
skips over it.
437
.PP
438
For each record in the input,
439
.I gawk
440
tests to see if it matches any
441
.I pattern
442
in the AWK program.
443
For each pattern that the record matches, the associated
444
.I action
445
is executed.
446
The patterns are tested in the order they occur in the program.
447
.PP
448
Finally, after all the input is exhausted,
449
.I gawk
450
executes the code in the
451
.B END
452
block(s) (if any).
453
.SH VARIABLES, RECORDS AND FIELDS
454
AWK variables are dynamic; they come into existence when they are
455
first used. Their values are either floating-point numbers or strings,
456
or both,
457
depending upon how they are used. AWK also has one dimensional
458
arrays; arrays with multiple dimensions may be simulated.
459
Several pre-defined variables are set as a program
460
runs; these will be described as needed and summarized below.
461
.SS Records
462
Normally, records are separated by newline characters. You can control how
463
records are separated by assigning values to the built-in variable
464
.BR RS .
465
If
466
.B RS
467
is any single character, that character separates records.
468
Otherwise,
469
.B RS
470
is a regular expression. Text in the input that matches this
471
regular expression will separate the record.
472
However, in compatibility mode,
473
only the first character of its string
474
value is used for separating records.
475
If
476
.B RS
477
is set to the null string, then records are separated by
478
blank lines.
479
When
480
.B RS
481
is set to the null string, the newline character always acts as
482
a field separator, in addition to whatever value
483
.B FS
484
may have.
485
.SS Fields
486
.PP
487
As each input record is read,
488
.I gawk
489
splits the record into
490
.IR fields ,
491
using the value of the
492
.B FS
493
variable as the field separator.
494
If
495
.B FS
496
is a single character, fields are separated by that character.
497
If
498
.B FS
499
is the null string, then each individual character becomes a
500
separate field.
501
Otherwise,
502
.B FS
503
is expected to be a full regular expression.
504
In the special case that
505
.B FS
506
is a single space, fields are separated
507
by runs of spaces and/or tabs.
508
Note that the value of
509
.B IGNORECASE
510
(see below) will also affect how fields are split when
511
.B FS
512
is a regular expression, and how records are separated when
513
.B RS
514
is a regular expression.
515
.PP
516
If the
517
.B FIELDWIDTHS
518
variable is set to a space separated list of numbers, each field is
519
expected to have fixed width, and
520
.I gawk
521
will split up the record using the specified widths. The value of
522
.B FS
523
is ignored.
524
Assigning a new value to
525
.B FS
526
overrides the use of
527
.BR FIELDWIDTHS ,
528
and restores the default behavior.
529
.PP
530
Each field in the input record may be referenced by its position,
531
.BR $1 ,
532
.BR $2 ,
533
and so on.
534
.B $0
535
is the whole record. The value of a field may be assigned to as well.
536
Fields need not be referenced by constants:
537
.RS
538
.PP
539
.ft B
540
n = 5
541
.br
542
print $n
543
.ft R
544
.RE
545
.PP
546
prints the fifth field in the input record.
547
The variable
548
.B NF
549
is set to the total number of fields in the input record.
550
.PP
551
References to non-existent fields (i.e. fields after
552
.BR $NF )
553
produce the null-string. However, assigning to a non-existent field
554
(e.g.,
555
.BR "$(NF+2) = 5" )
556
will increase the value of
557
.BR NF ,
558
create any intervening fields with the null string as their value, and
559
cause the value of
560
.B $0
561
to be recomputed, with the fields being separated by the value of
562
.BR OFS .
563
References to negative numbered fields cause a fatal error.
564
.SS Built-in Variables
565
.PP
566
.IR Gawk 's
567
built-in variables are:
568
.PP
569
.TP \w'\fBFIELDWIDTHS\fR'u+1n
570
.B ARGC
571
The number of command line arguments (does not include options to
572
.IR gawk ,
573
or the program source).
574
.TP
575
.B ARGIND
576
The index in
577
.B ARGV
578
of the current file being processed.
579
.TP
580
.B ARGV
581
Array of command line arguments. The array is indexed from
582
0 to
583
.B ARGC
584
\- 1.
585
Dynamically changing the contents of
586
.B ARGV
587
can control the files used for data.
588
.TP
589
.B CONVFMT
590
The conversion format for numbers, \fB"%.6g"\fR, by default.
591
.TP
592
.B ENVIRON
593
An array containing the values of the current environment.
594
The array is indexed by the environment variables, each element being
595
the value of that variable (e.g., \fBENVIRON["HOME"]\fP might be
596
.BR /home/arnold ).
597
Changing this array does not affect the environment seen by programs which
598
.I gawk
599
spawns via redirection or the
600
.B system()
601
function.
602
(This may change in a future version of
603
.IR gawk .)
604
.\" but don't hold your breath...
605
.TP
606
.B ERRNO
607
If a system error occurs either doing a redirection for
608
.BR getline ,
609
during a read for
610
.BR getline ,
611
or during a
612
.BR close() ,
613
then
614
.B ERRNO
615
will contain
616
a string describing the error.
617
.TP
618
.B FIELDWIDTHS
619
A white-space separated list of fieldwidths. When set,
620
.I gawk
621
parses the input into fields of fixed width, instead of using the
622
value of the
623
.B FS
624
variable as the field separator.
625
The fixed field width facility is still experimental; the
626
semantics may change as
627
.I gawk
628
evolves over time.
629
.TP
630
.B FILENAME
631
The name of the current input file.
632
If no files are specified on the command line, the value of
633
.B FILENAME
634
is ``\-''.
635
However,
636
.B FILENAME
637
is undefined inside the
638
.B BEGIN
639
block.
640
.TP
641
.B FNR
642
The input record number in the current input file.
643
.TP
644
.B FS
645
The input field separator, a space by default. See
646
.BR Fields ,
647
above.
648
.TP
649
.B IGNORECASE
650
Controls the case-sensitivity of all regular expression
651
and string operations. If
652
.B IGNORECASE
653
has a non-zero value, then string comparisons and
654
pattern matching in rules,
655
field splitting with
656
.BR FS ,
657
record separating with
658
.BR RS ,
659
regular expression
660
matching with
661
.B ~
662
and
663
.BR !~ ,
664
and the
665
.BR gensub() ,
666
.BR gsub() ,
667
.BR index() ,
668
.BR match() ,
669
.BR split() ,
670
and
671
.B sub()
672
pre-defined functions will all ignore case when doing regular expression
673
operations. Thus, if
674
.B IGNORECASE
675
is not equal to zero,
676
.B /aB/
677
matches all of the strings \fB"ab"\fP, \fB"aB"\fP, \fB"Ab"\fP,
678
and \fB"AB"\fP.
679
As with all AWK variables, the initial value of
680
.B IGNORECASE
681
is zero, so all regular expression and string
682
operations are normally case-sensitive.
683
Under Unix, the full ISO 8859-1 Latin-1 character set is used
684
when ignoring case.
685
.B NOTE:
686
In versions of
687
.I gawk
688
prior to 3.0,
689
.B IGNORECASE
690
only affected regular expression operations. It now affects string
691
comparisons as well.
692
.TP
693
.B NF
694
The number of fields in the current input record.
695
.TP
696
.B NR
697
The total number of input records seen so far.
698
.TP
699
.B OFMT
700
The output format for numbers, \fB"%.6g"\fR, by default.
701
.TP
702
.B OFS
703
The output field separator, a space by default.
704
.TP
705
.B ORS
706
The output record separator, by default a newline.
707
.TP
708
.B RS
709
The input record separator, by default a newline.
710
.TP
711
.B RT
712
The record terminator.
713
.I Gawk
714
sets
715
.B RT
716
to the input text that matched the character or regular expression
717
specified by
718
.BR RS .
719
.TP
720
.B RSTART
721
The index of the first character matched by
722
.BR match() ;
723
0 if no match.
724
.TP
725
.B RLENGTH
726
The length of the string matched by
727
.BR match() ;
728
\-1 if no match.
729
.TP
730
.B SUBSEP
731
The character used to separate multiple subscripts in array
732
elements, by default \fB"\e034"\fR.
733
.SS Arrays
734
.PP
735
Arrays are subscripted with an expression between square brackets
736
.RB ( [ " and " ] ).
737
If the expression is an expression list
738
.RI ( expr ", " expr " ...)"
739
then the array subscript is a string consisting of the
740
concatenation of the (string) value of each expression,
741
separated by the value of the
742
.B SUBSEP
743
variable.
744
This facility is used to simulate multiply dimensioned
745
arrays. For example:
746
.PP
747
.RS
748
.ft B
749
i = "A";\^ j = "B";\^ k = "C"
750
.br
751
x[i, j, k] = "hello, world\en"
752
.ft R
753
.RE
754
.PP
755
assigns the string \fB"hello, world\en"\fR to the element of the array
756
.B x
757
which is indexed by the string \fB"A\e034B\e034C"\fR. All arrays in AWK
758
are associative, i.e. indexed by string values.
759
.PP
760
The special operator
761
.B in
762
may be used in an
763
.B if
764
or
765
.B while
766
statement to see if an array has an index consisting of a particular
767
value.
768
.PP
769
.RS
770
.ft B
771
.nf
772
if (val in array)
773
print array[val]
774
.fi
775
.ft
776
.RE
777
.PP
778
If the array has multiple subscripts, use
779
.BR "(i, j) in array" .
780
.PP
781
The
782
.B in
783
construct may also be used in a
784
.B for
785
loop to iterate over all the elements of an array.
786
.PP
787
An element may be deleted from an array using the
788
.B delete
789
statement.
790
The
791
.B delete
792
statement may also be used to delete the entire contents of an array,
793
just by specifying the array name without a subscript.
794
.SS Variable Typing And Conversion
795
.PP
796
Variables and fields
797
may be (floating point) numbers, or strings, or both. How the
798
value of a variable is interpreted depends upon its context. If used in
799
a numeric expression, it will be treated as a number, if used as a string
800
it will be treated as a string.
801
.PP
802
To force a variable to be treated as a number, add 0 to it; to force it
803
to be treated as a string, concatenate it with the null string.
804
.PP
805
When a string must be converted to a number, the conversion is accomplished
806
using
807
.IR atof (3).
808
A number is converted to a string by using the value of
809
.B CONVFMT
810
as a format string for
811
.IR sprintf (3),
812
with the numeric value of the variable as the argument.
813
However, even though all numbers in AWK are floating-point,
814
integral values are
815
.I always
816
converted as integers. Thus, given
817
.PP
818
.RS
819
.ft B
820
.nf
821
CONVFMT = "%2.2f"
822
a = 12
823
b = a ""
824
.fi
825
.ft R
826
.RE
827
.PP
828
the variable
829
.B b
830
has a string value of \fB"12"\fR and not \fB"12.00"\fR.
831
.PP
832
.I Gawk
833
performs comparisons as follows:
834
If two variables are numeric, they are compared numerically.
835
If one value is numeric and the other has a string value that is a
836
``numeric string,'' then comparisons are also done numerically.
837
Otherwise, the numeric value is converted to a string and a string
838
comparison is performed.
839
Two strings are compared, of course, as strings.
840
According to the \*(PX standard, even if two strings are
841
numeric strings, a numeric comparison is performed. However, this is
842
clearly incorrect, and
843
.I gawk
844
does not do this.
845
.PP
846
Note that string constants, such as \fB"57"\fP, are
847
.I not
848
numeric strings, they are string constants. The idea of ``numeric string''
849
only applies to fields,
850
.B getline
851
input,
852
.BR FILENAME ,
853
.B ARGV
854
elements,
855
.B ENVIRON
856
elements and the elements of an array created by
857
.B split()
858
that are numeric strings.
859
The basic idea is that
860
.IR "user input" ,
861
and only user input, that looks numeric,
862
should be treated that way.
863
.PP
864
Uninitialized variables have the numeric value 0 and the string value ""
865
(the null, or empty, string).
866
.SH PATTERNS AND ACTIONS
867
AWK is a line oriented language. The pattern comes first, and then the
868
action. Action statements are enclosed in
869
.B {
870
and
871
.BR } .
872
Either the pattern may be missing, or the action may be missing, but,
873
of course, not both. If the pattern is missing, the action will be
874
executed for every single record of input.
875
A missing action is equivalent to
876
.RS
877
.PP
878
.B "{ print }"
879
.RE
880
.PP
881
which prints the entire record.
882
.PP
883
Comments begin with the ``#'' character, and continue until the
884
end of the line.
885
Blank lines may be used to separate statements.
886
Normally, a statement ends with a newline, however, this is not the
887
case for lines ending in
888
a ``,'',
889
.BR { ,
890
.BR ? ,
891
.BR : ,
892
.BR && ,
893
or
894
.BR || .
895
Lines ending in
896
.B do
897
or
898
.B else
899
also have their statements automatically continued on the following line.
900
In other cases, a line can be continued by ending it with a ``\e'',
901
in which case the newline will be ignored.
902
.PP
903
Multiple statements may
904
be put on one line by separating them with a ``;''.
905
This applies to both the statements within the action part of a
906
pattern-action pair (the usual case),
907
and to the pattern-action statements themselves.
908
.SS Patterns
909
AWK patterns may be one of the following:
910
.PP
911
.RS
912
.nf
913
.B BEGIN
914
.B END
915
.BI / "regular expression" /
916
.I "relational expression"
917
.IB pattern " && " pattern
918
.IB pattern " || " pattern
919
.IB pattern " ? " pattern " : " pattern
920
.BI ( pattern )
921
.BI ! " pattern"
922
.IB pattern1 ", " pattern2
923
.fi
924
.RE
925
.PP
926
.B BEGIN
927
and
928
.B END
929
are two special kinds of patterns which are not tested against
930
the input.
931
The action parts of all
932
.B BEGIN
933
patterns are merged as if all the statements had
934
been written in a single
935
.B BEGIN
936
block. They are executed before any
937
of the input is read. Similarly, all the
938
.B END
939
blocks are merged,
940
and executed when all the input is exhausted (or when an
941
.B exit
942
statement is executed).
943
.B BEGIN
944
and
945
.B END
946
patterns cannot be combined with other patterns in pattern expressions.
947
.B BEGIN
948
and
949
.B END
950
patterns cannot have missing action parts.
951
.PP
952
For
953
.BI / "regular expression" /
954
patterns, the associated statement is executed for each input record that matches
955
the regular expression.
956
Regular expressions are the same as those in
957
.IR egrep (1),
958
and are summarized below.
959
.PP
960
A
961
.I "relational expression"
962
may use any of the operators defined below in the section on actions.
963
These generally test whether certain fields match certain regular expressions.
964
.PP
965
The
966
.BR && ,
967
.BR || ,
968
and
969
.B !
970
operators are logical AND, logical OR, and logical NOT, respectively, as in C.
971
They do short-circuit evaluation, also as in C, and are used for combining
972
more primitive pattern expressions. As in most languages, parentheses
973
may be used to change the order of evaluation.
974
.PP
975
The
976
.B ?\^:
977
operator is like the same operator in C. If the first pattern is true
978
then the pattern used for testing is the second pattern, otherwise it is
979
the third. Only one of the second and third patterns is evaluated.
980
.PP
981
The
982
.IB pattern1 ", " pattern2
983
form of an expression is called a
984
.IR "range pattern" .
985
It matches all input records starting with a record that matches
986
.IR pattern1 ,
987
and continuing until a record that matches
988
.IR pattern2 ,
989
inclusive. It does not combine with any other sort of pattern expression.
990
.SS Regular Expressions
991
Regular expressions are the extended kind found in
992
.IR egrep .
993
They are composed of characters as follows:
994
.TP \w'\fB[^\fIabc...\fB]\fR'u+2n
995
.I c
996
matches the non-metacharacter
997
.IR c .
998
.TP
999
.I \ec
1000
matches the literal character
1001
.IR c .
1002
.TP
1003
.B .
1004
matches any character
1005
.I including
1006
newline.
1007
.TP
1008
.B ^
1009
matches the beginning of a string.
1010
.TP
1011
.B $
1012
matches the end of a string.
1013
.TP
1014
.BI [ abc... ]
1015
character list, matches any of the characters
1016
.IR abc... .
1017
.TP
1018
.BI [^ abc... ]
1019
negated character list, matches any character except
1020
.I abc...
1021
and newline.
1022
.TP
1023
.IB r1 | r2
1024
alternation: matches either
1025
.I r1
1026
or
1027
.IR r2 .
1028
.TP
1029
.I r1r2
1030
concatenation: matches
1031
.IR r1 ,
1032
and then
1033
.IR r2 .
1034
.TP
1035
.IB r +
1036
matches one or more
1037
.IR r 's.
1038
.TP
1039
.IB r *
1040
matches zero or more
1041
.IR r 's.
1042
.TP
1043
.IB r ?
1044
matches zero or one
1045
.IR r 's.
1046
.TP
1047
.BI ( r )
1048
grouping: matches
1049
.IR r .
1050
.TP
1051
.PD 0
1052
.IB r { n }
1053
.TP
1054
.PD 0
1055
.IB r { n ,}
1056
.TP
1057
.PD
1058
.IB r { n , m }
1059
One or two numbers inside braces denote an
1060
.IR "interval expression" .
1061
If there is one number in the braces, the preceding regexp
1062
.I r
1063
is repeated
1064
.I n
1065
times. If there are two numbers separated by a comma,
1066
.I r
1067
is repeated
1068
.I n
1069
to
1070
.I m
1071
times.
1072
If there is one number followed by a comma, then
1073
.I r
1074
is repeated at least
1075
.I n
1076
times.
1077
.sp .5
1078
Interval expressions are only available if either
1079
.B \-\^\-posix
1080
or
1081
.B \-\^\-re\-interval
1082
is specified on the command line.
1083
.TP
1084
.B \ey
1085
matches the empty string at either the beginning or the
1086
end of a word.
1087
.TP
1088
.B \eB
1089
matches the empty string within a word.
1090
.TP
1091
.B \e<
1092
matches the empty string at the beginning of a word.
1093
.TP
1094
.B \e>
1095
matches the empty string at the end of a word.
1096
.TP
1097
.B \ew
1098
matches any word-constituent character (letter, digit, or underscore).
1099
.TP
1100
.B \eW
1101
matches any character that is not word-constituent.
1102
.TP
1103
.B \e`
1104
matches the empty string at the beginning of a buffer (string).
1105
.TP
1106
.B \e'
1107
matches the empty string at the end of a buffer.
1108
.PP
1109
The escape sequences that are valid in string constants (see below)
1110
are also legal in regular expressions.
1111
.PP
1112
.I "Character classes"
1113
are a new feature introduced in the POSIX standard.
1114
A character class is a special notation for describing
1115
lists of characters that have a specific attribute, but where the
1116
actual characters themselves can vary from country to country and/or
1117
from character set to character set. For example, the notion of what
1118
is an alphabetic character differs in the USA and in France.
1119
.PP
1120
A character class is only valid in a regexp
1121
.I inside
1122
the brackets of a character list. Character classes consist of
1123
.BR [: ,
1124
a keyword denoting the class, and
1125
.BR :] .
1126
Here are the character
1127
classes defined by the POSIX standard.
1128
.TP
1129
.B [:alnum:]
1130
Alphanumeric characters.
1131
.TP
1132
.B [:alpha:]
1133
Alphabetic characters.
1134
.TP
1135
.B [:blank:]
1136
Space or tab characters.
1137
.TP
1138
.B [:cntrl:]
1139
Control characters.
1140
.TP
1141
.B [:digit:]
1142
Numeric characters.
1143
.TP
1144
.B [:graph:]
1145
Characters that are both printable and visible.
1146
(A space is printable, but not visible, while an
1147
.B a
1148
is both.)
1149
.TP
1150
.B [:lower:]
1151
Lower-case alphabetic characters.
1152
.TP
1153
.B [:print:]
1154
Printable characters (characters that are not control characters.)
1155
.TP
1156
.B [:punct:]
1157
Punctuation characters (characters that are not letter, digits,
1158
control characters, or space characters).
1159
.TP
1160
.B [:space:]
1161
Space characters (such as space, tab, and formfeed, to name a few).
1162
.TP
1163
.B [:upper:]
1164
Upper-case alphabetic characters.
1165
.TP
1166
.B [:xdigit:]
1167
Characters that are hexadecimal digits.
1168
.PP
1169
For example, before the POSIX standard, to match alphanumeric
1170
characters, you would have had to write
1171
.BR /[A\-Za\-z0\-9]/ .
1172
If your character set had other alphabetic characters in it, this would not
1173
match them. With the POSIX character classes, you can write
1174
.BR /[[:alnum:]]/ ,
1175
and this will match
1176
.I all
1177
the alphabetic and numeric characters in your character set.
1178
.PP
1179
Two additional special sequences can appear in character lists.
1180
These apply to non-ASCII character sets, which can have single symbols
1181
(called
1182
.IR "collating elements" )
1183
that are represented with more than one
1184
character, as well as several characters that are equivalent for
1185
.IR collating ,
1186
or sorting, purposes. (E.g., in French, a plain ``e''
1187
and a grave-accented e\` are equivalent.)
1188
.TP
1189
Collating Symbols
1190
A collating symbols is a multi-character collating element enclosed in
1191
.B [.
1192
and
1193
.BR .] .
1194
For example, if
1195
.B ch
1196
is a collating element, then
1197
.B [[.ch.]]
1198
is a regexp that matches this collating element, while
1199
.B [ch]
1200
is a regexp that matches either
1201
.B c
1202
or
1203
.BR h .
1204
.TP
1205
Equivalence Classes
1206
An equivalence class is a list of equivalent characters enclosed in
1207
.B [=
1208
and
1209
.BR =] .
1210
Thus,
1211
.B [[=ee\`=]]
1212
is regexp that matches either
1213
.B e
1214
or
1215
.B e\` .
1216
.PP
1217
These features are very valuable in non-English speaking locales.
1218
The library functions that
1219
.I gawk
1220
uses for regular expression matching
1221
currently only recognize POSIX character classes; they do not recognize
1222
collating symbols or equivalence classes.
1223
.PP
1224
The
1225
.BR \ey ,
1226
.BR \eB ,
1227
.BR \e< ,
1228
.BR \e> ,
1229
.BR \ew ,
1230
.BR \eW ,
1231
.BR \e` ,
1232
and
1233
.B \e'
1234
operators are specific to
1235
.IR gawk ;
1236
they are extensions based on facilities in the GNU regexp libraries.
1237
.PP
1238
The various command line options
1239
control how
1240
.I gawk
1241
interprets characters in regexps.
1242
.TP
1243
No options
1244
In the default case,
1245
.I gawk
1246
provide all the facilities of
1247
POSIX regexps and the GNU regexp operators described above.
1248
However, interval expressions are not supported.
1249
.TP
1250
.B \-\^\-posix
1251
Only POSIX regexps are supported, the GNU operators are not special.
1252
(E.g.,
1253
.B \ew
1254
matches a literal
1255
.BR w ).
1256
Interval expressions are allowed.
1257
.TP
1258
.B \-\^\-traditional
1259
Traditional Unix
1260
.I awk
1261
regexps are matched. The GNU operators
1262
are not special, interval expressions are not available, and neither
1263
are the POSIX character classes
1264
.RB ( [[:alnum:]]
1265
and so on).
1266
Characters described by octal and hexadecimal escape sequences are
1267
treated literally, even if they represent regexp metacharacters.
1268
.TP
1269
.B \-\^\-re\-interval
1270
Allow interval expressions in regexps, even if
1271
.B \-\^\-traditional
1272
has been provided.
1273
.SS Actions
1274
Action statements are enclosed in braces,
1275
.B {
1276
and
1277
.BR } .
1278
Action statements consist of the usual assignment, conditional, and looping
1279
statements found in most languages. The operators, control statements,
1280
and input/output statements
1281
available are patterned after those in C.
1282
.SS Operators
1283
.PP
1284
The operators in AWK, in order of decreasing precedence, are
1285
.PP
1286
.TP "\w'\fB*= /= %= ^=\fR'u+1n"
1287
.BR ( \&... )
1288
Grouping
1289
.TP
1290
.B $
1291
Field reference.
1292
.TP
1293
.B "++ \-\^\-"
1294
Increment and decrement, both prefix and postfix.
1295
.TP
1296
.B ^
1297
Exponentiation (\fB**\fR may also be used, and \fB**=\fR for
1298
the assignment operator).
1299
.TP
1300
.B "+ \- !"
1301
Unary plus, unary minus, and logical negation.
1302
.TP
1303
.B "* / %"
1304
Multiplication, division, and modulus.
1305
.TP
1306
.B "+ \-"
1307
Addition and subtraction.
1308
.TP
1309
.I space
1310
String concatenation.
1311
.TP
1312
.PD 0
1313
.B "< >"
1314
.TP
1315
.PD 0
1316
.B "<= >="
1317
.TP
1318
.PD
1319
.B "!= =="
1320
The regular relational operators.
1321
.TP
1322
.B "~ !~"
1323
Regular expression match, negated match.
1324
.B NOTE:
1325
Do not use a constant regular expression
1326
.RB ( /foo/ )
1327
on the left-hand side of a
1328
.B ~
1329
or
1330
.BR !~ .
1331
Only use one on the right-hand side. The expression
1332
.BI "/foo/ ~ " exp
1333
has the same meaning as \fB(($0 ~ /foo/) ~ \fIexp\fB)\fR.
1334
This is usually
1335
.I not
1336
what was intended.
1337
.TP
1338
.B in
1339
Array membership.
1340
.TP
1341
.B &&
1342
Logical AND.
1343
.TP
1344
.B ||
1345
Logical OR.
1346
.TP
1347
.B ?:
1348
The C conditional expression. This has the form
1349
.IB expr1 " ? " expr2 " : " expr3\c
1350
\&. If
1351
.I expr1
1352
is true, the value of the expression is
1353
.IR expr2 ,
1354
otherwise it is
1355
.IR expr3 .
1356
Only one of
1357
.I expr2
1358
and
1359
.I expr3
1360
is evaluated.
1361
.TP
1362
.PD 0
1363
.B "= += \-="
1364
.TP
1365
.PD
1366
.B "*= /= %= ^="
1367
Assignment. Both absolute assignment
1368
.BI ( var " = " value )
1369
and operator-assignment (the other forms) are supported.
1370
.SS Control Statements
1371
.PP
1372
The control statements are
1373
as follows:
1374
.PP
1375
.RS
1376
.nf
1377
\fBif (\fIcondition\fB) \fIstatement\fR [ \fBelse\fI statement \fR]
1378
\fBwhile (\fIcondition\fB) \fIstatement \fR
1379
\fBdo \fIstatement \fBwhile (\fIcondition\fB)\fR
1380
\fBfor (\fIexpr1\fB; \fIexpr2\fB; \fIexpr3\fB) \fIstatement\fR
1381
\fBfor (\fIvar \fBin\fI array\fB) \fIstatement\fR
1382
\fBbreak\fR
1383
\fBcontinue\fR
1384
\fBdelete \fIarray\^\fB[\^\fIindex\^\fB]\fR
1385
\fBdelete \fIarray\^\fR
1386
\fBexit\fR [ \fIexpression\fR ]
1387
\fB{ \fIstatements \fB}
1388
.fi
1389
.RE
1390
.SS "I/O Statements"
1391
.PP
1392
The input/output statements are as follows:
1393
.PP
1394
.TP "\w'\fBprintf \fIfmt, expr-list\fR'u+1n"
1395
.BI close( file )
1396
Close file (or pipe, see below).
1397
.TP
1398
.B getline
1399
Set
1400
.B $0
1401
from next input record; set
1402
.BR NF ,
1403
.BR NR ,
1404
.BR FNR .
1405
.TP
1406
.BI "getline <" file
1407
Set
1408
.B $0
1409
from next record of
1410
.IR file ;
1411
set
1412
.BR NF .
1413
.TP
1414
.BI getline " var"
1415
Set
1416
.I var
1417
from next input record; set
1418
.BR NF ,
1419
.BR FNR .
1420
.TP
1421
.BI getline " var" " <" file
1422
Set
1423
.I var
1424
from next record of
1425
.IR file .
1426
.TP
1427
.B next
1428
Stop processing the current input record. The next input record
1429
is read and processing starts over with the first pattern in the
1430
AWK program. If the end of the input data is reached, the
1431
.B END
1432
block(s), if any, are executed.
1433
.TP
1434
.B "nextfile"
1435
Stop processing the current input file. The next input record read
1436
comes from the next input file.
1437
.B FILENAME
1438
and
1439
.B ARGIND
1440
are updated,
1441
.B FNR
1442
is reset to 1, and processing starts over with the first pattern in the
1443
AWK program. If the end of the input data is reached, the
1444
.B END
1445
block(s), if any, are executed.
1446
.B NOTE:
1447
Earlier versions of gawk used
1448
.BR "next file" ,
1449
as two words. While this usage is still recognized, it generates a
1450
warning message and will eventually be removed.
1451
.TP
1452
.B print
1453
Prints the current record.
1454
The output record is terminated with the value of the
1455
.B ORS
1456
variable.
1457
.TP
1458
.BI print " expr-list"
1459
Prints expressions.
1460
Each expression is separated by the value of the
1461
.B OFS
1462
variable.
1463
The output record is terminated with the value of the
1464
.B ORS
1465
variable.
1466
.TP
1467
.BI print " expr-list" " >" file
1468
Prints expressions on
1469
.IR file .
1470
Each expression is separated by the value of the
1471
.B OFS
1472
variable. The output record is terminated with the value of the
1473
.B ORS
1474
variable.
1475
.TP
1476
.BI printf " fmt, expr-list"
1477
Format and print.
1478
.TP
1479
.BI printf " fmt, expr-list" " >" file
1480
Format and print on
1481
.IR file .
1482
.TP
1483
.BI system( cmd-line )
1484
Execute the command
1485
.IR cmd-line ,
1486
and return the exit status.
1487
(This may not be available on non-\*(PX systems.)
1488
.TP
1489
\&\fBfflush(\fR[\fIfile\^\fR]\fB)\fR
1490
Flush any buffers associated with the open output file or pipe
1491
.IR file .
1492
If
1493
.I file
1494
is missing, then standard output is flushed.
1495
If
1496
.I file
1497
is the null string,
1498
then all open output files and pipes
1499
have their buffers flushed.
1500
.PP
1501
Other input/output redirections are also allowed. For
1502
.B print
1503
and
1504
.BR printf ,
1505
.BI >> file
1506
appends output to the
1507
.IR file ,
1508
while
1509
.BI | " command"
1510
writes on a pipe.
1511
In a similar fashion,
1512
.IB command " | getline"
1513
pipes into
1514
.BR getline .
1515
The
1516
.BR getline
1517
command will return 0 on end of file, and \-1 on an error.
1518
.SS The \fIprintf\fP\^ Statement
1519
.PP
1520
The AWK versions of the
1521
.B printf
1522
statement and
1523
.B sprintf()
1524
function
1525
(see below)
1526
accept the following conversion specification formats:
1527
.TP
1528
.B %c
1529
An \s-1ASCII\s+1 character.
1530
If the argument used for
1531
.B %c
1532
is numeric, it is treated as a character and printed.
1533
Otherwise, the argument is assumed to be a string, and the only first
1534
character of that string is printed.
1535
.TP
1536
.PD 0
1537
.B %d
1538
.TP
1539
.PD
1540
.B %i
1541
A decimal number (the integer part).
1542
.TP
1543
.PD 0
1544
.B %e
1545
.TP
1546
.PD
1547
.B %E
1548
A floating point number of the form
1549
.BR [\-]d.dddddde[+\^\-]dd .
1550
The
1551
.B %E
1552
format uses
1553
.B E
1554
instead of
1555
.BR e .
1556
.TP
1557
.B %f
1558
A floating point number of the form
1559
.BR [\-]ddd.dddddd .
1560
.TP
1561
.PD 0
1562
.B %g
1563
.TP
1564
.PD
1565
.B %G
1566
Use
1567
.B %e
1568
or
1569
.B %f
1570
conversion, whichever is shorter, with nonsignificant zeros suppressed.
1571
The
1572
.B %G
1573
format uses
1574
.B %E
1575
instead of
1576
.BR %e .
1577
.TP
1578
.B %o
1579
An unsigned octal number (again, an integer).
1580
.TP
1581
.B %s
1582
A character string.
1583
.TP
1584
.PD 0
1585
.B %x
1586
.TP
1587
.PD
1588
.B %X
1589
An unsigned hexadecimal number (an integer).
1590
.The
1591
.B %X
1592
format uses
1593
.B ABCDEF
1594
instead of
1595
.BR abcdef .
1596
.TP
1597
.B %%
1598
A single
1599
.B %
1600
character; no argument is converted.
1601
.PP
1602
There are optional, additional parameters that may lie between the
1603
.B %
1604
and the control letter:
1605
.TP
1606
.B \-
1607
The expression should be left-justified within its field.
1608
.TP
1609
.I space
1610
For numeric conversions, prefix positive values with a space, and
1611
negative values with a minus sign.
1612
.TP
1613
.B +
1614
The plus sign, used before the width modifier (see below),
1615
says to always supply a sign for numeric conversions, even if the data
1616
to be formatted is positive. The
1617
.B +
1618
overrides the space modifier.
1619
.TP
1620
.B #
1621
Use an ``alternate form'' for certain control letters.
1622
For
1623
.BR %o ,
1624
supply a leading zero.
1625
For
1626
.BR %x ,
1627
and
1628
.BR %X ,
1629
supply a leading
1630
.BR 0x
1631
or
1632
.BR 0X
1633
for
1634
a nonzero result.
1635
For
1636
.BR %e ,
1637
.BR %E ,
1638
and
1639
.BR %f ,
1640
the result will always contain a
1641
decimal point.
1642
For
1643
.BR %g ,
1644
and
1645
.BR %G ,
1646
trailing zeros are not removed from the result.
1647
.TP
1648
.B 0
1649
A leading
1650
.B 0
1651
(zero) acts as a flag, that indicates output should be
1652
padded with zeroes instead of spaces.
1653
This applies even to non-numeric output formats.
1654
This flag only has an effect when the field width is wider than the
1655
value to be printed.
1656
.TP
1657
.I width
1658
The field should be padded to this width. The field is normally padded
1659
with spaces. If the
1660
.B 0
1661
flag has been used, it is padded with zeroes.
1662
.TP
1663
.BI \&. prec
1664
A number that specifies the precision to use when printing.
1665
For the
1666
.BR %e ,
1667
.BR %E ,
1668
and
1669
.BR %f
1670
formats, this specifies the
1671
number of digits you want printed to the right of the decimal point.
1672
For the
1673
.BR %g ,
1674
and
1675
.B %G
1676
formats, it specifies the maximum number
1677
of significant digits. For the
1678
.BR %d ,
1679
.BR %o ,
1680
.BR %i ,
1681
.BR %u ,
1682
.BR %x ,
1683
and
1684
.B %X
1685
formats, it specifies the minimum number of
1686
digits to print. For a string, it specifies the maximum number of
1687
characters from the string that should be printed.
1688
.PP
1689
The dynamic
1690
.I width
1691
and
1692
.I prec
1693
capabilities of the \*(AN C
1694
.B printf()
1695
routines are supported.
1696
A
1697
.B *
1698
in place of either the
1699
.B width
1700
or
1701
.B prec
1702
specifications will cause their values to be taken from
1703
the argument list to
1704
.B printf
1705
or
1706
.BR sprintf() .
1707
.SS Special File Names
1708
.PP
1709
When doing I/O redirection from either
1710
.B print
1711
or
1712
.B printf
1713
into a file,
1714
or via
1715
.B getline
1716
from a file,
1717
.I gawk
1718
recognizes certain special filenames internally. These filenames
1719
allow access to open file descriptors inherited from
1720
.IR gawk 's
1721
parent process (usually the shell).
1722
Other special filenames provide access to information about the running
1723
.B gawk
1724
process.
1725
The filenames are:
1726
.TP \w'\fB/dev/stdout\fR'u+1n
1727
.B /dev/pid
1728
Reading this file returns the process ID of the current process,
1729
in decimal, terminated with a newline.
1730
.TP
1731
.B /dev/ppid
1732
Reading this file returns the parent process ID of the current process,
1733
in decimal, terminated with a newline.
1734
.TP
1735
.B /dev/pgrpid
1736
Reading this file returns the process group ID of the current process,
1737
in decimal, terminated with a newline.
1738
.TP
1739
.B /dev/user
1740
Reading this file returns a single record terminated with a newline.
1741
The fields are separated with spaces.
1742
.B $1
1743
is the value of the
1744
.IR getuid (2)
1745
system call,
1746
.B $2
1747
is the value of the
1748
.IR geteuid (2)
1749
system call,
1750
.B $3
1751
is the value of the
1752
.IR getgid (2)
1753
system call, and
1754
.B $4
1755
is the value of the
1756
.IR getegid (2)
1757
system call.
1758
If there are any additional fields, they are the group IDs returned by
1759
.IR getgroups (2).
1760
Multiple groups may not be supported on all systems.
1761
.TP
1762
.B /dev/stdin
1763
The standard input.
1764
.TP
1765
.B /dev/stdout
1766
The standard output.
1767
.TP
1768
.B /dev/stderr
1769
The standard error output.
1770
.TP
1771
.BI /dev/fd/\^ n
1772
The file associated with the open file descriptor
1773
.IR n .
1774
.PP
1775
These are particularly useful for error messages. For example:
1776
.PP
1777
.RS
1778
.ft B
1779
print "You blew it!" > "/dev/stderr"
1780
.ft R
1781
.RE
1782
.PP
1783
whereas you would otherwise have to use
1784
.PP
1785
.RS
1786
.ft B
1787
print "You blew it!" | "cat 1>&2"
1788
.ft R
1789
.RE
1790
.PP
1791
These file names may also be used on the command line to name data files.
1792
.SS Numeric Functions
1793
.PP
1794
AWK has the following pre-defined arithmetic functions:
1795
.PP
1796
.TP \w'\fBsrand(\fR[\fIexpr\^\fR]\fB)\fR'u+1n
1797
.BI atan2( y , " x" )
1798
returns the arctangent of
1799
.I y/x
1800
in radians.
1801
.TP
1802
.BI cos( expr )
1803
returns the cosine in radians.
1804
.TP
1805
.BI exp( expr )
1806
the exponential function.
1807
.TP
1808
.BI int( expr )
1809
truncates to integer.
1810
.TP
1811
.BI log( expr )
1812
the natural logarithm function.
1813
.TP
1814
.B rand()
1815
returns a random number between 0 and 1.
1816
.TP
1817
.BI sin( expr )
1818
returns the sine in radians.
1819
.TP
1820
.BI sqrt( expr )
1821
the square root function.
1822
.TP
1823
\&\fBsrand(\fR[\fIexpr\^\fR]\fB)\fR
1824
uses
1825
.I expr
1826
as a new seed for the random number generator. If no
1827
.I expr
1828
is provided, the time of day will be used.
1829
The return value is the previous seed for the random
1830
number generator.
1831
.SS String Functions
1832
.PP
1833
.I Gawk
1834
has the following pre-defined string functions:
1835
.PP
1836
.TP "\w'\fBsprintf(\^\fIfmt\fB\^, \fIexpr-list\^\fB)\fR'u+1n"
1837
\fBgensub(\fIr\fB, \fIs\fB, \fIh \fR[\fB, \fIt\fR]\fB)\fR
1838
search the target string
1839
.I t
1840
for matches of the regular expression
1841
.IR r .
1842
If
1843
.I h
1844
is a string beginning with
1845
.B g
1846
or
1847
.BR G ,
1848
then replace all matches of
1849
.I r
1850
with
1851
.IR s .
1852
Otherwise,
1853
.I h
1854
is a number indicating which match of
1855
.I r
1856
to replace.
1857
If no
1858
.I t
1859
is supplied,
1860
.B $0
1861
is used instead.
1862
Within the replacement text
1863
.IR s ,
1864
the sequence
1865
.BI \e n\fR,
1866
where
1867
.I n
1868
is a digit from 1 to 9, may be used to indicate just the text that
1869
matched the
1870
.IR n 'th
1871
parenthesized subexpression. The sequence
1872
.B \e0
1873
represents the entire matched text, as does the character
1874
.BR & .
1875
Unlike
1876
.B sub()
1877
and
1878
.BR gsub() ,
1879
the modified string is returned as the result of the function,
1880
and the original target string is
1881
.I not
1882
changed.
1883
.TP "\w'\fBsprintf(\^\fIfmt\fB\^, \fIexpr-list\^\fB)\fR'u+1n"
1884
\fBgsub(\fIr\fB, \fIs \fR[\fB, \fIt\fR]\fB)\fR
1885
for each substring matching the regular expression
1886
.I r
1887
in the string
1888
.IR t ,
1889
substitute the string
1890
.IR s ,
1891
and return the number of substitutions.
1892
If
1893
.I t
1894
is not supplied, use
1895
.BR $0 .
1896
An
1897
.B &
1898
in the replacement text is replaced with the text that was actually matched.
1899
Use
1900
.B \e&
1901
to get a literal
1902
.BR & .
1903
See
1904
.I "AWK Language Programming"
1905
for a fuller discussion of the rules for
1906
.BR &'s
1907
and backslashes in the replacement text of
1908
.BR sub() ,
1909
.BR gsub() ,
1910
and
1911
.BR gensub() .
1912
.TP
1913
.BI index( s , " t" )
1914
returns the index of the string
1915
.I t
1916
in the string
1917
.IR s ,
1918
or 0 if
1919
.I t
1920
is not present.
1921
.TP
1922
\fBlength(\fR[\fIs\fR]\fB)
1923
returns the length of the string
1924
.IR s ,
1925
or the length of
1926
.B $0
1927
if
1928
.I s
1929
is not supplied.
1930
.TP
1931
.BI match( s , " r" )
1932
returns the position in
1933
.I s
1934
where the regular expression
1935
.I r
1936
occurs, or 0 if
1937
.I r
1938
is not present, and sets the values of
1939
.B RSTART
1940
and
1941
.BR RLENGTH .
1942
.TP
1943
\fBsplit(\fIs\fB, \fIa \fR[\fB, \fIr\fR]\fB)\fR
1944
splits the string
1945
.I s
1946
into the array
1947
.I a
1948
on the regular expression
1949
.IR r ,
1950
and returns the number of fields. If
1951
.I r
1952
is omitted,
1953
.B FS
1954
is used instead.
1955
The array
1956
.I a
1957
is cleared first.
1958
Splitting behaves identically to field splitting, described above.
1959
.TP
1960
.BI sprintf( fmt , " expr-list" )
1961
prints
1962
.I expr-list
1963
according to
1964
.IR fmt ,
1965
and returns the resulting string.
1966
.TP
1967
\fBsub(\fIr\fB, \fIs \fR[\fB, \fIt\fR]\fB)\fR
1968
just like
1969
.BR gsub() ,
1970
but only the first matching substring is replaced.
1971
.TP
1972
\fBsubstr(\fIs\fB, \fIi \fR[\fB, \fIn\fR]\fB)\fR
1973
returns the at most
1974
.IR n -character
1975
substring of
1976
.I s
1977
starting at
1978
.IR i .
1979
If
1980
.I n
1981
is omitted, the rest of
1982
.I s
1983
is used.
1984
.TP
1985
.BI tolower( str )
1986
returns a copy of the string
1987
.IR str ,
1988
with all the upper-case characters in
1989
.I str
1990
translated to their corresponding lower-case counterparts.
1991
Non-alphabetic characters are left unchanged.
1992
.TP
1993
.BI toupper( str )
1994
returns a copy of the string
1995
.IR str ,
1996
with all the lower-case characters in
1997
.I str
1998
translated to their corresponding upper-case counterparts.
1999
Non-alphabetic characters are left unchanged.
2000
.SS Time Functions
2001
.PP
2002
Since one of the primary uses of AWK programs is processing log files
2003
that contain time stamp information,
2004
.I gawk
2005
provides the following two functions for obtaining time stamps and
2006
formatting them.
2007
.PP
2008
.TP "\w'\fBsystime()\fR'u+1n"
2009
.B systime()
2010
returns the current time of day as the number of seconds since the Epoch
2011
(Midnight UTC, January 1, 1970 on \*(PX systems).
2012
.TP
2013
\fBstrftime(\fR[\fIformat \fR[\fB, \fItimestamp\fR]]\fB)\fR
2014
formats
2015
.I timestamp
2016
according to the specification in
2017
.IR format.
2018
The
2019
.I timestamp
2020
should be of the same form as returned by
2021
.BR systime() .
2022
If
2023
.I timestamp
2024
is missing, the current time of day is used.
2025
If
2026
.I format
2027
is missing, a default format equivalent to the output of
2028
.IR date (1)
2029
will be used.
2030
See the specification for the
2031
.B strftime()
2032
function in \*(AN C for the format conversions that are
2033
guaranteed to be available.
2034
A public-domain version of
2035
.IR strftime (3)
2036
and a man page for it come with
2037
.IR gawk ;
2038
if that version was used to build
2039
.IR gawk ,
2040
then all of the conversions described in that man page are available to
2041
.IR gawk.
2042
.SS String Constants
2043
.PP
2044
String constants in AWK are sequences of characters enclosed
2045
between double quotes (\fB"\fR). Within strings, certain
2046
.I "escape sequences"
2047
are recognized, as in C. These are:
2048
.PP
2049
.TP \w'\fB\e\^\fIddd\fR'u+1n
2050
.B \e\e
2051
A literal backslash.
2052
.TP
2053
.B \ea
2054
The ``alert'' character; usually the \s-1ASCII\s+1 \s-1BEL\s+1 character.
2055
.TP
2056
.B \eb
2057
backspace.
2058
.TP
2059
.B \ef
2060
form-feed.
2061
.TP
2062
.B \en
2063
newline.
2064
.TP
2065
.B \er
2066
carriage return.
2067
.TP
2068
.B \et
2069
horizontal tab.
2070
.TP
2071
.B \ev
2072
vertical tab.
2073
.TP
2074
.BI \ex "\^hex digits"
2075
The character represented by the string of hexadecimal digits following
2076
the
2077
.BR \ex .
2078
As in \*(AN C, all following hexadecimal digits are considered part of
2079
the escape sequence.
2080
(This feature should tell us something about language design by committee.)
2081
E.g., \fB"\ex1B"\fR is the \s-1ASCII\s+1 \s-1ESC\s+1 (escape) character.
2082
.TP
2083
.BI \e ddd
2084
The character represented by the 1-, 2-, or 3-digit sequence of octal
2085
digits. E.g. \fB"\e033"\fR is the \s-1ASCII\s+1 \s-1ESC\s+1 (escape) character.
2086
.TP
2087
.BI \e c
2088
The literal character
2089
.IR c\^ .
2090
.PP
2091
The escape sequences may also be used inside constant regular expressions
2092
(e.g.,
2093
.B "/[\ \et\ef\en\er\ev]/"
2094
matches whitespace characters).
2095
.PP
2096
In compatibility mode, the characters represented by octal and
2097
hexadecimal escape sequences are treated literally when used in
2098
regexp constants. Thus,
2099
.B /a\e52b/
2100
is equivalent to
2101
.BR /a\e*b/ .
2102
.SH FUNCTIONS
2103
Functions in AWK are defined as follows:
2104
.PP
2105
.RS
2106
\fBfunction \fIname\fB(\fIparameter list\fB) { \fIstatements \fB}\fR
2107
.RE
2108
.PP
2109
Functions are executed when they are called from within expressions
2110
in either patterns or actions. Actual parameters supplied in the function
2111
call are used to instantiate the formal parameters declared in the function.
2112
Arrays are passed by reference, other variables are passed by value.
2113
.PP
2114
Since functions were not originally part of the AWK language, the provision
2115
for local variables is rather clumsy: They are declared as extra parameters
2116
in the parameter list. The convention is to separate local variables from
2117
real parameters by extra spaces in the parameter list. For example:
2118
.PP
2119
.RS
2120
.ft B
2121
.nf
2122
function f(p, q, a, b) # a & b are local
2123
{
2124
\&.....
2125
}
2126
2127
/abc/ { ... ; f(1, 2) ; ... }
2128
.fi
2129
.ft R
2130
.RE
2131
.PP
2132
The left parenthesis in a function call is required
2133
to immediately follow the function name,
2134
without any intervening white space.
2135
This is to avoid a syntactic ambiguity with the concatenation operator.
2136
This restriction does not apply to the built-in functions listed above.
2137
.PP
2138
Functions may call each other and may be recursive.
2139
Function parameters used as local variables are initialized
2140
to the null string and the number zero upon function invocation.
2141
.PP
2142
If
2143
.B \-\^\-lint
2144
has been provided,
2145
.I gawk
2146
will warn about calls to undefined functions at parse time,
2147
instead of at run time.
2148
Calling an undefined function at run time is a fatal error.
2149
.PP
2150
The word
2151
.B func
2152
may be used in place of
2153
.BR function .
2154
.SH EXAMPLES
2155
.nf
2156
Print and sort the login names of all users:
2157
2158
.ft B
2159
BEGIN { FS = ":" }
2160
{ print $1 | "sort" }
2161
2162
.ft R
2163
Count lines in a file:
2164
2165
.ft B
2166
{ nlines++ }
2167
END { print nlines }
2168
2169
.ft R
2170
Precede each line by its number in the file:
2171
2172
.ft B
2173
{ print FNR, $0 }
2174
2175
.ft R
2176
Concatenate and line number (a variation on a theme):
2177
2178
.ft B
2179
{ print NR, $0 }
2180
.ft R
2181
.fi
2182
.SH SEE ALSO
2183
.IR egrep (1),
2184
.IR getpid (2),
2185
.IR getppid (2),
2186
.IR getpgrp (2),
2187
.IR getuid (2),
2188
.IR geteuid (2),
2189
.IR getgid (2),
2190
.IR getegid (2),
2191
.IR getgroups (2)
2192
.PP
2193
.IR "The AWK Programming Language" ,
2194
Alfred V. Aho, Brian W. Kernighan, Peter J. Weinberger,
2195
Addison-Wesley, 1988. ISBN 0-201-07981-X.
2196
.PP
2197
.IR "AWK Language Programming" ,
2198
Edition 1.0, published by the Free Software Foundation, 1995.
2199
.SH POSIX COMPATIBILITY
2200
A primary goal for
2201
.I gawk
2202
is compatibility with the \*(PX standard, as well as with the
2203
latest version of \*(UX
2204
.IR awk .
2205
To this end,
2206
.I gawk
2207
incorporates the following user visible
2208
features which are not described in the AWK book,
2209
but are part of the Bell Labs version of
2210
.IR awk ,
2211
and are in the \*(PX standard.
2212
.PP
2213
The
2214
.B \-v
2215
option for assigning variables before program execution starts is new.
2216
The book indicates that command line variable assignment happens when
2217
.I awk
2218
would otherwise open the argument as a file, which is after the
2219
.B BEGIN
2220
block is executed. However, in earlier implementations, when such an
2221
assignment appeared before any file names, the assignment would happen
2222
.I before
2223
the
2224
.B BEGIN
2225
block was run. Applications came to depend on this ``feature.''
2226
When
2227
.I awk
2228
was changed to match its documentation, this option was added to
2229
accommodate applications that depended upon the old behavior.
2230
(This feature was agreed upon by both the AT&T and GNU developers.)
2231
.PP
2232
The
2233
.B \-W
2234
option for implementation specific features is from the \*(PX standard.
2235
.PP
2236
When processing arguments,
2237
.I gawk
2238
uses the special option ``\fB\-\^\-\fP'' to signal the end of
2239
arguments.
2240
In compatibility mode, it will warn about, but otherwise ignore,
2241
undefined options.
2242
In normal operation, such arguments are passed on to the AWK program for
2243
it to process.
2244
.PP
2245
The AWK book does not define the return value of
2246
.BR srand() .
2247
The \*(PX standard
2248
has it return the seed it was using, to allow keeping track
2249
of random number sequences. Therefore
2250
.B srand()
2251
in
2252
.I gawk
2253
also returns its current seed.
2254
.PP
2255
Other new features are:
2256
The use of multiple
2257
.B \-f
2258
options (from MKS
2259
.IR awk );
2260
the
2261
.B ENVIRON
2262
array; the
2263
.BR \ea ,
2264
and
2265
.BR \ev
2266
escape sequences (done originally in
2267
.I gawk
2268
and fed back into AT&T's); the
2269
.B tolower()
2270
and
2271
.B toupper()
2272
built-in functions (from AT&T); and the \*(AN C conversion specifications in
2273
.B printf
2274
(done first in AT&T's version).
2275
.SH GNU EXTENSIONS
2276
.I Gawk
2277
has a number of extensions to \*(PX
2278
.IR awk .
2279
They are described in this section. All the extensions described here
2280
can be disabled by
2281
invoking
2282
.I gawk
2283
with the
2284
.B \-\^\-traditional
2285
option.
2286
.PP
2287
The following features of
2288
.I gawk
2289
are not available in
2290
\*(PX
2291
.IR awk .
2292
.RS
2293
.TP \w'\(bu'u+1n
2294
\(bu
2295
The
2296
.B \ex
2297
escape sequence.
2298
(Disabled with
2299
.BR \-\^\-posix .)
2300
.TP \w'\(bu'u+1n
2301
\(bu
2302
The
2303
.B fflush()
2304
function.
2305
(Disabled with
2306
.BR \-\^\-posix .)
2307
.TP
2308
\(bu
2309
The
2310
.BR systime(),
2311
.BR strftime(),
2312
and
2313
.B gensub()
2314
functions.
2315
.TP
2316
\(bu
2317
The special file names available for I/O redirection are not recognized.
2318
.TP
2319
\(bu
2320
The
2321
.BR ARGIND ,
2322
.BR ERRNO ,
2323
and
2324
.B RT
2325
variables are not special.
2326
.TP
2327
\(bu
2328
The
2329
.B IGNORECASE
2330
variable and its side-effects are not available.
2331
.TP
2332
\(bu
2333
The
2334
.B FIELDWIDTHS
2335
variable and fixed-width field splitting.
2336
.TP
2337
\(bu
2338
The use of
2339
.B RS
2340
as a regular expression.
2341
.TP
2342
\(bu
2343
The ability to split out individual characters using the null string
2344
as the value of
2345
.BR FS ,
2346
and as the third argument to
2347
.BR split() .
2348
.TP
2349
\(bu
2350
No path search is performed for files named via the
2351
.B \-f
2352
option. Therefore the
2353
.B AWKPATH
2354
environment variable is not special.
2355
.TP
2356
\(bu
2357
The use of
2358
.B "nextfile"
2359
to abandon processing of the current input file.
2360
.TP
2361
\(bu
2362
The use of
2363
.BI delete " array"
2364
to delete the entire contents of an array.
2365
.RE
2366
.PP
2367
The AWK book does not define the return value of the
2368
.B close()
2369
function.
2370
.IR Gawk\^ 's
2371
.B close()
2372
returns the value from
2373
.IR fclose (3),
2374
or
2375
.IR pclose (3),
2376
when closing a file or pipe, respectively.
2377
.PP
2378
When
2379
.I gawk
2380
is invoked with the
2381
.B \-\^\-traditional
2382
option,
2383
if the
2384
.I fs
2385
argument to the
2386
.B \-F
2387
option is ``t'', then
2388
.B FS
2389
will be set to the tab character.
2390
Since this is a rather ugly special case, it is not the default behavior.
2391
This behavior also does not occur if
2392
.B \-\^\-posix
2393
has been specified.
2394
.ig
2395
.PP
2396
If
2397
.I gawk
2398
was compiled for debugging, it will
2399
accept the following additional options:
2400
.TP
2401
.PD 0
2402
.B \-Wparsedebug
2403
.TP
2404
.PD
2405
.B \-\^\-parsedebug
2406
Turn on
2407
.IR yacc (1)
2408
or
2409
.IR bison (1)
2410
debugging output during program parsing.
2411
This option should only be of interest to the
2412
.I gawk
2413
maintainers, and may not even be compiled into
2414
.IR gawk .
2415
..
2416
.SH HISTORICAL FEATURES
2417
There are two features of historical AWK implementations that
2418
.I gawk
2419
supports.
2420
First, it is possible to call the
2421
.B length()
2422
built-in function not only with no argument, but even without parentheses!
2423
Thus,
2424
.RS
2425
.PP
2426
.ft B
2427
a = length # Holy Algol 60, Batman!
2428
.ft R
2429
.RE
2430
.PP
2431
is the same as either of
2432
.RS
2433
.PP
2434
.ft B
2435
a = length()
2436
.br
2437
a = length($0)
2438
.ft R
2439
.RE
2440
.PP
2441
This feature is marked as ``deprecated'' in the \*(PX standard, and
2442
.I gawk
2443
will issue a warning about its use if
2444
.B \-\^\-lint
2445
is specified on the command line.
2446
.PP
2447
The other feature is the use of either the
2448
.B continue
2449
or the
2450
.B break
2451
statements outside the body of a
2452
.BR while ,
2453
.BR for ,
2454
or
2455
.B do
2456
loop. Traditional AWK implementations have treated such usage as
2457
equivalent to the
2458
.B next
2459
statement.
2460
.I Gawk
2461
will support this usage if
2462
.B \-\^\-traditional
2463
has been specified.
2464
.SH ENVIRONMENT VARIABLES
2465
If
2466
.B POSIXLY_CORRECT
2467
exists in the environment, then
2468
.I gawk
2469
behaves exactly as if
2470
.B \-\^\-posix
2471
had been specified on the command line.
2472
If
2473
.B \-\^\-lint
2474
has been specified,
2475
.I gawk
2476
will issue a warning message to this effect.
2477
.PP
2478
The
2479
.B AWKPATH
2480
environment variable can be used to provide a list of directories that
2481
.I gawk
2482
will search when looking for files named via the
2483
.B \-f
2484
and
2485
.B \-\^\-file
2486
options.
2487
.SH BUGS
2488
The
2489
.B \-F
2490
option is not necessary given the command line variable assignment feature;
2491
it remains only for backwards compatibility.
2492
.PP
2493
If your system actually has support for
2494
.B /dev/fd
2495
and the associated
2496
.BR /dev/stdin ,
2497
.BR /dev/stdout ,
2498
and
2499
.B /dev/stderr
2500
files, you may get different output from
2501
.I gawk
2502
than you would get on a system without those files. When
2503
.I gawk
2504
interprets these files internally, it synchronizes output to the standard
2505
output with output to
2506
.BR /dev/stdout ,
2507
while on a system with those files, the output is actually to different
2508
open files.
2509
Caveat Emptor.
2510
.PP
2511
Syntactically invalid single character programs tend to overflow
2512
the parse stack, generating a rather unhelpful message. Such programs
2513
are surprisingly difficult to diagnose in the completely general case,
2514
and the effort to do so really is not worth it.
2515
.PP
2516
The word ``GNU'' is incorrectly capitalized in at least one file
2517
in the source code.
2518
.SH VERSION INFORMATION
2519
This man page documents
2520
.IR gawk ,
2521
version 3.0.
2522
.SH AUTHORS
2523
The original version of \*(UX
2524
.I awk
2525
was designed and implemented by Alfred Aho,
2526
Peter Weinberger, and Brian Kernighan of AT&T Bell Labs. Brian Kernighan
2527
continues to maintain and enhance it.
2528
.PP
2529
Paul Rubin and Jay Fenlason,
2530
of the Free Software Foundation, wrote
2531
.IR gawk ,
2532
to be compatible with the original version of
2533
.I awk
2534
distributed in Seventh Edition \*(UX.
2535
John Woods contributed a number of bug fixes.
2536
David Trueman, with contributions
2537
from Arnold Robbins, made
2538
.I gawk
2539
compatible with the new version of \*(UX
2540
.IR awk .
2541
Arnold Robbins is the current maintainer.
2542
.PP
2543
The initial DOS port was done by Conrad Kwok and Scott Garfinkle.
2544
Scott Deifik is the current DOS maintainer. Pat Rankin did the
2545
port to VMS, and Michal Jaegermann did the port to the Atari ST.
2546
The port to OS/2 was done by Kai Uwe Rommel, with contributions and
2547
help from Darrel Hankerson. Fred Fish supplied support for the Amiga.
2548
.SH BUG REPORTS
2549
If you find a bug in
2550
.IR gawk ,
2551
please send electronic mail to
2552
.BR bug-gnu-utils@prep.ai.mit.edu ,
2553
.I with
2554
a carbon copy to
2555
.BR arnold@gnu.ai.mit.edu .
2556
Please include your operating system and its revision, the version of
2557
.IR gawk ,
2558
what C compiler you used to compile it, and a test program
2559
and data that are as small as possible for reproducing the problem.
2560
.PP
2561
Before sending a bug report, please do two things. First, verify that
2562
you have the latest version of
2563
.IR gawk .
2564
Many bugs (usually subtle ones) are fixed at each release, and if
2565
yours is out of date, the problem may already have been solved.
2566
Second, please read this man page and the reference manual carefully to
2567
be sure that what you think is a bug really is, instead of just a quirk
2568
in the language.
2569
.PP
2570
Whatever you do, do
2571
.B NOT
2572
post a bug report in
2573
.BR comp.lang.awk .
2574
While the
2575
.I gawk
2576
developers occasionally read this newsgroup, posting bug reports there
2577
is an unreliable way to report bugs. Instead, please use the electronic mail
2578
addresses given above.
2579
.SH ACKNOWLEDGEMENTS
2580
Brian Kernighan of Bell Labs
2581
provided valuable assistance during testing and debugging.
2582
We thank him.
Loggerhead is a web-based interface for Breezy
Version: 2.0.1