1GAWK(1)                        Utility Commands                        GAWK(1)
2
3
4

NAME

6       gawk - pattern scanning and processing language
7

SYNOPSIS

9       gawk [ POSIX or GNU style options ] -f program-file [ -- ] file ...
10       gawk [ POSIX or GNU style options ] [ -- ] program-text file ...
11
12       pgawk [ POSIX or GNU style options ] -f program-file [ -- ] file ...
13       pgawk [ POSIX or GNU style options ] [ -- ] program-text file ...
14

DESCRIPTION

16       Gawk  is  the  GNU Project's implementation of the AWK programming lan‐
17       guage.  It conforms to the definition of  the  language  in  the  POSIX
18       1003.1  Standard.   This version in turn is based on the description in
19       The AWK Programming Language, by Aho, Kernighan, and  Weinberger,  with
20       the additional features found in the System V Release 4 version of UNIX
21       awk.  Gawk also provides more recent Bell Laboratories awk  extensions,
22       and a number of GNU-specific extensions.
23
24       Pgawk  is  the profiling version of gawk.  It is identical in every way
25       to gawk, except that programs run more  slowly,  and  it  automatically
26       produces  an  execution profile in the file awkprof.out when done.  See
27       the --profile option, below.
28
29       The command line consists of options to gawk itself,  the  AWK  program
30       text  (if  not supplied via the -f or --file options), and values to be
31       made available in the ARGC and ARGV pre-defined AWK variables.
32

OPTION FORMAT

34       Gawk options may be either traditional POSIX  one  letter  options,  or
35       GNU-style  long  options.  POSIX options start with a single “-”, while
36       long options start with “--”.  Long options are provided for both  GNU-
37       specific features and for POSIX-mandated features.
38
39       Following  the  POSIX  standard, gawk-specific options are supplied via
40       arguments to the -W option.  Multiple -W options may be  supplied  Each
41       -W  option  has  a corresponding long option, as detailed below.  Argu‐
42       ments to long options are either joined with the option by an  =  sign,
43       with no intervening spaces, or they may be provided in the next command
44       line argument.  Long options may be abbreviated, as long as the  abbre‐
45       viation remains unique.
46

OPTIONS

48       Gawk accepts the following options, listed by frequency.
49
50       -F fs
51       --field-separator fs
52              Use fs for the input field separator (the value of the FS prede‐
53              fined variable).
54
55       -v var=val
56       --assign var=val
57              Assign the value val to the variable var,  before  execution  of
58              the  program  begins.  Such variable values are available to the
59              BEGIN block of an AWK program.
60
61       -f program-file
62       --file program-file
63              Read the AWK program source from the file program-file,  instead
64              of  from  the  first  command  line  argument.   Multiple -f (or
65              --file) options may be used.
66
67       -mf NNN
68       -mr NNN
69              Set various memory limits to the value NNN.  The f flag sets the
70              maximum number of fields, and the r flag sets the maximum record
71              size.  These two flags and the -m option  are  from  an  earlier
72              version  of  the Bell Laboratories research version of UNIX awk.
73              They are ignored by gawk, since gawk has no pre-defined  limits.
74              (Current  versions of the Bell Laboratories awk no longer accept
75              them.)
76
77       -O
78       --optimize
79              Enable optimizations upon the  internal  representation  of  the
80              program.  Currently, this includes just simple constant-folding.
81              The gawk maintainer hopes to add additional  optimizations  over
82              time.
83
84       -W compat
85       -W traditional
86       --compat
87       --traditional
88              Run  in compatibility mode.  In compatibility mode, gawk behaves
89              identically to UNIX awk; none of the GNU-specific extensions are
90              recognized.   The  use  of  --traditional  is preferred over the
91              other forms of this option.  See GNU EXTENSIONS, below, for more
92              information.
93
94       -W copyleft
95       -W copyright
96       --copyleft
97       --copyright
98              Print the short version of the GNU copyright information message
99              on the standard output and exit successfully.
100
101       -W dump-variables[=file]
102       --dump-variables[=file]
103              Print a sorted list of global variables, their types  and  final
104              values  to file.  If no file is provided, gawk uses a file named
105              awkvars.out in the current directory.
106              Having a list of all the global variables is a good way to  look
107              for  typographical  errors in your programs.  You would also use
108              this option if you have a large program with a lot of functions,
109              and  you want to be sure that your functions don't inadvertently
110              use global variables that you meant to be  local.   (This  is  a
111              particularly  easy  mistake  to  make with simple variable names
112              like i, j, and so on.)
113
114       -W exec file
115       --exec file
116              Similar to -f, however, this is option  is  the  last  one  pro‐
117              cessed.   This should be used with #!  scripts, particularly for
118              CGI applications, to avoid passing in options or source code (!)
119              on  the  command line from a URL.  This option disables command-
120              line variable assignments.
121
122       -W gen-po
123       --gen-po
124              Scan and parse the AWK program, and generate a  GNU  .po  format
125              file on standard output with entries for all localizable strings
126              in the program.  The program itself is not  executed.   See  the
127              GNU gettext distribution for more information on .po files.
128
129       -W help
130       -W usage
131       --help
132       --usage
133              Print a relatively short summary of the available options on the
134              standard output.  (Per the GNU Coding Standards,  these  options
135              cause an immediate, successful exit.)
136
137       -W lint[=value]
138       --lint[=value]
139              Provide warnings about constructs that are dubious or non-porta‐
140              ble to other AWK implementations.  With an optional argument  of
141              fatal,  lint warnings become fatal errors.  This may be drastic,
142              but its use will certainly encourage the development of  cleaner
143              AWK  programs.  With an optional argument of invalid, only warn‐
144              ings about things that are actually invalid are issued. (This is
145              not fully implemented yet.)
146
147       -W lint-old
148       --lint-old
149              Provide  warnings  about constructs that are not portable to the
150              original version of Unix awk.
151
152       -W non-decimal-data
153       --non-decimal-data
154              Recognize octal and hexadecimal values in input data.  Use  this
155              option with great caution!
156
157       -W posix
158       --posix
159              This  turns on compatibility mode, with the following additional
160              restrictions:
161
162              · \x escape sequences are not recognized.
163
164              · Only space and tab act as field separators when FS is set to a
165                single space, newline does not.
166
167              · You cannot continue lines after ?  and :.
168
169              · The synonym func for the keyword function is not recognized.
170
171              · The operators ** and **= cannot be used in place of ^ and ^=.
172
173              · The fflush() function is not available.
174
175       -W profile[=prof_file]
176       --profile[=prof_file]
177              Send  profiling  data to prof_file.  The default is awkprof.out.
178              When run with gawk, the profile is just a “pretty printed”  ver‐
179              sion  of the program.  When run with pgawk, the profile contains
180              execution counts of each statement in the program  in  the  left
181              margin and function call counts for each user-defined function.
182
183       -W re-interval
184       --re-interval
185              Enable  the  use  of  interval expressions in regular expression
186              matching (see Regular Expressions, below).  Interval expressions
187              were not traditionally available in the AWK language.  The POSIX
188              standard added them, to make awk and egrep consistent with  each
189              other.   However, their use is likely to break old AWK programs,
190              so gawk only provides them  if  they  are  requested  with  this
191              option, or when --posix is specified.
192
193       -W source program-text
194       --source program-text
195              Use program-text as AWK program source code.  This option allows
196              the easy intermixing of library functions (used via the  -f  and
197              --file  options)  with  source code entered on the command line.
198              It is intended primarily for medium to large AWK  programs  used
199              in shell scripts.
200
201       -W use-lc-numeric
202       --use-lc-numeric
203              This  forces  gawk  to  use the locale's decimal point character
204              when parsing input data.  Although the POSIX  standard  requires
205              this  behavior,  and gawk does so when --posix is in effect, the
206              default is to follow traditional behavior and use  a  period  as
207              the  decimal  point, even in locales where the period is not the
208              decimal point character.   This  option  overrides  the  default
209              behavior,  without  the full draconian strictness of the --posix
210              option.
211
212       -W version
213       --version
214              Print version information for this particular copy  of  gawk  on
215              the  standard  output.  This is useful mainly for knowing if the
216              current copy of gawk on your system is up to date  with  respect
217              to  whatever the Free Software Foundation is distributing.  This
218              is also useful when reporting bugs.  (Per the GNU  Coding  Stan‐
219              dards, these options cause an immediate, successful exit.)
220
221       --     Signal the end of options. This is useful to allow further argu‐
222              ments to the AWK program itself to start with a “-”.  This  pro‐
223              vides  consistency  with the argument parsing convention used by
224              most other POSIX programs.
225
226       In compatibility mode, any other options are flagged  as  invalid,  but
227       are  otherwise  ignored.   In normal operation, as long as program text
228       has been supplied, unknown options are passed on to the AWK program  in
229       the ARGV array for processing.  This is particularly useful for running
230       AWK programs via the “#!” executable interpreter mechanism.
231

AWK PROGRAM EXECUTION

233       An AWK program consists of a sequence of pattern-action statements  and
234       optional function definitions.
235
236              pattern   { action statements }
237              function name(parameter list) { statements }
238
239       Gawk  first reads the program source from the program-file(s) if speci‐
240       fied, from arguments to --source, or from the first non-option argument
241       on  the command line.  The -f and --source options may be used multiple
242       times on the command line.  Gawk reads the program text as if  all  the
243       program-files  and  command  line  source  texts  had been concatenated
244       together.  This is useful for  building  libraries  of  AWK  functions,
245       without  having to include them in each new AWK program that uses them.
246       It also provides the ability to mix library functions with command line
247       programs.
248
249       The  environment  variable  AWKPATH specifies a search path to use when
250       finding source files named with the -f option.  If this  variable  does
251       not  exist,  the default path is ".:/usr/local/share/awk".  (The actual
252       directory may vary, depending upon how gawk was built  and  installed.)
253       If a file name given to the -f option contains a “/” character, no path
254       search is performed.
255
256       Gawk executes AWK programs in the following order.  First, all variable
257       assignments specified via the -v option are performed.  Next, gawk com‐
258       piles the program into an internal form.  Then, gawk executes the  code
259       in  the  BEGIN  block(s)  (if any), and then proceeds to read each file
260       named in the ARGV array.  If there are no files named  on  the  command
261       line, gawk reads the standard input.
262
263       If a filename on the command line has the form var=val it is treated as
264       a variable assignment.  The variable var will  be  assigned  the  value
265       val.   (This  happens after any BEGIN block(s) have been run.)  Command
266       line variable assignment is most useful for dynamically assigning  val‐
267       ues  to  the  variables  AWK  uses  to control how input is broken into
268       fields and records.  It is also useful for controlling state if  multi‐
269       ple passes are needed over a single data file.
270
271       If  the value of a particular element of ARGV is empty (""), gawk skips
272       over it.
273
274       For each record in the input, gawk tests to see if it matches any  pat‐
275       tern in the AWK program.  For each pattern that the record matches, the
276       associated action is executed.  The patterns are tested  in  the  order
277       they occur in the program.
278
279       Finally,  after  all  the input is exhausted, gawk executes the code in
280       the END block(s) (if any).
281

VARIABLES, RECORDS AND FIELDS

283       AWK variables are dynamic; they come into existence when they are first
284       used.   Their  values  are either floating-point numbers or strings, or
285       both, depending upon how they are used.  AWK also has  one  dimensional
286       arrays; arrays with multiple dimensions may be simulated.  Several pre-
287       defined variables are set as a program runs;  these  are  described  as
288       needed and summarized below.
289
290   Records
291       Normally, records are separated by newline characters.  You can control
292       how records are separated by assigning values to the built-in  variable
293       RS.   If  RS is any single character, that character separates records.
294       Otherwise, RS is a regular expression.  Text in the input that  matches
295       this  regular expression separates the record.  However, in compatibil‐
296       ity mode, only the first character of its string value is used for sep‐
297       arating  records.   If  RS  is set to the null string, then records are
298       separated by blank lines.  When RS is set to the null string, the  new‐
299       line  character  always acts as a field separator, in addition to what‐
300       ever value FS may have.
301
302   Fields
303       As each input record is read, gawk splits the record into fields, using
304       the value of the FS variable as the field separator.  If FS is a single
305       character, fields are separated by that character.  If FS is  the  null
306       string,  then each individual character becomes a separate field.  Oth‐
307       erwise, FS is expected to be a full regular expression.  In the special
308       case  that FS is a single space, fields are separated by runs of spaces
309       and/or tabs and/or newlines.  (But see the section POSIX COMPATIBILITY,
310       below).   NOTE:  The  value  of IGNORECASE (see below) also affects how
311       fields are split when FS is a regular expression, and how  records  are
312       separated when RS is a regular expression.
313
314       If  the  FIELDWIDTHS  variable is set to a space separated list of num‐
315       bers, each field is expected to have fixed width, and  gawk  splits  up
316       the  record  using  the  specified widths.  The value of FS is ignored.
317       Assigning a new value to FS  overrides  the  use  of  FIELDWIDTHS,  and
318       restores the default behavior.
319
320       Each  field  in the input record may be referenced by its position, $1,
321       $2, and so on.  $0 is the whole record.  Fields need not be  referenced
322       by constants:
323
324              n = 5
325              print $n
326
327       prints the fifth field in the input record.
328
329       The  variable  NF  is  set  to  the total number of fields in the input
330       record.
331
332       References to non-existent fields (i.e. fields after $NF)  produce  the
333       null-string.  However, assigning to a non-existent field (e.g., $(NF+2)
334       = 5) increases the value of NF, creates any intervening fields with the
335       null  string  as  their  value, and causes the value of $0 to be recom‐
336       puted, with the fields being separated by the value of OFS.  References
337       to  negative  numbered  fields  cause  a  fatal error.  Decrementing NF
338       causes the values of fields past the new value  to  be  lost,  and  the
339       value  of  $0  to be recomputed, with the fields being separated by the
340       value of OFS.
341
342       Assigning a value to an existing field causes the whole  record  to  be
343       rebuilt  when  $0  is  referenced.   Similarly, assigning a value to $0
344       causes the record to be resplit, creating new values for the fields.
345
346   Built-in Variables
347       Gawk's built-in variables are:
348
349       ARGC        The number of command  line  arguments  (does  not  include
350                   options to gawk, or the program source).
351
352       ARGIND      The index in ARGV of the current file being processed.
353
354       ARGV        Array of command line arguments.  The array is indexed from
355                   0 to ARGC - 1.  Dynamically changing the contents  of  ARGV
356                   can control the files used for data.
357
358       BINMODE     On  non-POSIX  systems,  specifies use of “binary” mode for
359                   all file I/O.  Numeric values of 1, 2, or 3,  specify  that
360                   input  files,  output  files,  or  all files, respectively,
361                   should use binary I/O.  String values of "r", or "w"  spec‐
362                   ify that input files, or output files, respectively, should
363                   use binary I/O.  String values of "rw" or "wr" specify that
364                   all files should use binary I/O.  Any other string value is
365                   treated as "rw", but generates a warning message.
366
367       CONVFMT     The conversion format for numbers, "%.6g", by default.
368
369       ENVIRON     An array containing the values of the current  environment.
370                   The  array  is  indexed  by the environment variables, each
371                   element being the  value  of  that  variable  (e.g.,  ENVI‐
372                   RON["HOME"]  might  be  /home/arnold).  Changing this array
373                   does not affect the environment seen by programs which gawk
374                   spawns via redirection or the system() function.
375
376       ERRNO       If  a  system  error  occurs either doing a redirection for
377                   getline, during a read for getline, or  during  a  close(),
378                   then ERRNO will contain a string describing the error.  The
379                   value is subject to translation in non-English locales.
380
381       FIELDWIDTHS A white-space separated list  of  fieldwidths.   When  set,
382                   gawk  parses  the input into fields of fixed width, instead
383                   of using the value of the FS variable as the field  separa‐
384                   tor.
385
386       FILENAME    The name of the current input file.  If no files are speci‐
387                   fied on the command line, the value  of  FILENAME  is  “-”.
388                   However,  FILENAME  is  undefined  inside  the  BEGIN block
389                   (unless set by getline).
390
391       FNR         The input record number in the current input file.
392
393       FS          The input field separator, a space by default.  See Fields,
394                   above.
395
396       IGNORECASE  Controls the case-sensitivity of all regular expression and
397                   string operations.  If IGNORECASE  has  a  non-zero  value,
398                   then  string  comparisons  and  pattern  matching in rules,
399                   field splitting with FS, record separating with RS, regular
400                   expression  matching  with  ~  and  !~,  and  the gensub(),
401                   gsub(), index(), match(), split(), and sub() built-in func‐
402                   tions  all ignore case when doing regular expression opera‐
403                   tions.  NOTE: Array subscripting is not affected.  However,
404                   the asort() and asorti() functions are affected.
405                   Thus,  if IGNORECASE is not equal to zero, /aB/ matches all
406                   of the strings "ab", "aB", "Ab", and "AB".  As with all AWK
407                   variables,  the initial value of IGNORECASE is zero, so all
408                   regular expression and string operations are normally case-
409                   sensitive.  Under Unix, the full ISO 8859-1 Latin-1 charac‐
410                   ter set is used when ignoring case.  As of gawk 3.1.4,  the
411                   case  equivalencies  are fully locale-aware, based on the C
412                   <ctype.h> facilities such as isalpha(), and toupper().
413
414       LINT        Provides dynamic control of the --lint option  from  within
415                   an AWK program.  When true, gawk prints lint warnings. When
416                   false,  it  does  not.   When  assigned  the  string  value
417                   "fatal",  lint  warnings  become fatal errors, exactly like
418                   --lint=fatal.  Any other true value just prints warnings.
419
420       NF          The number of fields in the current input record.
421
422       NR          The total number of input records seen so far.
423
424       OFMT        The output format for numbers, "%.6g", by default.
425
426       OFS         The output field separator, a space by default.
427
428       ORS         The output record separator, by default a newline.
429
430       PROCINFO    The elements of this array provide  access  to  information
431                   about  the running AWK program.  On some systems, there may
432                   be elements in the array,  "group1"  through  "groupn"  for
433                   some  n,  which  is the number of supplementary groups that
434                   the process has.  Use the in operator  to  test  for  these
435                   elements.   The  following  elements  are  guaranteed to be
436                   available:
437
438                   PROCINFO["egid"]   the value of the getegid(2) system call.
439
440                   PROCINFO["euid"]   the value of the geteuid(2) system call.
441
442                   PROCINFO["FS"]     "FS" if field splitting with  FS  is  in
443                                      effect, or "FIELDWIDTHS" if field split‐
444                                      ting with FIELDWIDTHS is in effect.
445
446                   PROCINFO["gid"]    the value of the getgid(2) system call.
447
448                   PROCINFO["pgrpid"] the process  group  ID  of  the  current
449                                      process.
450
451                   PROCINFO["pid"]    the process ID of the current process.
452
453                   PROCINFO["ppid"]   the  parent  process  ID  of the current
454                                      process.
455
456                   PROCINFO["uid"]    the value of the getuid(2) system call.
457
458                   PROCINFO["version"]
459                                      The version of gawk.  This is  available
460                                      from version 3.1.4 and later.
461
462       RS          The input record separator, by default a newline.
463
464       RT          The record terminator.  Gawk sets RT to the input text that
465                   matched the character or regular  expression  specified  by
466                   RS.
467
468       RSTART      The  index  of the first character matched by match(); 0 if
469                   no match.  (This implies that character  indices  start  at
470                   one.)
471
472       RLENGTH     The  length  of  the  string  matched  by match(); -1 if no
473                   match.
474
475       SUBSEP      The character used to separate multiple subscripts in array
476                   elements, by default "\034".
477
478       TEXTDOMAIN  The text domain of the AWK program; used to find the local‐
479                   ized translations for the program's strings.
480
481   Arrays
482       Arrays are subscripted with an expression between  square  brackets  ([
483       and ]).  If the expression is an expression list (expr, expr ...)  then
484       the array subscript is a string consisting of the concatenation of  the
485       (string) value of each expression, separated by the value of the SUBSEP
486       variable.  This facility  is  used  to  simulate  multiply  dimensioned
487       arrays.  For example:
488
489              i = "A"; j = "B"; k = "C"
490              x[i, j, k] = "hello, world\n"
491
492       assigns the string "hello, world\n" to the element of the array x which
493       is indexed by the string "A\034B\034C".  All arrays in AWK are associa‐
494       tive, i.e. indexed by string values.
495
496       The  special  operator  in may be used to test if an array has an index
497       consisting of a particular value.
498
499              if (val in array)
500                   print array[val]
501
502       If the array has multiple subscripts, use (i, j) in array.
503
504       The in construct may also be used in a for loop to iterate over all the
505       elements of an array.
506
507       An  element  may  be  deleted from an array using the delete statement.
508       The delete statement may also be used to delete the entire contents  of
509       an array, just by specifying the array name without a subscript.
510
511   Variable Typing And Conversion
512       Variables  and  fields  may be (floating point) numbers, or strings, or
513       both.  How the value of a variable is interpreted depends upon its con‐
514       text.  If used in a numeric expression, it will be treated as a number;
515       if used as a string it will be treated as a string.
516
517       To force a variable to be treated as a number, add 0 to it; to force it
518       to be treated as a string, concatenate it with the null string.
519
520       When  a  string must be converted to a number, the conversion is accom‐
521       plished using strtod(3).  A number is converted to a  string  by  using
522       the  value  of  CONVFMT  as  a  format  string for sprintf(3), with the
523       numeric value of the variable as the argument.   However,  even  though
524       all  numbers in AWK are floating-point, integral values are always con‐
525       verted as integers.  Thus, given
526
527              CONVFMT = "%2.2f"
528              a = 12
529              b = a ""
530
531       the variable b has a string value of "12" and not "12.00".
532
533       When operating in POSIX mode (such as with  the  --posix  command  line
534       option), beware that locale settings may interfere with the way decimal
535       numbers are treated: the decimal separator of the numbers you are feed‐
536       ing  to  gawk  must  conform  to what your locale would expect, be it a
537       comma (,) or a period (.).
538
539       Gawk performs comparisons as follows: If  two  variables  are  numeric,
540       they  are  compared numerically.  If one value is numeric and the other
541       has a string value that is a “numeric  string,”  then  comparisons  are
542       also  done numerically.  Otherwise, the numeric value is converted to a
543       string and a string comparison is performed.  Two strings are compared,
544       of course, as strings.
545
546       Note that string constants, such as "57", are not numeric strings, they
547       are string constants.  The idea of “numeric  string”  only  applies  to
548       fields,  getline  input,  FILENAME, ARGV elements, ENVIRON elements and
549       the elements of an array created by split() that are  numeric  strings.
550       The  basic  idea  is  that  user input, and only user input, that looks
551       numeric, should be treated that way.
552
553       Uninitialized variables have the numeric value 0 and the  string  value
554       "" (the null, or empty, string).
555
556   Octal and Hexadecimal Constants
557       Starting with version 3.1 of gawk , you may use C-style octal and hexa‐
558       decimal constants in your AWK program source code.   For  example,  the
559       octal  value  011 is equal to decimal 9, and the hexadecimal value 0x11
560       is equal to decimal 17.
561
562   String Constants
563       String constants in AWK are sequences of  characters  enclosed  between
564       double quotes (").  Within strings, certain escape sequences are recog‐
565       nized, as in C.  These are:
566
567       \\   A literal backslash.
568
569       \a   The “alert” character; usually the ASCII BEL character.
570
571       \b   backspace.
572
573       \f   form-feed.
574
575       \n   newline.
576
577       \r   carriage return.
578
579       \t   horizontal tab.
580
581       \v   vertical tab.
582
583       \xhex digits
584            The character represented by the string of hexadecimal digits fol‐
585            lowing the \x.  As in ANSI C, all following hexadecimal digits are
586            considered part of the escape sequence.  (This feature should tell
587            us something about language design by committee.)  E.g., "\x1B" is
588            the ASCII ESC (escape) character.
589
590       \ddd The character represented by the 1-, 2-, or  3-digit  sequence  of
591            octal digits.  E.g., "\033" is the ASCII ESC (escape) character.
592
593       \c   The literal character c.
594
595       The  escape  sequences may also be used inside constant regular expres‐
596       sions (e.g., /[ \t\f\n\r\v]/ matches whitespace characters).
597
598       In compatibility mode, the characters represented by octal and hexadec‐
599       imal  escape  sequences  are  treated  literally  when  used in regular
600       expression constants.  Thus, /a\52b/ is equivalent to /a\*b/.
601

PATTERNS AND ACTIONS

603       AWK is a line-oriented language.  The pattern comes first, and then the
604       action.  Action statements are enclosed in { and }.  Either the pattern
605       may be missing, or the action may be missing, but, of course, not both.
606       If  the  pattern  is  missing,  the action is executed for every single
607       record of input.  A missing action is equivalent to
608
609              { print }
610
611       which prints the entire record.
612
613       Comments begin with the “#” character, and continue until  the  end  of
614       the line.  Blank lines may be used to separate statements.  Normally, a
615       statement ends with a newline, however, this is not the case for  lines
616       ending  in  a “,”, {, ?, :, &&, or ||.  Lines ending in do or else also
617       have their statements automatically continued on  the  following  line.
618       In  other  cases,  a  line can be continued by ending it with a “\”, in
619       which case the newline will be ignored.
620
621       Multiple statements may be put on one line by separating  them  with  a
622       “;”.   This  applies to both the statements within the action part of a
623       pattern-action pair (the usual case), and to the pattern-action  state‐
624       ments themselves.
625
626   Patterns
627       AWK patterns may be one of the following:
628
629              BEGIN
630              END
631              /regular expression/
632              relational expression
633              pattern && pattern
634              pattern || pattern
635              pattern ? pattern : pattern
636              (pattern)
637              ! pattern
638              pattern1, pattern2
639
640       BEGIN  and  END  are two special kinds of patterns which are not tested
641       against the input.  The action parts of all BEGIN patterns  are  merged
642       as  if  all  the  statements  had been written in a single BEGIN block.
643       They are executed before any of the input is read.  Similarly, all  the
644       END blocks are merged, and executed when all the input is exhausted (or
645       when an exit statement is executed).  BEGIN and END patterns cannot  be
646       combined  with  other  patterns  in pattern expressions.  BEGIN and END
647       patterns cannot have missing action parts.
648
649       For /regular expression/ patterns, the associated statement is executed
650       for  each  input  record  that matches the regular expression.  Regular
651       expressions are the same as  those  in  egrep(1),  and  are  summarized
652       below.
653
654       A  relational  expression may use any of the operators defined below in
655       the section on actions.  These generally test  whether  certain  fields
656       match certain regular expressions.
657
658       The  &&,  ||, and !  operators are logical AND, logical OR, and logical
659       NOT, respectively, as in C.  They do short-circuit evaluation, also  as
660       in  C,  and  are used for combining more primitive pattern expressions.
661       As in most languages, parentheses may be used to change  the  order  of
662       evaluation.
663
664       The  ?:  operator is like the same operator in C.  If the first pattern
665       is true then the pattern used for testing is the second pattern, other‐
666       wise  it  is  the  third.  Only one of the second and third patterns is
667       evaluated.
668
669       The pattern1, pattern2 form of an expression is called a range pattern.
670       It  matches  all input records starting with a record that matches pat‐
671       tern1, and continuing until a record that matches pattern2,  inclusive.
672       It does not combine with any other sort of pattern expression.
673
674   Regular Expressions
675       Regular  expressions  are  the  extended kind found in egrep.  They are
676       composed of characters as follows:
677
678       c          matches the non-metacharacter c.
679
680       \c         matches the literal character c.
681
682       .          matches any character including newline.
683
684       ^          matches the beginning of a string.
685
686       $          matches the end of a string.
687
688       [abc...]   character list, matches any of the characters abc....
689
690       [^abc...]  negated character list, matches any character except abc....
691
692       r1|r2      alternation: matches either r1 or r2.
693
694       r1r2       concatenation: matches r1, and then r2.
695
696       r+         matches one or more r's.
697
698       r*         matches zero or more r's.
699
700       r?         matches zero or one r's.
701
702       (r)        grouping: matches r.
703
704       r{n}
705       r{n,}
706       r{n,m}     One or two numbers inside braces denote an interval  expres‐
707                  sion.   If  there is one number in the braces, the preceding
708                  regular expression r is repeated n times.  If there are  two
709                  numbers  separated  by  a comma, r is repeated n to m times.
710                  If there is one number  followed  by  a  comma,  then  r  is
711                  repeated at least n times.
712                  Interval expressions are only available if either --posix or
713                  --re-interval is specified on the command line.
714
715       \y         matches the empty string at either the beginning or the  end
716                  of a word.
717
718       \B         matches the empty string within a word.
719
720       \<         matches the empty string at the beginning of a word.
721
722       \>         matches the empty string at the end of a word.
723
724       \w         matches  any  word-constituent  character (letter, digit, or
725                  underscore).
726
727       \W         matches any character that is not word-constituent.
728
729       \`         matches the empty  string  at  the  beginning  of  a  buffer
730                  (string).
731
732       \'         matches the empty string at the end of a buffer.
733
734       The escape sequences that are valid in string constants (see below) are
735       also valid in regular expressions.
736
737       Character classes are a feature introduced in the  POSIX  standard.   A
738       character  class  is a special notation for describing lists of charac‐
739       ters that have a specific attribute, but where  the  actual  characters
740       themselves  can  vary from country to country and/or from character set
741       to character set.  For example, the notion of  what  is  an  alphabetic
742       character differs in the USA and in France.
743
744       A  character  class  is  only  valid in a regular expression inside the
745       brackets of a character list.  Character classes consist of [:, a  key‐
746       word  denoting the class, and :].  The character classes defined by the
747       POSIX standard are:
748
749       [:alnum:]  Alphanumeric characters.
750
751       [:alpha:]  Alphabetic characters.
752
753       [:blank:]  Space or tab characters.
754
755       [:cntrl:]  Control characters.
756
757       [:digit:]  Numeric characters.
758
759       [:graph:]  Characters that are both printable and visible.  (A space is
760                  printable, but not visible, while an a is both.)
761
762       [:lower:]  Lower-case alphabetic characters.
763
764       [:print:]  Printable  characters (characters that are not control char‐
765                  acters.)
766
767       [:punct:]  Punctuation characters (characters that are not letter, dig‐
768                  its, control characters, or space characters).
769
770       [:space:]  Space  characters (such as space, tab, and formfeed, to name
771                  a few).
772
773       [:upper:]  Upper-case alphabetic characters.
774
775       [:xdigit:] Characters that are hexadecimal digits.
776
777       For example, before the POSIX standard, to match  alphanumeric  charac‐
778       ters, you would have had to write /[A-Za-z0-9]/.  If your character set
779       had other alphabetic characters in it, this would not match  them,  and
780       if  your  character set collated differently from ASCII, this might not
781       even match the ASCII alphanumeric characters.  With the POSIX character
782       classes,  you  can write /[[:alnum:]]/, and this matches the alphabetic
783       and numeric characters in your character set, no matter what it is.
784
785       Two additional special sequences can appear in character lists.   These
786       apply  to  non-ASCII  character  sets,  which  can  have single symbols
787       (called collating elements) that are represented  with  more  than  one
788       character,  as  well as several characters that are equivalent for col‐
789       lating, or sorting, purposes.  (E.g., in French,  a  plain  “e”  and  a
790       grave-accented “e`” are equivalent.)
791
792       Collating Symbols
793              A  collating  symbol  is  a  multi-character  collating  element
794              enclosed in [.  and .].  For example, if ch is a collating  ele‐
795              ment,  then  [[.ch.]]  is a regular expression that matches this
796              collating element, while  [ch]  is  a  regular  expression  that
797              matches either c or h.
798
799       Equivalence Classes
800              An  equivalence  class  is  a locale-specific name for a list of
801              characters that are equivalent.  The name is enclosed in [=  and
802              =].   For  example, the name e might be used to represent all of
803              “e,” “e´,” and “e`.”  In this case, [[=e=]] is a  regular  expres‐
804              sion that matches any of e, e´, or e`.
805
806       These  features are very valuable in non-English speaking locales.  The
807       library functions that gawk uses for regular expression  matching  cur‐
808       rently  only  recognize  POSIX character classes; they do not recognize
809       collating symbols or equivalence classes.
810
811       The \y, \B, \<, \>, \w, \W, \`, and \' operators are specific to  gawk;
812       they  are  extensions based on facilities in the GNU regular expression
813       libraries.
814
815       The various command line options control how gawk interprets characters
816       in regular expressions.
817
818       No options
819              In  the  default  case, gawk provide all the facilities of POSIX
820              regular expressions and the  GNU  regular  expression  operators
821              described  above.   However,  interval  expressions are not sup‐
822              ported.
823
824       --posix
825              Only POSIX regular expressions are supported, the GNU  operators
826              are  not  special.   (E.g.,  \w  matches a literal w).  Interval
827              expressions are allowed. PLEASE NOTE that the regular expression
828              [A-Z]  will  also  match  the lowercase characters in this case!
829              Consult the info pages of  gawk  utility  for  more  information
830              about this behaviour.
831
832       --traditional
833              Traditional  Unix  awk regular expressions are matched.  The GNU
834              operators are not special, interval expressions are  not  avail‐
835              able,  and  neither are the POSIX character classes ([[:alnum:]]
836              and so on).   Characters  described  by  octal  and  hexadecimal
837              escape  sequences  are treated literally, even if they represent
838              regular expression metacharacters.
839
840       --re-interval
841              Allow interval  expressions  in  regular  expressions,  even  if
842              --traditional has been provided.
843
844   Actions
845       Action  statements  are enclosed in braces, { and }.  Action statements
846       consist of the usual assignment, conditional,  and  looping  statements
847       found  in  most  languages.   The  operators,  control  statements, and
848       input/output statements available are patterned after those in C.
849
850   Operators
851       The operators in AWK, in order of decreasing precedence, are
852
853       (...)       Grouping
854
855       $           Field reference.
856
857       ++ --       Increment and decrement, both prefix and postfix.
858
859       ^           Exponentiation (** may  also  be  used,  and  **=  for  the
860                   assignment operator).
861
862       + - !       Unary plus, unary minus, and logical negation.
863
864       * / %       Multiplication, division, and modulus.
865
866       + -         Addition and subtraction.
867
868       space       String concatenation.
869
870       | |&        Piped I/O for getline, print, and printf.
871
872       < >
873       <= >=
874       != ==       The regular relational operators.
875
876       ~ !~        Regular  expression match, negated match.  NOTE: Do not use
877                   a constant regular expression (/foo/) on the left-hand side
878                   of  a  ~  or !~.  Only use one on the right-hand side.  The
879                   expression /foo/ ~ exp has  the  same  meaning  as  (($0  ~
880                   /foo/) ~ exp).  This is usually not what was intended.
881
882       in          Array membership.
883
884       &&          Logical AND.
885
886       ||          Logical OR.
887
888       ?:          The  C  conditional  expression.  This has the form expr1 ?
889                   expr2 : expr3.  If expr1 is true, the value of the  expres‐
890                   sion  is  expr2,  otherwise it is expr3.  Only one of expr2
891                   and expr3 is evaluated.
892
893       = += -=
894       *= /= %= ^= Assignment.  Both absolute assignment  (var  =  value)  and
895                   operator-assignment (the other forms) are supported.
896
897   Control Statements
898       The control statements are as follows:
899
900              if (condition) statement [ else statement ]
901              while (condition) statement
902              do statement while (condition)
903              for (expr1; expr2; expr3) statement
904              for (var in array) statement
905              break
906              continue
907              delete array[index]
908              delete array
909              exit [ expression ]
910              { statements }
911
912   I/O Statements
913       The input/output statements are as follows:
914
915       close(file [, how])   Close file, pipe or co-process.  The optional how
916                             should only be used when closing  one  end  of  a
917                             two-way  pipe  to  a  co-process.   It  must be a
918                             string value, either "to" or "from".
919
920       getline               Set $0 from next input record; set NF, NR, FNR.
921
922       getline <file         Set $0 from next record of file; set NF.
923
924       getline var           Set var from next input record; set NR, FNR.
925
926       getline var <file     Set var from next record of file.
927
928       command | getline [var]
929                             Run command piping the output either into  $0  or
930                             var, as above.
931
932       command |& getline [var]
933                             Run  command  as  a  co-process piping the output
934                             either into $0 or var,  as  above.   Co-processes
935                             are  a  gawk  extension.   (command can also be a
936                             socket.  See the subsection Special  File  Names,
937                             below.)
938
939       next                  Stop  processing  the  current input record.  The
940                             next input record is read and  processing  starts
941                             over  with  the first pattern in the AWK program.
942                             If the end of the input data is reached, the  END
943                             block(s), if any, are executed.
944
945       nextfile              Stop processing the current input file.  The next
946                             input record read comes from the next input file.
947                             FILENAME  and ARGIND are updated, FNR is reset to
948                             1, and processing starts over with the first pat‐
949                             tern  in the AWK program. If the end of the input
950                             data is reached, the END block(s),  if  any,  are
951                             executed.
952
953       print                 Prints  the current record.  The output record is
954                             terminated with the value of the ORS variable.
955
956       print expr-list       Prints expressions.  Each expression is separated
957                             by  the  value  of  the OFS variable.  The output
958                             record is terminated with the value  of  the  ORS
959                             variable.
960
961       print expr-list >file Prints  expressions  on file.  Each expression is
962                             separated by the value of the OFS variable.   The
963                             output record is terminated with the value of the
964                             ORS variable.
965
966       printf fmt, expr-list Format and print.
967
968       printf fmt, expr-list >file
969                             Format and print on file.
970
971       system(cmd-line)      Execute the command cmd-line, and return the exit
972                             status.   (This may not be available on non-POSIX
973                             systems.)
974
975       fflush([file])        Flush any buffers associated with the open output
976                             file  or  pipe  file.   If  file is missing, then
977                             standard output is flushed.  If file is the  null
978                             string, then all open output files and pipes have
979                             their buffers flushed.
980
981       Additional output redirections are allowed for print and printf.
982
983       print ... >> file
984              Appends output to the file.
985
986       print ... | command
987              Writes on a pipe.
988
989       print ... |& command
990              Sends data to a co-process or socket.  (See also the  subsection
991              Special File Names, below.)
992
993       The  getline  command returns 1 on success, 0 on end of file, and -1 on
994       an error.  Upon an error, ERRNO contains a string describing the  prob‐
995       lem.
996
997       NOTE:  If using a pipe, co-process, or socket to getline, or from print
998       or printf within a loop, you must use close() to create  new  instances
999       of  the  command  or  socket.   AWK does not automatically close pipes,
1000       sockets, or co-processes when they return EOF.
1001
1002   The printf Statement
1003       The AWK versions of the printf statement and  sprintf()  function  (see
1004       below) accept the following conversion specification formats:
1005
1006       %c      An ASCII character.  If the argument used for %c is numeric, it
1007               is treated as a character and printed.  Otherwise, the argument
1008               is assumed to be a string, and the only first character of that
1009               string is printed.
1010
1011       %d, %i  A decimal number (the integer part).
1012
1013       %e, %E  A floating point number of the form [-]d.dddddde[+-]dd.  The %E
1014               format uses E instead of e.
1015
1016       %f, %F  A floating point number of the form [-]ddd.dddddd.  If the sys‐
1017               tem library supports it, %F is available as well. This is  like
1018               %f,  but  uses  capital  letters for special “not a number” and
1019               “infinity” values. If %F is not available, gawk uses %f.
1020
1021       %g, %G  Use %e or %f conversion, whichever is shorter, with nonsignifi‐
1022               cant zeros suppressed.  The %G format uses %E instead of %e.
1023
1024       %o      An unsigned octal number (also an integer).
1025
1026       %u      An unsigned decimal number (again, an integer).
1027
1028       %s      A character string.
1029
1030       %x, %X  An  unsigned  hexadecimal  number  (an integer).  The %X format
1031               uses ABCDEF instead of abcdef.
1032
1033       %%      A single % character; no argument is converted.
1034
1035       NOTE: When using the integer format-control letters for values that are
1036       outside  the range of a C long integer, gawk switches to the %0f format
1037       specifier. If --lint is provided on the command line gawk  warns  about
1038       this.   Other  versions of awk may print invalid values or do something
1039       else entirely.
1040
1041       Optional, additional parameters may lie between the % and  the  control
1042       letter:
1043
1044       count$ Use the count'th argument at this point in the formatting.  This
1045              is called a positional specifier and is intended  primarily  for
1046              use  in translated versions of format strings, not in the origi‐
1047              nal text of an AWK program.  It is a gawk extension.
1048
1049       -      The expression should be left-justified within its field.
1050
1051       space  For numeric conversions, prefix positive values  with  a  space,
1052              and negative values with a minus sign.
1053
1054       +      The  plus sign, used before the width modifier (see below), says
1055              to always supply a sign for numeric  conversions,  even  if  the
1056              data  to  be  formatted  is positive.  The + overrides the space
1057              modifier.
1058
1059       #      Use an “alternate form” for certain control  letters.   For  %o,
1060              supply  a  leading zero.  For %x, and %X, supply a leading 0x or
1061              0X for a nonzero result.  For %e, %E,  %f  and  %F,  the  result
1062              always contains a decimal point.  For %g, and %G, trailing zeros
1063              are not removed from the result.
1064
1065       0      A leading 0 (zero) acts as a flag, that indicates output  should
1066              be  padded  with zeroes instead of spaces.  This applies even to
1067              non-numeric output formats.  This flag only has an  effect  when
1068              the field width is wider than the value to be printed.
1069
1070       width  The field should be padded to this width.  The field is normally
1071              padded with spaces.  If the 0 flag has been used, it  is  padded
1072              with zeroes.
1073
1074       .prec  A number that specifies the precision to use when printing.  For
1075              the %e, %E, %f and %F, formats, this  specifies  the  number  of
1076              digits  you want printed to the right of the decimal point.  For
1077              the %g, and %G formats, it specifies the maximum number of  sig‐
1078              nificant digits.  For the %d, %o, %i, %u, %x, and %X formats, it
1079              specifies the minimum number of digits to  print.   For  %s,  it
1080              specifies  the maximum number of characters from the string that
1081              should be printed.
1082
1083       The dynamic width and prec capabilities of the ANSI C printf() routines
1084       are supported.  A * in place of either the width or prec specifications
1085       causes their values to be taken from the argument  list  to  printf  or
1086       sprintf().   To use a positional specifier with a dynamic width or pre‐
1087       cision, supply the count$ after the * in the format string.  For  exam‐
1088       ple, "%3$*2$.*1$s".
1089
1090   Special File Names
1091       When  doing I/O redirection from either print or printf into a file, or
1092       via getline from a file,  gawk  recognizes  certain  special  filenames
1093       internally.   These  filenames  allow  access  to open file descriptors
1094       inherited from gawk's parent process (usually the shell).   These  file
1095       names  may  also  be  used on the command line to name data files.  The
1096       filenames are:
1097
1098       /dev/stdin  The standard input.
1099
1100       /dev/stdout The standard output.
1101
1102       /dev/stderr The standard error output.
1103
1104       /dev/fd/n   The file associated with the open file descriptor n.
1105
1106       These are particularly useful for error messages.  For example:
1107
1108              print "You blew it!" > "/dev/stderr"
1109
1110       whereas you would otherwise have to use
1111
1112              print "You blew it!" | "cat 1>&2"
1113
1114       The following special filenames may be  used  with  the  |&  co-process
1115       operator for creating TCP/IP network connections.
1116
1117       /inet/tcp/lport/rhost/rport  File  for  TCP/IP connection on local port
1118                                    lport to remote host rhost on remote  port
1119                                    rport.  Use a port of 0 to have the system
1120                                    pick a port.
1121
1122       /inet/udp/lport/rhost/rport  Similar, but use UDP/IP instead of TCP/IP.
1123
1124       /inet/raw/lport/rhost/rport  Reserved for future use.
1125
1126       Other special filenames provide access to information about the running
1127       gawk  process.   These  filenames  are  now obsolete.  Use the PROCINFO
1128       array to obtain the information they provide.  The filenames are:
1129
1130       /dev/pid    Reading this file returns the process  ID  of  the  current
1131                   process, in decimal, terminated with a newline.
1132
1133       /dev/ppid   Reading this file returns the parent process ID of the cur‐
1134                   rent process, in decimal, terminated with a newline.
1135
1136       /dev/pgrpid Reading this file returns the process group ID of the  cur‐
1137                   rent process, in decimal, terminated with a newline.
1138
1139       /dev/user   Reading this file returns a single record terminated with a
1140                   newline.  The fields are separated with spaces.  $1 is  the
1141                   value  of the getuid(2) system call, $2 is the value of the
1142                   geteuid(2) system call, $3 is the value  of  the  getgid(2)
1143                   system  call,  and $4 is the value of the getegid(2) system
1144                   call.  If there are any additional  fields,  they  are  the
1145                   group  IDs  returned  by getgroups(2).  Multiple groups may
1146                   not be supported on all systems.
1147
1148   Numeric Functions
1149       AWK has the following built-in arithmetic functions:
1150
1151       atan2(y, x)   Returns the arctangent of y/x in radians.
1152
1153       cos(expr)     Returns the cosine of expr, which is in radians.
1154
1155       exp(expr)     The exponential function.
1156
1157       int(expr)     Truncates to integer.
1158
1159       log(expr)     The natural logarithm function.
1160
1161       rand()        Returns a random number N, between 0 and 1, such that 0 ≤
1162                     N < 1.
1163
1164       sin(expr)     Returns the sine of expr, which is in radians.
1165
1166       sqrt(expr)    The square root function.
1167
1168       srand([expr]) Uses  expr as a new seed for the random number generator.
1169                     If no expr is provided, the time of  day  is  used.   The
1170                     return  value  is the previous seed for the random number
1171                     generator.
1172
1173   String Functions
1174       Gawk has the following built-in string functions:
1175
1176       asort(s [, d])          Returns the number of elements  in  the  source
1177                               array  s.   The  contents of s are sorted using
1178                               gawk's normal rules for comparing  values,  and
1179                               the  indices  of  the  sorted  values  of s are
1180                               replaced with sequential integers starting with
1181                               1. If the optional destination array d is spec‐
1182                               ified, then s is first duplicated into  d,  and
1183                               then  d  is  sorted, leaving the indices of the
1184                               source array s unchanged.
1185
1186       asorti(s [, d])         Returns the number of elements  in  the  source
1187                               array  s.   The behavior is the same as that of
1188                               asort(), except that the array indices are used
1189                               for  sorting, not the array values.  When done,
1190                               the array is indexed numerically, and the  val‐
1191                               ues  are  those  of  the original indices.  The
1192                               original values are lost; thus provide a second
1193                               array if you wish to preserve the original.
1194
1195       gensub(r, s, h [, t])   Search  the  target string t for matches of the
1196                               regular expression r.  If h is a string  begin‐
1197                               ning with g or G, then replace all matches of r
1198                               with s.  Otherwise, h is  a  number  indicating
1199                               which  match of r to replace.  If t is not sup‐
1200                               plied, $0 is used instead.  Within the replace‐
1201                               ment  text  s,  the  sequence  \n, where n is a
1202                               digit from 1 to 9, may be used to indicate just
1203                               the  text  that  matched the n'th parenthesized
1204                               subexpression.  The sequence \0 represents  the
1205                               entire  matched  text, as does the character &.
1206                               Unlike sub() and gsub(), the modified string is
1207                               returned as the result of the function, and the
1208                               original target string is not changed.
1209
1210       gsub(r, s [, t])        For each substring matching the regular expres‐
1211                               sion  r  in the string t, substitute the string
1212                               s, and return the number of substitutions.   If
1213                               t  is  not  supplied,  use  $0.   An  &  in the
1214                               replacement text is replaced with the text that
1215                               was  actually matched.  Use \& to get a literal
1216                               &.  (This must be typed  as  "\\&";  see  GAWK:
1217                               Effective  AWK Programming for a fuller discus‐
1218                               sion of the rules for &'s  and  backslashes  in
1219                               the replacement text of sub(), gsub(), and gen‐
1220                               sub().)
1221
1222       index(s, t)             Returns the index of the string t in the string
1223                               s,  or  0  if  t is not present.  (This implies
1224                               that character indices start at one.)
1225
1226       length([s])             Returns the length of  the  string  s,  or  the
1227                               length  of  $0  if s is not supplied.  Starting
1228                               with version 3.1.5, as  a  non-standard  exten‐
1229                               sion,  with an array argument, length() returns
1230                               the number of elements in the array.
1231
1232       match(s, r [, a])       Returns the position in  s  where  the  regular
1233                               expression  r occurs, or 0 if r is not present,
1234                               and sets the  values  of  RSTART  and  RLENGTH.
1235                               Note that the argument order is the same as for
1236                               the ~ operator: str ~ re.  If array a  is  pro‐
1237                               vided, a is cleared and then elements 1 through
1238                               n are filled with the portions of s that  match
1239                               the  corresponding  parenthesized subexpression
1240                               in r.  The 0'th element of a contains the  por‐
1241                               tion of s matched by the entire regular expres‐
1242                               sion r.  Subscripts  a[n,  "start"],  and  a[n,
1243                               "length"]  provide  the  starting  index in the
1244                               string and length respectively, of each  match‐
1245                               ing substring.
1246
1247       split(s, a [, r])       Splits  the  string  s  into the array a on the
1248                               regular expression r, and returns the number of
1249                               fields.   If  r is omitted, FS is used instead.
1250                               The  array  a  is  cleared  first.    Splitting
1251                               behaves   identically   to   field   splitting,
1252                               described above.
1253
1254       sprintf(fmt, expr-list) Prints expr-list according to fmt, and  returns
1255                               the resulting string.
1256
1257       strtonum(str)           Examines  str,  and  returns its numeric value.
1258                               If str begins  with  a  leading  0,  strtonum()
1259                               assumes  that  str  is an octal number.  If str
1260                               begins with a  leading  0x  or  0X,  strtonum()
1261                               assumes that str is a hexadecimal number.
1262
1263       sub(r, s [, t])         Just  like  gsub(), but only the first matching
1264                               substring is replaced.
1265
1266       substr(s, i [, n])      Returns the at most n-character substring of  s
1267                               starting  at i.  If n is omitted, the rest of s
1268                               is used.
1269
1270       tolower(str)            Returns a copy of the string str, with all  the
1271                               upper-case  characters  in  str  translated  to
1272                               their  corresponding  lower-case  counterparts.
1273                               Non-alphabetic characters are left unchanged.
1274
1275       toupper(str)            Returns  a copy of the string str, with all the
1276                               lower-case  characters  in  str  translated  to
1277                               their  corresponding  upper-case  counterparts.
1278                               Non-alphabetic characters are left unchanged.
1279
1280       As of version 3.1.5, gawk is multibyte aware.  This means that index(),
1281       length(),  substr()  and  match()  all work in terms of characters, not
1282       bytes.
1283
1284   Time Functions
1285       Since one of the primary uses of AWK programs is processing  log  files
1286       that  contain time stamp information, gawk provides the following func‐
1287       tions for obtaining time stamps and formatting them.
1288
1289       mktime(datespec)
1290                 Turns datespec into a time stamp of the same form as returned
1291                 by  systime().   The datespec is a string of the form YYYY MM
1292                 DD HH MM SS[ DST].  The contents of the  string  are  six  or
1293                 seven numbers representing respectively the full year includ‐
1294                 ing century, the month from 1 to 12, the  day  of  the  month
1295                 from  1  to  31, the hour of the day from 0 to 23, the minute
1296                 from 0 to 59, and the second from 0 to 60,  and  an  optional
1297                 daylight  saving  flag.  The values of these numbers need not
1298                 be within the ranges specified; for example, an  hour  of  -1
1299                 means 1 hour before midnight.  The origin-zero Gregorian cal‐
1300                 endar is assumed, with year 0 preceding year 1  and  year  -1
1301                 preceding  year  0.   The  time is assumed to be in the local
1302                 timezone.  If the daylight saving flag is positive, the  time
1303                 is  assumed  to be daylight saving time; if zero, the time is
1304                 assumed to be standard time; and if negative  (the  default),
1305                 mktime()  attempts  to determine whether daylight saving time
1306                 is in effect for the specified time.  If  datespec  does  not
1307                 contain  enough  elements  or if the resulting time is out of
1308                 range, mktime() returns -1.
1309
1310       strftime([format [, timestamp[, utc-flag]]])
1311                 Formats timestamp according to the specification  in  format.
1312                 If  utc-flag  is  present  and  is  non-zero or non-null, the
1313                 result is in UTC, otherwise the result is in local time.  The
1314                 timestamp  should  be  of  the  same form as returned by sys‐
1315                 time().  If timestamp is missing, the current time of day  is
1316                 used.   If  format is missing, a default format equivalent to
1317                 the output of date(1) is used.  See the specification for the
1318                 strftime() function in ANSI C for the format conversions that
1319                 are guaranteed to be available.
1320
1321       systime() Returns the current time of day  as  the  number  of  seconds
1322                 since the Epoch (1970-01-01 00:00:00 UTC on POSIX systems).
1323
1324   Bit Manipulations Functions
1325       Starting with version 3.1 of gawk, the following bit manipulation func‐
1326       tions are available.  They work by converting double-precision floating
1327       point  values to uintmax_t integers, doing the operation, and then con‐
1328       verting the result back to floating point.  The functions are:
1329
1330       and(v1, v2)         Return the bitwise AND of the values provided by v1
1331                           and v2.
1332
1333       compl(val)          Return the bitwise complement of val.
1334
1335       lshift(val, count)  Return  the  value  of  val,  shifted left by count
1336                           bits.
1337
1338       or(v1, v2)          Return the bitwise OR of the values provided by  v1
1339                           and v2.
1340
1341       rshift(val, count)  Return  the  value  of  val, shifted right by count
1342                           bits.
1343
1344       xor(v1, v2)         Return the bitwise XOR of the values provided by v1
1345                           and v2.
1346
1347   Internationalization Functions
1348       Starting  with version 3.1 of gawk, the following functions may be used
1349       from within your AWK program for translating strings at run-time.   For
1350       full details, see GAWK: Effective AWK Programming.
1351
1352       bindtextdomain(directory [, domain])
1353              Specifies  the  directory where gawk looks for the .mo files, in
1354              case they will not or cannot be placed in the ``standard'' loca‐
1355              tions  (e.g.,  during  testing).  It returns the directory where
1356              domain is ``bound.''
1357              The default domain is the value of TEXTDOMAIN.  If directory  is
1358              the  null string (""), then bindtextdomain() returns the current
1359              binding for the given domain.
1360
1361       dcgettext(string [, domain [, category]])
1362              Returns the translation of string  in  text  domain  domain  for
1363              locale  category  category.  The default value for domain is the
1364              current value of TEXTDOMAIN.  The default value for category  is
1365              "LC_MESSAGES".
1366              If you supply a value for category, it must be a string equal to
1367              one of the known locale categories described in GAWK:  Effective
1368              AWK  Programming.   You  must  also  supply  a text domain.  Use
1369              TEXTDOMAIN if you want to use the current domain.
1370
1371       dcngettext(string1 , string2 , number [, domain [, category]])
1372              Returns the plural form used for number of  the  translation  of
1373              string1  and  string2  in text domain domain for locale category
1374              category.  The default value for domain is the current value  of
1375              TEXTDOMAIN.  The default value for category is "LC_MESSAGES".
1376              If you supply a value for category, it must be a string equal to
1377              one of the known locale categories described in GAWK:  Effective
1378              AWK  Programming.   You  must  also  supply  a text domain.  Use
1379              TEXTDOMAIN if you want to use the current domain.
1380

USER-DEFINED FUNCTIONS

1382       Functions in AWK are defined as follows:
1383
1384              function name(parameter list) { statements }
1385
1386       Functions are executed when they are called from within expressions  in
1387       either patterns or actions.  Actual parameters supplied in the function
1388       call are used to instantiate the  formal  parameters  declared  in  the
1389       function.   Arrays  are passed by reference, other variables are passed
1390       by value.
1391
1392       Since functions were not originally part of the AWK language, the  pro‐
1393       vision for local variables is rather clumsy: They are declared as extra
1394       parameters in the parameter list.  The convention is to separate  local
1395       variables  from  real parameters by extra spaces in the parameter list.
1396       For example:
1397
1398              function  f(p, q,     a, b)   # a and b are local
1399              {
1400                   ...
1401              }
1402
1403              /abc/     { ... ; f(1, 2) ; ... }
1404
1405       The left parenthesis in a function call is required to immediately fol‐
1406       low  the  function  name,  without  any  intervening white space.  This
1407       avoids a syntactic ambiguity with  the  concatenation  operator.   This
1408       restriction does not apply to the built-in functions listed above.
1409
1410       Functions  may  call each other and may be recursive.  Function parame‐
1411       ters used as local variables are initialized to the null string and the
1412       number zero upon function invocation.
1413
1414       Use return expr to return a value from a function.  The return value is
1415       undefined if no value is provided, or if the function returns by “fall‐
1416       ing off” the end.
1417
1418       If  --lint has been provided, gawk warns about calls to undefined func‐
1419       tions at parse time, instead of at  run  time.   Calling  an  undefined
1420       function at run time is a fatal error.
1421
1422       The word func may be used in place of function.
1423

DYNAMICALLY LOADING NEW FUNCTIONS

1425       Beginning  with version 3.1 of gawk, you can dynamically add new built-
1426       in functions to the running gawk interpreter.   The  full  details  are
1427       beyond  the scope of this manual page; see GAWK: Effective AWK Program‐
1428       ming for the details.
1429
1430       extension(object, function)
1431               Dynamically link the shared object file named  by  object,  and
1432               invoke  function  in  that  object,  to perform initialization.
1433               These should both be provided as strings.   Returns  the  value
1434               returned by function.
1435
1436       This  function  is  provided and documented in GAWK: Effective AWK Pro‐
1437       gramming, but everything about this feature is likely to change eventu‐
1438       ally.   We STRONGLY recommend that you do not use this feature for any‐
1439       thing that you aren't willing to redo.
1440

SIGNALS

1442       pgawk accepts two signals.  SIGUSR1 causes it to  dump  a  profile  and
1443       function  call  stack to the profile file, which is either awkprof.out,
1444       or whatever file was named with the --profile option.  It then  contin‐
1445       ues  to run.  SIGHUP causes pgawk to dump the profile and function call
1446       stack and then exit.
1447

EXAMPLES

1449       Print and sort the login names of all users:
1450
1451            BEGIN     { FS = ":" }
1452                 { print $1 | "sort" }
1453
1454       Count lines in a file:
1455
1456                 { nlines++ }
1457            END  { print nlines }
1458
1459       Precede each line by its number in the file:
1460
1461            { print FNR, $0 }
1462
1463       Concatenate and line number (a variation on a theme):
1464
1465            { print NR, $0 }
1466       Run an external command for particular lines of data:
1467
1468            tail -f access_log |
1469            awk '/myhome.html/ { system("nmap " $1 ">> logdir/myhome.html") }'
1470

INTERNATIONALIZATION

1472       String constants are sequences of characters enclosed in double quotes.
1473       In non-English speaking environments, it is possible to mark strings in
1474       the AWK program as requiring translation to  the  native  natural  lan‐
1475       guage. Such strings are marked in the AWK program with a leading under‐
1476       score (“_”).  For example,
1477
1478              gawk 'BEGIN { print "hello, world" }'
1479
1480       always prints hello, world.  But,
1481
1482              gawk 'BEGIN { print _"hello, world" }'
1483
1484       might print bonjour, monde in France.
1485
1486       There are several steps involved in producing and running a localizable
1487       AWK program.
1488
1489       1.  Add  a BEGIN action to assign a value to the TEXTDOMAIN variable to
1490           set the text domain to a name associated with your program.
1491
1492           BEGIN { TEXTDOMAIN = "myprog" }
1493
1494       This allows gawk to find the .mo file  associated  with  your  program.
1495       Without  this  step,  gawk  uses the messages text domain, which likely
1496       does not contain translations for your program.
1497
1498       2.  Mark all strings that should  be  translated  with  leading  under‐
1499           scores.
1500
1501       3.  If necessary, use the dcgettext() and/or bindtextdomain() functions
1502           in your program, as appropriate.
1503
1504       4.  Run gawk --gen-po -f myprog.awk > myprog.po to generate a .po  file
1505           for your program.
1506
1507       5.  Provide  appropriate translations, and build and install the corre‐
1508           sponding .mo files.
1509
1510       The internationalization features are described in full detail in GAWK:
1511       Effective AWK Programming.
1512

POSIX COMPATIBILITY

1514       A  primary  goal  for gawk is compatibility with the POSIX standard, as
1515       well as with the latest version of UNIX awk.  To this end, gawk  incor‐
1516       porates  the following user visible features which are not described in
1517       the AWK book, but are part of the Bell Laboratories version of awk, and
1518       are in the POSIX standard.
1519
1520       The  book  indicates that command line variable assignment happens when
1521       awk would otherwise open the argument as a file,  which  is  after  the
1522       BEGIN  block  is  executed.   However, in earlier implementations, when
1523       such an assignment appeared before any file names, the assignment would
1524       happen  before the BEGIN block was run.  Applications came to depend on
1525       this “feature.”  When awk was changed to match its  documentation,  the
1526       -v option for assigning variables before program execution was added to
1527       accommodate applications that depended upon the  old  behavior.   (This
1528       feature  was  agreed  upon  by  both  the Bell Laboratories and the GNU
1529       developers.)
1530
1531       The -W option for implementation specific features is  from  the  POSIX
1532       standard.
1533
1534       When  processing arguments, gawk uses the special option “--” to signal
1535       the end of arguments.  In compatibility mode, it warns about but other‐
1536       wise  ignores  undefined  options.  In normal operation, such arguments
1537       are passed on to the AWK program for it to process.
1538
1539       The AWK book does not define the return value of  srand().   The  POSIX
1540       standard has it return the seed it was using, to allow keeping track of
1541       random number sequences.  Therefore srand() in gawk  also  returns  its
1542       current seed.
1543
1544       Other  new features are: The use of multiple -f options (from MKS awk);
1545       the ENVIRON array; the \a, and \v escape sequences (done originally  in
1546       gawk  and  fed  back into the Bell Laboratories version); the tolower()
1547       and toupper() built-in functions (from the Bell Laboratories  version);
1548       and  the  ANSI C conversion specifications in printf (done first in the
1549       Bell Laboratories version).
1550

HISTORICAL FEATURES

1552       There are two features of historical AWK implementations that gawk sup‐
1553       ports.   First,  it  is possible to call the length() built-in function
1554       not only with no argument, but even without parentheses!  Thus,
1555
1556              a = length     # Holy Algol 60, Batman!
1557
1558       is the same as either of
1559
1560              a = length()
1561              a = length($0)
1562
1563       This feature is marked as “deprecated” in the POSIX standard, and  gawk
1564       issues  a  warning  about its use if --lint is specified on the command
1565       line.
1566
1567       The other feature is the use of either the continue or the break state‐
1568       ments  outside  the  body of a while, for, or do loop.  Traditional AWK
1569       implementations have treated such  usage  as  equivalent  to  the  next
1570       statement.   Gawk  supports this usage if --traditional has been speci‐
1571       fied.
1572

GNU EXTENSIONS

1574       Gawk has a number of extensions to POSIX awk.  They  are  described  in
1575       this  section.   All  the  extensions described here can be disabled by
1576       invoking gawk with the --traditional or --posix options.
1577
1578       The following features of gawk are not available in POSIX awk.
1579
1580       · No path search is performed  for  files  named  via  the  -f  option.
1581         Therefore the AWKPATH environment variable is not special.
1582
1583       · The \x escape sequence.  (Disabled with --posix.)
1584
1585       · The fflush() function.  (Disabled with --posix.)
1586
1587       · The  ability  to  continue  lines  after  ?   and  :.  (Disabled with
1588         --posix.)
1589
1590       · Octal and hexadecimal constants in AWK programs.
1591
1592       · The ARGIND, BINMODE, ERRNO, LINT, RT and TEXTDOMAIN variables are not
1593         special.
1594
1595       · The IGNORECASE variable and its side-effects are not available.
1596
1597       · The FIELDWIDTHS variable and fixed-width field splitting.
1598
1599       · The PROCINFO array is not available.
1600
1601       · The use of RS as a regular expression.
1602
1603       · The  special  file names available for I/O redirection are not recog‐
1604         nized.
1605
1606       · The |& operator for creating co-processes.
1607
1608       · The ability to split out individual characters using the null  string
1609         as the value of FS, and as the third argument to split().
1610
1611       · The optional second argument to the close() function.
1612
1613       · The optional third argument to the match() function.
1614
1615       · The ability to use positional specifiers with printf and sprintf().
1616
1617       · The ability to pass an array to length().
1618
1619       · The use of delete array to delete the entire contents of an array.
1620
1621       · The use of nextfile to abandon processing of the current input file.
1622
1623       · The and(), asort(), asorti(), bindtextdomain(), compl(), dcgettext(),
1624         dcngettext(), gensub(), lshift(),  mktime(),  or(),  rshift(),  strf‐
1625         time(), strtonum(), systime() and xor() functions.
1626
1627       · Localizable strings.
1628
1629       · Adding  new built-in functions dynamically with the extension() func‐
1630         tion.
1631
1632       The AWK book does not define the return value of the close()  function.
1633       Gawk's  close()  returns  the  value from fclose(3), or pclose(3), when
1634       closing an output file or pipe, respectively.  It returns the process's
1635       exit  status when closing an input pipe.  The return value is -1 if the
1636       named file, pipe or co-process was not opened with a redirection.
1637
1638       When gawk is invoked with the --traditional option, if the fs  argument
1639       to  the  -F  option  is “t”, then FS is set to the tab character.  Note
1640       that typing gawk -F\t ...  simply causes the shell to  quote  the  “t,”
1641       and  does  not pass “\t” to the -F option.  Since this is a rather ugly
1642       special case, it is not the default behavior.  This behavior also  does
1643       not occur if --posix has been specified.  To really get a tab character
1644       as the field separator, it is best to use single  quotes:  gawk  -F'\t'
1645       ....
1646
1647       If  gawk is configured with the --enable-switch option to the configure
1648       command, then it accepts an additional control-flow statement:
1649              switch (expression) {
1650              case value|regex : statement
1651              ...
1652              [ default: statement ]
1653              }
1654
1655       If gawk is configured with the --disable-directories-fatal option, then
1656       it  will  silently  skip directories named on the command line.  Other‐
1657       wise, it will do so only if invoked with the --traditional option.
1658

ENVIRONMENT VARIABLES

1660       The AWKPATH environment variable can be  used  to  provide  a  list  of
1661       directories  that gawk searches when looking for files named via the -f
1662       and --file options.
1663
1664       If POSIXLY_CORRECT exists in the environment, then gawk behaves exactly
1665       as  if  --posix  had been specified on the command line.  If --lint has
1666       been specified, gawk issues a warning message to this effect.
1667

SEE ALSO

1669       egrep(1), getpid(2),  getppid(2),  getpgrp(2),  getuid(2),  geteuid(2),
1670       getgid(2), getegid(2), getgroups(2)
1671
1672       The  AWK Programming Language, Alfred V. Aho, Brian W. Kernighan, Peter
1673       J. Weinberger, Addison-Wesley, 1988.  ISBN 0-201-07981-X.
1674
1675       GAWK: Effective AWK Programming, Edition 3.0,  published  by  the  Free
1676       Software  Foundation,  2001.   The  current version of this document is
1677       available online at http://www.gnu.org/software/gawk/manual.
1678

BUGS

1680       The -F option is not necessary given the command line variable  assign‐
1681       ment feature; it remains only for backwards compatibility.
1682
1683       Syntactically  invalid  single  character programs tend to overflow the
1684       parse stack, generating a rather unhelpful message.  Such programs  are
1685       surprisingly  difficult to diagnose in the completely general case, and
1686       the effort to do so really is not worth it.
1687

AUTHORS

1689       The original version of UNIX awk was designed and implemented by Alfred
1690       Aho, Peter Weinberger, and Brian Kernighan of Bell Laboratories.  Brian
1691       Kernighan continues to maintain and enhance it.
1692
1693       Paul Rubin and Jay Fenlason, of the  Free  Software  Foundation,  wrote
1694       gawk,  to be compatible with the original version of awk distributed in
1695       Seventh Edition UNIX.  John Woods contributed a number  of  bug  fixes.
1696       David  Trueman,  with contributions from Arnold Robbins, made gawk com‐
1697       patible with the new version of UNIX awk.  Arnold Robbins is  the  cur‐
1698       rent maintainer.
1699
1700       The  initial  DOS  port  was  done  by Conrad Kwok and Scott Garfinkle.
1701       Scott Deifik is the current DOS maintainer.  Pat Rankin did the port to
1702       VMS,  and  Michal Jaegermann did the port to the Atari ST.  The port to
1703       OS/2 was done by Kai Uwe Rommel, with contributions and help from  Dar‐
1704       rel Hankerson.  Andreas Buening now maintains the OS/2 port.  Fred Fish
1705       supplied support for the Amiga, and  Martin  Brown  provided  the  BeOS
1706       port.   Stephen  Davies  provided the original Tandem port, and Matthew
1707       Woehlke provided changes for Tandem's  POSIX-compliant  systems.   Ralf
1708       Wildenhues now maintains that port.
1709
1710       See  the  README  file in the gawk distribution for current information
1711       about maintainers and which ports are currently supported.
1712

VERSION INFORMATION

1714       This man page documents gawk, version 3.1.7.
1715

BUG REPORTS

1717       If you find a  bug  in  gawk,  please  send  electronic  mail  to  bug-
1718       gawk@gnu.org.   Please  include your operating system and its revision,
1719       the version of gawk (from gawk --version), what C compiler you used  to
1720       compile  it,  and a test program and data that are as small as possible
1721       for reproducing the problem.
1722
1723       Before sending a bug report, please do the  following  things.   First,
1724       verify  that  you  have the latest version of gawk.  Many bugs (usually
1725       subtle ones) are fixed at each release, and if yours is  out  of  date,
1726       the  problem  may already have been solved.  Second, please see if set‐
1727       ting the environment variable  LC_ALL  to  LC_ALL=C  causes  things  to
1728       behave  as  you  expect. If so, it's a locale issue, and may or may not
1729       really be a bug.  Finally, please read this man page and the  reference
1730       manual  carefully  to  be  sure that what you think is a bug really is,
1731       instead of just a quirk in the language.
1732
1733       Whatever you do, do NOT post a bug report in comp.lang.awk.  While  the
1734       gawk  developers  occasionally read this newsgroup, posting bug reports
1735       there is an unreliable way to report bugs.   Instead,  please  use  the
1736       electronic mail addresses given above.
1737
1738       If you're using a GNU/Linux system or BSD-based system, you may wish to
1739       submit a bug report to the vendor of your distribution.   That's  fine,
1740       but  please  send  a  copy to the official email address as well, since
1741       there's no guarantee that the bug will be forwarded to the  gawk  main‐
1742       tainer.
1743

ACKNOWLEDGEMENTS

1745       Brian  Kernighan of Bell Laboratories provided valuable assistance dur‐
1746       ing testing and debugging.  We thank him.
1747

COPYING PERMISSIONS

1749       Copyright © 1989, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
1750       2001, 2002, 2003, 2004, 2005, 2007, 2009 Free Software Foundation, Inc.
1751
1752       Permission  is  granted  to make and distribute verbatim copies of this
1753       manual page provided the copyright notice and  this  permission  notice
1754       are preserved on all copies.
1755
1756       Permission  is granted to copy and distribute modified versions of this
1757       manual page under the conditions for verbatim  copying,  provided  that
1758       the  entire  resulting derived work is distributed under the terms of a
1759       permission notice identical to this one.
1760
1761       Permission is granted to copy and distribute translations of this  man‐
1762       ual page into another language, under the above conditions for modified
1763       versions, except that this permission notice may be stated in a  trans‐
1764       lation approved by the Foundation.
1765
1766
1767
1768Free Software Foundation          Jul 10 2009                          GAWK(1)
Impressum