

\input texinfo


                         The GAWK Manual


                             by
                     Diane Barlow Close
                     Arnold D. Robbins
                       Paul H. Rubin
                      Richard Stallman


                     Edition 0.11 Beta


                        October 1989

     Copyright  1989 Free Software Foundation, Inc.


     This is Edition 0.11 Beta of _T_h_e _G_A_W_K _M_a_n_u_a_l,
for the 2.11 Beta version of the GNU implementation
of AWK.

     Published by the Free Software Foundation
675 Massachusetts Avenue,
Cambridge, MA 02139 USA
Printed copies are available for $10 each.

     Permission is granted to make and  distribute  verbatim
copies of this manual provided the copyright notice and this
permission notice are preserved on all copies.

     Permission is granted to copy and  distribute  modified
versions  of  this  manual under the conditions for verbatim
copying, provided that the entire resulting derived work  is
distributed under the terms of a permission notice identical
to this one.


     Permission is granted to copy and  distribute  transla-
tions  of this manual into another language, under the above
conditions for modified versions, except that  this  permis-
sion  notice  may be stated in a translation approved by the
Foundation.


22                                            TThhee GGAAWWKK MMaannuuaall


PPrreeffaaccee

     changes in various text files wherever certain patterns
appear,  or  extract  data from parts of certain lines while
discarding the rest.  To write a program to  do  this  in  a
language  such as C or Pascal is a time-consuming inconveni-
ence that may take many lines  of  code.   The  job  may  be
easier with awk.

     The awk utility interprets a  special-purpose  program-
ming  language that makes it possible to handle simple data-
reformatting jobs easily with just a few lines of code.

     The GNU implementation of awk is  called  gawk;  it  is
fully  upward  compatible  with the System V Release 3.1 and
later version of awk.  All  properly  written  awk  programs
should  work  with  gawk.   So  we usually don't distinguish
between gawk and other awk implementations in this manual.

     This manual teaches you what awk does and how  you  can
use  awk  effectively.   You should already be familiar with
basic system commands such as ls.  Using awk you can:

          manage small, personal databases,

          generate reports,

          validate data,

          produce  indexes,  and  perform   other   document
          preparation tasks,


TThhee GGAAWWKK MMaannuuaall                                            33


          even experiment with algorithms that can be adapt-
          ed later to other computer languages!


HHiissttoorryy ooff awk aanndd gawk

     The name awk comes from the initials of its  designers:
Alfred V.  Aho, Peter J. Weinberger, and Brian W. Kernighan.
The original version of awk was written in 1977.  In 1985  a
new  version  made  the  programming language more powerful,
introducing user-defined functions, multiple input  streams,
and  computed  regular expressions.  This new version became
generally available with System V Release 3.1.  The  version
in  System  V  Release  4  added  some new features and also
cleaned up the behaviour in some of the ``dark corners''  of
the language.

     The GNU implementation, gawk, was written  in  1986  by
Paul Rubin and Jay Fenlason, with advice from Richard Stall-
man.  John Woods contributed parts of the code as well.   In
1988 and 1989, David Trueman, with help from Arnold Robbins,
thoroughly reworked gawk for compatibility  with  the  newer
awk.

     Many people need to be thanked for their assistance  in
producing  this manual.  Jay Fenlason contributed many ideas
and sample programs.  Richard Mlynarik and  Robert  Chassell
gave helpful comments on drafts of this manual.  The paper _A
_S_u_p_p_l_e_m_e_n_t_a_l _D_o_c_u_m_e_n_t _f_o_r awk by  John  W.   Pierce  of  the
Chemistry  Department  at  UC  San Diego, pinpointed several
issues relevant both  to  awk  implementation  and  to  this
manual, that would otherwise have escaped us.

     Finally, we would like to thank Brian Kernighan of Bell
Labs for invaluable assistance during the testing and debug-
ging of gawk, and for  help  in  clarifying  several  points
about the language.

GGNNUU GGeenneerraall PPuubblliicc LLiicceennssee
                  Version 1, February 1989

    Copyright  1989 Free Software Foundation, Inc.
    675 Mass Ave, Cambridge, MA 02139, USA

    Everyone is permitted to copy and distribute verbatim copies
    of this license document, but changing it is not allowed.


44                                            TThhee GGAAWWKK MMaannuuaall


PPrreeaammbbllee

       The license agreements of most software companies try
to keep users at the mercy of those companies.  By contrast,
our General Public License is  intended  to  guarantee  your
freedom to share and change free software---to make sure the
software is free for all  its  users.   The  General  Public
License  applies  to the Free Software Foundation's software
and to any other program whose authors commit to  using  it.
You can use it for your programs, too.

       When we speak of free software, we are  referring  to
freedom,   not  price.   Specifically,  the  General  Public
License is designed to make sure that you have  the  freedom
to  give  away  or  sell  copies  of free software, that you
receive source code or can get it if you want it,  that  you
can change the software or use pieces of it in new free pro-
grams; and that you know you can do these things.

       To protect your rights, we need to make  restrictions
that forbid anyone to deny you these rights or to ask you to
surrender the rights.  These restrictions translate to  cer-
tain  responsibilities  for  you if you distribute copies of
the software, or if you modify it.

       For example, if you distribute copies  of  a  such  a
program,  whether  gratis  or  for  a fee, you must give the
recipients all the rights that you have.  You must make sure
that they, too, receive or can get the source code.  And you
must tell them their rights.

       We protect your rights with two steps: (1)  copyright
the software, and (2) offer you this license which gives you
legal permission  to  copy,  distribute  and/or  modify  the
software.

       Also, for each author's protection and ours, we  want
to  make  certain that everyone understands that there is no
warranty for this free software.  If the software  is  modi-
fied  by  someone else and passed on, we want its recipients
to know that what they have is not the original, so that any
problems introduced by others will not reflect on the origi-
nal authors' reputations.

       The precise terms and conditions for copying, distri-
bution and modification follow.


TThhee GGAAWWKK MMaannuuaall                                            55


TTEERRMMSS AANNDD CCOONNDDIITTIIOONNSS

     1.   This License Agreement applies to any  program  or
          other  work  which contains a notice placed by the
          copyright holder  saying  it  may  be  distributed
          under  the  terms  of this General Public License.
          The ``Program'', below, refers to any such program
          or work, and a ``work based on the Program'' means
          either the Program or any work containing the Pro-
          gram  or  a portion of it, either verbatim or with
          modifications.   Each  licensee  is  addressed  as
          ``you''.

     2.   You may copy and distribute verbatim copies of the
          Program's  source  code  as you receive it, in any
          medium, provided that you  conspicuously  and  ap-
          propriately  publish  on  each copy an appropriate
          copyright notice and disclaimer of warranty;  keep
          intact  all the notices that refer to this General
          Public License and to the absence of any warranty;
          and  give  any  other  recipients of the Program a
          copy of this General Public License along with the
          Program.   You  may  charge a fee for the physical
          act of transferring a copy.

     3.   You may modify your copy or copies of the  Program
          or any portion of it, and copy and distribute such
          modifications  under  the  terms  of  Paragraph  1
          above, provided that you also do the following:

               cause the modified files to  carry  prominent
               notices  stating  that  you changed the files
               and the date of any change; and

               cause the whole of any work that you  distri-
               bute  or  publish,  that  in whole or in part
               contains the Program or any part thereof, ei-
               ther  with  or  without  modifications, to be
               licensed at no charge to  all  third  parties
               under   the  terms  of  this  General  Public
               License (except that you may choose to  grant
               warranty protection to some or all third par-
               ties, at your option).

               If the modified program normally  reads  com-
               mands  interactively when run, you must cause
               it, when started running for such interactive
               use  in  the  simplest and most usual way, to
               print or display an announcement including an
               appropriate  copyright  notice  and  a notice
               that there is no warranty  (or  else,  saying
               that  you  provide a warranty) and that users
               may redistribute the program under these con-
               ditions,  and  telling the user how to view a


66                                            TThhee GGAAWWKK MMaannuuaall


               copy of this General Public License.

               You may charge a fee for the physical act  of
               transferring  a copy, and you may at your op-
               tion offer warranty  protection  in  exchange
               for a fee.


          Mere aggregation of another independent work  with
          the  Program  (or its derivative) on a volume of a
          storage or distribution medium does not bring  the
          other work under the scope of these terms.

     4.   You may copy and distribute the Program (or a por-
          tion  or  derivative  of it, under Paragraph 2) in
          object code or executable form under the terms  of
          Paragraphs 1 and 2 above provided that you also do
          one of the following:

               accompany it with the complete  corresponding
               machine-readable  source  code, which must be
               distributed under the terms of  Paragraphs  1
               and 2 above; or,

               accompany it with a written offer, valid  for
               at least three years, to give any third party
               free (except for a  nominal  charge  for  the
               cost  of  distribution)  a  complete machine-
               readable copy  of  the  corresponding  source
               code,  to  be  distributed under the terms of
               Paragraphs 1 and 2 above; or,

               accompany it with  the  information  you  re-
               ceived  as  to where the corresponding source
               code may be obtained.  (This  alternative  is
               allowed  only  for noncommercial distribution
               and only if you received the program  in  ob-
               ject code or executable form alone.)


          Source code for a work means the preferred form of
          the  work  for making modifications to it.  For an
          executable file, complete source  code  means  all
          the  source code for all modules it contains; but,
          as a special exception, it need not include source
          code for modules which are standard libraries that
          accompany the operating system on which  the  exe-
          cutable file runs, or for standard header files or
          definitions files that  accompany  that  operating
          system.

     5.   You may not copy, modify,  sublicense,  distribute
          or  transfer  the Program except as expressly pro-
          vided under this General Public License.  Any  at-


TThhee GGAAWWKK MMaannuuaall                                            77


          tempt  otherwise to copy, modify, sublicense, dis-
          tribute or transfer the Program is void, and  will
          automatically  terminate  your  rights  to use the
          Program under this License.  However, parties  who
          have  received  copies,  or  rights to use copies,
          from you under this General  Public  License  will
          not have their licenses terminated so long as such
          parties remain in full compliance.

     6.   By copying, distributing or modifying the  Program
          (or  any  work  based on the Program) you indicate
          your acceptance of this license to do so, and  all
          its terms and conditions.

     7.   Each time you redistribute  the  Program  (or  any
          work based on the Program), the recipient automat-
          ically receives a license from the original licen-
          sor to copy, distribute or modify the Program sub-
          ject to these terms and conditions.  You  may  not
          impose any further restrictions on the recipients'
          exercise of the rights granted herein.

     8.   The Free Software Foundation may  publish  revised
          and/or  new versions of the General Public License
          from time to time.   Such  new  versions  will  be
          similar  in spirit to the present version, but may
          differ in detail to address new problems  or  con-
          cerns.

          Each version is  given  a  distinguishing  version
          number.  If the Program specifies a version number
          of the license which applies to it and ``any later
          version'',  you  have  the option of following the
          terms and conditions either of that version or  of
          any  later  version published by the Free Software
          Foundation.  If the Program  does  not  specify  a
          version  number of the license, you may choose any
          version ever published by the Free Software  Foun-
          dation.

     9.   If you wish to incorporate parts  of  the  Program
          into other free programs whose distribution condi-
          tions are different, write to the  author  to  ask
          for permission.  For software which is copyrighted
          by the Free Software Foundation, write to the Free
          Software  Foundation; we sometimes make exceptions
          for this.  Our decision will be guided by the  two
          goals of preserving the free status of all deriva-
          tives of our free software and  of  promoting  the
          sharing and reuse of software generally.


88                                            TThhee GGAAWWKK MMaannuuaall


     NNOO WWAARRRRAANNTTYY

     10.  BECAUSE THE PROGRAM IS LICENSED  FREE  OF  CHARGE,
          THERE  IS  NO WARRANTY FOR THE PROGRAM, TO THE EX-
          TENT PERMITTED BY  APPLICABLE  LAW.   EXCEPT  WHEN
          OTHERWISE  STATED IN WRITING THE COPYRIGHT HOLDERS
          AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS''
          WITHOUT  WARRANTY OF ANY KIND, EITHER EXPRESSED OR
          IMPLIED, INCLUDING, BUT NOT LIMITED  TO,  THE  IM-
          PLIED  WARRANTIES  OF  MERCHANTABILITY AND FITNESS
          FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK  AS  TO
          THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH
          YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU  AS-
          SUME  THE  COST OF ALL NECESSARY SERVICING, REPAIR
          OR CORRECTION.

     11.  IN NO EVENT UNLESS REQUIRED BY APPLICABLE  LAW  OR
          AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR
          ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE
          THE  PROGRAM  AS PERMITTED ABOVE, BE LIABLE TO YOU
          FOR DAMAGES, INCLUDING ANY GENERAL,  SPECIAL,  IN-
          CIDENTAL  OR  CONSEQUENTIAL DAMAGES ARISING OUT OF
          THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING
          BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING REN-
          DERED INACCURATE OR LOSSES  SUSTAINED  BY  YOU  OR
          THIRD  PARTIES  OR  A  FAILURE  OF  THE PROGRAM TO
          OPERATE WITH ANY OTHER  PROGRAMS),  EVEN  IF  SUCH
          HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POS-
          SIBILITY OF SUCH DAMAGES.


EENNDD OOFF TTEERRMMSS AANNDD CCOONNDDIITTIIOONNSS

AAppppeennddiixx:: UUssiinngg TThheessee TTeerrmmss iinn NNeeww PPrrooggrraammss

       If you develop a new program, and you want it  to  be
of  the  greatest  possible use to humanity, the best way to
achieve this is to make it free software which everyone  can
redistribute and change under these terms.

       To do so, attach the following notices  to  the  pro-
gram.   It  is  safest  to  attach them to the start of each
source file to most effectively convey the exclusion of war-
ranty;  and each file should have at least the ``copyright''
line and a pointer to where the full notice is found.


    _o_n_e _l_i_n_e _t_o _g_i_v_e _t_h_e _p_r_o_g_r_a_m'_s _n_a_m_e _a_n_d _a _b_r_i_e_f _i_d_e_a _o_f _w_h_a_t _i_t _d_o_e_s.
    Copyright (C) 19_y_y  _n_a_m_e _o_f _a_u_t_h_o_r

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 1, or (at your option)
    any later version.


TThhee GGAAWWKK MMaannuuaall                                            99


    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.


     Also add information on how to  contact  you  by  elec-
tronic and paper mail.

     If the program is interactive, make it output  a  short
notice like this when it starts in an interactive mode:


    Gnomovision version 69, Copyright (C) 19_y_y _n_a_m_e _o_f _a_u_t_h_o_r
    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
    This is free software, and you are welcome to redistribute it
    under certain conditions; type `show c' for details.


     The hypothetical commands `show w' and `show c'  should
show  the  appropriate  parts of the General Public License.
Of course, the commands you  use  may  be  called  something
other  than `show w' and `show c'; they could even be mouse-
clicks or menu items---whatever suits your program.

     You should also get your employer (if  you  work  as  a
programmer)  or  your  school, if any, to sign a ``copyright
disclaimer'' for the program, if necessary.  Here a  sample;
alter the names:


    Yoyodyne, Inc., hereby disclaims all copyright interest in the
    program `Gnomovision' (a program to direct compilers to make passes
    at assemblers) written by James Hacker.

    _s_i_g_n_a_t_u_r_e _o_f _T_y _C_o_o_n, 1 April 1989
    Ty Coon, President of Vice


     That's all there is to it!


1100                                           TThhee GGAAWWKK MMaannuuaall


11..  UUssiinngg TThhiiss MMaannuuaall

     The term gawk refers to a particular program (a version
of  awk,  developed  as  part  the  GNU project), and to the
language you use to tell this program what to do.   When  we
need  to be careful, we call the program ``the awk utility''
and the language ``the awk language''.  The purpose of  this
manual is to explain the awk language and how to run the awk
utility.

     The term awk _p_r_o_g_r_a_m refers to a program written by you
in the awk programming language.

     See section Getting Started, for  the  bare  essentials
you need to know to start using awk.

     Some useful ``one-liners'' are included to give  you  a
feel for the awk language (see section  One-liners).


     A sizable sample awk program has been provided for  you
(see section  Sample Program).

     If you find terms that you aren't  familiar  with,  try
looking them up in the glossary (see section  Glossary).

     Most of the time complete  awk  programs  are  used  as
examples,  but  in  some of the more advanced sections, only
the part of the awk program  that  illustrates  the  concept
being described is shown.


11..11..  DDaattaa FFiilleess ffoorr tthhee EExxaammpplleess

     Many of the examples in this manual  take  their  input
from  two  sample data files.  The first, called `BBS-list',
represents a list of computer  bulletin  board  systems  and
information  about  those  systems.   The  second data file,
called `inventory-shipped', contains information about ship-
ments  on  a monthly basis.  Each line of these files is one
_r_e_c_o_r_d.

     In the file `BBS-list', each record contains  the  name
of  a computer bulletin board, its phone number, the board's
baud rate, and a code for the number of hours it  is  opera-
tional.   An `A' in the last column means the board operates
24 hours all week.  A `B' in the last column means the board
operates  evening  and weekend hours, only.  A `C' means the


TThhee GGAAWWKK MMaannuuaall                                           1111


board operates only on weekends.


        aardvark     555-5553     1200/300          B
        alpo-net     555-3412     2400/1200/300     A
        barfly       555-7685     1200/300          A
        bites        555-1675     2400/1200/300     A
        camelot      555-0542     300               C
        core         555-2912     1200/300          C
        fooey        555-1234     2400/1200/300     B
        foot         555-6699     1200/300          B
        macfoo       555-6480     1200/300          A
        sdace        555-3430     2400/1200/300     A
        sabafoo      555-2127     1200/300          C


     The  second  data  file,  called   `inventory-shipped',
represents  information  about  shipments  during  the year.
Each line of this file is also one record.  Each record con-
tains  the  month  of  the  year, the number of green crates
shipped, the number of red  boxes  shipped,  the  number  of
orange  bags  shipped,  and  the  number  of  blue  packages
shipped, respectively.  There are 16 entries,  covering  the
12 months of one year and 4 months of the next year.


        Jan  13  25  15 115
        Feb  15  32  24 226
        Mar  15  24  34 228
        Apr  31  52  63 420
        May  16  34  29 208
        Jun  31  42  75 492
        Jul  24  34  67 436
        Aug  15  34  47 316
        Sep  13  55  37 277
        Oct  29  54  68 525
        Nov  20  87  82 577
        Dec  17  35  61 401

        Jan  21  36  64 620
        Feb  26  58  80 652
        Mar  24  75  70 495
        Apr  21  70  74 514


1122                                           TThhee GGAAWWKK MMaannuuaall


22..  GGeettttiinngg SSttaarrtteedd WWiitthh awk

     The basic function of awk is to search files for  lines
(or  other  units  of  text)  that contain certain patterns.
When a line matches one of the patterns, awk performs speci-
fied actions on that line.  awk keeps processing input lines
in this way until the end of the input file is reached.

     When you run awk, you  specify  an  awk  _p_r_o_g_r_a_m  which
tells  awk  what to do.  The program consists of a series of
_r_u_l_e_s.  (It may also contain _f_u_n_c_t_i_o_n _d_e_f_i_n_i_t_i_o_n_s, but  that
is  an  advanced  feature,  so let's ignore it for now.  See
section User-defined.)  Each rule specifies one  pattern  to
search  for,  and one action to perform when that pattern is
found.

     Syntactically, a rule consists of a pattern followed by
an  action.   The  action  is  enclosed  in  curly braces to
separate it from the pattern.  Rules are  usually  separated
by newlines.  Therefore, an awk program looks like this:


    _p_a_t_t_e_r_n { _a_c_t_i_o_n }
    _p_a_t_t_e_r_n { _a_c_t_i_o_n }
    ...


22..11..  AA VVeerryy SSiimmppllee EExxaammppllee

     The following command runs a simple  awk  program  that
searches the input file `BBS-list' for the string of charac-
ters: `foo'.  (A string of  characters  is  usually  called,
quite simply, a _s_t_r_i_n_g.  The term _s_t_r_i_n_g is perhaps based on
similar usage in English, such as ``a  string  of  pearls,''
or, ``a string of cars in a train.'')


    awk '/foo/ { print $0 }' BBS-list


When lines containing `foo' are  found,  they  are  printed,
because  `print $0'
 means print the current line.  (Just `print' by itself also
means  the  same  thing,  so  we  could  have  written  that
instead.)

     You will notice that slashes, `/', surround the  string
`foo'  in the actual awk program.  The slashes indicate that
`foo' is a pattern to search for.  This type of  pattern  is
called  a  _r_e_g_u_l_a_r _e_x_p_r_e_s_s_i_o_n, and is covered in more detail


TThhee GGAAWWKK MMaannuuaall                                           1133


later (see section  Regexp).  There are single-quotes around
the  awk program so that the shell won't interpret any of it
as special shell characters.

     Here is what this program prints:


    fooey        555-1234     2400/1200/300     B
    foot         555-6699     1200/300          B
    macfoo       555-6480     1200/300          A
    sabafoo      555-2127     1200/300          C


     In an awk rule, either the pattern or the action can be
omitted,  but not both.  If the pattern is omitted, then the
action is performed for _e_v_e_r_y input line.  If the action  is
omitted, the default action is to print all lines that match
the pattern.

     Thus, we could leave out the action (the  print  state-
ment  and  the  curly  braces) in the above example, and the
result would be the same: all  lines  matching  the  pattern
`foo'  would  be printed.  By comparison, omitting the print
statement but retaining the  curly  braces  makes  an  empty
action that does nothing; then no lines would be printed.

22..22..  AAnn EExxaammppllee wwiitthh TTwwoo RRuulleess

     The awk utility reads the input files  one  line  at  a
time.   For  each  line,  awk  tries the patterns of all the
rules.  If several patterns match then several  actions  are
run,  in  the order in which they appear in the awk program.
If no patterns match, then no actions are run.

     After processing all  the  rules  (perhaps  none)  that
match  the  line, awk reads the next line (however, see sec-
tion  Next Statement).  This continues until the end of  the
file is reached.

     For example, the awk program:


    /12/  { print $0 }
    /21/  { print $0 }


contains two rules.  The first rule has the string  `12'  as
the  pattern  and `print $0' as the action.  The second rule
has the string `21' as the pattern and also has  `print  $0'
as  the  action.   Each rule's action is enclosed in its own
pair of braces.


1144                                           TThhee GGAAWWKK MMaannuuaall


     This awk program prints every line  that  contains  the
string  `12'  _o_r  the  string `21'.  If a line contains both
strings, it is printed twice, once by each rule.

     If we run this program on our two  sample  data  files,
`BBS-list' and `inventory-shipped', as shown here:


    awk '/12/ { print $0 }
         /21/ { print $0 }' BBS-list inventory-shipped


we get the following output:


    aardvark     555-5553     1200/300          B
    alpo-net     555-3412     2400/1200/300     A
    barfly       555-7685     1200/300          A
    bites        555-1675     2400/1200/300     A
    core         555-2912     1200/300          C
    fooey        555-1234     2400/1200/300     B
    foot         555-6699     1200/300          B
    macfoo       555-6480     1200/300          A
    sdace        555-3430     2400/1200/300     A
    sabafoo      555-2127     1200/300          C
    sabafoo      555-2127     1200/300          C
    Jan  21  36  64 620
    Apr  21  70  74 514


Note how the line in `BBS-list' beginning with `sabafoo' was
printed twice, once for each rule.

22..33..  AA MMoorree CCoommpplleexx EExxaammppllee

     Here is an example to give you an idea of what  typical
awk  programs do.  This example shows how awk can be used to
summarize, select, and rearrange the output of another util-
ity.   It  uses  features  that haven't been covered yet, so
don't worry if you don't understand all the details.


    ls -l | awk '$5 == "Nov" { sum += $4 }
                 END { print sum }'


     This command prints the total number of  bytes  in  all
the  files  in the current directory that were last modified
in November (of any year).  (In the C shell you  would  need
to  type  a semicolon and then a backslash at the end of the
first line; in the Bourne shell or the  Bourne-Again  shell,


TThhee GGAAWWKK MMaannuuaall                                           1155


you can type the example as shown.)

     The  `ls -l'
 part of this example is a command that  gives  you  a  full
listing of all the files in a directory, including file size
and date.  Its output looks like this:


    -rw-r--r--  1 close        1933 Nov  7 13:05 Makefile
    -rw-r--r--  1 close       10809 Nov  7 13:03 gawk.h
    -rw-r--r--  1 close         983 Apr 13 12:14 gawk.tab.h
    -rw-r--r--  1 close       31869 Jun 15 12:20 gawk.y
    -rw-r--r--  1 close       22414 Nov  7 13:03 gawk1.c
    -rw-r--r--  1 close       37455 Nov  7 13:03 gawk2.c
    -rw-r--r--  1 close       27511 Dec  9 13:07 gawk3.c
    -rw-r--r--  1 close        7989 Nov  7 13:03 gawk4.c


The first field contains read-write permissions, the  second
field  contains  the  number  of  links to the file, and the
third field identifies the owner of the  file.   The  fourth
field  contains  the  size of the file in bytes.  The fifth,
sixth, and seventh fields contain the month, day, and  time,
respectively, that the file was last modified.  Finally, the
eighth field contains the name of the file.

     The $5 == "Nov" in our awk  program  is  an  expression
that  tests  whether the fifth field of the output from  `ls
-l' matches the string `Nov'.  Each  time  a  line  has  the
string  `Nov' in its fifth field, the action `{ sum += $4 }'
is performed.  This adds the fourth field (the file size) to
the  variable sum.  As a result, when awk has finished read-
ing all the input lines, sum is the  sum  of  the  sizes  of
files whose lines matched the pattern.

     After the last line of output from  ls  has  been  pro-
cessed,  the  END  rule is executed, and the value of sum is
printed.  In this example, the value of sum would be 80600.

     These more advanced awk techniques are covered in later
sections  (see section  Actions).  Before you can move on to
more advanced awk programming, you  have  to  know  how  awk
interprets  your input and displays your output.  By manipu-
lating fields and using print statements,  you  can  produce
some very useful and spectacular looking reports.


1166                                           TThhee GGAAWWKK MMaannuuaall


22..44..  HHooww ttoo RRuunn awk PPrrooggrraammss

     There are several ways to run an awk program.   If  the
program is short, it is easiest to include it in the command
that runs awk, like this:


    awk '_p_r_o_g_r_a_m' _i_n_p_u_t-_f_i_l_e_1 _i_n_p_u_t-_f_i_l_e_2 ...


where _p_r_o_g_r_a_m consists of a series of patterns and  actions,
as described earlier.

     When the program is long, you would probably prefer  to
put it in a file and run it with a command like this:


    awk -f _p_r_o_g_r_a_m-_f_i_l_e _i_n_p_u_t-_f_i_l_e_1 _i_n_p_u_t-_f_i_l_e_2 ...


22..44..11..  OOnnee--sshhoott TThhrrooww--aawwaayy awk PPrrooggrraammss

     Once you are familiar with awk,  you  will  often  type
simple  programs  at  the moment you want to use them.  Then
you can write the program as the first argument of  the  awk
command, like this:


    awk '_p_r_o_g_r_a_m' _i_n_p_u_t-_f_i_l_e_1 _i_n_p_u_t-_f_i_l_e_2 ...


where _p_r_o_g_r_a_m consists of a series of _p_a_t_t_e_r_n_s and  _a_c_t_i_o_n_s,
as described earlier.

     This command format tells the shell to  start  awk  and
use  the  _p_r_o_g_r_a_m  to  process records in the input file(s).
There are single quotes around the _p_r_o_g_r_a_m so that the shell
doesn't  interpret any awk characters as special shell char-
acters.  They cause the shell to treat all of _p_r_o_g_r_a_m  as  a
single argument for awk.  They also allow _p_r_o_g_r_a_m to be more
than one line long.

     This  format  is  also  useful  for  running  short  or
medium-sized  awk  programs  from  shell scripts, because it
avoids the need for a separate file for the awk program.   A
self-contained shell script is more reliable since there are
no other files to misplace.


TThhee GGAAWWKK MMaannuuaall                                           1177


22..44..22..  RRuunnnniinngg awk wwiitthhoouutt IInnppuutt FFiilleess

     You can also use awk without any input files.   If  you
type the command line:


    awk '_p_r_o_g_r_a_m'


then awk applies the _p_r_o_g_r_a_m to the  _s_t_a_n_d_a_r_d  _i_n_p_u_t,  which
usually  means whatever you type on the terminal.  This con-
tinues until you indicate end-of-file by typing Control-d.

     For example, if you execute this command:


    awk '/th/'


whatever you type next is taken as data for  that  awk  pro-
gram.  If you go on to type the following data:


    Kathy
    Ben
    Tom
    Beth
    Seth
    Karen
    Thomas
    Control-d


then awk prints this output:


    Kathy
    Beth
    Seth


as matching the pattern `th'.  Notice that it did not recog-
nize  `Thomas' as matching the pattern.  The awk language is
_c_a_s_e _s_e_n_s_i_t_i_v_e, and matches patterns exactly.  (However, you
can override this with the variable IGNORECASE.  See section
Case-sensitivity.)


1188                                           TThhee GGAAWWKK MMaannuuaall


22..44..33..  RRuunnnniinngg LLoonngg PPrrooggrraammss

     Sometimes your awk programs can be very long.  In  this
case  it  is  more  convenient  to  put  the  program into a
separate file.  To tell awk to use that file  for  its  pro-
gram, you type:


    awk -f _s_o_u_r_c_e-_f_i_l_e _i_n_p_u_t-_f_i_l_e_1 _i_n_p_u_t-_f_i_l_e_2 ...


     The `-f' tells the awk utility to get the  awk  program
from  the  file  _s_o_u_r_c_e-_f_i_l_e.  Any file name can be used for
_s_o_u_r_c_e-_f_i_l_e.  For example, you could put the program:


    /th/


into the file `th-prog'.  Then this command:


    awk -f th-prog


does the same thing as this one:


    awk '/th/'


which was explained earlier (see  section   Read  Terminal).
Note  that  you  don't usually need single quotes around the
file name that you specify  with  `-f',  because  most  file
names don't contain any of the shell's special characters.

     If you want to identify your awk program files  clearly
as  such, you can add the extension `.awk' to the file name.
This doesn't affect the execution of the awk program, but it
does make ``housekeeping'' easier.

22..44..44..  EExxeeccuuttaabbllee awk PPrrooggrraammss

     Once you have learned awk, you may want to write  self-
contained awk scripts, using the `#!' script mechanism.  You
can do this on BSD Unix systems and (someday) on GNU.

     For example, you could create a text file  named  `hel-
lo', containing the following (where `BEGIN' is a feature we
have not yet discussed):


TThhee GGAAWWKK MMaannuuaall                                           1199


    #! /bin/awk -f

    # a sample awk program
    BEGIN    { print "hello, world" }


After making this file executable (with the chmod  command),
you can simply type:


    hello


at the shell, and the system will arrange to run awk  as  if
you had typed:


    awk -f hello


Self-contained awk scripts are useful when you want to write
a  program  which  users can invoke without knowing that the
program is written in awk.

     If your system does not support the `#!' mechanism, you
can  get  a similar effect using a regular shell script.  It
would look something like this:


    : The colon makes sure this script is executed by the Bourne shell.
    awk '_p_r_o_g_r_a_m' "$@"


     Using this technique, it is _v_i_t_a_l to enclose  the  _p_r_o_-
_g_r_a_m  in  single quotes to protect it from interpretation by
the shell.  If you omit the quotes, only a shell wizard  can
predict the result.

     The `"$@"' causes the shell to forward all the  command
line  arguments  to the awk program, without interpretation.
The first line, which starts with a colon, is used  so  that
this  shell  script  will work even if invoked by a user who
uses the C shell.


2200                                           TThhee GGAAWWKK MMaannuuaall


22..55..  CCoommmmeennttss iinn awk PPrrooggrraammss

     A _c_o_m_m_e_n_t is some text that is included  in  a  program
for  the  sake of human readers, and that is not really part
of the program.  Comments can explain what the program does,
and  how  it  works.   Nearly all programming languages have
provisions for comments, because programs are hard to under-
stand without their extra help.

     In the awk language, a comment starts  with  the  sharp
sign  character,  `#', and continues to the end of the line.
The awk language ignores the rest  of  a  line  following  a
sharp  sign.   For  example, we could have put the following
into `th-prog':


    # This program finds records containing the pattern `th'.  This is how
    # you continue comments on additional lines.
    /th/


     You  can  put  comment  lines  into   keyboard-composed
throw-away  awk  programs  also, but this usually isn't very
useful; the purpose of a comment is to help you  or  another
person understand the program at another time.

22..66..  awk SSttaatteemmeennttss vveerrssuuss LLiinneess

     Most often, each line in an awk program is  a  separate
statement or separate rule, like this:


    awk '/12/  { print $0 }
         /21/  { print $0 }' BBS-list inventory-shipped


     But sometimes statements can be more than one line, and
lines  can  contain  several  statements.   You  can split a
statement into multiple lines by inserting a  newline  after
any of the following:


    ,    {    ?    :    ||    &&    do    else


A newline at any other point is considered the  end  of  the
statement.

     If you would like to split a single statement into  two
lines at a point where a newline would terminate it, you can
_c_o_n_t_i_n_u_e it by  ending  the  first  line  with  a  backslash


TThhee GGAAWWKK MMaannuuaall                                           2211


character,  `\'.  This is allowed absolutely anywhere in the
statement, even in the middle of a string or regular expres-
sion.  For example:


    awk '/This program is too long, so continue it\
     on the next line/ { print $1 }'


We have generally not used  backslash  continuation  in  the
sample  programs in this manual.  Since there is no limit on
the length of a line, it is  never  strictly  necessary;  it
just  makes  programs  prettier.   We have preferred to make
them even more  pretty  by  keeping  the  statements  short.
Backslash  continuation is most useful when your awk program
is in a separate source file, instead of  typed  in  on  the
command line.

     WWaarrnniinngg::  bbaacckkssllaasshh  ccoonnttiinnuuaattiioonn  ddooeess  nnoott  wwoorrkk   aass
ddeessccrriibbeedd   aabboovvee  wwiitthh  tthhee  CC  sshheellll..   Continuation  with
backslash works for awk programs  in  files,  and  also  for
one-shot programs _p_r_o_v_i_d_e_d you are using the Bourne shell or
the Bourne-again shell.  But the C shell  used  on  Berkeley
Unix   behaves   differently!    There,  you  must  use  two
backslashes in a row, followed by a newline.

     When awk statements within  one  rule  are  short,  you
might  want  to put more than one of them on a line.  You do
this by separating  the  statements  with  semicolons,  `;'.
This  also applies to the rules themselves.  Thus, the above
example program could have been written:


    /12/ { print $0 } ; /21/ { print $0 }


NNoottee:: the requirement that rules on the same  line  must  be
separated  with  a  semicolon  is a recent change in the awk
language; it was done for consistency with the treatment  of
statements within an action.

22..77..  WWhheenn ttoo UUssee awk

     What use is all of this to me, you  might  ask?   Using
additional  utility  programs, more advanced patterns, field
separators, arithmetic statements, and other selection  cri-
teria,  you  can  produce much more complex output.  The awk
language is very useful for  producing  reports  from  large
amounts  of  raw  data, such as summarizing information from
the output of other utility programs such as ls.  (See  sec-
tion More Complex, , A More Complex Example.)


2222                                           TThhee GGAAWWKK MMaannuuaall


     Programs written with awk are usually much smaller than
they  would  be in other languages.  This makes awk programs
easy to compose and use.  Often awk programs can be  quickly
composed  at  your  terminal,  used  once,  and thrown away.
Since awk programs are interpreted, you can avoid  the  usu-
ally   lengthy  edit-compile-test-debug  cycle  of  software
development.

     Complex programs have been written in awk, including  a
complete  retargetable  assembler  for 8-bit microprocessors
(see section  Glossary, for more information) and  a  micro-
code  assembler for a special purpose Prolog computer.  How-
ever, awk's capabilities are strained by tasks of such  com-
plexity.

     If you find yourself writing awk scripts of more  than,
say,  a  few  hundred lines, you might consider using a dif-
ferent programming language.  Emacs Lisp is a good choice if
you  need sophisticated string or pattern matching capabili-
ties.  The shell is also good at string and  pattern  match-
ing; in addition, it allows powerful use of the system util-
ities.  More conventional languages, such  as  C,  C++,  and
Lisp, offer better facilities for system programming and for
managing the complexity  of  large  programs.   Programs  in
these  languages  may require more lines of source code than
the equivalent awk programs, but they are easier to maintain
and usually run more efficiently.

33..  RReeaaddiinngg IInnppuutt FFiilleess

     In the typical awk program, all input  is  read  either
from the standard input (usually the keyboard) or from files
whose names you specify on the awk  command  line.   If  you
specify input files, awk reads data from the first one until
it reaches the end; then it reads the second file  until  it
reaches  the  end, and so on.  The name of the current input
file can be found in the  built-in  variable  FILENAME  (see
section  Built-in Variables).

     The input is read in units  called  _r_e_c_o_r_d_s,  and  pro-
cessed  by the rules one record at a time.  By default, each
record is one line.  Each record read is split automatically
into  _f_i_e_l_d_s,  to make it more convenient for a rule to work
on parts of the record under consideration.

     On rare occasions you will need to use the getline com-
mand,  which  can do explicit input from any number of files
(see section  Getline).


TThhee GGAAWWKK MMaannuuaall                                           2233


33..11..  HHooww IInnppuutt iiss SSpplliitt iinnttoo RReeccoorrddss

     The awk language divides its  input  into  records  and
fields.   Records  are  separated  by a character called the
_r_e_c_o_r_d _s_e_p_a_r_a_t_o_r.  By default, the record separator  is  the
newline  character.  Therefore, normally, a record is a line
of text.

     records.  You can use different characters by  changing
the built-in variable RS.

     The value of RS is a string that says how  to  separate
records;  the  default  value  is "\n", the string of just a
newline character.  This is why  records  are,  by  default,
single lines.

     RS can have any string as its value, but only the first
character  of  the  string  is used as the record separator.
The other characters are ignored.  RS is exceptional in this
regard;  awk  uses  the full value of all its other built-in
variables.


     You can change the value of RS in the awk program  with
the  assignment operator, `=' (see section  Assignment Ops).
The new record-separator character  should  be  enclosed  in
quotation  marks to make a string constant.  Often the right
time to do this is at the beginning of execution, before any
input has been processed, so that the very first record will
be read with the proper separator.  To do this, use the spe-
cial BEGIN pattern (see section  BEGIN/END).  For example:


    awk 'BEGIN { RS = "/" } ; { print $0 }' BBS-list


changes the value of RS to "/", before  reading  any  input.
This  is  a  string  whose  first character is a slash; as a
result, records are separated by slashes.   Then  the  input
file  is  read,  and the second rule in the awk program (the
action with no pattern)  prints  each  record.   Since  each
print statement adds a newline at the end of its output, the
effect of this awk program is to copy the  input  with  each
slash changed to a newline.

     Another way to change the record separator  is  on  the
command  line,  using  the  variable-assignment feature (see
section  Command Line).


    awk '...' RS="/" _s_o_u_r_c_e-_f_i_l_e


2244                                           TThhee GGAAWWKK MMaannuuaall


This sets RS to `/' before processing _s_o_u_r_c_e-_f_i_l_e.

     The empty string (a string of no characters) has a spe-
cial  meaning  as the value of RS: it means that records are
separated only by blank lines.  See section  Multiple  Line,
for more details.

     The awk utility keeps track of the  number  of  records
that  have  been  read  so  far from the current input file.
This value is stored in a built-in variable called FNR.   It
is  reset  to  zero  when  a  new  file is started.  Another
built-in variable, NR, is the total number of input  records
read  so far from all files.  It starts at zero but is never
automatically reset to zero.

     If you change the value of RS in the middle of  an  awk
run,  the  new  value is used to delimit subsequent records,
but  the  record  currently  being  processed  (and  records
already finished) are not affected.

33..22..  EExxaammiinniinngg FFiieellddss

     When awk reads an input record, the record is automati-
cally  separated  or  _p_a_r_s_e_d  by the interpreter into pieces
called _f_i_e_l_d_s.  By default, fields  are  separated  by  whi-
tespace,  like words in a line.  Whitespace in awk means any
string of one or more spaces and/or tabs;  other  characters
such  as  newline,  formfeed, and so on, that are considered
whitespace by other languages are _n_o_t considered  whitespace
by awk.

     The purpose of fields is to make it more convenient for
you  to refer to these pieces of the record.  You don't have
to use them---you can operate on the  whole  record  if  you
wish---but  fields  are  what  make  simple  awk programs so
powerful.

     To refer to a field  in  an  awk  program,  you  use  a
dollar-sign,  `$',  followed  by the number of the field you
want.  Thus, $1 refers to the first field, $2 to the second,
and  so on.  For example, suppose the following is a line of
input:


    This seems like a pretty nice example.


Here the first field, or $1, is `This'; the second field, or
$2, is `seems'; and so on.  Note that the last field, $7, is
`example.'.  Because there is no space between the  `e'  and
the `.', the period is considered part of the seventh field.


TThhee GGAAWWKK MMaannuuaall                                           2255


     No matter how many fields there are, the last field  in
a  record  can  be  represented  by $NF.  So, in the example
above, $NF would be the same as  $7,  which  is  `example.'.
Why this works is explained below (see section  Non-Constant
Fields).  If you try to refer to a  field  beyond  the  last
one,  such  as $8 when the record has only 7 fields, you get
the empty string.

     Plain NF, with no `$', is  a  built-in  variable  whose
value is the number of fields in the current record.

     $0, which looks like an attempt to refer to the  zeroth
field,  is  a  special  case:  it represents the whole input
record.   This  is  what  you  would  use  when  you  aren't
interested in fields.

     Here are some more examples:


    awk '$1 ~ /foo/ { print $0 }' BBS-list


This example prints each record in the file `BBS-list' whose
first  field contains the string `foo'.  The operator `~' is
called a _m_a_t_c_h_i_n_g _o_p_e_r_a_t_o_r (see section  Comparison Ops); it
tests whether a string (here, the field $1) contains a match
for a given regular expression.

     By contrast, the following example:


    awk '/foo/ { print $1, $NF }' BBS-list


looks for `foo' in _t_h_e _e_n_t_i_r_e _r_e_c_o_r_d and  prints  the  first
field  and the last field for each input record containing a
match.

33..33..  NNoonn--ccoonnssttaanntt FFiieelldd NNuummbbeerrss

     The number of a field does not need to be  a  constant.
Any  expression  in the awk language can be used after a `$'
to refer to a field.  The value of the expression  specifies
the  field  number.  If the value is a string, rather than a
number, it is converted to a number.  Consider this example:


    awk '{ print $NR }'


2266                                           TThhee GGAAWWKK MMaannuuaall


Recall that NR is the number of records read so  far:  1  in
the  first  record,  2  in the second, etc.  So this example
prints the first field of the first record, the second field
of  the second record, and so on.  For the twentieth record,
field number 20 is printed;  most  likely,  the  record  has
fewer than 20 fields, so this prints a blank line.

     Here is another example of using expressions  as  field
numbers:


    awk '{ print $(2*2) }' BBS-list


     The awk language must evaluate the expression (2*2) and
use  its value as the number of the field to print.  The `*'
sign represents multiplication, so the expression 2*2 evalu-
ates to 4.  The parentheses are used so that the multiplica-
tion is done before the `$' operation;  they  are  necessary
whenever  there  is  a  binary  operator in the field-number
expression.  This example, then, prints the hours of  opera-
tion  (the  fourth  field)  for every line of the file `BBS-
list'.

     If the field number you compute is zero,  you  get  the
entire  record.   Thus,  $(2-2)  has  the  same value as $0.
Negative field numbers are not allowed.

     The number of fields in the current record is stored in
the  built-in variable NF (see section  Built-in Variables).
The expression $NF is not  a  special  feature:  it  is  the
direct consequence of evaluating NF and using its value as a
field number.

33..44..  CChhaannggiinngg tthhee CCoonntteennttss ooff aa FFiieelldd

     You can change the contents of a field as seen  by  awk
within  an  awk  program; this changes what awk perceives as
the current input record.  (The actual input  is  untouched:
awk never modifies the input file.)

     Look at this example:


    awk '{ $3 = $2 - 10; print $2, $3 }' inventory-shipped


The `-' sign represents subtraction, so this  program  reas-
signs  field  three,  $3, to be the value of field two minus
ten, $2 - 10.  (See section  Arithmetic  Ops.)   Then  field
two, and the new value for field three, are printed.


TThhee GGAAWWKK MMaannuuaall                                           2277


     In order for this to work, the text in  field  $2  must
make  sense  as  a  number; the string of characters must be
converted to a number in order for the computer to do arith-
metic  on  it.  The number resulting from the subtraction is
converted back to a string of characters which then  becomes
field three.  See section Conversion.

     When you change the value of a field (as  perceived  by
awk),  the  text of the input record is recalculated to con-
tain the new field where the old  one  was.   Therefore,  $0
changes to reflect the altered field.  Thus,


    awk '{ $2 = $2 - 10; print $0 }' inventory-shipped


prints a copy of the input file, with 10 subtracted from the
second field of each line.

     You can also assign contents to fields that are out  of
range.  For example:


    awk '{ $6 = ($5 + $4 + $3 + $2) ; print $6 }' inventory-shipped


We've just created $6, whose value is the sum of fields  $2,
$3,  $4, and $5.  The `+' sign represents addition.  For the
file `inventory-shipped', $6 represents the total number  of
parcels shipped for a particular month.

     Creating a new field changes the internal awk  copy  of
the current input record---the value of $0.  Thus, if you do
`print $0' after adding a field, the record printed includes
the  new field, with the appropriate number of field separa-
tors between it and the previously existing fields.

     This recomputation affects and is affected  by  several
features  not yet discussed, in particular, the _o_u_t_p_u_t _f_i_e_l_d
_s_e_p_a_r_a_t_o_r, OFS, which is used to separate  the  fields  (see
section   Output  Separators), and NF (the number of fields;
see section  Fields).  For example, the value of NF  is  set
to the number of the highest field you create.

     Note, however, that merely _r_e_f_e_r_e_n_c_i_n_g an  out-of-range
field  does  _n_o_t  change  the  value  of  either  $0  or NF.
Referencing an out-of-range field  merely  produces  a  null
string.  For example:


    if ($(NF+1) != "")
        print "can't happen"


2288                                           TThhee GGAAWWKK MMaannuuaall


    else
        print "everything is normal"


should print `everything is normal', because NF+1 is certain
to  be  out  of  range.  (See section If Statement, for more
information about awk's if-else statements.)

33..55..  SSppeecciiffyyiinngg HHooww FFiieellddss AArree SSeeppaarraatteedd

     The way awk splits an input record into fields is  con-
trolled  by the _f_i_e_l_d _s_e_p_a_r_a_t_o_r, which is a single character
or a regular expression.  awk scans  the  input  record  for
matches  for  the  separator;  the fields themselves are the
text between the matches.  For example, if the field separa-
tor is `oo', then the following line:


    moo goo gai pan


would be split into three fields: `m', ` g' and ` gai pan'.

     The field separator  is  represented  by  the  built-in
variable FS.  Shell programmers take note!  awk does not use
the name IFS which is used by the shell.

     You can change the value of FS in the awk program  with
the  assignment operator, `=' (see section  Assignment Ops).
Often the right time to do this is at the beginning of  exe-
cution,  before  any  input  has been processed, so that the
very first record will be read with  the  proper  separator.
To  do  this,  use  the  special  BEGIN pattern (see section
BEGIN/END).  For example, here we set the value of FS to the
string ",":


    awk 'BEGIN { FS = "," } ; { print $2 }'


Given the input line,


    John Q. Smith, 29 Oak St., Walamazoo, MI 42139


this awk program extracts the string `29 Oak St.'.

     Sometimes your input data will contain separator  char-
acters  that  don't separate fields the way you thought they


TThhee GGAAWWKK MMaannuuaall                                           2299


would.  For instance, the person's name in the example we've
been  using  might  have a title or suffix attached, such as
`John Q. Smith, LXIX'.  From input containing such a name:


    John Q. Smith, LXIX, 29 Oak St., Walamazoo, MI 42139


the previous sample program would extract `LXIX', instead of
`29  Oak  St.'.   If you were expecting the program to print
the address, you would be surprised.  So  choose  your  data
layout  and  separator  characters carefully to prevent such
problems.

     As you know, by default, fields are separated  by  whi-
tespace  sequences  (spaces and tabs), not by single spaces:
two spaces in a row do not  delimit  an  empty  field.   The
default value of the field separator is a string  " "
 containing a single space.  If this value were  interpreted
in  the  usual  way,  each  space  character  would separate
fields, so two spaces in a row would  make  an  empty  field
between  them.   The  reason  this does not happen is that a
single space as the value of FS is a  special  case:  it  is
taken to specify the default manner of delimiting fields.

     If FS is any other single character, such as ",",  then
each occurrence of that character separates two fields.  Two
consecutive occurrences delimit  an  empty  field.   If  the
character  occurs  at  the beginning or the end of the line,
that too delimits an empty field.  The  space  character  is
the only single character which does not follow these

     More generally, the value of FS may be  a  string  con-
taining  any  regular  expression.   Then  each match in the
record for the regular  expression  separates  fields.   For
example, the assignment:


    FS = ", \t"


makes every area of an input line that consists of  a  comma
followed  by  a  space  and  a  tab, into a field separator.
(`\t' stands for a tab.)

     For a less trivial example  of  a  regular  expression,
suppose  you  want  single spaces to separate fields the way
single commas were used above.  You can set FS  to    "[  ]"
matches a single space and nothing else.

     FS can be set on the command line.  You  use  the  `-F'
argument to do so.  For example:


3300                                           TThhee GGAAWWKK MMaannuuaall


    awk -F, '_p_r_o_g_r_a_m' _i_n_p_u_t-_f_i_l_e_s


sets FS to be the `,' character.  Notice that  the  argument
uses  a  capital `F'.  Contrast this with `-f', which speci-
fies a file containing an awk program.  Case is  significant
in  command  options: the `-F' and `-f' options have nothing
to do with each other.  You can use both options at the same
time  to  set  the FS argument _a_n_d get an awk program from a
file.

     As a special case, in compatibility mode  (see  section
Command  Line),  if  the argument to `-F' is `t', then FS is
set to the tab character.  (This is because if you  type  `-
F\t',  without  the  quotes,  at  the  shell,  the  `\' gets
deleted, so awk figures that you really want your fields  to
be  separated  with tabs, and not `t's.  Use `FS="t"' on the
command line if you really do want to separate  your  fields
with `t's.)

     For example, let's  use  an  awk  program  file  called
`baud.awk'  that  contains the pattern /300/, and the action
`print $1'.  Here is the program:


    /300/   { print $1 }


     Let's also set FS to be the `-' character, and run  the
program  on  the  file  `BBS-list'.   The  following command
prints a list of the  names  of  the  bulletin  boards  that
operate  at  300  baud  and  the first three digits of their
phone numbers:


    awk -F- -f baud.awk BBS-list


It produces this output:


    aardvark     555
    alpo
    barfly       555
    bites        555
    camelot      555
    core         555
    fooey        555
    foot         555
    macfoo       555


TThhee GGAAWWKK MMaannuuaall                                           3311


    sdace        555
    sabafoo      555


Note the second line of output.  If you check  the  original
file, you will see that the second line looked like this:


    alpo-net     555-3412     2400/1200/300     A


     The `-' as part of the system's name was  used  as  the
field separator, instead of the `-' in the phone number that
was originally intended.  This demonstrates why you have  to
be careful in choosing your field and record separators.

     The following  program  searches  the  system  password
file, and prints the entries for users who have no password:


    awk -F: '$2 == ""' /etc/passwd


Here we use the `-F' option on the command line to  set  the
field  separator.   Note  that  fields  in `/etc/passwd' are
separated by colons.  The second field represents  a  user's
encrypted password, but if the field is empty, that user has
no password.

33..66..  MMuullttiippllee--LLiinnee RReeccoorrddss

     In some data bases, a single line  cannot  conveniently
hold  all  the information in one entry.  In such cases, you
can use multi-line records.

     The first step in doing this is  to  choose  your  data
format: when records are not defined as single lines, how do
you want to define them?  What should separate records?

     One technique is to use an unusual character or  string
to  separate  records.   For  example,  you  could  use  the
formfeed character  (written  `\f'  in  awk,  as  in  C)  to
separate them, making each record a page of the file.  To do
this, just set the variable RS to "\f" (a string  containing
the  formfeed character).  Any other character could equally
well be used, as long as it won't be part of the data  in  a
record.


3322                                           TThhee GGAAWWKK MMaannuuaall


     Another technique  is  to  have  blank  lines  separate
records.   By  a  special dispensation, a null string as the
value of RS indicates that records are separated by  one  or
more  blank  lines.   If  you  set  RS to the null string, a
record always ends at the first blank line encountered.  And
the  next record doesn't start until the first nonblank line
that follows---no matter how many blank lines  appear  in  a
row, they are considered one record-separator.

     The second step  is  to  separate  the  fields  in  the
record.   One  way  to  do  this  is  to put each field on a
separate line: to do this, just set the variable FS  to  the
string "\n".  (This simple regular expression matches a sin-
gle newline.)

     Another idea is to divide each of the lines into fields
in  the  normal manner.  This happens by default as a result
of a special feature: when RS is set to the null string, the
newline character _a_l_w_a_y_s acts as a field separator.  This is
in addition to whatever field separations result from FS.

     The original motivation for this special exception  was
probably so that you get useful behavior in the default case
(i.e.,  FS == " " ).  This feature can be a problem  if  you
really  don't want the newline character to separate fields,
since there is no way to prevent it.  However, you can  work
around  this  by  using  the  split function to break up the
record manually (see section  String Functions).


33..77..  EExxpplliicciitt IInnppuutt wwiitthh getline

     So far we have been getting our input files from  awk's
main  input stream---either the standard input (usually your
terminal) or the files specified on the command  line.   The
awk  language  has a special built-in command called getline
that can be used to read input under your explicit control.

     This command is quite complex and should _n_o_t be used by
beginners.   It  is covered here because this is the chapter
on input.  The examples that follow the explanation  of  the
getline  command  include material that has not been covered
yet.  Therefore, come back and  study  the  getline  command
_a_f_t_e_r  you  have reviewed the rest of this manual and have a
good knowledge of how awk works.

     getline returns 1 if it finds a record, and  0  if  the
end  of  the file is encountered.  If there is some error in
getting a record, such as a file that cannot be opened, then
getline returns -1.


TThhee GGAAWWKK MMaannuuaall                                           3333


     In the following examples, _c_o_m_m_a_n_d stands for a  string
value that represents a shell command.

     getline
          The getline command can be used without  arguments
          to read input from the current input file.  All it
          does in this case is read the  next  input  record
          and  split  it  up into fields.  This is useful if
          you've finished processing the current record, but
          you  want  to do some special processing _r_i_g_h_t _n_o_w
          on the next record.  Here's an example:


              awk '{
                   if (t = index($0, "/*")) {
                        if(t > 1)
                             tmp = substr($0, 1, t - 1)
                        else
                             tmp = ""
                        u = index(substr($0, t + 2), "*/")
                        while (! u) {
                             getline
                             t = -1
                             u = index($0, "*/")
                        }
                        if(u <= length($0) - 2)
                             $0 = tmp substr($0, t + u + 3)
                        else
                             $0 = tmp
                   }
                   print $0
              }'


          This awk program deletes all comments, `/* ...
          */',  from the input.  By replacing the `print
          $0' with other statements, you  could  perform
          more complicated processing on the decommented
          input, such as searching it for matches for  a
          regular expression.

          This form of the getline command sets NF  (the
          number  of  fields;  see  section  Fields), NR
          (the number of records read so far;  see  sec-
          tion   Records),  FNR  (the  number of records
          read from this input file), and the  value  of
          $0.

          NNoottee:: the new value of $0 is used  in  testing
          the  patterns  of  any  subsequent rules.  The
          original value of $0 that triggered  the  rule
          which  executed getline is lost.  By contrast,
          the next statement reads a new record but  im-


3344                                           TThhee GGAAWWKK MMaannuuaall


          mediately   begins   processing  it  normally,
          starting with the first rule in  the  program.
          See section Next Statement.

     getline _v_a_r
          This form of getline reads a record  into  the
          variable  _v_a_r.   This  is useful when you want
          your program to read the next record from  the
          current input file, but you don't want to sub-
          ject the record to the normal  input  process-
          ing.

          For example, suppose the next line is  a  com-
          ment,  or  a  special  string, and you want to
          read it, but you must  make  certain  that  it
          won't trigger any rules.  This version of get-
          line allows you to read that line and store it
          in  a  variable  so that the main read-a-line-
          and-check-each-rule loop of awk never sees it.

          The following example swaps every two lines of
          input.  For example, given:


              wan
              tew
              free
              phore


     it outputs:


              tew
              wan
              phore
              free


     Here's the program:


              awk '{
                   if ((getline tmp) > 0) {
                        print tmp
                        print $0
                   } else
                        print $0
              }'


TThhee GGAAWWKK MMaannuuaall                                           3355


          The getline function used  in  this  way  sets
          only  the variables NR and FNR (and of course,
          _v_a_r).  The record is not split into fields, so
          the  values  of  the fields (including $0) and
          the value of NF do not change.

     getline < _f_i_l_e
          This form of the getline  function  takes  its
          input  from  the  file  _f_i_l_e.   Here _f_i_l_e is a
          string-valued expression  that  specifies  the
          file  name.   `< _f_i_l_e' is called a _r_e_d_i_r_e_c_t_i_o_n
          since it directs input to  come  from  a  dif-
          ferent place.

          This form is useful if you want to  read  your
          input  from a particular file, instead of from
          the main input stream.  For example, the  fol-
          lowing program reads its input record from the
          file `foo.input' when it  encounters  a  first
          field  with a value equal to 10 in the current
          input file.


              awk '{
              if ($1 == 10) {
                   getline < "foo.input"
                   print
              } else
                   print
              }'


          Since the main input stream is not  used,  the
          values of NR and FNR are not changed.  But the
          record read is split into fields in the normal
          manner,  so  the values of $0 and other fields
          are changed.  So is the value of NF.

          This does not cause the record  to  be  tested
          against  all  the patterns in the awk program,
          in the way that would  happen  if  the  record
          were read normally by the main processing loop
          of awk.  However  the  new  record  is  tested
          against  any  subsequent  rules,  just as when
          getline is used without a redirection.

     getline _v_a_r < _f_i_l_e
          This form of the getline  function  takes  its
          input  from  the  file _f_i_l_e and puts it in the
          variable _v_a_r.  As above,  _f_i_l_e  is  a  string-
          valued  expression  that specifies the file to
          read from.


3366                                           TThhee GGAAWWKK MMaannuuaall


          In  this  version  of  getline,  none  of  the
          built-in variables are changed, and the record
          is not split into fields.  The  only  variable
          changed is _v_a_r.

          For example, the following program copies  all
          the  input  files  to  the  output, except for
          records that say  `@include _f_i_l_e_n_a_m_e'  Such  a
          record is replaced by the contents of the file
          _f_i_l_e_n_a_m_e.


              awk '{
                   if (NF == 2 && $1 == "@include") {
                        while ((getline line < $2) > 0)
                             print line
                        close($2)
                   } else
                        print
              }'


          Note here how the name of the extra input file
          is  not  built  into  the program; it is taken
          from the data, from the second  field  on  the
          `@include' line.

          The close function is called to ensure that if
          two  identical  `@include' lines appear in the
          input, the entire specified file  is  included
          twice.  See section Close Input.

          One deficiency of this program is that it does
          not  process  nested `@include' statements the
          way a true macro preprocessor would.

     _c_o_m_m_a_n_d | getline
          You can _p_i_p_e the output of a command into get-
          line.  A pipe is simply a way to link the out-
          put of one program to the  input  of  another.
          In  this  case, the string _c_o_m_m_a_n_d is run as a
          shell command and its output is piped into awk
          to  be  used  as  input.  This form of getline
          reads one record from the pipe.

          For example, the following program copies  in-
          put  to  output,  except  for lines that begin
          with `@execute', which  are  replaced  by  the
          output  produced  by  running  the rest of the
          line as a shell command:


              awk '{


TThhee GGAAWWKK MMaannuuaall                                           3377


                   if ($1 == "@execute") {
                        tmp = substr($0, 10)
                        while ((tmp | getline) > 0)
                             print
                        close(tmp)
                   } else
                        print
              }'


     The close function is called to ensure that if  two
     identical `@execute' lines appear in the input, the
     command is run again for  each  one.   See  section
     Close Input.

          Given the input:


              foo
              bar
              baz
              @execute who
              bletch


     the program might produce:


              foo
              bar
              baz
              hack     ttyv0   Jul 13 14:22
              hack     ttyp0   Jul 13 14:23     (gnu:0)
              hack     ttyp1   Jul 13 14:23     (gnu:0)
              hack     ttyp2   Jul 13 14:23     (gnu:0)
              hack     ttyp3   Jul 13 14:23     (gnu:0)
              bletch


     Notice that this program ran the  command  who  and
     printed the result.  (If you try this program your-
     self, you will get different results,  showing  you
     logged in.)

          This variation of getline  splits  the  record
          into  fields,  sets the value of NF and recom-
          putes the value of $0.  The values of  NR  and
          FNR are not changed.

     _c_o_m_m_a_n_d | getline _v_a_r
          The output of  the  command  _c_o_m_m_a_n_d  is  sent


3388                                           TThhee GGAAWWKK MMaannuuaall


          through  a  pipe to getline and into the vari-
          able _v_a_r.  For example, the following  program
          reads the current date and time into the vari-
          able current_time, using  the  utility  called
          date, and then prints it.


                  awk 'BEGIN {
                       "date" | getline current_time
                       close("date")
                       print "Report printed on " current_time
                  }'


          In this version of getline, none of  the  built-in
          variables are changed, and the record is not split
          into fields.


33..88..  CClloossiinngg IInnppuutt FFiilleess aanndd PPiippeess

     If the same file name or the same shell command is used
with  getline  more than once during the execution of an awk
program, the file is opened (or  the  command  is  executed)
only  the  first  time.   At  that time, the first record of
input is read from that file or command.  The next time  the
same  file  or command is used in getline, another record is
read from it, and so on.

     This implies that if you want to start reading the same
file  again  from  the  beginning, or if you want to rerun a
shell command (rather that reading more output from the com-
mand),  you must take special steps.  What you can do is use
the close function, as follows:


    close(_f_i_l_e_n_a_m_e)


or


    close(_c_o_m_m_a_n_d)


     The argument _f_i_l_e_n_a_m_e or _c_o_m_m_a_n_d can be any expression.
Its  value  must  exactly  equal the string that was used to
open the file or start the  command---for  example,  if  you
open a pipe with this:


TThhee GGAAWWKK MMaannuuaall                                           3399


    "sort -r names" | getline foo


then you must close it with this:


    close("sort -r names")


     Once this function call is executed, the  next  getline
from  that file or command will reopen the file or rerun the
command.

44..  PPrriinnttiinngg OOuuttppuutt

     One of the most common things that  actions  do  is  to
output  or  _p_r_i_n_t some or all of the input.  For simple out-
put, use the print statement.  For  fancier  formatting  use
the printf statement.  Both are described in this chapter.


44..11..  TThhee print SSttaatteemmeenntt

     The print statement does output with simple,  standard-
ized formatting.  You specify only the strings or numbers to
be printed, in a list separated by commas.  They are output,
separated  by  single  spaces,  followed  by a newline.  The
statement looks like this:


    print _i_t_e_m_1, _i_t_e_m_2, ...


The entire list of  items  may  optionally  be  enclosed  in
parentheses.   The  parentheses  are necessary if any of the
item expressions uses a relational  operator;  otherwise  it
could  be confused with a redirection (see section  Redirec-
tion).  The relational operators are `==', `!=',  `<',  `>',
`>=', `<=', `~' and `!~' (see section  Comparison Ops).

     The items printed can be constant strings  or  numbers,
fields of the current record (such as $1), variables, or any
awk expressions.  The print statement is completely  general
for computing _w_h_a_t values to print.  With one exception (see
section  Output Separators), what you can't  do  is  specify
_h_o_w  to print them---how many columns to use, whether to use
exponential notation or not, and so on.  For that, you  need
the printf statement (see section  Printf).


4400                                           TThhee GGAAWWKK MMaannuuaall


     The  simple  statement  `print'  with   no   items   is
equivalent  to  `print  $0':  it  prints  the entire current
record.  To print a blank line, use `print ""', where ""  is
the null, or empty, string.

     To print a fixed piece of text, use a  string  constant
such as  "Hello there"
 as one item.  If you forget to use the double-quote charac-
ters,  your text will be taken as an awk expression, and you
will probably get an error.  Keep in mind that  a  space  is
printed between any two items.

     Most often, each print statement makes one line of out-
put.  But it isn't limited to one line.  If an item value is
a string that contains a  newline,  the  newline  is  output
along  with the rest of the string.  A single print can make
any number of lines this way.

44..22..  EExxaammpplleess ooff print SSttaatteemmeennttss

     Here is an example of printing a string  that  contains
embedded newlines:


    awk 'BEGIN { print "line one\nline two\nline three" }'


produces output like this:


    line one
    line two
    line three


     Here is an example that prints the first two fields  of
each input record, with a space between them:


    awk '{ print $1, $2 }' inventory-shipped


Its output looks like this:


    Jan 13
    Feb 15
    Mar 15
    ...


TThhee GGAAWWKK MMaannuuaall                                           4411


     A common mistake in using the  print  statement  is  to
omit the comma between two items.  This often has the effect
of making the items run together  in  the  output,  with  no
space.   The  reason for this is that juxtaposing two string
expressions in awk means to concatenate them.  For  example,
without the comma:


    awk '{ print $1 $2 }' inventory-shipped


prints:


    Jan13
    Feb15
    Mar15
    ...


     Neither example's output makes much  sense  to  someone
unfamiliar  with  the  file  `inventory-shipped'.  A heading
line at the beginning would make it clearer.  Let's add some
headings  to  our  table  of  months  ($1)  and green crates
shipped ($2).  We do this using the BEGIN pattern (see  sec-
tion   BEGIN/END)  to  cause the headings to be printed only
once:


    awk 'BEGIN {  print "Month Crates"
                  print "----- ------" }
               {  print $1, $2 }' inventory-shipped


Did you already guess what happens?  This program prints the
following:


        Month Crates
        ----- ------
        Jan 13
        Feb 15
        Mar 15
        ...


The headings and the table data don't line up!  We  can  fix
this by printing some spaces between the two fields:


4422                                           TThhee GGAAWWKK MMaannuuaall


    awk 'BEGIN { print "Month Crates"
                 print "----- ------" }
               { print $1, "     ", $2 }' inventory-shipped


     You can imagine that this way of lining up columns  can
get  pretty  complicated  when you have many columns to fix.
Counting spaces for two or three columns can be simple,  but
more  than this and you can get ``lost'' quite easily.  This
is  why  the  printf  statement  was  created  (see  section
Printf);  one  of  its  specialties  is lining up columns of
data.

44..33..  OOuuttppuutt SSeeppaarraattoorrss

     As mentioned previously, a print statement  contains  a
list  of  items,  separated  by  commas.  In the output, the
items are normally separated by single spaces.  But they  do
not  have  to be spaces; a single space is only the default.
You can specify any string of characters to use as the  _o_u_t_-
_p_u_t  _f_i_e_l_d  _s_e_p_a_r_a_t_o_r  by setting the built-in variable OFS.
The initial value of this variable is the string  " "

     The output from an entire print statement is called  an
_o_u_t_p_u_t  _r_e_c_o_r_d.   Each  print  statement  outputs one output
record and then outputs a string called  the  _o_u_t_p_u_t  _r_e_c_o_r_d
_s_e_p_a_r_a_t_o_r.  The built-in variable ORS specifies this string.
The initial value of the variable is the  string  "\n"  con-
taining  a  newline  character;  thus,  normally  each print
statement makes a separate line.

     You can  change  how  output  fields  and  records  are
separated  by  assigning  new  values  to  the variables OFS
and/or ORS.  The usual place to do this is in the BEGIN rule
(see  section   BEGIN/END),  so  that  it happens before any
input is processed.  You may also do this  with  assignments
on the command line, before the names of your input files.

     The following  example  prints  the  first  and  second
fields of each input record separated by a semicolon, with a
blank line added after each line:


    awk 'BEGIN { OFS = ";"; ORS = "\n\n" }
               { print $1, $2 }'  BBS-list


     If the value of ORS does not  contain  a  newline,  all
your  output  will  be run together on a single line, unless
you output newlines some other way.


TThhee GGAAWWKK MMaannuuaall                                           4433


44..44..  UUssiinngg printf SSttaatteemmeennttss FFoorr FFaanncciieerr PPrriinnttiinngg

     If you want more precise control over the output format
than  print  gives  you,  use  printf.   With printf you can
specify the width to use for each item, and you can  specify
various stylistic choices for numbers (such as what radix to
use, whether to print an exponent, whether to print a  sign,
and  how many digits to print after the decimal point).  You
do this by specifying a string, called  the  _f_o_r_m_a_t  _s_t_r_i_n_g,
which controls how and where to print the other arguments.


44..44..11..  IInnttrroodduuccttiioonn ttoo tthhee printf SSttaatteemmeenntt

     The printf statement looks like this:


    printf _f_o_r_m_a_t, _i_t_e_m_1, _i_t_e_m_2, ...


The entire list of  items  may  optionally  be  enclosed  in
parentheses.   The  parentheses  are necessary if any of the
item expressions uses a relational  operator;  otherwise  it
could  be confused with a redirection (see section  Redirec-
tion).  The relational operators are `==', `!=',  `<',  `>',
`>=', `<=', `~' and `!~' (see section  Comparison Ops).

     The difference between printf and print is the argument
_f_o_r_m_a_t.   This  is  an  expression whose value is taken as a
string; its job is to say how to output each  of  the  other
arguments.  It is called the _f_o_r_m_a_t _s_t_r_i_n_g.

     The format string is essentially the same as in  the  C
library  function printf.  Most of _f_o_r_m_a_t is text to be out-
put verbatim.  Scattered among this text are _f_o_r_m_a_t  _s_p_e_c_i_f_-
_i_e_r_s,  one  per  item.  Each format specifier says to output
the next item at that place in the format.

     The printf statement does not  automatically  append  a
newline to its output.  It outputs nothing but what the for-
mat specifies.  So if you want a newline, you  must  include
one  in  the format.  The output separator variables OFS and
ORS have no effect on printf statements.

44..44..22..  FFoorrmmaatt--CCoonnttrrooll LLeetttteerrss

     A format specifier starts with the  character  `%'  and
ends  with  a  _f_o_r_m_a_t-_c_o_n_t_r_o_l  _l_e_t_t_e_r;  it  tells the printf
statement how to output one item.  (If you actually want  to
output a `%', write `%%'.)  The format-control letter speci-
fies what kind of value to print.  The rest  of  the  format
specifier  is  made  up  of  optional  _m_o_d_i_f_i_e_r_s  which  are


4444                                           TThhee GGAAWWKK MMaannuuaall


parameters such as the field width to use.

     Here is a list of the format-control letters:

     `c'  This prints a number as an ASCII character.  Thus,
          `printf  "%c",  65'  outputs  the letter `A'.  The
          output for a string value is the  first  character
          of the string.

     `d'  This prints a decimal integer.

     `i'  This also prints a decimal integer.

     `e'  This prints a number in  scientific  (exponential)
          notation.  For example,


              printf "%4.3e", 1950


     prints `1.950e+03', with a total of  4  significant
     figures  of  which 3 follow the decimal point.  The
     `4.3' are _m_o_d_i_f_i_e_r_s, discussed below.

     `f'  This prints a number in floating  point  nota-
          tion.

     `g'  This  prints  either  scientific  notation  or
          floating point notation, whichever is shorter.

     `o'  This prints an unsigned octal integer.

     `s'  This prints a string.

     `x'  This prints an unsigned hexadecimal integer.

     `X'  This prints an unsigned  hexadecimal  integer.
          However, for the values 10 through 15, it uses
          the letters `A' through  `F'  instead  of  `a'
          through `f'.

     `%'  This isn't really a format-control letter, but
          it  does have a meaning when used after a `%':
          the sequence `%%' outputs one  `%'.   It  does
          not consume an argument.


TThhee GGAAWWKK MMaannuuaall                                           4455


44..44..33..  MMooddiiffiieerrss ffoorr printf FFoorrmmaattss

     A format specification can also include _m_o_d_i_f_i_e_r_s  that
can  control how much of the item's value is printed and how
much space it gets.  The modifiers come between the `%'  and
the format-control letter.  Here are the possible modifiers,
in the order in which they may appear:

     `-'  The minus sign, used before  the  width  modifier,
          says  to  left-justify  the  argument  within  its
          specified width.  Normally the argument is printed
          right-justified in the specified width.  Thus,


              printf "%-4s", "foo"


     prints `foo '.

     `_w_i_d_t_h'
          This is  a  number  representing  the  desired
          width   of  a  field.   Inserting  any  number
          between the `%' sign and  the  format  control
          character  forces  the field to be expanded to
          this width.  The default way to do this is  to
          pad with spaces on the left.  For example,


              printf "%4s", "foo"


     prints ` foo'.

          The value of _w_i_d_t_h is a minimum width,  not  a
          maximum.  If the item value requires more than
          _w_i_d_t_h characters, it can be as wide as  neces-
          sary.  Thus,


              printf "%4s", "foobar"


     prints `foobar'.  Preceding the _w_i_d_t_h with a  minus
     sign  causes the output to be padded with spaces on
     the right, instead of on the left.

     `._p_r_e_c'
          This is a number that specifies the  precision
          to  use  when  printing.   This  specifies the
          number of digits you want printed to the right
          of the decimal point.  For a string, it speci-


4466                                           TThhee GGAAWWKK MMaannuuaall


          fies the maximum number of characters from the
          string that should be printed.


     The C library printf's dynamic _w_i_d_t_h and _p_r_e_c  capabil-
ity  (for  example, "%*.*s") is not yet supported.  However,
it can easily be simulated using  concatenation  to  dynami-
cally build the format string.

44..44..44..  EExxaammpplleess ooff UUssiinngg printf

     Here is how to use printf to make an aligned table:


    awk '{ printf "%-10s %s\n", $1, $2 }' BBS-list


prints the names of bulletin boards ($1) of the  file  `BBS-
list' as a string of 10 characters, left justified.  It also
prints the phone numbers ($2) afterward on the  line.   This
produces  an  aligned  two-column  table  of names and phone
numbers:


    aardvark   555-5553
    alpo-net   555-3412
    barfly     555-7685
    bites      555-1675
    camelot    555-0542
    core       555-2912
    fooey      555-1234
    foot       555-6699
    macfoo     555-6480
    sdace      555-3430
    sabafoo    555-2127


     Did you notice that we did not specify that  the  phone
numbers  be  printed  as numbers?  They had to be printed as
strings because the numbers are separated by a  dash.   This
dash would be interpreted as a minus sign if we had tried to
print the phone numbers as numbers.  This would have led  to
some pretty confusing results.

     We did not  specify  a  width  for  the  phone  numbers
because  they  are the last things on their lines.  We don't
need to put spaces after them.

     We could make our table look even nicer by adding head-
ings  to the tops of the columns.  To do this, use the BEGIN
pattern (see section  BEGIN/END) to cause the header  to  be
printed only once, at the beginning of the awk program:


TThhee GGAAWWKK MMaannuuaall                                           4477


    awk 'BEGIN { print "Name      Number"
                 print "----      ------" }
         { printf "%-10s %s\n", $1, $2 }' BBS-list


     Did you notice that we mixed print  and  printf  state-
ments  in the above example?  We could have used just printf
statements to get the same results:


    awk 'BEGIN { printf "%-10s %s\n", "Name", "Number"
                 printf "%-10s %s\n", "----", "------" }
         { printf "%-10s %s\n", $1, $2 }' BBS-list


By outputting each  column  heading  with  the  same  format
specification  used  for the elements of the column, we have
made sure that  the  headings  are  aligned  just  like  the
columns.

     The fact that the same  format  specification  is  used
three  times  can be emphasized by storing it in a variable,
like this:


    awk 'BEGIN { format = "%-10s %s\n"
                 printf format, "Name", "Number"
                 printf format, "----", "------" }
         { printf format, $1, $2 }' BBS-list


     See if you can use the printf statement to line up  the
headings  and table data for our `inventory-shipped' example
covered earlier in the section on the print  statement  (see
section  Print).

44..55..  RReeddiirreeccttiinngg OOuuttppuutt ooff print aanndd printf

     So far we have  been  dealing  only  with  output  that
prints  to the standard output, usually your terminal.  Both
print and printf can be told to send their output  to  other
places.  This is called _r_e_d_i_r_e_c_t_i_o_n.

     A redirection appears after the print or printf  state-
ment.   Redirections  in  awk are written just like redirec-
tions in shell commands, except that they are written inside
the awk program.


4488                                           TThhee GGAAWWKK MMaannuuaall


44..55..11..  RReeddiirreeccttiinngg OOuuttppuutt ttoo FFiilleess aanndd PPiippeess

     Here are the three forms of output  redirection.   They
are all shown for the print statement, but they work identi-
cally for printf also.

     print _i_t_e_m_s > _o_u_t_p_u_t-_f_i_l_e
          This type of redirection prints the items onto the
          output  file  _o_u_t_p_u_t-_f_i_l_e.   The file name _o_u_t_p_u_t-
          _f_i_l_e can be any expression.  Its value is  changed
          to a string and then used as a file name (see sec-
          tion  Expressions).

          When  this  type  of  redirection  is  used,   the
          _o_u_t_p_u_t-_f_i_l_e  is  erased before the first output is
          written to it.  Subsequent  writes  do  not  erase
          _o_u_t_p_u_t-_f_i_l_e,  but  append  to  it.  If _o_u_t_p_u_t-_f_i_l_e
          does not exist, then it is created.

          For example, here is how one awk program can write
          a  list  of  BBS names to a file `name-list' and a
          list of phone  numbers  to  a  file  `phone-list'.
          Each  output  file contains one name or number per
          line.


              awk '{ print $2 > "phone-list"
                     print $1 > "name-list" }' BBS-list


     print _i_t_e_m_s >> _o_u_t_p_u_t-_f_i_l_e
          This type of redirection prints the items onto
          the  output  file _o_u_t_p_u_t-_f_i_l_e.  The difference
          between this and the single-`>' redirection is
          that  the old contents (if any) of _o_u_t_p_u_t-_f_i_l_e
          are not erased.  Instead, the  awk  output  is
          appended to the file.

     print _i_t_e_m_s | _c_o_m_m_a_n_d
          It is also possible to send output  through  a
          _p_i_p_e  instead  of  into a file.   This type of
          redirection opens a pipe to _c_o_m_m_a_n_d and writes
          the  values  of  _i_t_e_m_s  through  this pipe, to
          another process created to execute _c_o_m_m_a_n_d.

          The redirection argument _c_o_m_m_a_n_d  is  actually
          an  awk expression.  Its value is converted to
          a string, whose contents give the  shell  com-
          mand to be run.

          For example, this produces two files, one  un-
          sorted  list  of BBS names and one list sorted
          in reverse alphabetical order:


TThhee GGAAWWKK MMaannuuaall                                           4499


              awk '{ print $1 > "names.unsorted"
                     print $1 | "sort -r > names.sorted" }' BBS-list


          Here the unsorted list is written with an  or-
          dinary  redirection  while  the sorted list is
          written by piping through the sort utility.

          Here is an example that  uses  redirection  to
          mail a message to a mailing list `bug-system'.
          This might be useful when trouble  is  encoun-
          tered  in  an  awk script run periodically for
          system maintenance.


              print "Awk script failed:", $0 | "mail bug-system"
              print "at record number", FNR, "of", FILENAME  | "mail bug-system"
              close("mail bug-system")


          We call the close function here because it's a
          good idea to close the pipe as soon as all the
          intended output has been sent to it.  See sec-
          tion  Close  Output,  for  more information on
          this.


     Redirecting output using `>', `>>',  or  `|'  asks  the
system to open a file or pipe only if the particular _f_i_l_e or
_c_o_m_m_a_n_d you've specified has not already been written to  by
your program.

44..55..22..  CClloossiinngg OOuuttppuutt FFiilleess aanndd PPiippeess

     When a file or pipe is opened, the file name or command
associated  with  it  is  remembered  by  awk and subsequent
writes to the same file or command are appended to the  pre-
vious  writes.  The file or pipe stays open until awk exits.
This is usually convenient.

     Sometimes there is a reason to close an output file  or
pipe earlier than that.  To do this, use the close function,
as follows:


    close(_f_i_l_e_n_a_m_e)


or


5500                                           TThhee GGAAWWKK MMaannuuaall


    close(_c_o_m_m_a_n_d)


     The argument _f_i_l_e_n_a_m_e or _c_o_m_m_a_n_d can be any expression.
Its  value  must  exactly  equal the string used to open the
file or pipe to begin with---for example, if you open a pipe
with this:


    print $1 | "sort -r > names.sorted"


then you must close it with this:


    close("sort -r > names.sorted")


     Here are some reasons why you might need  to  close  an
output file:

          To write a file and read it back later on  in  the
          same  awk  program.   Close  the file when you are
          finished writing it; then you can start reading it
          with getline (see section  Getline).

          To write numerous files, successively, in the same
          awk  program.  If you don't close the files, even-
          tually you will exceed the  system  limit  on  the
          number  of  open  files  in one process.  So close
          each one when you are finished writing it.

          To make a command finish.  When you redirect  out-
          put  through  a pipe, the command reading the pipe
          normally continues to try to read input as long as
          the  pipe  is  open.  Often this means the command
          cannot really  do  its  work  until  the  pipe  is
          closed.   For  example,  if you redirect output to
          the mail program, the message is not actually sent
          until the pipe is closed.

          To run the same program a second  time,  with  the
          same  arguments.   This  is  not the same thing as
          giving more input to the first run!

          For example, suppose you pipe output to  the  mail
          program.   If  you output several lines redirected
          to this pipe without closing it, they make a  sin-
          gle message of several lines.  By contrast, if you
          close the pipe after each  line  of  output,  then


TThhee GGAAWWKK MMaannuuaall                                           5511


          each line makes a separate message.


44..66..  SSttaannddaarrdd II//OO SSttrreeaammss

     Running programs conventionally have  three  input  and
output  streams  already  available  to them for reading and
writing.  These are known as the  _s_t_a_n_d_a_r_d  _i_n_p_u_t,  _s_t_a_n_d_a_r_d
_o_u_t_p_u_t,  and  _s_t_a_n_d_a_r_d  _e_r_r_o_r _o_u_t_p_u_t.  These streams are, by
default, terminal input  and  output,  but  they  are  often
redirected  with  the  shell,  via the `<', `<<', `>', `>>',
`>&' and `|' operators.  Standard error  is  used  only  for
writing  error  messages;  the  reason  we have two separate
streams, standard output and standard error, is so that they
can be redirected separately.

     message to standard error in an awk program is as  fol-
lows:


    print "Serious error detected!\n" | "cat 1>&2"


This works by opening a pipeline to a  shell  command  which
can  access the standard error stream which it inherits from
the awk process.  This is far  from  elegant,  and  is  also
inefficient,  since it requires a separate process.  So peo-
ple writing awk programs have often neglected  to  do  this.
Instead,  they have sent the error messages to the terminal,
like this:


    NF != 4 {
       printf("line %d skipped: doesn't have 4 fields\n", FNR) > "/dev/tty"
    }


This has the same effect most of the time, but  not  always:
although  the standard error stream is usually the terminal,
it can be redirected, and when that happens, writing to  the
terminal  is  not  correct.   In  fact, if awk is run from a
background job, it may not have a  terminal  at  all.   Then
opening `/dev/tty' will fail.

     gawk provides special  file  names  for  accessing  the
three  standard  streams.  When you redirect input or output
in gawk, if the file  name  matches  one  of  these  special
names, then gawk directly uses the stream it stands for.

     `/dev/stdin'
          The standard input (file descriptor 0).


5522                                           TThhee GGAAWWKK MMaannuuaall


     `/dev/stdout'
          The standard output (file descriptor 1).

     `/dev/stderr'
          The standard error output (file descriptor 2).

     `/dev/fd/_n'
          The file associated with file descriptor _n.   Such
          a  file  must have been opened by the program ini-
          tiating the awk execution (typically  the  shell).
          Unless you take special pains, only descriptors 0,
          1 and 2 are available.


     The  file  names   `/dev/stdin',   `/dev/stdout',   and
`/dev/stderr'  are aliases for `/dev/fd/0', `/dev/fd/1', and
`/dev/fd/2',  respectively,  but   they   are   more   self-
explanatory.

     The proper way to write an error message in a gawk pro-
gram is to use `/dev/stderr', like this:


    NF != 4 {
      printf("line %d skipped: doesn't have 4 fields\n", FNR) > "/dev/stderr"
    }


     Recognition of these special file names is disabled  if
gawk is in compatibility mode (see section  Command Line).

55..  UUsseeffuull ````OOnnee--lliinneerrss''''

     Useful awk programs are often short,  just  a  line  or
two.   Here is a collection of useful, short programs to get
you started.  Some of these programs contain constructs that
haven't  been  covered  yet.  The description of the program
will give you a good idea of what is going  on,  but  please
read the rest of the manual to become an awk expert!

     awk '{ num_fields = num_fields + NF }

          END { print num_fields }'
          This program prints the total number of fields  in
          all input lines.

     awk 'length($0) > 80'
          This program prints  every  line  longer  than  80
          characters.   The  sole  rule has a relational ex-
          pression as its pattern, and has no action (so the
          default action, printing the record, is used).


TThhee GGAAWWKK MMaannuuaall                                           5533


     awk 'NF > 0'
          This program prints every line that has  at  least
          one  field.   This  is an easy way to delete blank
          lines from a file (or rather, to create a new file
          similar  to  the old file but from which the blank
          lines have been deleted).

     awk '{ if (NF > 0) print }'
          This program also prints every line  that  has  at
          least  one field.  Here we allow the rule to match
          every line, then decide in the action  whether  to
          print.

     awk 'BEGIN { for (i = 1; i <= 7; i++)

                    print int(101 * rand()) }'
          This program prints 7 random  numbers  from  0  to
          100, inclusive.

     ls -
          l _f_i_l_e_s | awk '{ x += $4 } ; END { print "total bytes: " x }'
          This program prints the total number of bytes used
          by _f_i_l_e_s.

     expand _f_i_l_e | awk '{ if (x < length()) x = length() }

                       END { print "maximum line length is " x }'
          This  program  prints  the  maximum line length of
          _f_i_l_e.  The input is piped through the expand  pro-
          gram  to  change  tabs  into spaces, so the widths
          compared are actually the right-margin columns.


66..  PPaatttteerrnnss

     Patterns in awk control the execution of rules: a  rule
is  executed  when  its  pattern  matches  the current input
record.  This chapter tells all about how to write patterns.


66..11..  KKiinnddss ooff PPaatttteerrnnss

     Here is a summary of the types of patterns supported in
awk.

     /_r_e_g_u_l_a_r _e_x_p_r_e_s_s_i_o_n/
          A regular expression as  a  pattern.   It  matches
          when the text of the input record fits the regular
          expression.  (See section Regexp,  ,  Regular  Ex-
          pressions as Patterns.)


5544                                           TThhee GGAAWWKK MMaannuuaall


     _e_x_p_r_e_s_s_i_o_n
          A single expression.  It matches when  its  value,
          converted to a number, is nonzero (if a number) or
          nonnull (if a string).   (See  section  Expression
          Patterns.)

     _p_a_t_1, _p_a_t_2
          A pair of patterns separated by a comma,  specify-
          ing  a  range  of records.  (See section Ranges, ,
          Specifying Record Ranges With Patterns.)

     BEGIN

     END  Special patterns to supply  start-up  or  clean-up
          information to awk.  (See section BEGIN/END.)

     _n_u_l_l
          The empty  pattern  matches  every  input  record.
          (See section Empty, , The Empty Pattern.)


66..22..  TThhee EEmmppttyy PPaatttteerrnn

     An empty pattern is considered  to  match  _e_v_e_r_y  input
record.  For example, the program:


    awk '{ print $1 }' BBS-list


prints just the first field of every record.

66..33..  RReegguullaarr EExxpprreessssiioonnss aass PPaatttteerrnnss

     A _r_e_g_u_l_a_r _e_x_p_r_e_s_s_i_o_n, or _r_e_g_e_x_p, is a way of describing
a  class  of  strings.   A  regular  expression  enclosed in
slashes (`/') is an awk pattern  that  matches  every  input
record whose text belongs to that class.

     The  simplest  regular  expression  is  a  sequence  of
letters, numbers, or both.  Such a regexp matches any string
that contains that sequence.  Thus, the regexp `foo' matches
any  string  containing `foo'.  Therefore, the pattern /foo/
matches any input record containing `foo'.  Other  kinds  of
regexps let you specify more complicated classes of strings.


TThhee GGAAWWKK MMaannuuaall                                           5555


66..33..11..  HHooww ttoo UUssee RReegguullaarr EExxpprreessssiioonnss

     A regular expression  can  be  used  as  a  pattern  by
enclosing  it  in  slashes.   Then the regular expression is
matched against the entire text of each record.   (Normally,
it  only  needs  to  match some part of the text in order to
succeed.)  For example, this prints the second field of each
record that contains `foo' anywhere:


    awk '/foo/ { print $2 }' BBS-list


     Regular expressions can  also  be  used  in  comparison
expressions.   Then  you  can  specify  the  string to match
against; it need not be the  entire  current  input  record.
These  comparison  expressions can be used as patterns or in
if and while statements.

     _e_x_p ~ /_r_e_g_e_x_p/
          This is true if the expression  _e_x_p  (taken  as  a
          character  string) is matched by _r_e_g_e_x_p.  The fol-
          lowing example  matches,  or  selects,  all  input
          records  with  the upper-case letter `J' somewhere
          in the first field:


              awk '$1 ~ /J/' inventory-shipped


          So does this:


              awk '{ if ($1 ~ /J/) print }' inventory-shipped


     _e_x_p !~ /_r_e_g_e_x_p/
          This is true if the expression _e_x_p (taken as a
          character  string)  is  _n_o_t matched by _r_e_g_e_x_p.
          The following example matches, or selects, all
          input  records whose first field _d_o_e_s _n_o_t con-
          tain the upper-case letter `J':


              awk '$1 !~ /J/' inventory-shipped


     The right hand side of a `~' or `!~' operator need  not
be  a  constant regexp (i.e., a string of characters between


5566                                           TThhee GGAAWWKK MMaannuuaall


slashes).  It may be  any  expression.   The  expression  is
evaluated,  and converted if necessary to a string; the con-
tents of the string are used as the regexp.  A  regexp  that
is  computed  in  this  way is called a _d_y_n_a_m_i_c _r_e_g_e_x_p.  For
example:


    identifier_regexp = "[A-Za-z_][A-Za-z_0-9]+"
    $0 ~ identifier_regexp


sets identifier_regexp to a regexp that describes awk  vari-
able  names,  and  tests  if  the  input record matches this
regexp.

66..33..22..  RReegguullaarr EExxpprreessssiioonn OOppeerraattoorrss

     You can combine regular expressions with the  following
characters,  called  _r_e_g_u_l_a_r  _e_x_p_r_e_s_s_i_o_n _o_p_e_r_a_t_o_r_s, or _m_e_t_a_-
_c_h_a_r_a_c_t_e_r_s, to increase the power and versatility of regular
expressions.

     Here is a table of metacharacters.  All characters  not
listed in the table stand for themselves.

     ^    This matches the beginning of the  string  or  the
          beginning  of a line within the string.  For exam-
          ple:


              ^@chapter


     matches  the  `@chapter'  at  the  beginning  of  a
     string,  and can be used to identify chapter begin-
     nings in Texinfo source files.

     $    This is similar to `^', but it matches only at
          the  end  of  a  string  or  the end of a line
          within the string.  For example:


              p$


     matches a record that ends with a `p'.

     .    This matches any  single  character  except  a
          newline.  For example:


TThhee GGAAWWKK MMaannuuaall                                           5577


              .P


     matches any single character followed by a `P' in a
     string.   Using  concatenation  we can make regular
     expressions like `U.A', which  matches  any  three-
     character  sequence  that  begins with `U' and ends
     with `A'.

     [...]
          This is called a _c_h_a_r_a_c_t_e_r  _s_e_t.   It  matches
          any one of the characters that are enclosed in
          the square brackets.  For example:


              [MVX]


     matches any of the characters `M', `V', or `X' in a
     string.

          Ranges of characters are indicated by using  a
          hyphen  between the beginning and ending char-
          acters,  and  enclosing  the  whole  thing  in
          brackets.  For example:


              [0-9]


     matches any digit.

          To include the character `\', `]', `-' or  `^'
          in  a character set, put a `\' in front of it.
          For example:


              [d\]]


     matches either `]', or `d'.

          This treatment of `\' is compatible with other
          awk  implementations but incompatible with the
          proposed POSIX  specification  for  awk.   The
          current  draft  specifies  the use of the same
          syntax used in egrep.


5588                                           TThhee GGAAWWKK MMaannuuaall


          We may change gawk to fit the  standard,  once
          we are sure it will no longer change.  For the
          meanwhile, the `-a' option specifies the trad-
          itional  awk  syntax described above (which is
          also  the  default),  while  the  `-e'  option
          specifies egrep syntax.  See section Options.

          In egrep syntax, backslash is not syntactical-
          ly special within square brackets.  This means
          that  special  tricks  have  to  be  used   to
          represent  the  characters `]', `-' and `^' as
          members of a character set.

          To match `-', write it as `---',  which  is  a
          range  containing only `-'.  You may also give
          `-' as the first or last character in the set.
          To  match  `^',  put it anywhere except as the
          first character of a set.   To  match  a  `]',
          make  it  the first character in the set.  For
          example:


              []d^]


     matches either `]', `d' or `^'.

     [^ ...]
          This is a  _c_o_m_p_l_e_m_e_n_t_e_d  _c_h_a_r_a_c_t_e_r  _s_e_t.   The
          first  character  after the `[' _m_u_s_t be a `^'.
          It matches any characters _e_x_c_e_p_t those in  the
          square brackets.  For example:


              [^0-9]


     matches any character that is not a digit.

     |    This is the _a_l_t_e_r_n_a_t_i_o_n  _o_p_e_r_a_t_o_r  and  it  is
          used to specify alternatives.  For example:


              ^P|[0-9]


     matches any string  that  matches  either  `^P'  or
     `[0-9]'.   This  means  it  matches any string that
     contains a digit or starts with `P'.


TThhee GGAAWWKK MMaannuuaall                                           5599


          The alternation applies to the largest  possi-
          ble regexps on either side.

     (...)
          Parentheses are used for grouping  in  regular
          expressions  as  in  arithmetic.   They can be
          used to concatenate regular  expressions  con-
          taining the alternation operator, `|'.

     *    This symbol means that the  preceding  regular
          expression  is to be repeated as many times as
          possible to find a match.  For example:


              ph*


     applies the `*' symbol to  the  preceding  `h'  and
     looks for matches to one `p' followed by any number
     of `h's.  This will also match just `p' if no  `h's
     are present.

          The `*' repeats the _s_m_a_l_l_e_s_t possible  preced-
          ing  expression.  (Use parentheses if you wish
          to repeat a larger expression.)  It  finds  as
          many repetitions as possible.  For example:


              awk '/\(c[ad][ad]*r x\)/ { print }' sample


     prints every  record  in  the  input  containing  a
     string  of  the  form  `(car x)', `(cdr x)', `(cadr
     x)', and so on.

     +    This symbol is similar to `*', but the preced-
          ing  expression must be matched at least once.
          This means that:


              wh+y


     would match `why' and `whhy' but not `wy',  whereas
     `wh*y'  would  match  all  three  of these strings.
     This is a simpler way of writing the last `*' exam-
     ple:


              awk '/\(c[ad]+r x\)/ { print }' sample


6600                                           TThhee GGAAWWKK MMaannuuaall


     ?    This symbol is similar to `*', but the preced-
          ing  expression  can be matched once or not at
          all.  For example:


              fe?d


     will match `fed' or `fd', but nothing else.

     \    This is used to suppress the  special  meaning
          of a character when matching.  For example:


              \$


     matches the character `$'.

          The escape sequences used for string constants
          (see  section  Constants) are valid in regular
          expressions as well; they are also  introduced
          by a `\'.


     In regular expressions, the `*', `+', and `?' operators
have  the highest precedence, followed by concatenation, and
finally by `|'.  As in arithmetic,  parentheses  can  change
how operators are grouped.

66..33..33..  CCaassee--sseennssiittiivviittyy iinn MMaattcchhiinngg

     Case is normally significant  in  regular  expressions,
both  when matching ordinary characters (i.e., not metachar-
acters), and inside character sets.  Thus a `w' in a regular
expression  matches  only  a lower case `w' and not an upper
case `W'.

     The simplest way to do a case-independent match  is  to
use  a  character set: `[Ww]'.  However, this can be cumber-
some if you need to use it often; and it can make the  regu-
lar  expressions  harder  for humans to read.  There are two
other alternatives that you might prefer.

     One way to do a case-insensitive match at a  particular
point  in  the  program  is  to convert the data to a single
case, using the tolower or toupper built-in string functions
(which  we  haven't discussed yet; see section  String Func-
tions).  For example:


TThhee GGAAWWKK MMaannuuaall                                           6611


    tolower($1) ~ /foo/  { ... }


converts the first  field  to  lower  case  before  matching
against it.

     Another method is to set the variable IGNORECASE  to  a
nonzero  value  (see  section   Built-in  Variables).   When
IGNORECASE is not zero, _a_l_l regexp operations  ignore  case.
Changing  the  value  of IGNORECASE dynamically controls the
case sensitivity of your program as it runs.  Case is signi-
ficant  by  default because IGNORECASE (like most variables)
is initialized to zero.


    x = "aB"
    if (x ~ /ab/) ...   # this test will fail

    IGNORECASE = 1
    if (x ~ /ab/) ...   # now it will succeed


     You cannot generally use  IGNORECASE  to  make  certain
rules   case-insensitive  and  other  rules  case-sensitive,
because there is no way to set IGNORECASE just for the  pat-
tern of a particular rule.  To do this, you must use charac-
ter sets or tolower.  However, one thing  you  can  do  only
with  IGNORECASE  is turn case-sensitivity on or off dynami-
cally for all the rules at once.

     IGNORECASE can be set on the  command  line,  or  in  a
BEGIN  rule.   Setting IGNORECASE from the command line is a
way to make a program  case-insensitive  without  having  to
edit it.

     The value of IGNORECASE has no effect  if  gawk  is  in
compatibility  mode  (see  section   Command Line).  Case is
always significant in compatibility mode.

66..44..  CCoommppaarriissoonn EExxpprreessssiioonnss aass PPaatttteerrnnss

     _C_o_m_p_a_r_i_s_o_n _p_a_t_t_e_r_n_s test relationships such as equality
between  two strings or numbers.  They are a special case of
expression  patterns  (see  section   Expression  Patterns).
They  are  written  with  _r_e_l_a_t_i_o_n_a_l  _o_p_e_r_a_t_o_r_s, which are a
superset of those in C.  Here is a table of them:

     _x < _y
          True if _x is less than _y.


6622                                           TThhee GGAAWWKK MMaannuuaall


     _x <= _y
          True if _x is less than or equal to _y.

     _x > _y
          True if _x is greater than _y.

     _x >= _y
          True if _x is greater than or equal to _y.

     _x == _y
          True if _x is equal to _y.

     _x != _y
          True if _x is not equal to _y.

     _x ~ _y
          True if _x matches the regular expression described
          by _y.

     _x !~ _y
          True if _x does not match  the  regular  expression
          described by _y.


     The operands of a relational operator are  compared  as
numbers  if  they are both numbers.  Otherwise they are con-
verted to, and compared as, strings  (see  section   Conver-
sion).   Strings are compared by comparing the first charac-
ter of each, then the second character of each, and  so  on,
until  there  is a difference.  If the two strings are equal
until the shorter one runs out,  the  shorter  one  is  con-
sidered  to be less than the longer one.  Thus, "10" is less
than "9".

     The left operand of the `~' and  `!~'  operators  is  a
string.   The  right  operand  is  either a constant regular
expression enclosed in slashes (/_r_e_g_e_x_p/),  or  any  expres-
sion,  whose  string  value  is  used  as  a dynamic regular
expression (see section  Regexp Usage).

     The following example prints the second field  of  each
input record whose first field is precisely `foo'.


    awk '$1 == "foo" { print $2 }' BBS-list


Contrast this with the following regular  expression  match,
which  would  accept any record with a first field that con-
tains `foo':


    awk '$1 ~ "foo" { print $2 }' BBS-list


TThhee GGAAWWKK MMaannuuaall                                           6633


or, equivalently, this one:


    awk '$1 ~ /foo/ { print $2 }' BBS-list


66..55..  BBoooolleeaann OOppeerraattoorrss aanndd PPaatttteerrnnss

     A _b_o_o_l_e_a_n _p_a_t_t_e_r_n is an expression which combines other
patterns  using the _b_o_o_l_e_a_n _o_p_e_r_a_t_o_r_s ``or'' (`||'), ``and''
(`&&'), and ``not''  (`!').   Whether  the  boolean  pattern
matches  an  input record depends on whether its subpatterns
match.

     For example, the following command prints  all  records
in  the  input  file `BBS-list' that contain both `2400' and
`foo'.


    awk '/2400/ && /foo/' BBS-list


     The following command prints all records in  the  input
file  `BBS-list'  that  contain  _e_i_t_h_e_r  `2400' or `foo', or
both.


    awk '/2400/ || /foo/' BBS-list


     The following command prints all records in  the  input
file `BBS-list' that do _n_o_t contain the string `foo'.


    awk '! /foo/' BBS-list


     Note that  boolean  patterns  are  a  special  case  of
expression patterns (see section  Expression Patterns); they
are expressions that use the boolean  operators.   For  com-
plete  information  on  the  boolean operators, see `Boolean
Ops'.

     The subpatterns of a boolean pattern  can  be  constant
regular  expressions, comparisons, or any other gawk expres-
sions.  Range patterns are not expressions, so  they  cannot
appear  inside boolean patterns.  Likewise, the special pat-
terns BEGIN and END, which never match any input record, are


6644                                           TThhee GGAAWWKK MMaannuuaall


not expressions and cannot appear inside boolean patterns.

66..66..  EExxpprreessssiioonnss aass PPaatttteerrnnss

     Any awk expression is valid also as a pattern in  gawk.
Then  the  pattern  ``matches'' if the expression's value is
nonzero (if a number) or nonnull (if a string).

     The expression is reevaluated each  time  the  rule  is
tested  against  a new input record.  If the expression uses
fields such as $1, the value depends  directly  on  the  new
input  record's text; otherwise, it depends only on what has
happened so far in the execution of  the  awk  program,  but
that may still be useful.

     Comparison patterns are  actually  a  special  case  of
this.  For example, the expression $5 == "foo" has the value
1 when the value of $5 equals "foo", and 0 otherwise; there-
fore,  this  expression  as  a  pattern matches when the two
values are equal.

     Boolean patterns are also special cases  of  expression
patterns.

     A constant regexp as a pattern is also a  special  case
of  an  expression  pattern.  /foo/ as an expression has the
value 1 if `foo' appears in the current input record;  thus,
as a pattern, /foo/ matches any record containing `foo'.

     Other implementations of  awk  are  less  general  than
gawk:  they allow comparison expressions, and boolean combi-
nations  thereof  (optionally  with  parentheses),  but  not
necessarily other kinds of expressions.

66..77..  SSppeecciiffyyiinngg RReeccoorrdd RRaannggeess WWiitthh PPaatttteerrnnss

     A _r_a_n_g_e _p_a_t_t_e_r_n is made of two patterns separated by  a
comma,  of  the  form  _b_e_g_p_a_t, _e_n_d_p_a_t.  It matches ranges of
consecutive input records.  The first  pattern  _b_e_g_p_a_t  con-
trols where the range begins, and the second one _e_n_d_p_a_t con-
trols where it ends.  For example,


    awk '$1 == "on", $1 == "off"'


prints every record between `on'/`off' pairs, inclusive.

     In more detail, a range pattern starts out by  matching
_b_e_g_p_a_t  against  every  input  record; when a record matches
_b_e_g_p_a_t, the range pattern becomes _t_u_r_n_e_d _o_n.  The range pat-
tern matches this record.  As long as it stays turned on, it
automatically  matches  every  input   record   read.    But


TThhee GGAAWWKK MMaannuuaall                                           6655


meanwhile,  it  also  matches  _e_n_d_p_a_t  against  every  input
record, and when that succeeds, the range pattern is  turned
off  again  for  the  following record.  Now it goes back to
checking _b_e_g_p_a_t against each record.

     The record that turns on the range pattern and the  one
that  turns  it  off  both  match the range pattern.  If you
don't want to operate on these records,  you  can  write  if
statements in the rule's action to distinguish them.

     It is possible for a pattern to be turned both  on  and
off  by the same record, if both conditions are satisfied by
that record.  Then the action  is  executed  for  just  that
record.

66..88..  BEGIN aanndd END SSppeecciiaall PPaatttteerrnnss

     BEGIN and END are special patterns.  They are not  used
to match input records.  Rather, they are used for supplying
start-up or clean-up information  to  your  awk  script.   A
BEGIN  rule is executed, once, before the first input record
has been read.  An END rule is executed, once, after all the
input has been read.  For example:


        awk 'BEGIN { print "Analysis of `foo'" }
             /foo/ { ++foobar }
             END   { print "`foo' appears " foobar " times." }' BBS-list


     This program finds out how many times the string  `foo'
appears in the input file `BBS-list'.  The BEGIN rule prints
a title for the report.  There is no need to use  the  BEGIN
rule  to  initialize the counter foobar to zero, as awk does
this for us automatically (see section  Variables).

     The second rule increments the  variable  foobar  every
time a record containing the pattern `foo' is read.  The END
rule prints the value of foobar at the end of the run.

     The special patterns BEGIN and END cannot  be  used  in
ranges or with boolean operators.

     An awk program  may  have  multiple  BEGIN  and/or  END
rules.   They are executed in the order they appear, all the
BEGIN rules at start-up and all the END  rules  at  termina-
tion.

     Multiple BEGIN and END sections are useful for  writing
library functions, since each library can have its own BEGIN
or END rule to do its  own  initialization  and/or  cleanup.


6666                                           TThhee GGAAWWKK MMaannuuaall


Note  that the order in which library functions are named on
the command line controls the order in which their BEGIN and
END rules are executed.  Therefore you have to be careful to
write such rules in library files so that it doesn't  matter
what  order they are executed in.  See section Command Line,
for more information on using library functions.

     If an awk program only has a BEGIN rule, and  no  other
rules,  then the program exits after the BEGIN rule has been
run.  (Older versions of awk used to keep reading and ignor-
ing  input  until end of file was seen.)  However, if an END
rule exists as well, then the input will be  read,  even  if
there  are no other rules in the program.  This is necessary
in case the END rule checks the NR variable.

     BEGIN and END rules must  have  actions;  there  is  no
default  action  for  these  rules since there is no current
record when they run.

77..  AAccttiioonnss:: OOvveerrvviieeww

     An awk _p_r_o_g_r_a_m or _s_c_r_i_p_t consists of a series of  _r_u_l_e_s
and  function  definitions,  interspersed.   (Functions  are
described later; see `User-defined'.)

     A rule contains a pattern  and  an  _a_c_t_i_o_n,  either  of
which  may be omitted.  The purpose of the action is to tell
awk what to do once a match for the pattern is found.  Thus,
the entire program looks somewhat like this:


    [_p_a_t_t_e_r_n] [{ _a_c_t_i_o_n }]
    [_p_a_t_t_e_r_n] [{ _a_c_t_i_o_n }]
    ...
    function _n_a_m_e (_a_r_g_s) { ... }
    ...


     An action consists  of  one  or  more  awk  _s_t_a_t_e_m_e_n_t_s,
enclosed  in  curly  braces  (`{'  and `}').  Each statement
specifies  one  thing  to  be  done.   The  statements   are
separated by newlines or semicolons.

     The curly braces around an action must be used even  if
the  action  contains only one statement, or even if it con-
tains no statements at all.  However, if you omit the action
entirely, omit the curly braces as well.  (An omitted action
is equivalent to `{ print $0 }'.)

     Here are the kinds of statement supported in awk:

          Expressions, which can call  functions  or  assign
          values  to  variables  (see section  Expressions).


TThhee GGAAWWKK MMaannuuaall                                           6677


          Executing this kind of statement  simply  computes
          the  value  of the expression and then ignores it.
          This is useful when the expression  has  side  ef-
          fects (see section  Assignment Ops).

          Control statements, which specify the control flow
          of  awk  programs.   The awk language gives you C-
          like constructs (if, for, while,  and  so  on)  as
          well  as  a  few special ones (see section  State-
          ments).

          Compound statements, which consist of one or  more
          statements  enclosed  in curly braces.  A compound
          statement is used in order to put  several  state-
          ments  together in the body of an if, while, do or
          for statement.

          Input control, using  the  getline  function  (see
          section   Getline),  and  the  next statement (see
          section  Next Statement).

          Output statements, print and printf.  See  section
          Printing.

          Deletion statements, for deleting array  elements.
          See section Delete.


     The next two chapters cover in detail  expressions  and
control statements, respectively.  We go on to treat arrays,
and built-in functions, both of which are  used  in  expres-
sions.   Then  we  proceed to discuss how to define your own
functions.

88..  AAccttiioonnss:: EExxpprreessssiioonnss

     Expressions  are  the  basic  building  block  of   awk
actions.   An expression evaluates to a value, which you can
print, test, store in a variable or pass to a function.

     But, beyond that, an expression can assign a new  value
to a variable or a field, with an assignment operator.

     An expression can serve as  a  statement  on  its  own.
Most  other  kinds  of statement contain one or more expres-
sions which specify data to be operated  on.   As  in  other
languages,  expressions  in  awk  include  variables,  array
references, constants, and function calls, as well as combi-
nations of these with various operators.


6688                                           TThhee GGAAWWKK MMaannuuaall


88..11..  CCoonnssttaanntt EExxpprreessssiioonnss

     The simplest type of expression is the _c_o_n_s_t_a_n_t,  which
always  has  the  same value.  There are three types of con-
stant: numeric  constants,  string  constants,  and  regular
expression constants.

     A _n_u_m_e_r_i_c _c_o_n_s_t_a_n_t stands for a  number.   This  number
can be an integer, a decimal fraction, or a number in scien-
tific (exponential) notation.  Note that all numeric  values
are  represented  within  awk  in  double-precision floating
point.  Here are some examples of numeric  constants,  which
all have the same value:


    105
    1.05e+2
    1050e-1


     A string constant consists of a sequence of  characters
enclosed in double-quote marks.  For example:


    "parrot"


gawk can be of any length and they can contain all the  pos-
sible 8-bit ASCII characters including ASCII NUL.  Other awk
implementations may  have  difficulty  with  some  character
codes.

     Some characters  cannot  be  included  literally  in  a
string  constant.   You  represent  them instead with _e_s_c_a_p_e
_s_e_q_u_e_n_c_e_s, which are character sequences  beginning  with  a
backslash (`\').

     One use of an escape sequence is to include  a  double-
quote  character  in  a  string  constant.   Since  a  plain
double-quote would end the string,  you  must  use  `\"'  to
represent  a  single double-quote character as a part of the
string.  Backslash itself is another character that can't be
included  normally;  you  write `\\' to put one backslash in
the string.  Thus, the string whose  contents  are  the  two
characters `"\' must be written "\"\\".

     Another use of backslash is  to  represent  unprintable
characters  such as newline.  While there is nothing to stop
you from writing most of  these  characters  directly  in  a
string constant, they may look ugly.


TThhee GGAAWWKK MMaannuuaall                                           6699


     Here is a table of all the  escape  sequences  used  in
awk:

     \\   Represents a literal backslash, `\'.

     \a   Represents  the  ``alert''  character,  control-g,
          ASCII code 7.

     \b   Represents a backspace, control-h, ASCII code 8.

     \f   Represents a formfeed, control-l, ASCII code 12.

     \n   Represents a newline, control-j, ASCII code 10.

     \r   Represents a  carriage  return,  control-m,  ASCII
          code 13.

     \t   Represents a horizontal tab, control-i, ASCII code
          9.

     \v   Represents a vertical tab, control-k,  ASCII  code
          11.

     \_n_n_n
          Represents the octal value _n_n_n, where _n_n_n are  one
          to three digits between 0 and 7.  For example, the
          code for  the  ASCII  ESC  (escape)  character  is
          `\033'.

     \x_h_h...
          Represents the hexadecimal value _h_h, where _h_h  are
          hexadecimal digits (`0' through `9' and either `A'
          through `F' or `a' through `f').   Like  the  same
          construct in ANSI C, the escape sequence continues
          until the first  non-hexadecimal  digit  is  seen.
          However,  using  more  than two hexadecimal digits
          produces undefined results.


     A constant regexp is a regular  expression  description
enclosed  in  slashes,  such as /^beginning and end$/.  Most
regexps used in awk programs are constant, but the  `~'  and
`!~'  operators  can  also  match  computed  or  ``dynamic''
regexps (see section  Regexp Usage).

     Constant regexps are useful only with the `~' and  `!~'
operators;  you  cannot  assign  them  to variables or print
them.  They are not truly expressions in the usual sense.


7700                                           TThhee GGAAWWKK MMaannuuaall


88..22..  VVaarriiaabblleess

     Variables let you give names to  values  and  refer  to
them  later.  You have already seen variables in many of the
examples.  The name of a variable  must  be  a  sequence  of
letters, digits and underscores, but it may not begin with a
digit.  Case is significant in variable names; a and  A  are
distinct variables.

     A variable name is a valid  expression  by  itself;  it
represents  the  variable's  current  value.   Variables are
given new values with  _a_s_s_i_g_n_m_e_n_t  _o_p_e_r_a_t_o_r_s  and  _i_n_c_r_e_m_e_n_t
_o_p_e_r_a_t_o_r_s.  See section Assignment Ops.

     A few variables have special built-in meanings, such as
FS, the field separator, and NF, the number of fields in the
current input record.  See section Built-in Variables, for a
list  of  them.   These  built-in  variables can be used and
assigned just like all other variables, but their values are
also  used  or  changed automatically by awk.  Each built-in
variable's name is made entirely of upper case letters.

     Variables in awk can be assigned either numeric  values
or  string values.  By default, variables are initialized to
the null string, which is effectively zero if converted to a
number.  So there is no need to ``initialize'' each variable
explicitly in awk, the way you would need to do in C or most
other traditional programming languages.

88..22..11..  AAssssiiggnniinngg VVaarriiaabblleess oonn tthhee CCoommmmaanndd LLiinnee

     You can set any awk variable by  including  a  _v_a_r_i_a_b_l_e
_a_s_s_i_g_n_m_e_n_t  among the arguments on the command line when you
invoke awk (see section  Command Line).  Such an  assignment
has this form:


    _v_a_r_i_a_b_l_e=_t_e_x_t


With it, you can set a variable either at the  beginning  of
the awk run or in between input files.

     If you precede the assignment  with  the  `-v'  option,
like this:


    -v _v_a_r_i_a_b_l_e=_t_e_x_t


then the variable is set at the very beginning, before  even
the BEGIN rules are run.  The `-v' option and its assignment


TThhee GGAAWWKK MMaannuuaall                                           7711


must precede all the file name arguments.

     Otherwise, the variable assignment is  performed  at  a
time  determined  by its position among the input file argu-
ments: after the processing  of  the  preceding  input  file
argument.  For example:


    awk '{ print $n }' n=4 inventory-shipped n=2 BBS-list


prints the value of field number n for  all  input  records.
Before  the  first  file  is read, the command line sets the
variable n equal to 4.  This causes the fourth field  to  be
printed  in  lines from the file `inventory-shipped'.  After
the first file has finished, but before the second  file  is
started,  n is set to 2, so that the second field is printed
in lines from `BBS-list'.

     Command line arguments are made available for  explicit
examination  by  the awk program in an array named ARGV (see
section  Built-in Variables).

88..33..  AArriitthhmmeettiicc OOppeerraattoorrss

     The awk language uses the common  arithmetic  operators
when evaluating expressions.  All of these arithmetic opera-
tors follow normal precedence rules, and work as  you  would
expect  them  to.  This example divides field three by field
four, adds field two, stores the result into field one,  and
prints the resulting altered input record:


    awk '{ $1 = $2 + $3 / $4; print }' inventory-shipped


     The arithmetic operators in awk are:

     _x + _y
          Addition.

     _x - _y
          Subtraction.

     - _x  Negation.

     _x * _y
          Multiplication.

     _x / _y
          Division.  Since all numbers in  awk  are  double-
          precision floating point, the result is not round-


7722                                           TThhee GGAAWWKK MMaannuuaall


          ed to an integer: 3 / 4 has the value 0.75.

     _x % _y
          multiplied by _y and this result is subtracted from
          _x.   This operation is sometimes known as ``trunc-
          mod''.  The following relation always holds:


              b * int(a / b) + (a % b) == a


          One undesirable effect of this  definition  of
          remainder  is  that  _x % _y is negative if _x is
          negative.  Thus,


              -17 % 8 = -1


          In other awk implementations,  the  signedness
          of the remainder may be machine dependent.

     _x ^ _y

     _x ** _y
          Exponentiation: _x raised to the _y power.  2  ^
          3  has  the  value  8.  The character sequence
          `**' is equivalent to `^'.


88..44..  SSttrriinngg CCoonnccaatteennaattiioonn

     There is only one string operation: concatenation.   It
does not have a specific operator to represent it.  Instead,
concatenation is performed by writing  expressions  next  to
one another, with no operator.  For example:


    awk '{ print "Field number one: " $1 }' BBS-list


produces, for the first record in `BBS-list':


    Field number one: aardvark


     Without the space in the string constant after the `:',
the line would run together.  For example:


TThhee GGAAWWKK MMaannuuaall                                           7733


    awk '{ print "Field number one:" $1 }' BBS-list


produces, for the first record in `BBS-list':


    Field number one:aardvark


     Since string concatenation does not  have  an  explicit
operator,  it  is  often necessary to insure that it happens
where you want it to by  enclosing  the  items  to  be  con-
catenated  in  parentheses.  For example, the following code
fragment does not concatenate file and  name  as  you  might
expect:


    file = "file"
    name = "name"
    print "something meaningful" > file name


It is necessary to use the following:


    print "something meaningful" > (file name)


     We recommend you use parentheses  around  concatenation
in  all  but the most common contexts (such as in the right-
hand operand of `=').


88..55..  CCoommppaarriissoonn EExxpprreessssiioonnss

     _C_o_m_p_a_r_i_s_o_n _e_x_p_r_e_s_s_i_o_n_s compare strings or  numbers  for
relationships  such  as  equality.   They  are written using
_r_e_l_a_t_i_o_n_a_l _o_p_e_r_a_t_o_r_s, which are a superset of  those  in  C.
Here is a table of them:

     _x < _y
          True if _x is less than _y.

     _x <= _y
          True if _x is less than or equal to _y.

     _x > _y
          True if _x is greater than _y.


7744                                           TThhee GGAAWWKK MMaannuuaall


     _x >= _y
          True if _x is greater than or equal to _y.

     _x == _y
          True if _x is equal to _y.

     _x != _y
          True if _x is not equal to _y.

     _x ~ _y
          True if the string _x matches the regexp denoted by
          _y.

     _x !~ _y
          True if the string _x does  not  match  the  regexp
          denoted by _y.

     _s_u_b_s_c_r_i_p_t in _a_r_r_a_y
          True if array _a_r_r_a_y has an element with  the  sub-
          script _s_u_b_s_c_r_i_p_t.


     Comparison expressions have the value 1 if true  and  0
if false.

     The operands of a relational operator are  compared  as
numbers  if  they are both numbers.  Otherwise they are con-
verted to, and compared as, strings  (see  section   Conver-
sion).   Strings are compared by comparing the first charac-
ter of each, then the second character of each, and  so  on.
Thus, "10" is less than "9".

     For example,


    $1 == "foo"


has the value of 1, or is true, if the first  field  of  the
current input record is precisely `foo'.  By contrast,


    $1 ~ /foo/


has the value 1 if the first field contains `foo'.

     The right hand operand of the `~'  and  `!~'  operators
may  be  either  a  constant regexp (/.../), or it may be an
ordinary expression, in which case the value of the  expres-
sion  as  a  string is a dynamic regexp (see section  Regexp
Usage).


TThhee GGAAWWKK MMaannuuaall                                           7755


     In very recent implementations of awk, a constant regu-
lar  expression  in slashes by itself is also an expression.
The regexp /_r_e_g_e_x_p/ is an abbreviation for  this  comparison
expression:


    $0 ~ /_r_e_g_e_x_p/


     In  some  contexts  it  may  be  necessary   to   write
parentheses  around  the  regexp to avoid confusing the gawk
parser.  For  example,  (/x/  -  /y/)  >  threshold  is  not
allowed, but ((/x/) - (/y/)) > threshold parses properly.

     One special place where /foo/ is  _n_o_t  an  abbreviation
for  $0  ~ /foo/ is when it is the right-hand operand of `~'
or `!~'!

88..66..  BBoooolleeaann EExxpprreessssiioonnss

     A  _b_o_o_l_e_a_n  _e_x_p_r_e_s_s_i_o_n  is  combination  of  comparison
expressions  or  matching  expressions,  using  the  _b_o_o_l_e_a_n
_o_p_e_r_a_t_o_r_s ``or'' (`||'), ``and'' (`&&'), and ``not''  (`!'),
along with parentheses to control nesting.  The truth of the
boolean expression is computed by combining the truth values
of the component expressions.

     Boolean expressions can be used wherever comparison and
matching  expressions  can  be used.  They can be used in if
and while statements.  They have numeric values (1 if  true,
0  if  false),  which  come  into place if the result of the
boolean expression is stored  in  a  variable,  or  used  in
arithmetic.

     In addition, every boolean expression is also  a  valid
boolean  pattern,  so you can use it as a pattern to control
the execution of rules.

     Here are descriptions of the three  boolean  operators,
with  an  example of each.  It may be instructive to compare
these examples with the analogous examples of  boolean  pat-
terns  (see  section   Boolean Patterns), which use the same
boolean operators in patterns instead of expressions.

     _b_o_o_l_e_a_n_1 && _b_o_o_l_e_a_n_2
          True if both _b_o_o_l_e_a_n_1 and _b_o_o_l_e_a_n_2 are true.   For
          example,   the   following  statement  prints  the
          current input record if it  contains  both  `2400'
          and `foo'.


              if ($0 ~ /2400/ && $0 ~ /foo/) print


7766                                           TThhee GGAAWWKK MMaannuuaall


          The subexpression _b_o_o_l_e_a_n_2 is  evaluated  only
          if  _b_o_o_l_e_a_n_1 is true.  This can make a differ-
          ence when _b_o_o_l_e_a_n_2 contains  expressions  that
          have  side  effects: in the case of $0 ~ /foo/
          && ($2 == bar++), the variable bar is not  in-
          cremented if there is no `foo' in the record.

     _b_o_o_l_e_a_n_1 || _b_o_o_l_e_a_n_2
          True if at least one of _b_o_o_l_e_a_n_1 and  _b_o_o_l_e_a_n_2
          is  true.   For example, the following command
          prints all records in  the  input  file  `BBS-
          list'  that contain _e_i_t_h_e_r `2400' or `foo', or
          both.


              awk '{ if ($0 ~ /2400/ || $0 ~ /foo/) print }' BBS-list


          The subexpression _b_o_o_l_e_a_n_2 is  evaluated  only
          if _b_o_o_l_e_a_n_1 is false.  This can make a differ-
          ence when _b_o_o_l_e_a_n_2 contains  expressions  that
          have side effects.

     !_b_o_o_l_e_a_n
          True if _b_o_o_l_e_a_n is false.   For  example,  the
          following  program  prints  all records in the
          input file `BBS-list' that do _n_o_t contain  the
          string `foo'.


              awk '{ if (! ($0 ~ /foo/)) print }' BBS-list


88..77..  AAssssiiggnnmmeenntt EExxpprreessssiioonnss

     An _a_s_s_i_g_n_m_e_n_t is an expression that stores a new  value
into  a  variable.  For example, let's assign the value 1 to
the variable z:


    z = 1


     After this expression is executed, the variable  z  has
the value 1.  Whatever old value z had before the assignment
is forgotten.


TThhee GGAAWWKK MMaannuuaall                                           7777


     Assignments can store string values also.  For example,
this  would store the value "this food is good" in the vari-
able message:


    thing = "food"
    predicate = "good"
    message = "this " thing " is " predicate


(This also illustrates concatenation of strings.)

     The `=' sign is called an _a_s_s_i_g_n_m_e_n_t _o_p_e_r_a_t_o_r.   It  is
the  simplest  assignment  operator because the value of the
right-hand operand is stored unchanged.

     Most operators (addition,  concatenation,  and  so  on)
have no effect except to compute a value.  If you ignore the
value, you might as well not use the operator.   An  assign-
ment  operator  is  different;  it does produce a value, but
even if you ignore the value,  the  assignment  still  makes
itself felt through the alteration of the variable.  We call
this a _s_i_d_e _e_f_f_e_c_t.

     The left-hand operand of an assignment need  not  be  a
variable  (see  section   Variables); it can also be a field
(see section  Changing Fields) or an array element (see sec-
tion   Arrays).   These  are all called _l_v_a_l_u_e_s, which means
they can appear on  the  left-hand  side  of  an  assignment
operator.   The right-hand operand may be any expression; it
produces the new value which the assignment  stores  in  the
specified variable, field or array element.

     It is important to note that variables do _n_o_t have per-
manent  types.  The type of a variable is simply the type of
whatever value it happens to hold at  the  moment.   In  the
following  program  fragment, the variable foo has a numeric
value at first, and a string value later on:


    foo = 1
    print foo
    foo = "bar"
    print foo


When the second assignment gives foo  a  string  value,  the
fact that it previously had a numeric value is forgotten.

     An assignment is an expression, so it has a value:  the
same  value  that is assigned.  Thus, z = 1 as an expression
has the value 1.  One consequence of this is  that  you  can


7788                                           TThhee GGAAWWKK MMaannuuaall


write multiple assignments together:


    x = y = z = 0


stores the value 0 in all three  variables.   It  does  this
because  the  value  of z = 0, which is 0, is stored into y,
and then the value of y = z = 0, which is 0, is stored  into
x.

     You can use an assignment  anywhere  an  expression  is
called  for.  For example, it is valid to write x != (y = 1)
to set y to 1 and then test whether x equals  1.   But  this
style  tends to make programs hard to read; except in a one-
shot program, you should rewrite it to get rid of such nest-
ing of assignments.  This is never very hard.

     Aside from `=',  there  are  several  other  assignment
operators that do arithmetic with the old value of the vari-
able.  For example, the operator `+=' computes a  new  value
by adding the right-hand value to the old value of the vari-
able.  Thus, the following assignment adds 5 to the value of
foo:


    foo += 5


This is precisely equivalent to the following:


    foo = foo + 5


Use whichever one makes the meaning of your program clearer.

     Here is a table of the arithmetic assignment operators.
In  each case, the right-hand operand is an expression whose
value is converted to a number.

     _l_v_a_l_u_e += _i_n_c_r_e_m_e_n_t
          Adds _i_n_c_r_e_m_e_n_t to the value of _l_v_a_l_u_e to make  the
          new value of _l_v_a_l_u_e.

     _l_v_a_l_u_e -= _d_e_c_r_e_m_e_n_t
          Subtracts _d_e_c_r_e_m_e_n_t from the value of _l_v_a_l_u_e.

     _l_v_a_l_u_e *= _c_o_e_f_f_i_c_i_e_n_t
          Multiplies the value of _l_v_a_l_u_e by _c_o_e_f_f_i_c_i_e_n_t.


TThhee GGAAWWKK MMaannuuaall                                           7799


     _l_v_a_l_u_e /= _q_u_o_t_i_e_n_t
          Divides the value of _l_v_a_l_u_e by _q_u_o_t_i_e_n_t.

     _l_v_a_l_u_e %= _m_o_d_u_l_u_s
          Sets _l_v_a_l_u_e to its remainder by _m_o_d_u_l_u_s.

     _l_v_a_l_u_e ^= _p_o_w_e_r

     _l_v_a_l_u_e **= _p_o_w_e_r
          Raises _l_v_a_l_u_e to the power _p_o_w_e_r.


88..88..  IInnccrreemmeenntt OOppeerraattoorrss

     _I_n_c_r_e_m_e_n_t _o_p_e_r_a_t_o_r_s increase or decrease the value of a
variable  by 1.  You could do the same thing with an assign-
ment operator, so the increment operators add  no  power  to
the  awk language; but they are convenient abbreviations for
something very common.

     The operator to add 1 is written `++'.  It can be  used
to  increment  a  variable either before or after taking its
value.

     To pre-increment a variable _v, write ++_v.  This adds  1
to  the  value  of _v and that new value is also the value of
this expression.  The assignment expression _v += 1  is  com-
pletely equivalent.

     Writing the `++' after  the  variable  specifies  post-
increment.   This  increments  the  variable  value just the
same; the difference is that  the  value  of  the  increment
expression itself is the variable's _o_l_d value.  Thus, if foo
has value 4, then the expression foo++ has the value 4,  but
it changes the value of foo to 5.

     The post-increment foo++ is nearly equivalent to  writ-
ing  (foo += 1) - 1.  It is not perfectly equivalent because
all numbers in awk are floating point:  in  floating  point,
foo + 1 - 1 does not necessarily equal foo.  But the differ-
ence is minute as long as you  stick  to  numbers  that  are
fairly small (less than a trillion).

     Any lvalue can be incremented.  Fields and  array  ele-
ments are incremented just like variables.

     The decrement operator `--' works just like `++' except
that it subtracts 1 instead of adding.  Like `++', it can be
used before the lvalue  to  pre-decrement  or  after  it  to
post-decrement.

     Here is a summary of increment  and  decrement  expres-
sions.


8800                                           TThhee GGAAWWKK MMaannuuaall


     ++_l_v_a_l_u_e
          This expression  increments  _l_v_a_l_u_e  and  the  new
          value becomes the value of this expression.

     _l_v_a_l_u_e++
          This expression causes the contents of  _l_v_a_l_u_e  to
          be  incremented.   The  value of the expression is
          the _o_l_d value of _l_v_a_l_u_e.

     --_l_v_a_l_u_e
          Like ++_l_v_a_l_u_e, but  instead  of  adding,  it  sub-
          tracts.   It  decrements  _l_v_a_l_u_e  and delivers the
          value that results.

     _l_v_a_l_u_e--
          Like _l_v_a_l_u_e++, but  instead  of  adding,  it  sub-
          tracts.   It  decrements _l_v_a_l_u_e.  The value of the
          expression is the _o_l_d value of _l_v_a_l_u_e.


88..99..  CCoonnvveerrssiioonn ooff SSttrriinnggss aanndd NNuummbbeerrss

     Strings  are  converted  to  numbers,  and  numbers  to
strings,  if the context of the awk program demands it.  For
example, if the value of either foo or bar in the expression
foo  +  bar  happens  to  be  a string, it is converted to a
number before the addition is performed.  If numeric  values
appear  in  string  concatenation,  they  are  converted  to
strings.  Consider this:


    two = 2; three = 3
    print (two three) + 4


This eventually prints the (numeric) value 27.  The  numeric
values  of  the  variables  two  and  three are converted to
strings and concatenated together, and the resulting  string
is  converted  back  to  the  number  23, to which 4 is then
added.

     If, for some reason, you need to force a number  to  be
converted to a string, concatenate the null string with that
number.  To force a string to be converted to a number,  add
zero to that string.

     Strings are converted to numbers by  interpreting  them
as  numerals:  "2.5"  converts to 2.5, and "1e3" converts to
1000.  Strings that can't be interpreted  as  valid  numbers
are converted to zero.

     The exact manner in which numbers  are  converted  into
strings is controlled by the awk built-in variable OFMT (see


TThhee GGAAWWKK MMaannuuaall                                           8811


section  Built-in Variables).  Numbers are converted using a
special   version  of  the  sprintf  function  (see  section
Built-in) with OFMT as the format specifier.

     OFMT's default value is "%.6g", which  prints  a  value
with at least six significant digits.  For some applications
you will want to change it to specify more precision.   Dou-
ble  precision  on  most  modern machines gives you 16 or 17
decimal digits of precision.

     Strange results can happen if you set OFMT to a  string
that  doesn't  tell  sprintf  how  to  format floating point
numbers in a useful way.  For example, if you forget the `%'
in  the  format,  all  numbers will be converted to the same
constant string.

88..1100..  CCoonnddiittiioonnaall EExxpprreessssiioonnss

     A _c_o_n_d_i_t_i_o_n_a_l _e_x_p_r_e_s_s_i_o_n is a special kind  of  expres-
sion  with  three  operands.   It  allows  you  to  use  one
expression's value to select one of two other expressions.

     The conditional expression looks the same as in  the  C
language:


    _s_e_l_e_c_t_o_r ? _i_f-_t_r_u_e-_e_x_p : _i_f-_f_a_l_s_e-_e_x_p


There are three subexpressions.   The  first,  _s_e_l_e_c_t_o_r,  is
always  computed  first.   If it is ``true'' (not zero) then
_i_f-_t_r_u_e-_e_x_p is computed next and its value becomes the value
of  the  whole  expression.  Otherwise, _i_f-_f_a_l_s_e-_e_x_p is com-
puted next and its value becomes  the  value  of  the  whole
expression.

     For example,  this  expression  produces  the  absolute
value of x:


    x > 0 ? x : -x


     Each  time  the  conditional  expression  is  computed,
exactly one of _i_f-_t_r_u_e-_e_x_p and _i_f-_f_a_l_s_e-_e_x_p is computed; the
other is ignored.  This is important  when  the  expressions
contain side effects.  For example, this conditional expres-
sion examines element i of either array a or  array  b,  and
increments i.


    x == y ? a[i++] : b[i++]


8822                                           TThhee GGAAWWKK MMaannuuaall


This is guaranteed to increment i exactly once, because each
time  one  or  the other of the two increment expressions is
executed, and the other is not.

88..1111..  FFuunnccttiioonn CCaallllss

     A _f_u_n_c_t_i_o_n is a  name  for  a  particular  calculation.
Because  it  has  a  name, you can ask for it by name at any
point in the program.  For example, the function  sqrt  com-
putes the square root of a number.

     A fixed set of functions are _b_u_i_l_t _i_n, which means they
are  available  in  every awk program.  The sqrt function is
one of these.  See section Built-in, for a list of  built-in
functions  and  their  descriptions.   In  addition, you can
define your own functions in the program for  use  elsewhere
in  the  same program.  See section User-defined, for how to
do this.

     The way to use a  function  is  with  a  _f_u_n_c_t_i_o_n  _c_a_l_l
expression,  which consists of the function name followed by
a list of  _a_r_g_u_m_e_n_t_s  in  parentheses.   The  arguments  are
expressions which give the raw materials for the calculation
that the function will do.  When  there  is  more  than  one
argument,  they  are  separated  by commas.  If there are no
arguments, write just `()' after the  function  name.   Here
are some examples:


    sqrt(x**2 + y**2)    # One argument
    atan2(y, x)          # Two arguments
    rand()               # No arguments


     DDoo nnoott ppuutt aannyy ssppaaccee bbeettwweeeenn tthhee ffuunnccttiioonn nnaammee aanndd  tthhee
ooppeenn--ppaarreenntthheessiiss!!   A  user-defined function name looks just
like the name of  a  variable,  and  space  would  make  the
expression  look  like  concatenation  of a variable with an
expression inside parentheses.  Space before the parenthesis
is  harmless  with built-in functions, but it is best not to
get into the habit of using space, lest you do likewise  for
a user-defined function one day by mistake.

     Each function expects a particular number of arguments.
For  example, the sqrt function must be called with a single
argument, the number to take the square root of:


    sqrt(_a_r_g_u_m_e_n_t)


TThhee GGAAWWKK MMaannuuaall                                           8833


     Some of the built-in functions allow you  to  omit  the
final  argument.   If  you  do  so,  they  use  a reasonable
default.  See section Built-in, for full details.  If  argu-
ments  are  omitted in calls to user-defined functions, then
those arguments are treated as local variables,  initialized
to the null string (see section  User-defined).

     Like every other expression, the function  call  has  a
value,  which is computed by the function based on the argu-
ments  you  give  it.   In  this  example,  the   value   of
sqrt(_a_r_g_u_m_e_n_t)  is the square root of the argument.  A func-
tion can also have  side  effects,  such  as  assigning  the
values of certain variables or doing I/O.

     Here is a command to read numbers, one number per line,
and print the square root of each one:


    awk '{ print "The square root of", $1, "is", sqrt($1) }'


88..1122..  OOppeerraattoorr PPrreecceeddeennccee:: HHooww OOppeerraattoorrss NNeesstt

     _O_p_e_r_a_t_o_r  _p_r_e_c_e_d_e_n_c_e  determines  how   operators   are
grouped,  when  different  operators  appear close by in one
expression.  For example, `*'  has  higher  precedence  than
`+'; thus, a + b * c means to multiply b and c, and then add
a to the product.

     You can overrule the precedence  of  the  operators  by
writing  parentheses  yourself.   You  can think of the pre-
cedence rules as saying where the parentheses are assumed if
you  do not write parentheses yourself.  In fact, it is wise
always to use parentheses whenever you have an unusual  com-
bination  of  operators,  because  other people who read the
program may not remember what  the  precedence  is  in  this
case.  You might forget, too; then you could make a mistake.
Explicit parentheses will prevent any such mistake.

     When operators of equal precedence are  used  together,
the  leftmost  operator groups first, except for the assign-
ment, conditional and and  exponentiation  operators,  which
group in the opposite order.  Thus, a - b + c groups as (a -
b) + c; a = b = c groups as a = (b = c).

     The precedence  of  prefix  unary  operators  does  not
matter as long as only unary operators are involved, because
there is only  one  way  to  parse  them---innermost  first.
Thus,  $++i  means  $(++i)  and ++$x means ++($x).  However,
when another operator follows the  operand,  then  the  pre-
cedence  of  the  unary  operators  can matter.  Thus, $x**2
means ($x)**2, but -x**2  means  -(x**2),  because  `-'  has
lower precedence than `**' while `$' has higher precedence.


8844                                           TThhee GGAAWWKK MMaannuuaall


     Here is a table of the operators of awk,  in  order  of
increasing precedence:

     assignment
          `=', `+=', `-=', `*=', `/=',  `%=',  `^=',  `**='.
          These operators group right-to-left.

     conditional
          `?:'.  These operators group right-to-left.

     logical ``or''.
          `||'.

     logical ``and''.
          `&&'.

     array membership
          in.

     matching
          `~', `!~'.

     relational, and redirection
          The relational operators and the redirections have
          the same precedence level.  Characters such as `>'
          serve both as relationals and as redirections; the
          context distinguishes between the two meanings.

          The relational  operators  are  `<',  `<=',  `==',
          `!=', `>=' and `>'.

          The I/O redirection operators are `<',  `>',  `>>'
          and `|'.

          Note that I/O redirection operators in  print  and
          printf  statements  belong to the statement level,
          not to expressions.  The redirection does not pro-
          duce  an  expression which could be the operand of
          another operator.  As a result, it does  not  make
          sense  to  use a redirection operator near another
          operator of lower precedence, without parentheses.
          Such  combinations, for example `print foo > a ? b
          : c', result in syntax errors.

     concatentation
          No special token is used  to  indicate  concatena-
          tion.   The  operands  are  simply written side by
          side.

     add, subtract
          `+', `-'.

     multiply, divide, mod
          `*', `/', `%'.


TThhee GGAAWWKK MMaannuuaall                                           8855


     unary plus, minus, ``not''
          `+', `-', `!'.

     exponentiation
          `^', `**'.  These operators group right-to-left.

     increment, decrement
          `++', `--'.

     field
          `$'.


99..  AAccttiioonnss:: CCoonnttrrooll SSttaatteemmeennttss

     _C_o_n_t_r_o_l _s_t_a_t_e_m_e_n_t_s such as if, while, and so on control
the  flow of execution in awk programs.  Most of the control
statements in awk are patterned on similar statements in C.

     All the control statements start with special  keywords
such  as  if  and  while,  to  distinguish  them from simple
expressions.

     Many control statements contain other  statements;  for
example,  the  if statement contains another statement which
may or may not be  executed.   The  contained  statement  is
called  the  _b_o_d_y.   If  you  want  to include more than one
statement in the body, group them  into  a  single  compound
statement  with  curly braces, separating them with newlines
or semicolons.


99..11..  TThhee if SSttaatteemmeenntt

     The if-else statement is awk's  decision-making  state-
ment.  It looks like this:


    if (_c_o_n_d_i_t_i_o_n) _t_h_e_n-_b_o_d_y [else _e_l_s_e-_b_o_d_y]


Here _c_o_n_d_i_t_i_o_n is an expression that controls what the  rest
of  the  statement will do.  If _c_o_n_d_i_t_i_o_n is true, _t_h_e_n-_b_o_d_y
is executed; otherwise, _e_l_s_e-_b_o_d_y is executed (assuming that
the else clause is present).  The else part of the statement
is optional.  The condition is considered false if its value
is zero or the null string, true otherwise.

     Here is an example:


8866                                           TThhee GGAAWWKK MMaannuuaall


    if (x % 2 == 0)
        print "x is even"
    else
        print "x is odd"


     In this example, if the expression x % 2 == 0  is  true
(that  is, the value of x is divisible by 2), then the first
print statement is  executed,  otherwise  the  second  print
statement is performed.

     If the else appears on the same line as _t_h_e_n-_b_o_d_y,  and
_t_h_e_n-_b_o_d_y  is not a compound statement (i.e., not surrounded
by curly braces), then a semicolon must  separate  _t_h_e_n-_b_o_d_y
from  else.   To illustrate this, let's rewrite the previous
example:


        awk '{ if (x % 2 == 0) print "x is even"; else
                print "x is odd" }'


If you forget the `;', awk won't be able to parse the state-
ment, and you will get a syntax error.

     We would not actually  write  this  example  this  way,
because a human reader might fail to see the else if it were
not the first thing on its line.

99..22..  TThhee while SSttaatteemmeenntt

     In programming, a _l_o_o_p means a part of a  program  that
is  (or  at least can be) executed two or more times in suc-
cession.

     The while statement is the simplest  looping  statement
in  awk.   It  repeatedly  executes a statement as long as a
condition is true.  It looks like this:


    while (_c_o_n_d_i_t_i_o_n)
      _b_o_d_y


Here _b_o_d_y is a statement that we call the _b_o_d_y of the  loop,
and  _c_o_n_d_i_t_i_o_n  is  an expression that controls how long the
loop keeps running.


TThhee GGAAWWKK MMaannuuaall                                           8877


     The first thing the while statement does is test _c_o_n_d_i_-
_t_i_o_n.  If _c_o_n_d_i_t_i_o_n is true, it executes the statement _b_o_d_y.
(Truth, as usual in awk, means that the value  of  _c_o_n_d_i_t_i_o_n
is  not  zero  and  not a null string.)  After _b_o_d_y has been
executed, _c_o_n_d_i_t_i_o_n is tested again,  and  if  it  is  still
true,  _b_o_d_y  is  executed again.  This process repeats until
_c_o_n_d_i_t_i_o_n is no longer  true.   If  _c_o_n_d_i_t_i_o_n  is  initially
false, the body of the loop is never executed.

     This example prints the  first  three  fields  of  each
record, one per line.


    awk '{ i = 1
           while (i <= 3) {
               print $i
               i++
           }
    }'


Here the body of the loop is a compound  statement  enclosed
in braces, containing two statements.

     The loop works like this: first, the value of i is  set
to 1.  Then, the while tests whether i is less than or equal
to three.  This is the case when i equals one, so  the  i-th
field  is  printed.   Then the i++ increments the value of i
and the loop repeats.  The loop terminates when i reaches 4.

     As you can see, a newline is not required  between  the
condition  and  the  body;  but  using one makes the program
clearer unless the body is a compound statement or  is  very
simple.   The  newline  after the open-brace that begins the
compound statement is not required either, but  the  program
would be hard to read without it.

99..33..  TThhee do--while SSttaatteemmeenntt

     The do loop is a variation of the while looping  state-
ment.  The do loop executes the _b_o_d_y once, then repeats _b_o_d_y
as long as _c_o_n_d_i_t_i_o_n is true.  It looks like this:


        do
          _b_o_d_y
        while (_c_o_n_d_i_t_i_o_n)


8888                                           TThhee GGAAWWKK MMaannuuaall


     Even if _c_o_n_d_i_t_i_o_n is false at the start, _b_o_d_y  is  exe-
cuted  at  least  once (and only once, unless executing _b_o_d_y
makes _c_o_n_d_i_t_i_o_n true).  Contrast this with the corresponding
while statement:


    while (_c_o_n_d_i_t_i_o_n)
      _b_o_d_y


This statement does not execute _b_o_d_y even once if  _c_o_n_d_i_t_i_o_n
is false to begin with.

     Here is an example of a do statement:


    awk '{ i = 1
           do {
              print $0
              i++
           } while (i <= 10)
    }'


prints each input record ten times.  It isn't a very realis-
tic  example,  since in this case an ordinary while would do
just as well.  But this reflects actual experience; there is
only occasionally a real use for a do statement.

99..44..  TThhee for SSttaatteemmeenntt

     The for statement makes it  more  convenient  to  count
iterations of a loop.  The general form of the for statement
looks like this:


    for (_i_n_i_t_i_a_l_i_z_a_t_i_o_n; _c_o_n_d_i_t_i_o_n; _i_n_c_r_e_m_e_n_t)
      _b_o_d_y


This statement starts by executing _i_n_i_t_i_a_l_i_z_a_t_i_o_n.  Then, as
long  as  _c_o_n_d_i_t_i_o_n is true, it repeatedly executes _b_o_d_y and
then _i_n_c_r_e_m_e_n_t.  Typically _i_n_i_t_i_a_l_i_z_a_t_i_o_n sets a variable to
either  zero  or  one, _i_n_c_r_e_m_e_n_t adds 1 to it, and _c_o_n_d_i_t_i_o_n
compares it against the desired number of iterations.

     Here is an example of a for statement:


    awk '{ for (i = 1; i <= 3; i++)
              print $i


TThhee GGAAWWKK MMaannuuaall                                           8899


    }'


This prints the first three fields of each input record, one
field per line.

     In the for statement, _b_o_d_y stands  for  any  statement,
but _i_n_i_t_i_a_l_i_z_a_t_i_o_n, _c_o_n_d_i_t_i_o_n and _i_n_c_r_e_m_e_n_t are just expres-
sions.  You cannot set more than one variable  in  the  _i_n_i_-
_t_i_a_l_i_z_a_t_i_o_n part unless you use a multiple assignment state-
ment such as x = y = 0, which is possible only  if  all  the
initial  values  are  equal.   (But you can initialize addi-
tional variables by writing their  assignments  as  separate
statements preceding the for loop.)

     The same is true of the _i_n_c_r_e_m_e_n_t  part;  to  increment
additional  variables, you must write separate statements at
the end of the loop.  The C compound expression,  using  C's
comma  operator,  would be useful in this context, but it is
not supported in awk.

     Most often, _i_n_c_r_e_m_e_n_t is an increment expression, as in
the  example above.  But this is not required; it can be any
expression whatever.  For example, this statement prints all
the powers of 2 between 1 and 100:


    for (i = 1; i <= 100; i *= 2)
      print i


     Any of the three expressions in the parentheses follow-
ing for may be omitted if there is nothing to be done there.
Thus,  `for (;x > 0;)'
 is equivalent to  `while (x > 0)' _c_o_n_d_i_t_i_o_n is omitted,  it
is treated as _t_r_u_e, effectively yielding an infinite loop.

     In most cases, a for loop  is  an  abbreviation  for  a
while loop, as shown here:


    _i_n_i_t_i_a_l_i_z_a_t_i_o_n
    while (_c_o_n_d_i_t_i_o_n) {
      _b_o_d_y
      _i_n_c_r_e_m_e_n_t
    }


The only exception is when the continue statement (see  sec-
tion   Continue Statement) is used inside the loop; changing
a for statement to a while statement in this way can  change


9900                                           TThhee GGAAWWKK MMaannuuaall


the effect of the continue statement inside the loop.

     There is an alternate version  of  the  for  loop,  for
iterating over all the indices of an array:


    for (i in array)
        _d_o _s_o_m_e_t_h_i_n_g _w_i_t_h array[i]


See section Arrays, for more information on this version  of
the for loop.

     The awk language has a for statement in addition  to  a
while  statement  because often a for loop is both less work
to type and more natural to think of.  Counting  the  number
of  iterations is very common in loops.  It can be easier to
think of this counting as part of  looping  rather  than  as
something to do inside the loop.

     The next section has more complicated examples  of  for
loops.

99..55..  TThhee break SSttaatteemmeenntt

     The break statement jumps out  of  the  innermost  for,
while,  or  do-while  loop  that encloses it.  The following
example finds the smallest divisor of any integer, and  also
identifies prime numbers:


    awk '# find smallest divisor of num
         { num = $1
           for (div = 2; div*div <= num; div++)
             if (num % div == 0)
               break
           if (num % div == 0)
             printf "Smallest divisor of %d is %d\n", num, div
           else
             printf "%d is prime\n", num  }'


     When the remainder is zero in the first  if  statement,
awk immediately _b_r_e_a_k_s _o_u_t of the containing for loop.  This
means that awk proceeds immediately to the statement follow-
ing  the  loop and continues processing.  (This is very dif-
ferent from the exit statement (see section  Exit Statement)
which stops the entire awk program.)

     Here is another program equivalent to the previous one.
It  illustrates  how  the  _c_o_n_d_i_t_i_o_n of a for or while could
just as well be replaced with a break inside an if:


TThhee GGAAWWKK MMaannuuaall                                           9911


    awk '# find smallest divisor of num
         { num = $1
           for (div = 2; ; div++) {
             if (num % div == 0) {
               printf "Smallest divisor of %d is %d\n", num, div
               break
             }
             if (div*div > num) {
               printf "%d is prime\n", num
               break
             }
           }
    }'


99..66..  TThhee continue SSttaatteemmeenntt

     The continue statement, like break, is used only inside
for,  while,  and do-while loops.  It skips over the rest of
the loop body, causing the next cycle  around  the  loop  to
begin  immediately.   Contrast  this with break, which jumps
out of the loop altogether.  Here is an example:


    # print names that don't contain the string "ignore"

    # first, save the text of each line
    { names[NR] = $0 }

    # print what we're interested in
    END {
       for (x in names) {
           if (names[x] ~ /ignore/)
               continue
           print names[x]
       }
    }


     If one of the input records contains  the  string  `ig-
nore',  this  example  skips  the  print  statement for that
record, and continues back to the  first  statement  in  the
loop.

     This isn't a practical example of  continue,  since  it
would be just as easy to write the loop like this:


    for (x in names)
      if (names[x] !~ /ignore/)
        print names[x]


9922                                           TThhee GGAAWWKK MMaannuuaall


     The continue statement in a for  loop  directs  awk  to
skip  the rest of the body of the loop, and resume execution
with the increment-expression of  the  for  statement.   The
following program illustrates this fact:


    awk 'BEGIN {
         for (x = 0; x <= 20; x++) {
             if (x == 5)
                 continue
             printf ("%d ", x)
         }
         print ""
    }'


This program prints all the numbers from 0 to 20, except for
5, for which the printf is skipped.  Since the increment x++
is not skipped, x does not remain stuck at 5.  Contrast  the
for loop above with the while loop:


    awk 'BEGIN {
         x = 0
         while (x <= 20) {
             if (x == 5)
                 continue
             printf ("%d ", x)
             x++
         }
         print ""
    }'


This program loops forever once x gets to 5.

99..77..  TThhee next SSttaatteemmeenntt

     The next statement forces awk to immediately stop  pro-
cessing  the  current  record  and go on to the next record.
This means that  no  further  rules  are  executed  for  the
current  record.   The  rest of the current rule's action is
not executed either.

     Contrast this with the effect of the  getline  function
(see  section   Getline).   That  too causes awk to read the
next record immediately, but it does not alter the  flow  of
control  in any way.  So the rest of the current action exe-
cutes with a new input record.


TThhee GGAAWWKK MMaannuuaall                                           9933


     At the grossest level, awk program execution is a  loop
that  reads  an input record and then tests each rule's pat-
tern against it.  If you think of this loop as a for  state-
ment  whose body contains the rules, then the next statement
is analogous to a continue statement: it skips to the end of
the  body  of this implicit loop, and executes the increment
(which reads another record).

     For example, if your awk program works only on  records
with  four  fields, and you don't want it to fail when given
bad input, you might use this rule near the beginning of the
program:


    NF != 4 {
      printf("line %d skipped: doesn't have 4 fields", FNR) > "/dev/stderr"
      next
    }


so that the following rules will not  see  the  bad  record.
The error message is redirected to the standard error output
stream, as error messages should be.   See  section  Special
Files.

     The next statement is not allowed in  a  BEGIN  or  END
rule.

99..88..  TThhee exit SSttaatteemmeenntt

     The exit statement causes awk to immediately stop  exe-
cuting  the  current  rule and to stop processing input; any
remaining input is ignored.

     If an exit statement is executed from a BEGIN rule  the
program  stops  processing everything immediately.  No input
records are read.  However, if an END rule is present, it is
executed (see section  BEGIN/END).

     If exit is used as part of an END rule, it  causes  the
program to stop immediately.

     An exit statement that is part an ordinary  rule  (that
is,  not part of a BEGIN or END rule) stops the execution of
any further automatic rules, but the END rule is executed if
there  is one.  If you don't want the END rule to do its job
in this case, you can set a variable to nonzero  before  the
exit statement, and check that variable in the END rule.

     If an argument is supplied to exit, its value  is  used
as the exit status code for the awk process.  If no argument
is supplied, exit returns status zero (success).


9944                                           TThhee GGAAWWKK MMaannuuaall


     For example, let's say you've discovered an error  con-
dition you really don't know how to handle.  Conventionally,
programs report this by exiting with a nonzero status.  Your
awk  program  can  do  this  using  an exit statement with a
nonzero argument.  Here's an example of this:


    BEGIN {
           if (("date" | getline date_now) < 0) {
             print "Can't get system date" > "/dev/stderr"
             exit 4
           }
    }


1100..  AArrrraayyss iinn awk

     An _a_r_r_a_y is a table of various values, called _e_l_e_m_e_n_t_s.
The elements of an array are distinguished by their _i_n_d_i_c_e_s.
Indices may be either numbers or strings.  Each array has  a
name,  which  looks like a variable name, but must not be in
use as a variable name in the same awk program.


1100..11..  IInnttrroodduuccttiioonn ttoo AArrrraayyss

     The awk language has one-dimensional _a_r_r_a_y_s for storing
groups of related strings or numbers.

     Every awk array must have a name.  Array names have the
same syntax as variable names; any valid variable name would
also be a valid array name.  But you cannot use one name  in
both  ways  (as  an array and as a variable) in one awk pro-
gram.

     Arrays in awk superficially resemble  arrays  in  other
programming  languages;  but  there  are fundamental differ-
ences.  In awk, you don't need to specify  the  size  of  an
array  before  you start to use it.  What's more, in awk any
number or even a string may be used as an array index.

     In most other languages, you have to _d_e_c_l_a_r_e  an  array
and specify how many elements or components it has.  In such
languages, the declaration  causes  a  contiguous  block  of
memory  to be allocated for that many elements.  An index in
the array must be a positive integer; for example, the index


TThhee GGAAWWKK MMaannuuaall                                           9955


0  specifies  the first element in the array, which is actu-
ally stored at the beginning of the block of memory.   Index
1  specifies  the  second element, which is stored in memory
right after the first element, and so on.  It is  impossible
to  add  more elements to the array, because it has room for
only as many elements as you declared.

     A contiguous array of four  elements  might  look  like
this,  conceptually,  if the element values are 8, "foo", ""
and 30:


    +---------+---------+--------+---------+
    |    8    |  "foo"  |   ""   |    30   |    value
    +---------+---------+--------+---------+
         0         1         2         3        index


Only the values are stored; the indices  are  implicit  from
the order of the values.  8 is the value at index 0, because
8 appears in the position with 0 elements before it.

     Arrays in awk  are  different:  they  are  _a_s_s_o_c_i_a_t_i_v_e.
This  means  that  each  array  is a collection of pairs: an
index, and its corresponding array element value:


    Element 4     Value 30
    Element 2     Value "foo"
    Element 1     Value 8
    Element 3     Value ""


We have shown the pairs in jumbled order because their order
doesn't mean anything.

     One advantage of an associative array is that new pairs
can  be  added  at any time.  For example, suppose we add to
that array a tenth element whose value is  "number ten"


    Element 10    Value "number ten"
    Element 4     Value 30
    Element 2     Value "foo"
    Element 1     Value 8
    Element 3     Value ""


Now the array is _s_p_a_r_s_e (i.e., some indices are missing): it
has elements 4 and 10, but doesn't have elements 5, 6, 7, 8,
or 9.


9966                                           TThhee GGAAWWKK MMaannuuaall


     Another consequence of associative arrays is  that  the
indices  don't have to be positive integers.  Any number, or
even a string, can be an index.  For  example,  here  is  an
array which translates words from English into French:


    Element "dog" Value "chien"
    Element "cat" Value "chat"
    Element "one" Value "un"
    Element 1     Value "un"


Here we decided to translate the number 1 in  both  spelled-
out and numeric form---thus illustrating that a single array
can have both numbers and strings as indices.

     When awk creates an array for you, e.g., with the split
built-in  function  (see  section   String  Functions), that
array's indices are consecutive integers starting at 1.

1100..22..  RReeffeerrrriinngg ttoo aann AArrrraayy EElleemmeenntt

     The principal way of using an array is to refer to  one
of  its elements.  An array reference is an expression which
looks like this:


    _a_r_r_a_y[_i_n_d_e_x]


Here _a_r_r_a_y is the name of an array.  The expression _i_n_d_e_x is
the index of the element of the array that you want.

     The value of the array reference is the  current  value
of  that array element.  For example, foo[4.3] is an expres-
sion for the element of array foo at index 4.3.

     If you refer to an array element that has  no  recorded
value,  the  value  of the reference is "", the null string.
This includes elements to which you have  not  assigned  any
value,  and  elements  that  have  been deleted (see section
Delete).  Such a reference automatically creates that  array
element, with the null string as its value.  (In some cases,
this is unfortunate, because it might  waste  memory  inside
awk).

     You can find out if an element exists in an array at  a
certain index with the expression:


    _i_n_d_e_x in _a_r_r_a_y


TThhee GGAAWWKK MMaannuuaall                                           9977


This expression tests whether or not  the  particular  index
exists,  without the side effect of creating that element if
it is not present.  The expression has the value 1 (true) if
_a_r_r_a_y[_i_n_d_e_x] exists, and 0 (false) if it does not exist.

     For example, to test whether the array frequencies con-
tains the index "2", you could write this statement:


    if ("2" in frequencies) print "Subscript \"2\" is present."


     Note that this is _n_o_t a test  of  whether  or  not  the
array  frequencies  contains  an element whose _v_a_l_u_e is "2".
(There is no way to do that except  to  scan  all  the  ele-
ments.)   Also, this _d_o_e_s _n_o_t create frequencies["2"], while
the following (incorrect) alternative would do so:


    if (frequencies["2"] != "") print "Subscript \"2\" is present."


1100..33..  AAssssiiggnniinngg AArrrraayy EElleemmeennttss

     Array elements are lvalues: they can be assigned values
just like awk variables:


    _a_r_r_a_y[_s_u_b_s_c_r_i_p_t] = _v_a_l_u_e


Here _a_r_r_a_y is the name of your array.  The  expression  _s_u_b_-
_s_c_r_i_p_t  is  the  index  of the element of the array that you
want to assign a value.  The expression _v_a_l_u_e is  the  value
you are assigning to that element of the array.

1100..44..  BBaassiicc EExxaammppllee ooff aann AArrrraayy

     The following program  takes  a  list  of  lines,  each
beginning  with  a line number, and prints them out in order
of line number.  The line numbers are not in order, however,
when they are first read:  they are scrambled.  This program
sorts the lines by making an array using the line numbers as
subscripts.  It then prints out the lines in sorted order of
their numbers.  It is a very simple program, and  gets  con-
fused if it encounters repeated numbers, gaps, or lines that
don't begin with a number.


9988                                           TThhee GGAAWWKK MMaannuuaall


    {
      if ($1 > max)
        max = $1
      arr[$1] = $0
    }

    END {
      for (x = 1; x <= max; x++)
        print arr[x]
    }


     The first rule keeps track of the largest  line  number
seen so far; it also stores each line into the array arr, at
an index that is the line's number.

     The second rule runs after all the input has been read,
to print out all the lines.

     When this program is run with the following input:


    5  I am the Five man
    2  Who are you?  The new number two!
    4  . . . And four on the floor
    1  Who is number one?
    3  I three you.


its output is this:


    1  Who is number one?
    2  Who are you?  The new number two!
    3  I three you.
    4  . . . And four on the floor
    5  I am the Five man


     If a line number is repeated,  the  last  line  with  a
given number overrides the others.

     Gaps in the line numbers can be handled  with  an  easy
improvement to the program's END rule:


    END {
      for (x = 1; x <= max; x++)


TThhee GGAAWWKK MMaannuuaall                                           9999


        if (x in arr)
          print arr[x]
    }


1100..55..  SSccaannnniinngg AAllll EElleemmeennttss ooff aann AArrrraayy

     In programs that use arrays, often you need a loop that
executes  once  for  each  element  of  an  array.  In other
languages, where arrays are contiguous and indices are  lim-
ited  to  positive integers, this is easy: the largest index
is one less than the length of the array, and you  can  find
all  the  valid  indices  by  counting  from zero up to that
value.  This technique won't do the job in  awk,  since  any
number  or  string may be an array index.  So awk has a spe-
cial kind of for statement for scanning an array:


    for (_v_a_r in _a_r_r_a_y)
      _b_o_d_y


This loop executes _b_o_d_y once for each different  value  that
your  program has previously used as an index in _a_r_r_a_y, with
the variable _v_a_r set to that index.

     Here is a program that uses this form of the for state-
ment.   The  first  rule  scans  the input records and notes
which words appear (at least once) in the input, by  storing
a  1 into the array used with the word as index.  The second
rule scans the elements of used to  find  all  the  distinct
words that appear in the input.  It prints each word that is
more than 10 characters long, and also prints the number  of
such  words.   See section Built-in, for more information on
the built-in function length.


    # Record a 1 for each word that is used at least once.
    {
      for (i = 0; i < NF; i++)
        used[$i] = 1
    }

    # Find number of distinct words more than 10 characters long.
    END {
      num_long_words = 0
      for (x in used)
        if (length(x) > 10) {
          ++num_long_words
          print x
      }
      print num_long_words, "words longer than 10 characters"


110000                                          TThhee GGAAWWKK MMaannuuaall


    }


See section Sample Program, for a more detailed  example  of
this type.

     The order in which elements of the array  are  accessed
by  this statement is determined by the internal arrangement
of the array elements within awk and cannot be controlled or
changed.   This  can  lead  to  problems if new elements are
added to _a_r_r_a_y by statements in  _b_o_d_y;  you  cannot  predict
whether  or  not  the  for loop will reach them.  Similarly,
changing _v_a_r inside the loop can  produce  strange  results.
It is best to avoid such things.

1100..66..  TThhee delete SSttaatteemmeenntt

     You can remove an individual element of an array  using
the delete statement:


    delete _a_r_r_a_y[_i_n_d_e_x]


     When an array element is deleted, it is as if  you  had
never  referred to it and had never given it any value.  Any
value the element formerly had can no longer be obtained.

     Here is an example of deleting elements in an array:


    for (i in frequencies)
      delete frequencies[i]


This example removes all the elements from  the  array  fre-
quencies.

     If you delete an element, a subsequent for statement to
scan  the  array  will  not  report that element, and the in
operator to check for the  presence  of  that  element  will
return 0:


    delete foo[4]
    if (4 in foo)
      print "This will never be printed"


TThhee GGAAWWKK MMaannuuaall                                          110011


1100..77..  MMuullttii--ddiimmeennssiioonnaall AArrrraayyss

     A multi-dimensional array is an array in which an  ele-
ment  is  identified  by a sequence of indices, not a single
index.  For example, a two-dimensional  array  requires  two
indices.   The  usual way (in most languages, including awk)
to refer to an element of a two-dimensional array named grid
is with grid[_x,_y].

     Multi-dimensional arrays are supported in  awk  through
concatenation  of  indices into one string.  What happens is
that awk converts the  indices  into  strings  (see  section
Conversion) and concatenates them together, with a separator
between them.  This creates a single string  that  describes
the  values of the separate indices.  The combined string is
used as a single index  into  an  ordinary,  one-dimensional
array.   The  separator  used  is  the value of the built-in
variable SUBSEP.

     For  example,  suppose  we  evaluate   the   expression
foo[5,12]="value"  when  the  value  of  SUBSEP is "@".  The
numbers 5 and 12 are concatenated with a comma between them,
yielding  "5@12"; thus, the array element foo["5@12"] is set
to "value".

     Once the element's value is stored, awk has  no  record
of  whether  it was stored with a single index or a sequence
of indices.  The two expressions foo[5,12] and  foo[5 SUBSEP
12]
 always have the same value.

     The default value of  SUBSEP  is  actually  the  string
"\034",  which  contains  a  nonprinting  character  that is
unlikely to appear in an awk program or in the input data.

     The usefulness of choosing an unlikely character  comes
from the fact that index values that contain a string match-
ing SUBSEP lead to  combined  strings  that  are  ambiguous.
Suppose that SUBSEP were "@"; then  foo["a@b", "c"]
 and  foo["a", "b@c"]
 would be indistinguishable because both would  actually  be
stored as foo["a@b@c"].  Because SUBSEP is "\034", such con-
fusion can actually happen only when an index  contains  the
character with ASCII code 034, which is a rare event.

     You can test whether a particular index-sequence exists
in  a  ``multi-dimensional'' array with the same operator in
used for single dimensional arrays.   Instead  of  a  single
index  as the left-hand operand, write the whole sequence of
indices, separated by commas, in parentheses:


    (_s_u_b_s_c_r_i_p_t_1, _s_u_b_s_c_r_i_p_t_2, ...) in _a_r_r_a_y


110022                                          TThhee GGAAWWKK MMaannuuaall


     The following  example  treats  its  input  as  a  two-
dimensional  array  of  fields;  it  rotates  this  array 90
degrees clockwise and prints the result.   It  assumes  that
all lines have the same number of elements.


    awk '{
         if (max_nf < NF)
              max_nf = NF
         max_nr = NR
         for (x = 1; x <= NF; x++)
              vector[x, NR] = $x
    }

    END {
         for (x = 1; x <= max_nf; x++) {
              for (y = max_nr; y >= 1; --y)
                   printf("%s ", vector[x, y])
              printf("\n")
         }
    }'


When given the input:


    1 2 3 4 5 6
    2 3 4 5 6 1
    3 4 5 6 1 2
    4 5 6 1 2 3


it produces:


    4 3 2 1
    5 4 3 2
    6 5 4 3
    1 6 5 4
    2 1 6 5
    3 2 1 6


TThhee GGAAWWKK MMaannuuaall                                          110033


1100..88..  SSccaannnniinngg MMuullttii--ddiimmeennssiioonnaall AArrrraayyss

     There is  no  special  for  statement  for  scanning  a
``multi-dimensional'' array; there cannot be one, because in
truth there are no  multi-dimensional  arrays  or  elements;
there is only a multi-dimensional _w_a_y _o_f _a_c_c_e_s_s_i_n_g an array.

     However, if your program has an array  that  is  always
accessed  as  multi-dimensional,  you  can get the effect of
scanning it by combining the  scanning  for  statement  (see
section  Scanning an Array) with the split built-in function
(see section  String Functions).  It works like this:


    for (combined in _a_r_r_a_y) {
      split(combined, separate, SUBSEP)
      ...
    }


This finds each concatenated, combined index in  the  array,
and  splits  it  into  the individual indices by breaking it
apart where the value  of  SUBSEP  appears.   The  split-out
indices become the elements of the array separate.

     Thus, suppose you have previously  stored  in  _a_r_r_a_y[1,
"foo"];  then  an  element  with  index "1\034foo" exists in
_a_r_r_a_y.  (Recall that the default value  of  SUBSEP  contains
the  character  with  code  034.)   Sooner  or later the for
statement will find that index and do an iteration with com-
bined  set to "1\034foo".  Then the split function is called
as follows:


    split("1\034foo", separate, "\034")


The  result  of  this  is  to  set  separate[1]  to  1   and
separate[2]  to  "foo".   Presto,  the  original sequence of
separate indices has been recovered.

1111..  BBuuiilltt--iinn FFuunnccttiioonnss

     _B_u_i_l_t-_i_n functions are functions that are always avail-
able for your awk program to call.  This chapter defines all
the built-in functions in awk; some of them are mentioned in
other  sections,  but they are summarized here for your con-
venience.  (You can also define new functions yourself.  See
section User-defined.)


110044                                          TThhee GGAAWWKK MMaannuuaall


1111..11..  CCaalllliinngg BBuuiilltt--iinn FFuunnccttiioonnss

     To call a built-in function,  write  the  name  of  the
function followed by arguments in parentheses.  For example,
atan2(y + z, 1) is a call to the function  atan2,  with  two
arguments.

     Whitespace is ignored  between  the  built-in  function
name  and  the  open-parenthesis,  but we recommend that you
avoid using whitespace there.  User-defined functions do not
permit  whitespace  in this way, and you will find it easier
to avoid mistakes by following  a  simple  convention  which
always works: no whitespace after a function name.

     Each built-in function  accepts  a  certain  number  of
arguments.   In  most  cases,  any  extra arguments given to
built-in functions are ignored.  The  defaults  for  omitted
arguments  vary  from function to function and are described
under the individual functions.

     When a function is called, expressions that create  the
function's actual parameters are evaluated completely before
the function call is performed.  For example,  in  the  code
fragment:


    i = 4
    j = sqrt(i++)


the variable i is set to 5 before  sqrt  is  called  with  a
value of 4 for its actual parameter.

1111..22..  NNuummeerriicc BBuuiilltt--iinn FFuunnccttiioonnss

     Here is a full list of  built-in  functions  that  work
with numbers:

     int(_x)
          This gives you the integer part  of  _x,  truncated
          toward 0.  This produces the nearest integer to _x,
          located between _x and 0.

          For example, int(3) is 3, int(3.9) is 3, int(-3.9)
          is -3, and int(-3) is -3 as well.

     sqrt(_x)
          This gives you the positive square root of _x.   It
          reports  an error if _x is negative.  Thus, sqrt(4)
          is 2.


TThhee GGAAWWKK MMaannuuaall                                          110055


     exp(_x)
          This gives you the exponential of _x, or reports an
          error if _x is out of range.  The range of values _x
          can have depends on your machine's floating  point
          representation.

     log(_x)
          This gives you the natural logarithm of _x, if _x is
          positive; otherwise, it reports an error.

     sin(_x)
          This gives you the sine of _x, with _x in radians.

     cos(_x)
          This gives you the cosine of _x, with _x in radians.

     atan2(_y, _x)
          This gives you the arctangent of _y / _x,  with  the
          quotient understood in radians.

     rand()
          This gives you a random  number.   The  values  of
          rand  are  uniformly-distributed  between 0 and 1.
          The value is never 0 and never 1.

          Often you want random integers instead.  Here is a
          user-defined function you can use to obtain a ran-
          dom nonnegative integer less than _n:


              function randint(n) {
                   return int(n * rand())
              }


     The multiplication produces a  random  real  number
     greater than 0 and less than _n.  We then make it an
     integer (using int) between 0 and _n - 1.

          Here is an example where a similar function is
          used  to produce random integers between 1 and
          _n:


              awk '
              # Function to roll a simulated die.
              function roll(n) { return 1 + int(rand() * n) }

              # Roll 3 six-sided dice and print total number of points.
              {
                    printf("%d points\n", roll(6)+roll(6)+roll(6))
              }'


110066                                          TThhee GGAAWWKK MMaannuuaall


          NNoottee:: rand starts generating numbers from  the
          same  point,  or  _s_e_e_d, each time you run awk.
          This means that a  program  will  produce  the
          same  results  each  time  you  run  it.   The
          numbers are random within  one  awk  run,  but
          predictable  from  run  to  run.  This is con-
          venient for debugging, but if you want a  pro-
          gram  to  do  different things each time it is
          used, you must change the seed to a value that
          will  be  different  in each run.  To do this,
          use srand.

     srand(_x)
          The function srand sets the starting point, or
          _s_e_e_d,  for  generating  random  numbers to the
          value _x.

          Each seed value leads to a particular sequence
          of  ``random''  numbers.  Thus, if you set the
          seed to the same value a second time, you will
          get  the  same  sequence of ``random'' numbers
          again.

          If you omit the argument  _x,  as  in  srand(),
          then the current date and time of day are used
          for a seed.  This is the  way  to  get  random
          numbers that are truly unpredictable.

          The return value  of  srand  is  the  previous
          seed.  This makes it easy to keep track of the
          seeds for use in consistently reproducing  se-
          quences of random numbers.


1111..33..  BBuuiilltt--iinn FFuunnccttiioonnss ffoorr SSttrriinngg MMaanniippuullaattiioonn

       The functions in this section look at the text of one
or more strings.

     index(_i_n, _f_i_n_d)
          This searches the string  _i_n  for  the  first  oc-
          currence of the string _f_i_n_d, and returns the posi-
          tion where that occurrence begins  in  the  string
          _i_n.  For example:


              awk 'BEGIN { print index("peanut", "an") }'


     prints `3'.  If _f_i_n_d is not found, index returns 0.


TThhee GGAAWWKK MMaannuuaall                                          110077


     length(_s_t_r_i_n_g)
          This gives you the  number  of  characters  in
          _s_t_r_i_n_g.   If _s_t_r_i_n_g is a number, the length of
          the digit string representing that  number  is
          returned.   For example, length("abcde") is 5.
          By contrast, length(15 * 35) works out  to  3.
          How?   Well,  15  *  35 = 525, and 525 is then
          converted to the  string  `"525"',  which  has
          three characters.

          If no argument is supplied, length returns the
          length of $0.

     match(_s_t_r_i_n_g, _r_e_g_e_x_p)
          The  match  function  searches   the   string,
          _s_t_r_i_n_g,  for  the  longest, leftmost substring
          matched by the regular expression, _r_e_g_e_x_p.  It
          returns  the  character position, or _i_n_d_e_x, of
          where that substring begins (1, if  it  starts
          at  the  beginning of _s_t_r_i_n_g).  If no match if
          found, it returns 0.

          The match function sets the built-in  variable
          RSTART  to the index.  It also sets the built-
          in variable  RLENGTH  to  the  length  of  the
          matched  substring.   If  no  match  is found,
          RSTART is set to 0, and RLENGTH to -1.

          For example:


              awk '{
                     if ($1 == "FIND")
                       regex = $2
                     else {
                       where = match($0, regex)
                       if (where)
                         print "Match of", regex, "found at", where, "in", $0
                     }
              }'


     This program looks for lines that match the regular
     expression stored in the variable regex.  This reg-
     ular expression can be changed.  If the first  word
     on  a  line  is  `FIND', regex is changed to be the
     second word on that line.  Therefore, given:


              FIND fo*bar
              My program was a foobar
              But none of it would doobar
              FIND Melvin


110088                                          TThhee GGAAWWKK MMaannuuaall


              JF+KM
              This line is property of The Reality Engineering Co.
              This file created by Melvin.


     awk prints:


              Match of fo*bar found at 18 in My program was a foobar
              Match of Melvin found at 26 in This file created by Melvin.


     split(_s_t_r_i_n_g, _a_r_r_a_y, _f_i_e_l_d_s_e_p)
          This divides _s_t_r_i_n_g up into  pieces  separated
          by  _f_i_e_l_d_s_e_p,  and stores the pieces in _a_r_r_a_y.
          The first piece is  stored  in  _a_r_r_a_y[1],  the
          second  piece  in _a_r_r_a_y[2], and so forth.  The
          string value of the third argument,  _f_i_e_l_d_s_e_p,
          is  used as a regexp to search for to find the
          places to split _s_t_r_i_n_g.  If  the  _f_i_e_l_d_s_e_p  is
          omitted,  the  value of FS is used.  split re-
          turns the number of elements created.

          The split function, then, splits strings  into
          pieces  in  a  manner similar to the way input
          lines are split into fields.  For example:


              split("auto-da-fe", a, "-")


     splits the string `auto-da-fe'  into  three  fields
     using  `-'  as the separator.  It sets the contents
     of the array a as follows:


              a[1] = "auto"
              a[2] = "da"
              a[3] = "fe"


     The value returned by this call to split is 3.

     sprintf(_f_o_r_m_a_t, _e_x_p_r_e_s_s_i_o_n_1,...)
          This returns  (without  printing)  the  string
          that  printf  would  have printed out with the
          same arguments (see section  Printf).  For ex-
          ample:


TThhee GGAAWWKK MMaannuuaall                                          110099


              sprintf("pi = %.2f (approx.)", 22/7)


     returns the string  "pi = 3.14 (approx.)"

     sub(_r_e_g_e_x_p, _r_e_p_l_a_c_e_m_e_n_t, _t_a_r_g_e_t)
          The sub function alters the value  of  _t_a_r_g_e_t.
          It  searches  this  value,  which  should be a
          string, for the leftmost substring matched  by
          the regular expression, _r_e_g_e_x_p, extending this
          match as far as  possible.   Then  the  entire
          string  is  changed  by  replacing the matched
          text with _r_e_p_l_a_c_e_m_e_n_t.   The  modified  string
          becomes the new value of _t_a_r_g_e_t.

          This function is peculiar  because  _t_a_r_g_e_t  is
          not  simply  used  to compute a value, and not
          just any expression will  do:  it  must  be  a
          variable,  field  or  array reference, so that
          sub can store a modified value there.  If this
          argument  is  omitted,  then the default is to
          use and alter $0.

          For example:


              str = "water, water, everywhere"
              sub(/at/, "ith", str)


     sets str to  "wither, water, everywhere" ,  by  re-
     placing  the  leftmost,  longest occurrence of `at'
     with `ith'.

          The sub function returns the number of substi-
          tutions made (either one or zero).

          If the special character `&'  appears  in  _r_e_-
          _p_l_a_c_e_m_e_n_t, it stands for the precise substring
          that was matched by _r_e_g_e_x_p.   (If  the  regexp
          can match more than one string, then this pre-
          cise substring may vary.)  For example:


              awk '{ sub(/candidate/, "& and his wife"); print }'


     changes the  first  occurrence  of  `candidate'  to
     `candidate and his wife' on each input line.


111100                                          TThhee GGAAWWKK MMaannuuaall


          The effect of this special  character  can  be
          turned off by putting a backslash before it in
          the string.  As usual, to insert one backslash
          in the string, you must write two backslashes.
          Therefore, write `\\&' in a string constant to
          include a literal `&' in the replacement.  For
          example, here is how to replace the first  `|'
          on each line with an `&':


              awk '{ sub(/\|/, "\\&"); print }'


          NNoottee:: as mentioned above, the  third  argument
          to  sub  must  be an lvalue.  Some versions of
          awk allow the third argument to be an  expres-
          sion  which is not an lvalue.  In such a case,
          sub would still search for the pattern and re-
          turn  0  or 1, but the result of the substitu-
          tion (if any) would  be  thrown  away  because
          there is no place to put it.  Such versions of
          awk accept expressions like this:


              sub(/USA/, "United States", "the USA and Canada")


     But that is considered erroneous in gawk.

     gsub(_r_e_g_e_x_p, _r_e_p_l_a_c_e_m_e_n_t, _t_a_r_g_e_t)
          This is similar to the  sub  function,  except
          gsub  replaces  _a_l_l  of the longest, leftmost,
          _n_o_n_o_v_e_r_l_a_p_p_i_n_g  matching  substrings  it   can
          find.   The `g' in gsub stands for ``global'',
          which means replace everywhere.  For example:


              awk '{ gsub(/Britain/, "United Kingdom"); print }'


     replaces all occurrences of  the  string  `Britain'
     with `United Kingdom' for all input records.

          The gsub function returns the number  of  sub-
          stitutions   made.   If  the  variable  to  be
          searched and altered, _t_a_r_g_e_t, is omitted, then
          the entire input record, $0, is used.

          As in sub, the characters `&' and `\' are spe-
          cial,  and  the  third  argument  must  be  an
          lvalue.


TThhee GGAAWWKK MMaannuuaall                                          111111


     substr(_s_t_r_i_n_g, _s_t_a_r_t, _l_e_n_g_t_h)
          This returns a _l_e_n_g_t_h-character-long substring
          of _s_t_r_i_n_g, starting at character number _s_t_a_r_t.
          The first character of a string  is  character
          number one.  For example, substr("washington",
          5, 3) returns "ing".

          If _l_e_n_g_t_h is not present,  this  function  re-
          turns  the  whole suffix of _s_t_r_i_n_g that begins
          at  character  number  _s_t_a_r_t.   For   example,
          substr("washington", 5) returns "ington".

     tolower(_s_t_r_i_n_g)
          This returns  a  copy  of  _s_t_r_i_n_g,  with  each
          upper-case  character  in  the string replaced
          with its corresponding  lower-case  character.
          Nonalphabetic  characters  are left unchanged.
          For example, tolower("MiXeD cAsE 123") returns
          "mixed case 123".

     toupper(_s_t_r_i_n_g)
          This returns  a  copy  of  _s_t_r_i_n_g,  with  each
          lower-case  character  in  the string replaced
          with its corresponding  upper-case  character.
          Nonalphabetic  characters  are left unchanged.
          For example, toupper("MiXeD cAsE 123") returns
          "MIXED CASE 123".


1111..44..  BBuuiilltt--iinn FFuunnccttiioonnss FFoorr IInnppuutt//OOuuttppuutt

     close(_f_i_l_e_n_a_m_e)
          Close the file _f_i_l_e_n_a_m_e, for input or output.  The
          argument may alternatively be a shell command that
          was used for redirecting to or from a  pipe;  then
          the pipe is closed.

          See section Close Input, regarding  closing  input
          files  and  pipes.   See section Close Output, re-
          garding closing output files and pipes.

     system(_c_o_m_m_a_n_d)
          The system function allows  the  user  to  execute
          operating  system  commands and then return to the
          awk program.  The  system  function  executes  the
          command  given by the string _c_o_m_m_a_n_d.  It returns,
          as its value, the status returned by  the  command
          that was executed.

          For example, if the following fragment of code  is
          put in your awk program:


              END {


111122                                          TThhee GGAAWWKK MMaannuuaall


                   system("mail -s 'awk run done' operator < /dev/null")
              }


     the system operator will be sent mail when the  awk
     program  finishes  processing  input and begins its
     end-of-input processing.

          Note that much the same result can be obtained
          by  redirecting  print  or printf into a pipe.
          However, if your awk program  is  interactive,
          system  is  useful for cranking up large self-
          contained programs, such as a shell or an edi-
          tor.

          Some operating systems  cannot  implement  the
          system  function.  system causes a fatal error
          if it is not supported.


1122..  UUsseerr--ddeeffiinneedd FFuunnccttiioonnss

     Complicated awk programs can  often  be  simplified  by
defining  your own functions.  User-defined functions can be
called  just  like  built-in  ones  (see  section   Function
Calls),  but  it  is  up to you to define them---to tell awk
what they should do.

1122..11..  SSyynnttaaxx ooff FFuunnccttiioonn DDeeffiinniittiioonnss

     Definitions of functions can  appear  anywhere  between
the  rules of the awk program.  Thus, the general form of an
awk program is extended to include sequences  of  rules  _a_n_d
user-defined function definitions.

     The definition of a  function  named  _n_a_m_e  looks  like
this:


    function _n_a_m_e (_p_a_r_a_m_e_t_e_r-_l_i_s_t) {
         _b_o_d_y-_o_f-_f_u_n_c_t_i_o_n
    }


The keyword function may be abbreviated func.

     _n_a_m_e is the name of the  function  to  be  defined.   A
valid  function  name  is  like  a  valid  variable  name: a
sequence of letters, digits and  underscores,  not  starting
with a digit.


TThhee GGAAWWKK MMaannuuaall                                          111133


     _p_a_r_a_m_e_t_e_r-_l_i_s_t is a list of  the  function's  arguments
and  local  variable  names,  separated by commas.  When the
function is called, the argument names are used to hold  the
argument  values given in the call.  The local variables are
initialized to the null string.

     The _b_o_d_y-_o_f-_f_u_n_c_t_i_o_n consists of awk statements.  It is
the  most  important part of the definition, because it says
what the function should actually _d_o.   The  argument  names
exist  to  give  the body a way to talk about the arguments;
local variables, to give the body places to  keep  temporary
values.

     Argument names are not distinguished syntactically from
local  variable names; instead, the number of arguments sup-
plied when the function is called determines how many  argu-
ment  variables  there  are.  Thus, if three argument values
are given, the first three names in _p_a_r_a_m_e_t_e_r-_l_i_s_t are argu-
ments, and the rest are local variables.

     It follows that if the number of arguments is  not  the
same  in  all  calls  to  the function, some of the names in
_p_a_r_a_m_e_t_e_r-_l_i_s_t may be arguments on some occasions and  local
variables  on  others.  Another way to think of this is that
omitted arguments default to the null string.

     Usually when you write a function  you  know  how  many
names  you  intend  to  use  for  arguments and how many you
intend to use as locals.  By convention, you should write an
extra  space  between  the arguments and the locals, so that
other people can follow how your function is supposed to  be
used.

     During execution of the function  body,  the  arguments
and  local  variable  values hide or _s_h_a_d_o_w any variables of
the same names used in the rest of the  program.   The  sha-
dowed  variables  are not accessible in the function defini-
tion, because there is no way to name them while their names
have  been  taken  away  for the local variables.  All other
variables used in the awk program can be referenced  or  set
normally in the function definition.

     The arguments and local variables last only as long  as
the function body is executing.  Once the body finishes, the
shadowed variables come back.

     The function body can contain  expressions  which  call
functions.    They  can  even  call  this  function,  either
directly or by way of another function.  When this  happens,
we say the function is _r_e_c_u_r_s_i_v_e.

     There is no need in awk to  put  the  definition  of  a
function  before  all uses of the function.  This is because
awk reads the entire program before starting to execute  any


111144                                          TThhee GGAAWWKK MMaannuuaall


of it.

1122..22..  FFuunnccttiioonn DDeeffiinniittiioonn EExxaammppllee

     Here is an example of a user-defined  function,  called
myprint,  that  takes  a  number and prints it in a specific
format.


    function myprint(num)
    {
         printf "%6.3g\n", num
    }


To illustrate, here is an awk rule which  uses  our  myprint
function:


    $3 > 0     { myprint($3) }


This program prints, in our special format,  all  the  third
fields  that contain a positive number in our input.  There-
fore, when given:


     1.2   3.4   5.6   7.8
     9.10 11.12 13.14 15.16
    17.18 19.20 21.22 23.24


this program, using our  function  to  format  the  results,
prints:


       5.6
      13.1
      21.2


     Here is a rather contrived example of a recursive func-
tion.  It prints a string backwards:


    function rev (str, len) {
        if (len == 0) {
            printf "\n"
            return
        }


TThhee GGAAWWKK MMaannuuaall                                          111155


        printf "%c", substr(str, len, 1)
        rev(str, len - 1)
    }


1122..33..  CCaalllliinngg UUsseerr--ddeeffiinneedd FFuunnccttiioonnss

     _C_a_l_l_i_n_g _a _f_u_n_c_t_i_o_n means causing the  function  to  run
and  do  its job.  A function call is an expression, and its
value is the value returned by the function.

     A function call consists of the function name  followed
by the arguments in parentheses.  What you write in the call
for the arguments are awk expressions; each time the call is
executed,  these  expressions  are evaluated, and the values
are the actual arguments.  For example, here is  a  call  to
foo with three arguments:


    foo(x y, "lose", 4 * z)


     NNoottee:: whitespace characters (spaces and tabs)  are  not
allowed  between  the function name and the open-parenthesis
of the argument list.  If you write whitespace  by  mistake,
awk might think that you mean to concatenate a variable with
an expression in parentheses.  However, it notices that  you
used a function name and not a variable name, and reports an
error.

     When a function is called, it is given a  _c_o_p_y  of  the
values of its arguments.  This is called _c_a_l_l _b_y _v_a_l_u_e.  The
caller may use a variable as the expression  for  the  argu-
ment,  but  the  called  function does not know this: all it
knows is what value the argument had.  For example,  if  you
write this code:


    foo = "bar"
    z = myfunc(foo)


then you should not think of the argument to myfunc as being
``the variable foo''.  Instead, think of the argument as the
string value, "bar".

     If the function myfunc alters the values of  its  local
variables,  this  has  no effect on any other variables.  In
particular, if myfunc does this:


111166                                          TThhee GGAAWWKK MMaannuuaall


    function myfunc (win) {
      print win
      win = "zzz"
      print win
    }


to change its first argument variable  win,  this  _d_o_e_s  _n_o_t
change  the  value of foo in the caller.  The role of foo in
calling myfunc ended when its value,  "bar",  was  computed.
If win also exists outside of myfunc, the function body can-
not alter this outer value, because it  is  shadowed  during
the  execution  of myfunc and cannot be seen or changed from
there.

     However, when arrays are the parameters  to  functions,
they  are  _n_o_t  copied.   Instead,  the array itself is made
available for direct manipulation by the function.  This  is
usually  called _c_a_l_l _b_y _r_e_f_e_r_e_n_c_e.  Changes made to an array
parameter inside the body of a function _a_r_e visible  outside
that  function.   _T_h_i_s  _c_a_n  _b_e  _v_e_r_y _d_a_n_g_e_r_o_u_s _i_f _y_o_u _d_o_n'_t
_w_a_t_c_h _w_h_a_t _y_o_u _a_r_e _d_o_i_n_g.  For example:


    function changeit (array, ind, nvalue) {
         array[ind] = nvalue
    }

    BEGIN {
               a[1] = 1 ; a[2] = 2 ; a[3] = 3
               changeit(a, 2, "two")
               printf "a[1] = %s, a[2] = %s, a[3] = %s\n", a[1], a[2], a[3]
          }


prints `a[1] = 1, a[2] = two, a[3]  =  3',  because  calling
changeit stores "two" in the second element of a.

1122..44..  TThhee return SSttaatteemmeenntt

     The body of  a  user-defined  function  can  contain  a
return  statement.   This  statement  returns control to the
rest of the awk program.  It can also be used  to  return  a
value for use in the rest of the awk program.  It looks like
this:


    return _e_x_p_r_e_s_s_i_o_n


TThhee GGAAWWKK MMaannuuaall                                          111177


     The _e_x_p_r_e_s_s_i_o_n part is optional.   If  it  is  omitted,
then   the  returned  value  is  undefined  and,  therefore,
unpredictable.

     A return statement with no value expression is  assumed
at  the  end  of  every  function definition.  So if control
reaches the end of the function definition, then  the  func-
tion returns an unpredictable value.

     Here is an example  of  a  user-defined  function  that
returns a value for the largest number among the elements of
an array:


    function maxelt (vec,   i, ret) {
         for (i in vec) {
              if (ret == "" || vec[i] > ret)
                   ret = vec[i]
         }
         return ret
    }


You call maxelt with one argument, an array name.  The local
variables  i and ret are not intended to be arguments; while
there is nothing to stop you from passing two or three argu-
ments  to  maxelt,  the results would be strange.  The extra
space before i in the function parameter list is to indicate
that  i and ret are not supposed to be arguments.  This is a
convention which you should follow  when  you  define  func-
tions.

     Here is a program that uses our  maxelt  function.   It
loads  an  array, calls maxelt, and then reports the maximum
number in that array:


    awk '
    function maxelt (vec,   i, ret) {
         for (i in vec) {
              if (ret == "" || vec[i] > ret)
                   ret = vec[i]
         }
         return ret
    }

    # Load all fields of each record into nums.
    {
              for(i = 1; i <= NF; i++)
                   nums[NR, i] = $i
    }

    END {


111188                                          TThhee GGAAWWKK MMaannuuaall


         print maxelt(nums)
    }'


     Given the following input:


     1 5 23 8 16
    44 3 5 2 8 26
    256 291 1396 2962 100
    -6 467 998 1101
    99385 11 0 225


our program tells us (predictably) that:


    99385


is the largest number in our array.

1133..  BBuuiilltt--iinn VVaarriiaabblleess

     Most awk variables are available for  you  to  use  for
your  own  purposes; they never change except when your pro-
gram assigns them, and never  affect  anything  except  when
your program examines them.

     A few variables have special built-in  meanings.   Some
of  them awk examines automatically, so that they enable you
to tell awk how  to  do  certain  things.   Others  are  set
automatically  by  awk,  so that they carry information from
the internal workings of awk to your program.

     This chapter documents all the  built-in  variables  of
gawk.   Most  of  them  are  also documented in the chapters
where their areas of activity are described.


1133..11..  BBuuiilltt--iinn VVaarriiaabblleess TThhaatt CCoonnttrrooll awk

     This is a list of the variables which you can change to
control how awk does certain things.

The value is a single-character string or a  multi-character
regular  expression  that  matches  the  separations between
fields in an input record.


TThhee GGAAWWKK MMaannuuaall                                          111199


          The default value is  " " , a string consisting of
          a  single  space.   As  a  special exception, this
          value actually means that any sequence  of  spaces
          and  tabs  is  a single separator.  It also causes
          spaces and tabs at the beginning or end of a  line
          to be ignored.

          You can set the value of FS on  the  command  line
          using the `-F' option:


              awk -F, '_p_r_o_g_r_a_m' _i_n_p_u_t-_f_i_l_e_s


     IGNORECASE
          matching  is  done   in   a   case-independent
          fashion.   In particular, regexp matching with
          `~' and `!~', and the gsub index, match, split
          and  sub  functions all ignore case when doing
          their  particular  regexp  operations.   NNoottee::
          since field splitting with the value of the FS
          variable is also a regular  expression  opera-
          tion, that too is done with case ignored.  See
          section Case-sensitivity.

          If gawk is in compatibility mode (see  section
          Command  Line), then IGNORECASE has no special
          meaning,  and  regexp  operations  are  always
          case-sensitive.

     OFMT
          strings (see section  Conversion).   It  works
          by being passed, in effect, as the first argu-
          ment to the  sprintf  function.   Its  default
          value is "%.6g".

     OFS  output between the fields output  by  a  print
          statement.   Its  default  value  is   " " , a
          string consisting of a single space.

     ORS  print  statement.   Its  default  value  is  a
          string  containing a single newline character,
          which could be written as "\n".  (See  section
          Output Separators).

     RS   containing a single newline  character,  which
          means  that an input record consists of a sin-
          gle line of text.  (See section Records.)

     SUBSEP
          "\034", and is used to separate the  parts  of
          the  name of a multi-dimensional array.  Thus,
          if you access foo[12,3],  it  really  accesses


112200                                          TThhee GGAAWWKK MMaannuuaall


          foo["12\0343"].      (See    section    Multi-
          dimensional).


1133..22..  BBuuiilltt--iinn VVaarriiaabblleess TThhaatt CCoonnvveeyy IInnffoorrmmaattiioonn ttoo YYoouu

     This is a list of the variables that are set  automati-
cally  by awk on certain occasions so as to provide informa-
tion for your program.

     ARGC

     ARGV
          arguments present.  ARGV is indexed from zero to
          ARGC - 1 See section Command Line.  For example:


              awk '{ print ARGV[$1] }' inventory-shipped BBS-list


     In this example, ARGV[0]  contains  "awk",  ARGV[1]
     contains  "inventory-shipped", and ARGV[2] contains
     "BBS-list".  The value of ARGC is 3, one more  than
     the  index  of  the  last element in ARGV since the
     elements are numbered from zero.

          Notice that the awk program is not entered  in
          ARGV.  The other special command line options,
          with their arguments, are  also  not  entered.
          But  variable  assignments on the command line
          _a_r_e treated as arguments, and do  show  up  in
          the ARGV array.

          Your program can alter ARGC and  the  elements
          of  ARGV.  Each time awk reaches the end of an
          input file, it uses the next element  of  ARGV
          as  the name of the next input file.  By stor-
          ing a different string there, your program can
          change  which files are read.  You can use "-"
          to represent the standard input.   By  storing
          additional  elements and incrementing ARGC you
          can cause additional files to be read.

          If you decrease the value of ARGC, that  elim-
          inates  input  files from the end of the list.
          By recording the old value of ARGC  elsewhere,
          your  program  can  treat the eliminated argu-
          ments as something other than file names.

          To eliminate a file from  the  middle  of  the
          list,  store the null string ("") into ARGV in
          place  of  the  file's  name.   As  a  special
          feature, awk ignores file names that have been


TThhee GGAAWWKK MMaannuuaall                                          112211


          replaced with the null string.

     ENVIRON
          This is an array that contains the  values  of
          the  environment.   The  array indices are the
          environment variable names; the values are the
          values  of  the  particular  environment vari-
          ables.  For example, ENVIRON["HOME"] might  be
          `/u/close'.   Changing this array does not af-
          fect the environment passed on to any programs
          that awk may spawn via redirection or the sys-
          tem function.  (In a future version  of  gawk,
          it may do so.)

          Some operating systems may not  have  environ-
          ment  variables.   On  such systems, the array
          ENVIRON is empty.

     FILENAME
          If awk is reading from the standard input  (in
          other  words, there are no files listed on the
          command  line),  FILENAME  is  set   to   "-".
          FILENAME  is  changed  each time a new file is
          read (see section  Reading Files).

     FNR  incremented each time a  new  record  is  read
          (see  section   Getline).  It is reinitialized
          to 0 each time a new input file is started.

     NF   NF is set each time a new record is read, when
          a  new  field  is  created, or when $0 changes
          (see section  Fields).

     NR   the  beginning  of  the  program's  execution.
          (see section  Records).  NR is set each time a
          new record is read.

     RLENGTH
          match  function  (see  section   String  Func-
          tions).   RLENGTH is set by invoking the match
          function.  Its value  is  the  length  of  the
          matched string, or -1 if no match was found.

     RSTART
          match  function  (see  section   String  Func-
          tions).   RSTART  is set by invoking the match
          function.  Its value is the  position  of  the
          string  where the matched substring starts, or
          0 if no match was found.


112222                                          TThhee GGAAWWKK MMaannuuaall


1144..  IInnvvooccaattiioonn ooff awk

     There are two ways to run awk: with  an  explicit  pro-
gram, or with one or more program files.  Here are templates
for both of them; items enclosed in `[...]'  in  these  tem-
plates are optional.


    awk [-F_f_s] [-v _v_a_r=_v_a_l] [-V] [-C] [-c] [-a] [-e] [--] '_p_r_o_g_r_a_m' _f_i_l_e ...
    awk [-F_f_s] -f _s_o_u_r_c_e-_f_i_l_e [-f _s_o_u_r_c_e-_f_i_l_e ...] [-v _v_a_r=_v_a_l] [-V] [-C] [-c] [-a] [-e] [--] _f_i_l_e ...


1144..11..  CCoommmmaanndd LLiinnee OOppttiioonnss

     Options begin with a minus sign, and consist of a  sin-
gle  character.   The options and their meanings are as fol-
lows:

     -F_f_s
          Sets the FS variable to  _f_s  (see  section   Field
          Separators).

     -f _s_o_u_r_c_e-_f_i_l_e
          Indicates that the awk program is to be  found  in
          _s_o_u_r_c_e-_f_i_l_e instead of in the first non-option ar-
          gument.

     -v _v_a_r=_v_a_l
          Sets the variable _v_a_r to the value _v_a_l _b_e_f_o_r_e exe-
          cution  of  the  program  begins.   Such  variable
          values are available inside the  BEGIN  rule  (see
          below for a fuller explanation).

          The `-v' option only has room to set one variable,
          but you can use it more than once, setting another
          variable each time, like this: `  -v foo=1

           -v bar=2 '.

     -a   Specifies use of traditional awk syntax for  regu-
          lar  expressions.  This means that `\' can be used
          to quote any regular expression  operators  inside
          of  square  brackets, just as it can be outside of
          them.  This mode is currently the default; the  `-
          a'  option is useful in shell scripts so that they
          will not break if the  default  is  changed.   See
          section Regexp Operators.

     -e   Specifies use of egrep syntax for regular  expres-
          sions.   This  means  that `\' does not serve as a
          quoting  character  inside  of  square   brackets;


TThhee GGAAWWKK MMaannuuaall                                          112233


          ideosyncratic  techniques  are  needed  to include
          various special characters within them.  This mode
          may become the default at some time in the future.
          See section Regexp Operators.

     -c   Specifies _c_o_m_p_a_t_i_b_i_l_i_t_y _m_o_d_e, in which the GNU ex-
          tensions  in  gawk  are  disabled,  so  that  gawk
          behaves just like Unix awk.  These extensions  are
          noted  below, where their usage is explained.  See
          section Compatibility Mode.

     -V   Prints version  information  for  this  particular
          copy  of  gawk.   This  is so you can determine if
          your copy of gawk is up to date  with  respect  to
          whatever the Free Software Foundation is currently
          distributing.  This option may disappear in a  fu-
          ture version of gawk.

     -C   Prints the short version  of  the  General  Public
          License.   This  option  may disappear in a future
          version of gawk.

     --   Signals the end of the command line options.   The
          following  arguments  are  not  treated as options
          even if they begin with `-'.  This  interpretation
          of `--' follows the POSIX argument parsing conven-
          tions.

          This is useful if you have file names  that  start
          with  `-',  or  in shell scripts, if you have file
          names that will be specified by the user and  that
          might start with `-'.


     Any other options are flagged as invalid with a warning
message, but are otherwise ignored.

     In compatibility mode, as a special case, if the  value
of  _f_s supplied to the `-F' option is `t', then FS is set to
the tab character ("\t").  Also, the `-C' and  `-V'  options
are not recognized.

     If the `-f' option is _n_o_t used,  then  the  first  non-
option  command  line argument is expected to be the program
text.

     The `-f' option may be used more than once on the  com-
mand  line.   Then  awk reads its program source from all of
the named files, as if they had been  concatenated  together
into one big file.  This is useful for creating libraries of
awk functions.  Useful functions can be  written  once,  and
then  retrieved  from a standard place, instead of having to
be included into each individual  program.   You  can  still
type in a program at the terminal and use library functions,


112244                                          TThhee GGAAWWKK MMaannuuaall


by specifying `-f /dev/tty'.  awk will read a file from  the
terminal  to  use  as part of the awk program.  After typing
your program, type Control-d (the end-of-file character)  to
terminate it.

1144..22..  OOtthheerr CCoommmmaanndd LLiinnee AArrgguummeennttss

     Any additional arguments on the command line  are  nor-
mally  treated  as  input files to be processed in the order
specified.   However,  an  argument  that   has   the   form
_v_a_r=_v_a_l_u_e,  means  to assign the value _v_a_l_u_e to the variable
_v_a_r---it does not specify a file at all.

     All these arguments are made available to your awk pro-
gram  in  the  ARGV array (see section  Built-in Variables).
Command line options and the program text (if  present)  are
omitted from the ARGV array.  All other arguments, including
variable assignments, are included.

     The  distinction  between  file  name   arguments   and
variable-assignment  arguments  is made when awk is about to
open the next input file.  At that point  in  execution,  it
checks the ``file name'' to see whether it is really a vari-
able assignment; if so, awk sets  the  variable  instead  of
reading a file.

     Therefore, the variables actually receive the specified
values  after all previously specified files have been read.
In particular, the values  of  variables  assigned  in  this
fashion  are  _n_o_t available inside a BEGIN rule (see section
BEGIN/END), since such rules are run before awk begins scan-
ning the argument list.

     In some earlier implementations of awk, when a variable
assignment  occurred  before  any file names, the assignment
would happen _b_e_f_o_r_e  the  BEGIN  rule  was  executed.   Some
applications came to depend upon this ``feature''.  When awk
was changed to be more consistent, the `-v' option was added
to  accomodate  applications  that  depended  upon  this old
behaviour.

     The variable assignment  feature  is  most  useful  for
assigning  to variables such as RS, OFS, and ORS, which con-
trol input and output  formats,  before  scanning  the  data
files.   It is also useful for controlling state if multiple
passes are needed over a data file.  For example:


    awk 'pass == 1  { _p_a_s_s _1 _s_t_u_f_f }
         pass == 2  { _p_a_s_s _2 _s_t_u_f_f }' pass=1 datafile pass=2 datafile


TThhee GGAAWWKK MMaannuuaall                                          112255


1144..33..  TThhee AWKPATH EEnnvviirroonnmmeenntt VVaarriiaabbllee

     The previous section described how  awk  program  files
can  be  named on the command line with the `-f' option.  In
some awk implementations, you must  supply  a  precise  path
name  for  each  program  file,  unless  the  file is in the
current directory.

     But in gawk, if the file  name  supplied  in  the  `-f'
option  does not contain a `/', then gawk searches a list of
directories (called the _s_e_a_r_c_h _p_a_t_h), one  by  one,  looking
for a file with the specified name.

     The search path is actually a string containing  direc-
tory  names  separated by colons.  gawk gets its search path
from the AWKPATH environment  variable.   If  that  variable
does  not  exist,  gawk  uses  the  default  path,  which is
`.:/usr/lib/awk:/usr/local/lib/awk'.

     The search path  feature  is  particularly  useful  for
building  up libraries of useful awk functions.  The library
files can be placed in a standard directory that is  in  the
default  path, and then specified on the command line with a
short file name.  Otherwise, the full file name  would  have
to be typed for each file.

     Path searching is not done if gawk is in  compatibility
mode.  See section Command Line.

     NNoottee:: if you want files in the current directory to  be
found,  you  must include the current directory in the path,
either by writing `.' as an entry in the path, or by writing
a  null  entry  in  the path.  (A null entry is indicated by
starting or ending the path with a colon, or by placing  two
colons next to each other (`::').)  If the current directory
is not included in the path, then files cannot be  found  in
the current directory.  This path search mechanism is ident-
ical to the shell's.

1155..  TThhee EEvvoolluuttiioonn ooff tthhee awk LLaanngguuaaggee

     This manual describes the GNU  implementation  of  awk,
which  is  patterned  after  the System V Release 4 version.
Many awk users are  only  familiar  with  the  original  awk
implementation  in  Version  7 Unix, which is also the basis
for the version in  Berkeley  Unix.   This  chapter  briefly
describes the evolution of the awk language.


112266                                          TThhee GGAAWWKK MMaannuuaall


1155..11..  MMaajjoorr CChhaannggeess BBeettwweeeenn VV77 aanndd SS55RR33..11

     The  awk  language  evolved  considerably  between  the
release  of  Version 7 Unix (1978) and the new version first
made widely available in System V Release 3.1 (1987).   This
section  summarizes  the  changes,  with cross-references to
further details.

          The requirement for `;' to  separate  rules  on  a
          line (see section  Statements/Lines).

          User-defined functions, and the  return  statement
          (see section  User-defined).

          The delete statement (see section  Delete).

          The do-while statement  (see  section   Do  State-
          ment).

          The built-in functions atan2, cos, sin,  rand  and
          srand (see section  Numeric Functions).

          The built-in functions gsub, sub, and  match  (see
          section  String Functions).

          The built-in functions close and system (see  sec-
          tion  I/O Functions).

          The ARGC, ARGV, FNR, RLENGTH, RSTART,  and  SUBSEP
          built-in  variables  (see  section  Built-in Vari-
          ables).

          The conditional expression using the operators `?'
          and `:' (see section  Conditional Exp).

          The exponentiation operator `^' (see section   Ar-
          ithmetic  Ops)  and  its  assignment operator form
          `^=' (see section  Assignment Ops).

          C-compatible  operator  precedence,  which  breaks
          some old awk programs (see section  Precedence).

          Regexps as the value of  FS  (see  section   Field
          Separators), or as the third argument to the split
          function (see section  String Functions).

          Dynamic regexps as operands of the  `~'  and  `!~'
          operators (see section  Regexp Usage).

          Escape sequences (see section  Constants)  in  re-
          gexps.

          The escape sequences `\b',  `\f',  and  `\r'  (see
          section  Constants).


TThhee GGAAWWKK MMaannuuaall                                          112277


          Redirection of input for the getline function (see
          section  Getline).

          Multiple  BEGIN  and  END   rules   (see   section
          BEGIN/END).

          Simulation of multidimensional arrays (see section
          Multi-dimensional).


1155..22..  MMiinnoorr CChhaannggeess bbeettwweeeenn SS55RR33..11 aanndd SS55RR44

     The System V Release 4 version of Unix awk added  these
features:

          The ENVIRON variable (see section  Built-in  Vari-
          ables).

          Multiple `-f' options on  the  command  line  (see
          section  Command Line).

          The `-v' option  for  assigning  variables  before
          program  execution  begins  (see  section  Command
          Line).

          The `--' option for terminating command  line  op-
          tions.

          The `\a', `\v', and  `\x'  escape  sequences  (see
          section  Constants).

          A defined return  value  for  the  srand  built-in
          function (see section  Numeric Functions).

          The toupper and tolower built-in string  functions
          for  case  translation  (see section  String Func-
          tions).

          A  cleaner  specification  for  the  `%c'  format-
          control letter in the printf function (see section
          Printf).

          The use of constant regexps such as /foo/  as  ex-
          pressions, where they are equivalent to use of the
          matching operator, as in $0 ~ /foo/.


112288                                          TThhee GGAAWWKK MMaannuuaall


1155..33..  EExxtteennssiioonnss IInn gawk NNoott IInn SS55RR44

     The GNU implementation, gawk, adds these features:

          The AWKPATH environment variable for specifying  a
          path  search for the `-f' command line option (see
          section  Command Line).

          The `-C' and `-V' command line options  (see  sec-
          tion  Command Line).

          The IGNORECASE variable and its effects (see  sec-
          tion  Case-sensitivity).

          The  `/dev/stdin',  `/dev/stdout',  `/dev/stderr',
          and `/dev/fd/_n' file name interpretation (see sec-
          tion  Special Files).

          The `-c' option to turn off these extensions  (see
          section  Command Line).

          The `-a' and `-e' options to specify the syntax of
          regular  expressions  that  gawk  will accept (see
          section  Command Line).


AA..  gawk SSuummmmaarryy

     This appendix provides a brief summary of the gawk com-
mand  line and the awk language.  It is designed to serve as
``quick reference.''  It is therefore terse, but complete.

AA..11..  CCoommmmaanndd LLiinnee OOppttiioonnss SSuummmmaarryy

     The command line consists of options  to  gawk  itself,
the  awk program text (if not supplied via the `-f' option),
and values to be made available in the ARGC and ARGV  prede-
fined awk variables:


    awk [-F_f_s] [-v _v_a_r=_v_a_l] [-V] [-C] [-c] [-a] [-e] [--] '_p_r_o_g_r_a_m' _f_i_l_e ...
    awk [-F_f_s] -f _s_o_u_r_c_e-_f_i_l_e [-f _s_o_u_r_c_e-_f_i_l_e ...] [-v _v_a_r=_v_a_l] [-V] [-C] [-c] [-a] [-e] [--] _f_i_l_e ...


     The options that gawk accepts are:

     -F_f_s
          Use _f_s for the input field separator (the value of
          the FS predefined variable).

     -f _p_r_o_g_r_a_m-_f_i_l_e
          Read  the  awk  program  source  from   the   file
          _p_r_o_g_r_a_m-_f_i_l_e,  instead  of  from the first command


TThhee GGAAWWKK MMaannuuaall                                          112299


          line argument.

     -v _v_a_r=_v_a_l
          Assign the variable _v_a_r the value _v_a_l before  pro-
          gram execution begins.

     -a   Specifies use of traditional awk syntax for  regu-
          lar  expressions.  This means that `\' can be used
          to quote regular expression  operators  inside  of
          square  brackets,  just  as  it  can be outside of
          them.

     -e   Specifies use of egrep syntax for regular  expres-
          sions.   This  means  that `\' does not serve as a
          quoting character inside of square brackets.

     -c   Specifies compatibility mode, in which gawk exten-
          sions are turned off.

     -V   Print version information for this particular copy
          of  gawk  on  the  error  output.  This option may
          disappear in a future version of gawk.

     -C   Print the short  version  of  the  General  Public
          License  on  the  error  output.   This option may
          disappear in a future version of gawk.

     --   Signal the end of options.  This is useful to  al-
          low further arguments to the awk program itself to
          start with a `-'.  This is mainly for  consistency
          with the argument parsing conventions of POSIX.


     Any other options are flagged as invalid, but are  oth-
erwise ignored.  See section Command Line, for more details.

AA..22..  LLaanngguuaaggee SSuummmmaarryy

     An awk program consists of a sequence of pattern-action
statements and optional function definitions.


    _p_a_t_t_e_r_n    { _a_c_t_i_o_n _s_t_a_t_e_m_e_n_t_s }

    function _n_a_m_e(_p_a_r_a_m_e_t_e_r _l_i_s_t)     { _a_c_t_i_o_n _s_t_a_t_e_m_e_n_t_s }


     gawk first reads the program source from  the  _p_r_o_g_r_a_m-
_f_i_l_e(s)  if specified, or from the first non-option argument
on the command line.  The `-f' option may be  used  multiple
times on the command line.  gawk reads the program text from
all the _p_r_o_g_r_a_m-_f_i_l_e files, effectively  concatenating  them
in  the  order  they  are  specified.   This  is  useful for


113300                                          TThhee GGAAWWKK MMaannuuaall


building libraries  of  awk  functions,  without  having  to
include them in each new awk program that uses them.  To use
a library function in a file from a program typed in on  the
command line, specify `-f /dev/tty'; then type your program,
and end it with a C-d.  See section Command Line.

     The environment variable  AWKPATH  specifies  a  search
path  to  use  when finding source files named with the `-f'
option.  If the variable AWKPATH is not set, gawk  uses  the
default  path,  `.:/usr/lib/awk:/usr/local/lib/awk'.   If  a
file name given to the `-f' option contains a `/' character,
no  path search is performed.  See section AWKPATH Variable,
for a full description of the AWKPATH environment variable.

     gawk compiles the program into an  internal  form,  and
then proceeds to read each file named in the ARGV array.  If
there are no files named on the command line, gawk reads the
standard input.

     If a ``file'' named on the command line  has  the  form
`_v_a_r=_v_a_l', it is treated as a variable assignment: the vari-
able _v_a_r is assigned the value _v_a_l.

     For each line in the input, gawk tests  to  see  if  it
matches  any  _p_a_t_t_e_r_n  in the awk program.  For each pattern
that the line matches, the associated _a_c_t_i_o_n is executed.

AA..33..  VVaarriiaabblleess aanndd FFiieellddss

     awk variables are dynamic;  they  come  into  existence
when   they   are  first  used.   Their  values  are  either
floating-point  numbers  or  strings.   awk  also  has  one-
dimension  arrays;  multiple-dimensional arrays may be simu-
lated.  There are several predefined variables that awk sets
as a program runs; these are summarized below.


AA..33..11..  FFiieellddss

     As each input line is read, gawk splits the  line  into
_f_i_e_l_d_s,  using  the  value  of  the FS variable as the field
separator.   If  FS  is  a  single  character,  fields   are
separated  by  that character.  Otherwise, FS is expected to
be a full regular expression.  In the special case  that  FS
is  a  single  blank, fields are separated by runs of blanks
and/or tabs.  Note that the value of IGNORECASE (see section
Case-sensitivity)  also affects how fields are split when FS
is a regular expression.

     Each field in the input line may be referenced  by  its
position,  $1,  $2,  and  so on.  $0 is the whole line.  The
value of a field may be assigned to as well.  Field  numbers
need not be constants:


TThhee GGAAWWKK MMaannuuaall                                          113311


    n = 5
    print $n


prints the fifth field in the input line.  The  variable  NF
is set to the total number of fields in the input line.

     References to nonexistent fields  (i.e.,  fields  after
$NF) return the null-string.  However, assigning to a nonex-
istent field (e.g., $(NF+2) = 5) increases the value of  NF,
creates any intervening fields with the null string as their
value, and causes the value of $0 to be recomputed, with the
fields being separated by the value of OFS.

     See section Reading Files, for a  full  description  of
the way awk defines and uses fields.

AA..33..22..  BBuuiilltt--iinn VVaarriiaabblleess

     awk's built-in variables are:

     ARGC
          The number of command line arguments (not  includ-
          ing options or the awk program itself).

     ARGV
          The array of command line arguments.  The array is
          indexed  from 0 to ARGC - 1.  Dynamically changing
          the contents of ARGV can control  the  files  used
          for data.

     ENVIRON
          An array containing the values of the  environment
          variables.  The array is indexed by variable name,
          each element being the  value  of  that  variable.
          Thus,  the  environment  variable HOME would be in
          ENVIRON["HOME"].  Its value might be `/u/close'.

          Changing this array does not affect  the  environ-
          ment  seen  by  programs  which  gawk  spawns  via
          redirection or the  system  function.   (This  may
          change in a future version of gawk.)

          Some operating systems  do  not  have  environment
          variables.   The  array ENVIRON is empty when run-
          ning on these systems.

     FILENAME
          The name of the current input file.  If  no  files
          are  specified  on  the command line, the value of
          FILENAME is `-'.


113322                                          TThhee GGAAWWKK MMaannuuaall


     FNR  The input record number in the current input file.

     FS   The input field separator, a blank by default.

     IGNORECASE
          The case-sensitivity flag for  regular  expression
          operations.   If  IGNORECASE  has a nonzero value,
          then pattern matching in  rules,  field  splitting
          with  FS, regular expression matching with `~' and
          `!~', and the gsub, index, match,  split  and  sub
          predefined  functions  all  ignore case when doing
          regular expression operations.

     NF   The number of fields in the current input record.

     NR   The total number of input records seen so far.

     OFMT
          The output format for numbers, "%.6g" by default.

     OFS  The output field separator, a blank by default.

     ORS  The output record separator, by default a newline.

     RS   The input record separator, by default a  newline.
          RS is exceptional in that only the first character
          of  its  string  value  is  used  for   separating
          records.   If  RS  is set to the null string, then
          records are separated by blank lines.  When RS  is
          set to the null string, then the newline character
          always acts as a field separator, in  addition  to
          whatever value FS may have.

     RSTART
          The index of the first character matched by match;
          0 if no match.

     RLENGTH
          The length of the string matched by match;  -1  if
          no match.

     SUBSEP
          The string used to separate multiple subscripts in
          array elements, by default "\034".


     See section Built-in Variables.


TThhee GGAAWWKK MMaannuuaall                                          113333


AA..33..33..  AArrrraayyss

     Arrays  are  subscripted  with  an  expression  between
square brackets (`[' and `]').  The expression may be either
a number or a string.  Since arrays are associative,  string
indices are meaningful and are not converted to numbers.

     If you use multiple  expressions  separated  by  commas
inside  the  square  brackets, then the array subscript is a
string consisting of the  concatenation  of  the  individual
subscript  values,  converted  to  strings, separated by the
subscript separator (the value of SUBSEP).

     The special operator in may be used in an if  or  while
statement  to  see  if an array has an index consisting of a
particular value.


        if (val in array)
                print array[val]


     If the array has multiple subscripts, use (i,  j,  ...)
in array to test for existence of an element.

     The in construct may also be used  in  a  for  loop  to
iterate  over  all  the  elements  of an array.  See section
Scanning an Array.

     An element may be  deleted  from  an  array  using  the
delete statement.

     See section Arrays, for more detailed information.

AA..33..44..  DDaattaa TTyyppeess

     The value of an  awk  expression  is  always  either  a
number or a string.

     Certain contexts (such as arithmetic operators) require
numeric  values.   They convert strings to numbers by inter-
preting the text of the string as a numeral.  If the  string
does not look like a numeral, it converts to 0.

     Certain contexts (such as concatenation) require string
values.   They  convert  numbers  to  strings by effectively
printing them.

     To force conversion of a string value to a number, sim-
ply  add  0 to it.  If the value you start with is already a
number, this does not change it.


113344                                          TThhee GGAAWWKK MMaannuuaall


     To force conversion of a numeric  value  to  a  string,
concatenate it with the null string.

     The awk language  defines  comparisons  as  being  done
numerically  if possible, otherwise one or both operands are
converted to strings and a string comparison is performed.

     Uninitialized variables have the string value  ""  (the
null,  or  empty,  string).   In  contexts where a number is
required, this is equivalent to 0.

     See section Variables, for more information on variable
naming and initialization; see section  Conversion, for more
information on how variable values are interpreted.

AA..44..  PPaatttteerrnnss aanndd AAccttiioonnss

     An awk program is mostly composed of rules,  each  con-
sisting  of  a pattern followed by an action.  The action is
enclosed in `{' and `}'.  Either the pattern may be missing,
or  the action may be missing, but, of course, not both.  If
the pattern is missing, the action  is  executed  for  every
single  line  of  input.   A missing action is equivalent to
this action,


    { print }


which prints the entire line.

     Comments begin with the  `#'  character,  and  continue
until  the  end  of  the  line.   Blank lines may be used to
separate statements.  Normally, a statement ends with a new-
line,  however,  this  is not the case for lines ending in a
`,', `{', `?', `:', `&&', or `||'.  Lines ending  in  do  or
else  also  have their statements automatically continued on
the following line.  In other cases, a line can be continued
by  ending  it  with  a  `\',  in  which case the newline is
ignored.

     Multiple statements may be put on one line by  separat-
ing  them  with  a `;'.  This applies to both the statements
within the action part of a rule (the usual  case),  and  to
the rule statements themselves.

     See section Comments, for information on awk's comment-
ing   convention;   see  section   Statements/Lines,  for  a
description of the line continuation mechanism in awk.


TThhee GGAAWWKK MMaannuuaall                                          113355


AA..44..11..  PPaatttteerrnnss

     awk patterns may be one of the following:


    /_r_e_g_u_l_a_r _e_x_p_r_e_s_s_i_o_n/
    _r_e_l_a_t_i_o_n_a_l _e_x_p_r_e_s_s_i_o_n
    _p_a_t_t_e_r_n && _p_a_t_t_e_r_n
    _p_a_t_t_e_r_n || _p_a_t_t_e_r_n
    _p_a_t_t_e_r_n ? _p_a_t_t_e_r_n : _p_a_t_t_e_r_n
    (_p_a_t_t_e_r_n)
    ! _p_a_t_t_e_r_n
    _p_a_t_t_e_r_n_1, _p_a_t_t_e_r_n_2
    BEGIN
    END


     BEGIN and END are two special kinds  of  patterns  that
are  not  tested against the input.  The action parts of all
BEGIN rules are merged as if all  the  statements  had  been
written  in  a  single BEGIN rule.  They are executed before
any of the input is read.  Similarly, all the END rules  are
merged,  and  executed  when  all the input is exhausted (or
when an exit statement is executed).  BEGIN and END patterns
cannot  be  combined  with other patterns in pattern expres-
sions.  BEGIN and  END  rules  cannot  have  missing  action
parts.

     For  `/_r_e_g_u_l_a_r-_e_x_p_r_e_s_s_i_o_n/'  patterns,  the  associated
statement  is  executed for each input line that matches the
regular expression.  Regular expressions  are  the  same  as
those in egrep, and are summarized below.

     A _r_e_l_a_t_i_o_n_a_l _e_x_p_r_e_s_s_i_o_n may use any  of  the  operators
defined  below  in  the section on actions.  These generally
test whether certain fields match  certain  regular  expres-
sions.

     The `&&', `||', and `!' operators are logical  ``and'',
logical  ``or'', and logical ``not'', respectively, as in C.
They do short-circuit evaluation, also as in C, and are used
for  combining  more  primitive  pattern expressions.  As in
most languages, parentheses may be used to change the  order
of evaluation.

     The `?:' operator is like the same operator in  C.   If
the  first  pattern  matches,  then  the  second  pattern is
matched against the input record; otherwise,  the  third  is
matched.   Only  one  of  the  second  and third patterns is
matched.

     The `_p_a_t_t_e_r_n_1, _p_a_t_t_e_r_n_2' form of a pattern is called  a
range  pattern.   It matches all input lines starting with a


113366                                          TThhee GGAAWWKK MMaannuuaall


line that matches _p_a_t_t_e_r_n_1, and continuing until a line that
matches _p_a_t_t_e_r_n_2, inclusive.  A range pattern cannot be used
as an operand to any of the pattern operators.

     See section Patterns, for a  full  description  of  the
pattern part of awk rules.

AA..44..22..  RReegguullaarr EExxpprreessssiioonnss

     Regular expressions are  the  extended  kind  found  in
egrep.  They are composed of characters as follows:

     _c    matches the character _c (assuming _c is a character
          with no special meaning in regexps).

     \_c   matches the literal character _c.

     .    matches any character except newline.

     ^    matches the beginning of a line or a string.

     $    matches the end of a line or a string.

     [_a_b_c...]
          matches any of the  characters  _a_b_c...  (character
          class).

     [^_a_b_c...]
          matches any character except  _a_b_c...  and  newline
          (negated character class).

     _r_1|_r_2
          matches either _r_1 or _r_2 (alternation).

     _r_1_r_2
          matches _r_1, and then _r_2 (concatenation).

     _r+   matches one or more _r's.

     _r*   matches zero or more _r's.

     _r?   matches zero or one _r's.

     (_r)  matches _r (grouping).


     See section Regexp, for a more detailed explanation  of
regular expressions.

     The escape sequences allowed in  string  constants  are
also valid in regular expressions (see section  Constants).


TThhee GGAAWWKK MMaannuuaall                                          113377


AA..44..33..  AAccttiioonnss

     Action statements are enclosed in braces, `{' and  `}'.
Action  statements  consist  of the usual assignment, condi-
tional, and looping statements found in most languages.  The
operators,  control  statements, and input/output statements
available are patterned after those in C.


AA..44..33..11..  OOppeerraattoorrss

     The operators in  awk,  in  order  of  increasing  pre-
cedence, are

     = += -= *= /= %= ^=
          Assignment.  Both absolute assignment  (_v_a_r=_v_a_l_u_e)
          and operator assignment (the other forms) are sup-
          ported.

     ?:   A conditional expression, as in C.  This  has  the
          form  _e_x_p_r_1  ?   _e_x_p_r_2 : _e_x_p_r_3.  If _e_x_p_r_1 is true,
          the value of the expression is _e_x_p_r_2; otherwise it
          is _e_x_p_r_3.  Only one of _e_x_p_r_2 and _e_x_p_r_3 is evaluat-
          ed.

     ||   Logical ``or''.

     &&   Logical ``and''.

     ~ !~
          Regular expression match, negated match.

     < <= > >= != ==
          The usual relational operators.

     _b_l_a_n_k
          String concatenation.

     + -  Addition and subtraction.

     * / %
          Multiplication, division, and modulus.

     + - !
          Unary plus, unary minus, and logical negation.

     ^    Exponentiation (`**' may also be used,  and  `**='
          for the assignment operator).

     ++ --
          Increment and decrement, both prefix and postfix.


113388                                          TThhee GGAAWWKK MMaannuuaall


     $    Field reference.


     See section Expressions, for a full description of  all
the  operators  listed  above.   See  section  Fields, for a
description of the field reference operator.

AA..44..33..22..  CCoonnttrrooll SSttaatteemmeennttss

     The control statements are as follows:


    if (_c_o_n_d_i_t_i_o_n) _s_t_a_t_e_m_e_n_t [ else _s_t_a_t_e_m_e_n_t ]
    while (_c_o_n_d_i_t_i_o_n) _s_t_a_t_e_m_e_n_t
    do _s_t_a_t_e_m_e_n_t while (_c_o_n_d_i_t_i_o_n)
    for (_e_x_p_r_1; _e_x_p_r_2; _e_x_p_r_3) _s_t_a_t_e_m_e_n_t
    for (_v_a_r in _a_r_r_a_y) _s_t_a_t_e_m_e_n_t
    break
    continue
    delete _a_r_r_a_y[_i_n_d_e_x]
    exit [ _e_x_p_r_e_s_s_i_o_n ]
    { _s_t_a_t_e_m_e_n_t_s }


     See section Statements, for a full description  of  all
the control statements listed above.

AA..44..33..33..  II//OO SSttaatteemmeennttss

     The input/output statements are as follows:

     getline
          Set $0 from next input record; set NF, NR, FNR.

     getline <_f_i_l_e
          Set $0 from next record of _f_i_l_e; set NF.

     getline _v_a_r
          Set _v_a_r from next input record; set NF, FNR.

     getline _v_a_r <_f_i_l_e
          Set _v_a_r from next record of _f_i_l_e.

     next
          Stop processing the  current  input  record.   The
          next  input  record  is read and processing starts
          over with the first pattern in  the  awk  program.
          If  the  end of the input data is reached, the END
          rule(s), if any, are executed.

     print
          Prints the current record.


TThhee GGAAWWKK MMaannuuaall                                          113399


     print _e_x_p_r-_l_i_s_t
          Prints expressions.

     print _e_x_p_r-_l_i_s_t > _f_i_l_e
          Prints expressions on _f_i_l_e.

     printf _f_m_t, _e_x_p_r-_l_i_s_t
          Format and print.

     printf _f_m_t, _e_x_p_r-_l_i_s_t > file
          Format and print on _f_i_l_e.


     Other input/output redirections are also allowed.   For
print  and  printf,  `>>  _f_i_l_e'  appends output to the _f_i_l_e,
while `| _c_o_m_m_a_n_d' writes on a pipe.  In a  similar  fashion,
`_c_o_m_m_a_n_d  |  getline'  pipes  input  into  getline.  getline
returns 0 on end of file, and -1 on an error.

     See section Getline, for a full description of the get-
line  statement.   See section Printing, for a full descrip-
tion of print and printf.  Finally, see section  Next State-
ment, for a description of how the next statement works.

AA..44..33..44..  printf SSuummmmaarryy

     The awk printf statement and  sprintf  function  accept
the following conversion specification formats:

     %c   An ASCII character.  If the argument used for `%c'
          is  numeric,  it  is  treated  as  a character and
          printed.  Otherwise, the argument is assumed to be
          a  string,  and  the  only first character of that
          string is printed.

     %d   A decimal number (the integer part).

     %i   Also a decimal integer.

     %e   A  floating  point  number   of   the   form   `[-
          ]d.ddddddE[+-]dd'.

     %f   A floating point number of the form [-]ddd.dddddd.

     %g   Use `%e' or `%f' conversion, whichever is shorter,
          with nonsignificant zeros suppressed.

     %o   An unsigned octal number (again, an integer).

     %s   A character string.

     %x   An unsigned hexadecimal number (an integer).


114400                                          TThhee GGAAWWKK MMaannuuaall


     %X   Like `%x', except use `A' through `F'  instead  of
          `a' through `f' for decimal 10 through 15.

     %%   A single `%' character; no argument is converted.


     There are optional, additional parameters that may  lie
between the `%' and the control letter:

     -    The expression should be left-justified within its
          field.

     _w_i_d_t_h
          The field should be  padded  to  this  width.   If
          _w_i_d_t_h has a leading zero, then the field is padded
          with zeros.  Otherwise it is padded with blanks.

     ._p_r_e_c
          A number indicating the maximum width  of  strings
          or digits to the right of the decimal point.


     See  section  Printf,  for  examples  and  for  a  more
detailed description.

AA..44..33..55..  SSppeecciiaall FFiillee NNaammeess

     When doing I/O redirection from either print or  printf
into  a  file,  or  via getline from a file, gawk recognizes
certain special file names  internally.   These  file  names
allow  access to open file descriptors inherited from gawk's
parent process (usually the shell).  The file names are:

     `/dev/stdin'
          The standard input.

     `/dev/stdout'
          The standard output.

     `/dev/stderr'
          The standard error output.

     `/dev/fd/_n'
          The file denoted by the open file descriptor _n.


These file names may also be used on  the  command  line  to
name data files.

     See section Special Files,  for  a  longer  description
that provides the motivation for this feature.


TThhee GGAAWWKK MMaannuuaall                                          114411


AA..44..33..66..  NNuummeerriicc FFuunnccttiioonnss

     awk has the following predefined arithmetic functions:

     atan2(_y, _x)
          returns the arctangent of _y/_x in radians.

     cos(_e_x_p_r)
          returns the cosine in radians.

     exp(_e_x_p_r)
          the exponential function.

     int(_e_x_p_r)
          truncates to integer.

     log(_e_x_p_r)
          the natural logarithm function.

     rand()
          returns a random number between 0 and 1.

     sin(_e_x_p_r)
          returns the sine in radians.

     sqrt(_e_x_p_r)
          the square root function.

     srand(_e_x_p_r)
          use _e_x_p_r as a new seed for the random number  gen-
          erator.   If  no _e_x_p_r is provided, the time of day
          is used.  The return value is  the  previous  seed
          for the random number generator.


AA..44..33..77..  SSttrriinngg FFuunnccttiioonnss

     awk has the following predefined string functions:

     gsub(_r, _s, _t)
          for each substring matching the regular expression
          _r  in  the  string _t, substitute the string _s, and
          return the number of substitutions.  If _t  is  not
          supplied, use $0.

     index(_s, _t)
          returns the index of the string _t in the string _s,
          or 0 if _t is not present.

     length(_s)
          returns the length of the string _s.

     match(_s, _r)
          returns the position in _s where  the  regular  ex-


114422                                          TThhee GGAAWWKK MMaannuuaall


          pression  _r  occurs, or 0 if _r is not present, and
          sets the values of RSTART and RLENGTH.

     split(_s, _a, _r)
          splits the string _s into the array _a on the  regu-
          lar  expression  _r,  and  returns  the  number  of
          fields.  If _r is omitted, FS is used instead.

     sprintf(_f_m_t, _e_x_p_r-_l_i_s_t)
          prints _e_x_p_r-_l_i_s_t according to _f_m_t, and returns the
          resulting string.

     sub(_r, _s, _t)
          this is just like gsub, but only the first  match-
          ing substring is replaced.

     substr(_s, _i, _n)
          returns the _n-character substring of _s starting at
          _i.  If _n is omitted, the rest of _s is used.

     tolower(_s_t_r)
          returns a copy of the string  _s_t_r,  with  all  the
          upper-case  characters  in _s_t_r translated to their
          corresponding lower-case counterparts.   Nonalpha-
          betic characters are left unchanged.

     toupper(_s_t_r)
          returns a copy of the string  _s_t_r,  with  all  the
          lower-case  characters  in _s_t_r translated to their
          corresponding upper-case counterparts.   Nonalpha-
          betic characters are left unchanged.

     system(_c_m_d-_l_i_n_e)
          Execute the command _c_m_d-_l_i_n_e, and return the  exit
          status.


     See section Built-in, for a description of all of awk's
built-in functions.

AA..44..33..88..  SSttrriinngg CCoonnssttaannttss

     String constants in awk  are  sequences  of  characters
enclosed between double quotes (").  Within strings, certain
_e_s_c_a_p_e _s_e_q_u_e_n_c_e_s are recognized, as in C.  These are:

     \\   A literal backslash.

     \a   The ``alert'' character;  usually  the  ASCII  BEL
          character.

     \b   Backspace.


TThhee GGAAWWKK MMaannuuaall                                          114433


     \f   Formfeed.

     \n   Newline.

     \r   Carriage return.

     \t   Horizontal tab.

     \v   Vertical tab.

     \x_h_e_x _d_i_g_i_t_s
          The character represented by the string of hexade-
          cimal  digits  following  the `\x'.  As in ANSI C,
          all following hexadecimal  digits  are  considered
          part of the escape sequence.  (This feature should
          tell us something about language design by commit-
          tee.)   E.g.,  "\x1B"  is  a string containing the
          ASCII ESC (escape) character.

     \_d_d_d
          The character represented by the  1-,  2-,  or  3-
          digit  sequence  of octal digits.  Thus, "\033" is
          also a string containing the  ASCII  ESC  (escape)
          character.

     \_c   The literal character _c.


     The escape sequences may also be used  inside  constant
regular  expressions  (e.g.,  the  regexp   /[ \t\f\n\r\v]/
matches whitespace characters).

     See section Constants.

AA..55..  FFuunnccttiioonnss

     Functions in awk are defined as follows:


    function _n_a_m_e(_p_a_r_a_m_e_t_e_r _l_i_s_t) { _s_t_a_t_e_m_e_n_t_s }


     Actual parameters supplied in  the  function  call  are
used  to  instantiate  the formal parameters declared in the
function.  Arrays are passed by reference,  other  variables
are passed by value.

     If there are fewer  arguments  passed  than  there  are
names  in _p_a_r_a_m_e_t_e_r-_l_i_s_t, the extra names are given the null
string as value.  Extra names have the effect of local vari-
ables.


114444                                          TThhee GGAAWWKK MMaannuuaall


     The open-parenthesis in a function  call  must  immedi-
ately  follow  the  function  name,  without any intervening
white space.  This is to avoid a  syntactic  ambiguity  with
the concatenation operator.

     The word func may be used in place of function.

     See section User-defined, for a more complete  descrip-
tion.

BB..  SSaammppllee PPrrooggrraamm

     The following example is a complete awk program,  which
prints  the number of occurrences of each word in its input.
It illustrates the associative nature of awk arrays by using
strings  as  subscripts.  It also demonstrates the `for _x in
_a_r_r_a_y' construction.  Finally, it shows how awk can be  used
in  conjunction  with  other utility programs to do a useful
task of some complexity with  a  minimum  of  effort.   Some
explanations follow the program listing.


    awk '
    # Print list of word frequencies
    {
        for (i = 1; i <= NF; i++)
            freq[$i]++
    }

    END {
        for (word in freq)
            printf "%s\t%d\n", word, freq[word]
    }'


     The first thing to notice about this program is that it
has two rules.  The first rule, because it has an empty pat-
tern, is executed on every line of the input.  It uses awk's
field-accessing  mechanism (see section  Fields) to pick out
the individual words from the line, and the  built-in  vari-
able  NF  (see section  Built-in Variables) to know how many
fields are available.

     For each input word, an element of the  array  freq  is
incremented  to reflect that the word has been seen an addi-
tional time.

     The second rule, because it has the pattern END, is not
executed  until the input has been exhausted.  It prints out
the contents of the freq table that has been built up inside
the first action.


TThhee GGAAWWKK MMaannuuaall                                          114455


     Note that this program has several problems that  would
prevent it from being useful by itself on real text files:

          Words are detected using the awk  convention  that
          fields  are separated by whitespace and that other
          characters in the input  (except  newlines)  don't
          have  any special meaning to awk.  This means that
          punctuation characters count as part of words.

          The awk language considers upper  and  lower  case
          characters  to  be distinct.  Therefore, `foo' and
          `Foo' are not treated by this program as the  same
          word.   This  is undesirable since in normal text,
          words are capitalized if they begin sentences, and
          a  frequency  analyzer  should not be sensitive to
          that.

          The output does not come out in any useful  order.
          You're more likely to be interested in which words
          occur most frequently, or having  an  alphabetized
          table of how frequently each word occurs.


     The way to solve these problems is to use other  system
utilities to process the input and output of the awk script.
Suppose  the  script  shown  above  is  saved  in  the  file
`frequency.awk'.  Then the shell command:


    tr A-Z a-z < file1 | tr -cd 'a-z\012' \
      | awk -f frequency.awk \
      | sort +1 -nr


produces a table of the words appearing in `file1' in  order
of decreasing frequency.

     The first tr command in this  pipeline  translates  all
the  upper  case  characters  in `file1' to lower case.  The
second tr command deletes all the characters  in  the  input
except lower case characters and newlines.  The second argu-
ment to the second tr is quoted to protect the backslash  in
it  from  being  interpreted  by the shell.  The awk program
reads this suitably massaged data and produces a  word  fre-
quency table, which is not ordered.

     The awk script's output is now sorted by the sort  com-
mand and printed on the terminal.  The options given to sort
in this example specify to sort by the second field of  each
input  line  (skipping one field), that the sort keys should
be treated as numeric quantities (otherwise `15' would  come
before `5'), and that the sorting should be done in descend-
ing (reverse) order.


114466                                          TThhee GGAAWWKK MMaannuuaall


     See the general operating system documentation for more
information on how to use the tr and sort commands.


CC..  IImmpplleemmeennttaattiioonn NNootteess

     This appendix contains information mainly  of  interest
to  implementors  and maintainers of gawk.  Everything in it
applies specifically to gawk, and not to  other  implementa-
tions.


CC..11..  DDoowwnnwwaarrddss CCoommppaattiibbiilliittyy aanndd DDeebbuuggggiinngg

     See section S5R4/GNU, for a summary of the  GNU  exten-
sions  to  the  awk  language  and  program.   All  of these
features can be turned off either by compiling gawk with  `-
DSTRICT'  (not recommended), or by invoking gawk with the `-
c' option.

     If gawk is compiled for debugging with `-DDEBUG',  then
there are two more options available on the command line.

     `-d'
          Print out debugging information during execution.

     `-D'
          Print out the parse stack information as the  pro-
          gram is being parsed.


     Both of these options are  intended  only  for  serious
gawk developers, and not for the casual user.  They probably
have not even been compiled into your version of gawk, since
they slow down execution.

     The code for recognizing special  file  names  such  as
`/dev/stdin'  can  be  disabled  at  compile  time  with  `-
DNO_DEV_FD', or with `-DSTRICT'.

CC..22..  PPrroobbaabbllee FFuuttuurree EExxtteennssiioonnss

     This section briefly lists extensions that indicate the
directions we are currently considering for gawk.

     ANSI C compatible printf
          The printf and sprintf functions may  be  enhanced
          to  be fully compatible with the specification for
          the printf family of functions in ANSI C.


TThhee GGAAWWKK MMaannuuaall                                          114477


     RS as a regexp
          The meaning of RS may  be  generalized  along  the
          lines of FS.

     Control of subprocess environment
          Changes made in gawk to the array ENVIRON  may  be
          propagated to subprocesses run by gawk.

     Data bases
          It may be possible to map an NDBM/GDBM  file  into
          an awk array.

     Single-character fields
          The null string, "", as a  field  separator,  will
          cause  field  splitting  and the split function to
          separate individual  characters.   Thus,  split(a,
          "abcd",  "") would yield a[1] == "a", a[2] == "b",
          and so on.

     Fixed-length fields and records
          A mechanism may be provided to allow the  specifi-
          cation of fixed length fields and records.

     Regexp syntax
          The egrep  syntax  for  regular  expressions,  now
          specified with the `-e' option, may become the de-
          fault, since the POSIX standard may specify this.


CC..33..  SSuuggggeessttiioonnss ffoorr IImmpprroovveemmeennttss

     Here are some projects that would-be gawk hackers might
like to take on.  They vary in size from a few days to a few
weeks of programming, depending on which one you choose  and
how fast a programmer you are.  Please send any improvements
you write to the maintainers at the GNU project.

     1.   State machine regexp  matcher:  At  present,  gawk
          uses  the  backtracking regular expression matcher
          from the GNU subroutine library.  If a  regexp  is
          really going to be used a lot of times, it is fas-
          ter to convert it once to a description of a  fin-
          ite  state  machine, then run a routine simulating
          that machine every time you want to match the  re-
          gexp.   You might be able to use the matching rou-
          tines used by GNU egrep.

     2.   Compilation of awk programs:  gawk  uses  a  Bison
          (YACC-like)  parser to convert the script given it
          into a syntax tree; the syntax tree is  then  exe-
          cuted  by  a  simple recursive evaluator.  Both of
          these steps incur a lot of overhead, since parsing


114488                                          TThhee GGAAWWKK MMaannuuaall


          can  be slow (especially if you also do the previ-
          ous project and  convert  regular  expressions  to
          finite state machines at compile time) and the re-
          cursive evaluator performs many procedure calls to
          do even the simplest things.

          It should be possible  for  gawk  to  convert  the
          script's  parse  tree  into  a C program which the
          user would then compile, using the normal  C  com-
          piler  and  a  special gawk library to provide all
          the needed functions (regexps, fields, associative
          arrays, type coercion, and so on).

          An easier possibility might be for an intermediate
          phase  of  awk  to  convert  the parse tree into a
          linear byte code form like the  one  used  in  GNU
          Emacs Lisp.  The recursive evaluator would then be
          replaced by a straight line byte code  interpreter
          that  would  be intermediate in speed between run-
          ning a compiled program and doing what  gawk  does
          now.

     3.   An error message section has not been included  in
          this  version  of  the  manual.  Perhaps some nice
          beta testers will document some  of  the  messages
          for the future.


DD..  GGlloossssaarryy

     Action
          A series of awk statements attached to a rule.  If
          the  rule's  pattern  matches an input record, the
          awk language executes the rule's action.   Actions
          are  always enclosed in curly braces.  See section
          Actions.

     Amazing awk Assembler
          Henry Spencer at the University of Toronto wrote a
          retargetable  assembler completely as awk scripts.
          It is thousands of lines long,  including  machine
          descriptions for several 8-bit microcomputers.  It
          is distributed with gawk and is a good example  of
          a  program  that would have been better written in
          another language.

     Assignment
          An awk expression that changes the value  of  some
          awk  variable  or data object.  An object that you
          can assign to is called an  _l_v_a_l_u_e.   See  section
          Assignment Ops.

     awk Language
          The language in which awk programs are written.


TThhee GGAAWWKK MMaannuuaall                                          114499


     awk Program
          An awk program consists of a  series  of  _p_a_t_t_e_r_n_s
          and  _a_c_t_i_o_n_s,  collectively  known  as _r_u_l_e_s.  For
          each  input  record  given  to  the  program,  the
          program's  rules  are  all processed in turn.  awk
          programs may also contain function definitions.

     awk Script
          Another name for an awk program.

     Built-in Function
          The awk language provides built-in functions  that
          perform various numerical and string computations.
          Examples are  sqrt  (for  the  square  root  of  a
          number)  and substr (for a substring of a string).
          See section Built-in.

     Built-in Variable
          The variables ARGC, ARGV, ENVIRON,  FILENAME, FNR,
          FS,  NF,  IGNORECASE, NR, OFMT, OFS, ORS, RLENGTH,
          RSTART, RS, and SUBSEP, have  special  meaning  to
          awk.   Changing some of them affects awk's running
          environment.  See section Built-in Variables.

     C    The system  programming  language  that  most  GNU
          software  is  written  in.   The  awk  programming
          language has C-like syntax, and this manual points
          out  similarities between awk and C when appropri-
          ate.

     Compound Statement
          A series of  awk  statements,  enclosed  in  curly
          braces.   Compound  statements may be nested.  See
          section Statements.

     Concatenation
          Concatenating two strings means sticking them  to-
          gether,  one  after  another, giving a new string.
          For example, the string  `foo'  concatenated  with
          the  string  `bar' gives the string `foobar'.  See
          section Concatenation.

     Conditional Expression
          An expression using  the  `?:'  ternary  operator,
          such  as  _e_x_p_r_1  ?  _e_x_p_r_2 : _e_x_p_r_3.  The expression
          _e_x_p_r_1 is evaluated; if the  result  is  true,  the
          value  of  the  whole  expression  is the value of
          _e_x_p_r_2 otherwise the value  is  _e_x_p_r_3.   In  either
          case,  only  one  of _e_x_p_r_2 and _e_x_p_r_3 is evaluated.
          See section Conditional Exp.

     Constant Regular Expression
          A constant regular expression is a regular expres-
          sion  written  within  slashes,  such  as `/foo/'.


115500                                          TThhee GGAAWWKK MMaannuuaall


          This regular expression is chosen when  you  write
          the  awk  program, and cannot be changed doing its
          execution.  See section Regexp Usage.

     Comparison Expression
          A relation that is either true or false,  such  as
          (a  <  b).   Comparison expressions are used in if
          and while statements, and in  patterns  to  select
          which  input records to process.  See section Com-
          parison Ops.

     Curly Braces
          The characters `{' and `}'.  Curly braces are used
          in  awk  for  delimiting  actions, compound state-
          ments, and function bodies.

     Data Objects
          These  are  numbers  and  strings  of  characters.
          Numbers are converted into strings and vice versa,
          as needed.  See section Conversion.

     Dynamic Regular Expression
          A dynamic regular expression is a regular  expres-
          sion  written as an ordinary expression.  It could
          be a string constant, such as "foo",  but  it  may
          also  be  an expression whose value may vary.  See
          section Regexp Usage.

     Escape Sequences
          A special sequence of characters used for describ-
          ing  nonprinting characters, such as `\n' for new-
          line, or `\033' for the ASCII ESC (escape) charac-
          ter.  See section Constants.

     Field
          When awk reads an  input  record,  it  splits  the
          record  into pieces separated by whitespace (or by
          a separator regexp which you can change by setting
          the built-in variable FS).  Such pieces are called
          fields.  See section Records.

     Format
          Format strings are used to control the  appearance
          of  output  in  the  printf statement.  Also, data
          conversions from numbers to strings are controlled
          by  the  format  string  contained in the built-in
          variable OFMT.  See section Control Letters;  also
          see section  Output Separators.

     Function
          A specialized group of statements  often  used  to
          encapsulate  general  or  program-specific  tasks.
          awk has a number of built-in functions,  and  also
          allows  you  to  define  your  own.   See  section


TThhee GGAAWWKK MMaannuuaall                                          115511


          Built-in; also see section  User-defined.

     gawk
          The GNU implementation of awk.

     Input Record
          A single chunk of data read in by  awk.   Usually,
          an  awk input record consists of one line of text.
          See section Records.

     Keyword
          In the awk language, a keyword is a word that  has
          special  meaning.   Keywords  are reserved and may
          not be used as variable names.

          The  keywords  of  awk  are:  if,   else,   while,
          do...while,   for,   for...in,   break,  continue,
          delete, next, function, func, and exit.

     Lvalue
          An expression that can appear on the left side  of
          an   assignment   operator.   In  most  languages,
          lvalues can be variables or  array  elements.   In
          awk,  a  field  designator  can also be used as an
          lvalue.

     Number
          A numeric valued data object.  The gawk  implemen-
          tation  uses  double  precision  floating point to
          represent numbers.

     Pattern
          Patterns tell awk  which  input  records  are  in-
          teresting to which rules.

          A pattern is an arbitrary  conditional  expression
          against  which  input is tested.  If the condition
          is satisfied, the pattern is said to _m_a_t_c_h the in-
          put  record.   A typical pattern might compare the
          input record against a  regular  expression.   See
          section Patterns.

     Range (of input lines)
          A sequence of consecutive  lines  from  the  input
          file.  A pattern can specify ranges of input lines
          for awk to  process,  or  it  can  specify  single
          lines.  See section Patterns.

     Recursion
          When a function calls itself, either  directly  or
          indirectly.  If this isn't clear, refer to the en-
          try for ``recursion''.


115522                                          TThhee GGAAWWKK MMaannuuaall


     Redirection
          Redirection means performing input from other than
          the standard input stream, or output to other than
          the standard output stream.

          You can redirect  the  output  of  the  print  and
          printf  statements  to a file or a system command,
          using the `>', `>>', and `|' operators.   You  can
          redirect  input to the getline statement using the
          `<' and `|' operators.  See section Redirection.

     Regular Expression
          See ``regexp''.

     Regexp
          Short for _r_e_g_u_l_a_r _e_x_p_r_e_s_s_i_o_n.  A regexp is a  pat-
          tern  that  denotes  a set of strings, possibly an
          infinite set.  For  example,  the  regexp  `R.*xp'
          matches  any  string  starting with the letter `R'
          and ending with the letters `xp'.  In awk, regexps
          are  used  in  patterns and in conditional expres-
          sions.  Regexps may contain escape sequences.  See
          section Regexp.

     Rule
          A segment of an awk program, that specifies how to
          process  single input records.  A rule consists of
          a _p_a_t_t_e_r_n and  an  _a_c_t_i_o_n.   awk  reads  an  input
          record;  then,  for each rule, if the input record
          satisfies the rule's  pattern,  awk  executes  the
          rule's  action.   Otherwise, the rule does nothing
          for that input record.

     Side Effect
          A side effect occurs when an expression has an ef-
          fect aside from merely producing a value.  Assign-
          ment expressions, increment expressions and  func-
          tion calls have side effects.  See section Assign-
          ment Ops.

     Special File
          A file name interpreted internally  by  gawk,  in-
          stead  of  being handed directly to the underlying
          operating system.  For example, `/dev/stdin'.  See
          section Special Files.

     Stream Editor
          A program that reads records from an input  stream
          and processes them one or more at a time.  This is
          in contrast with batch programs, which may  expect
          to  read  their  input  files  in  entirety before
          starting to do anything, and with interactive pro-
          grams, which require input from the user.


TThhee GGAAWWKK MMaannuuaall                                          115533


     String
          A datum consisting of a  sequence  of  characters,
          such  as  `I  am  a string'.  Constant strings are
          written with double-quotes in  the  awk  language,
          and  may  contain  _e_s_c_a_p_e  _s_e_q_u_e_n_c_e_s.  See section
          Constants.

     Whitespace
          A sequence of blank or  tab  characters  occurring
          inside an input record or a string.


IInnddeexx


TThhee GGAAWWKK MMaannuuaall                                            ii


                        TTaabbllee ooff CCoonntteennttss


Preface ...............................................    2
History of awk aanndd gawk ...............................    33
GGNNUU GGeenneerraall PPuubblliicc LLiicceennssee ............................    33
PPrreeaammbbllee ..............................................    33
TTEERRMMSS AANNDD CCOONNDDIITTIIOONNSS ..................................    44
NNOO WWAARRRRAANNTTYY ...........................................    77
EENNDD OOFF TTEERRMMSS AANNDD CCOONNDDIITTIIOONNSS ...........................    88
AAppppeennddiixx:: UUssiinngg TThheessee TTeerrmmss iinn NNeeww PPrrooggrraammss ...........    88
11       UUssiinngg TThhiiss MMaannuuaall .............................   1100
11..11      DDaattaa FFiilleess ffoorr tthhee EExxaammpplleess ..................   1100
22       GGeettttiinngg SSttaarrtteedd WWiitthh awk ......................   1122
22..11      AA VVeerryy SSiimmppllee EExxaammppllee ........................   1122
22..22      AAnn EExxaammppllee wwiitthh TTwwoo RRuulleess ....................   1133
22..33      AA MMoorree CCoommpplleexx EExxaammppllee .......................   1144
22..44      HHooww ttoo RRuunn awk PPrrooggrraammss ......................   1166
22..44..11    OOnnee--sshhoott TThhrrooww--aawwaayy awk PPrrooggrraammss .............   1166
22..44..22    RRuunnnniinngg awk wwiitthhoouutt IInnppuutt FFiilleess ..............   1177
22..44..33    RRuunnnniinngg LLoonngg PPrrooggrraammss ........................   1188
22..44..44    EExxeeccuuttaabbllee awk PPrrooggrraammss ......................   1188
22..55      CCoommmmeennttss iinn awk PPrrooggrraammss .....................   2200
22..66      awk SSttaatteemmeennttss vveerrssuuss LLiinneess ..................   2200
22..77      WWhheenn ttoo UUssee awk ..............................   2211
33       RReeaaddiinngg IInnppuutt FFiilleess ...........................   2222
33..11      HHooww IInnppuutt iiss SSpplliitt iinnttoo RReeccoorrddss ..............   2233
33..22      EExxaammiinniinngg FFiieellddss .............................   2244
33..33      NNoonn--ccoonnssttaanntt FFiieelldd NNuummbbeerrss ...................   2255
33..44      CChhaannggiinngg tthhee CCoonntteennttss ooff aa FFiieelldd .............   2266
33..55      SSppeecciiffyyiinngg HHooww FFiieellddss AArree SSeeppaarraatteedd ..........   2288
33..66      MMuullttiippllee--LLiinnee RReeccoorrddss ........................   3311
33..77      EExxpplliicciitt IInnppuutt wwiitthh getline ..................   3322
33..88      CClloossiinngg IInnppuutt FFiilleess aanndd PPiippeess ................   3388
44       PPrriinnttiinngg OOuuttppuutt ...............................   3399
44..11      TThhee print SSttaatteemmeenntt ..........................   3399
44..22      EExxaammpplleess ooff print SSttaatteemmeennttss .................   4400
44..33      OOuuttppuutt SSeeppaarraattoorrss ............................   4422
44..44
     UUssiinngg printf SSttaatteemmeennttss FFoorr FFaanncciieerr PPrriinnttiinngg .....   4433
44..44..11    IInnttrroodduuccttiioonn ttoo tthhee printf SSttaatteemmeenntt .........   4433
44..44..22    FFoorrmmaatt--CCoonnttrrooll LLeetttteerrss .......................   4433
44..44..33    MMooddiiffiieerrss ffoorr printf FFoorrmmaattss .................   4455
44..44..44    EExxaammpplleess ooff UUssiinngg printf .....................   4466
44..55      RReeddiirreeccttiinngg OOuuttppuutt ooff print aanndd printf .......   4477
44..55..11    RReeddiirreeccttiinngg OOuuttppuutt ttoo FFiilleess aanndd PPiippeess ........   4488
44..55..22    CClloossiinngg OOuuttppuutt FFiilleess aanndd PPiippeess ...............   4499
44..66      SSttaannddaarrdd II//OO SSttrreeaammss .........................   5511
55       UUsseeffuull ````OOnnee--lliinneerrss'''' .........................   5522
66       PPaatttteerrnnss ......................................   5533
66..11      KKiinnddss ooff PPaatttteerrnnss ............................   5533
66..22      TThhee EEmmppttyy PPaatttteerrnn ............................   5544
66..33      RReegguullaarr EExxpprreessssiioonnss aass PPaatttteerrnnss ..............   5544
66..33..11    HHooww ttoo UUssee RReegguullaarr EExxpprreessssiioonnss ...............   5555


iiii                                           TThhee GGAAWWKK MMaannuuaall


66..33..22    RReegguullaarr EExxpprreessssiioonn OOppeerraattoorrss .................   5566
66..33..33    CCaassee--sseennssiittiivviittyy iinn MMaattcchhiinngg .................   6600
66..44      CCoommppaarriissoonn EExxpprreessssiioonnss aass PPaatttteerrnnss ...........   6611
66..55      BBoooolleeaann OOppeerraattoorrss aanndd PPaatttteerrnnss ...............   6633
66..66      EExxpprreessssiioonnss aass PPaatttteerrnnss ......................   6644
66..77      SSppeecciiffyyiinngg RReeccoorrdd RRaannggeess WWiitthh PPaatttteerrnnss .......   6644
66..88      BEGIN aanndd END SSppeecciiaall PPaatttteerrnnss ...............   6655
77       AAccttiioonnss:: OOvveerrvviieeww .............................   6666
88       AAccttiioonnss:: EExxpprreessssiioonnss ..........................   6677
88..11      CCoonnssttaanntt EExxpprreessssiioonnss .........................   6688
88..22      VVaarriiaabblleess ....................................   7700
88..22..11    AAssssiiggnniinngg VVaarriiaabblleess oonn tthhee CCoommmmaanndd LLiinnee ......   7700
88..33      AArriitthhmmeettiicc OOppeerraattoorrss .........................   7711
88..44      SSttrriinngg CCoonnccaatteennaattiioonn .........................   7722
88..55      CCoommppaarriissoonn EExxpprreessssiioonnss .......................   7733
88..66      BBoooolleeaann EExxpprreessssiioonnss ..........................   7755
88..77      AAssssiiggnnmmeenntt EExxpprreessssiioonnss .......................   7766
88..88      IInnccrreemmeenntt OOppeerraattoorrss ..........................   7799
88..99      CCoonnvveerrssiioonn ooff SSttrriinnggss aanndd NNuummbbeerrss ............   8800
88..1100      CCoonnddiittiioonnaall EExxpprreessssiioonnss .....................   8811
88..1111      FFuunnccttiioonn CCaallllss ..............................   8822
88..1122      OOppeerraattoorr PPrreecceeddeennccee:: HHooww OOppeerraattoorrss NNeesstt .....   8833
99       AAccttiioonnss:: CCoonnttrrooll SSttaatteemmeennttss ...................   8855
99..11      TThhee if SSttaatteemmeenntt .............................   8855
99..22      TThhee while SSttaatteemmeenntt ..........................   8866
99..33      TThhee do--while SSttaatteemmeenntt .......................   8877
99..44      TThhee for SSttaatteemmeenntt ............................   8888
99..55      TThhee break SSttaatteemmeenntt ..........................   9900
99..66      TThhee continue SSttaatteemmeenntt .......................   9911
99..77      TThhee next SSttaatteemmeenntt ...........................   9922
99..88      TThhee exit SSttaatteemmeenntt ...........................   9933
1100      AArrrraayyss iinn awk .................................   9944
1100..11      IInnttrroodduuccttiioonn ttoo AArrrraayyss ......................   9944
1100..22      RReeffeerrrriinngg ttoo aann AArrrraayy EElleemmeenntt ...............   9966
1100..33      AAssssiiggnniinngg AArrrraayy EElleemmeennttss ....................   9977
1100..44      BBaassiicc EExxaammppllee ooff aann AArrrraayy ...................   9977
1100..55      SSccaannnniinngg AAllll EElleemmeennttss ooff aann AArrrraayy ...........   9999
1100..66      TThhee delete SSttaatteemmeenntt ........................  110000
1100..77      MMuullttii--ddiimmeennssiioonnaall AArrrraayyss ....................  110011
1100..88      SSccaannnniinngg MMuullttii--ddiimmeennssiioonnaall AArrrraayyss ...........  110033
1111      BBuuiilltt--iinn FFuunnccttiioonnss ............................  110033
1111..11      CCaalllliinngg BBuuiilltt--iinn FFuunnccttiioonnss ..................  110044
1111..22      NNuummeerriicc BBuuiilltt--iinn FFuunnccttiioonnss ..................  110044
1111..33      BBuuiilltt--iinn FFuunnccttiioonnss ffoorr SSttrriinngg MMaanniippuullaattiioonn
     ..................................................  110066
1111..44      BBuuiilltt--iinn FFuunnccttiioonnss FFoorr IInnppuutt//OOuuttppuutt .........  111111
1122      UUsseerr--ddeeffiinneedd FFuunnccttiioonnss ........................  111122
1122..11      SSyynnttaaxx ooff FFuunnccttiioonn DDeeffiinniittiioonnss ..............  111122
1122..22      FFuunnccttiioonn DDeeffiinniittiioonn EExxaammppllee .................  111144
1122..33      CCaalllliinngg UUsseerr--ddeeffiinneedd FFuunnccttiioonnss ..............  111155
1122..44      TThhee return SSttaatteemmeenntt ........................  111166
1133      BBuuiilltt--iinn VVaarriiaabblleess ............................  111188
1133..11      BBuuiilltt--iinn VVaarriiaabblleess TThhaatt CCoonnttrrooll awk .........  111188
1133..22                                          BBuuiilltt--


TThhee GGAAWWKK MMaannuuaall                                          iiiiii


     iinn VVaarriiaabblleess TThhaatt CCoonnvveeyy IInnffoorrmmaattiioonn ttoo YYoouu ......  112200
1144      IInnvvooccaattiioonn ooff awk .............................  112222
1144..11      CCoommmmaanndd LLiinnee OOppttiioonnss ........................  112222
1144..22      OOtthheerr CCoommmmaanndd LLiinnee AArrgguummeennttss ................  112244
1144..33      TThhee AWKPATH EEnnvviirroonnmmeenntt VVaarriiaabbllee ............  112255
1155      TThhee EEvvoolluuttiioonn ooff tthhee awk LLaanngguuaaggee .............  112255
1155..11      MMaajjoorr CChhaannggeess BBeettwweeeenn VV77 aanndd SS55RR33..11 .........  112266
1155..22      MMiinnoorr CChhaannggeess bbeettwweeeenn SS55RR33..11 aanndd SS55RR44 .......  112277
1155..33      EExxtteennssiioonnss IInn gawk NNoott IInn SS55RR44 ..............  112288
AA       gawk SSuummmmaarryy ..................................  112288
AA..11      CCoommmmaanndd LLiinnee OOppttiioonnss SSuummmmaarryy .................  112288
AA..22      LLaanngguuaaggee SSuummmmaarryy .............................  112299
AA..33      VVaarriiaabblleess aanndd FFiieellddss .........................  113300
AA..33..11    FFiieellddss .......................................  113300
AA..33..22    BBuuiilltt--iinn VVaarriiaabblleess ...........................  113311
AA..33..33    AArrrraayyss .......................................  113333
AA..33..44    DDaattaa TTyyppeess ...................................  113333
AA..44      PPaatttteerrnnss aanndd AAccttiioonnss .........................  113344
AA..44..11    PPaatttteerrnnss .....................................  113355
AA..44..22    RReegguullaarr EExxpprreessssiioonnss ..........................  113366
AA..44..33    AAccttiioonnss ......................................  113377
AA..44..33..11  OOppeerraattoorrss ....................................  113377
AA..44..33..22  CCoonnttrrooll SSttaatteemmeennttss ...........................  113388
AA..44..33..33  II//OO SSttaatteemmeennttss ...............................  113388
AA..44..33..44  printf SSuummmmaarryy ...............................  113399
AA..44..33..55  SSppeecciiaall FFiillee NNaammeess ...........................  114400
AA..44..33..66  NNuummeerriicc FFuunnccttiioonnss ............................  114411
AA..44..33..77  SSttrriinngg FFuunnccttiioonnss .............................  114411
AA..44..33..88  SSttrriinngg CCoonnssttaannttss .............................  114422
AA..55      FFuunnccttiioonnss ....................................  114433
BB       SSaammppllee PPrrooggrraamm ................................  114444
CC       IImmpplleemmeennttaattiioonn NNootteess ..........................  114466
CC..11      DDoowwnnwwaarrddss CCoommppaattiibbiilliittyy aanndd DDeebbuuggggiinngg ........  114466
CC..22      PPrroobbaabbllee FFuuttuurree EExxtteennssiioonnss ...................  114466
CC..33      SSuuggggeessttiioonnss ffoorr IImmpprroovveemmeennttss .................  114477
DD       GGlloossssaarryy ......................................  114488
IInnddeexx .................................................  115533


TThhee GGAAWWKK MMaannuuaall                                            ii


                     TTaabbllee ooff CCoonntteennttss


c uses of awk   2 c acronym   3  c  history  of  awk    3  c
manual, using this   10 c using this manual   10 c language,
awk   10 c program, awk   10 c awk language   10 c awk  pro-
gram   10 c input file, sample   10 c sample input file   10
c BBS-list file   10 c inventory-shipped file   11 c script,
definition  of    12  c  rule, definition of   12 c program,
definition of   12 c basic function of gawk   12 c print  $0
12  c action, default   13 c pattern, default   13 c default
action   13 c default pattern   13 c how awk  works    13  c
command line formats   16 c running awk programs   16 c sin-
gle quotes, why needed   16 c standard input   17  c  input,
standard   17 c case sensitivity   17 c pattern, case sensi-
tive   17 c running long programs   18 c -f  option    18  c
program  file    18  c  file,  awk program   18 c executable
scripts   18 c scripts, executable    18  c  self  contained
programs    18  c  program,  self contained   18 c #!   18 c
shell scripts   19 c scripts, shell   19 c comments    20  c
use  of comments   20 c documenting awk programs   20 c pro-
grams, documenting   20 c backslash continuation   20 c con-
tinuation  of  lines    20 c multiple statements on one line
21 c when to use awk   21 c applications of awk   21 c read-
ing files   22 c input   22 c standard input   22 v FILENAME
22 c record separator   23 c number of records,  NR  or  FNR
24  v  NR    24  v FNR   24 c examining fields   24 c fields
24 c accessing fields   24  c  $  (field  operator)    24  c
operators,  $    24  v NF   25 c number of fields, NF   25 c
field, changing contents of   26 c changing  contents  of  a
field    26  c assignment to fields   26 v FS   28 c fields,
separating   28 c field separator, FS   28 c -F option    28
c  field  separator, choice of   28 c regular expressions as
field separators   28 c field separator, setting on  command
line   29 c command line, setting FS on   29 c multiple line
records   31 c input, multiple line records   31  c  reading
files,  multiple  line records   31 c records, multiple line
31 f getline   32 c input, explicit   32  c  explicit  input
32  c  input,  getline command   32 c reading files, getline
command   32 c input redirection   35 c redirection of input
35  c  closing  input  files  and  pipes   38 f close   38 c
printing   39 c output   39 c print statement   39 c  output
field  separator,  OFS    42  v OFS   42 v ORS   42 c output
record separator, ORS   42 c formatted output   43 c output,
formatted    43  c printf statement, syntax of   43 c format
string   43 c printf, format-control characters   43 c  for-
mat  specifier   43 c printf, modifiers   45 c modifiers (in
format specifiers)   45 c output redirection   47 c redirec-
tion of output   47 c pipes for output   48 c output, piping
48 c closing output files and pipes    49  f  close    49  c
standard  input   51 c standard output   51 c standard error
output   51 c file descriptors    51  c  /dev/stdin    51  c
/dev/stdout    51  c /dev/stderr   51 c /dev/fd/   51 c one-
liners   52 c pattern, definition of   53 c patterns,  types
of    53  c  empty pattern   54 c pattern, empty   54 c pat-
tern, regular expressions    54  c  regexp    54  c  regular
expressions  as  patterns   54 c regular expression matching


operators   55 c string-matching operators   55 c operators,
string-matching    55 c operators, regular expression match-
ing   55 c regexp search operators   55 c  computed  regular
expressions    55  c  regular  expressions,  computed   55 c
dynamic regular expressions   55  c  metacharacters    56  c
regular  expression metacharacters   56 c comparison expres-
sions as patterns   61  c  pattern,  comparison  expressions
61  c relational operators   61 c operators, relational   61
c patterns, boolean   63 c boolean  patterns    63  c  range
pattern    64 c patterns, range   64 c BEGIN special pattern
65 c patterns, BEGIN   65 c END special pattern   65 c  pat-
terns,  END   65 c action, definition of   66 c curly braces
66 c action, curly braces   66 c action,  separating  state-
ments    66  c  expression   67 c constants, types of   68 c
string constants   68 c  numeric  constant    68  c  numeric
value    68  c  escape  sequence  notation   68 c variables,
user-defined   70 c user-defined variables   70 c arithmetic
operators    71 c operators, arithmetic   71 c addition   71
c subtraction   71 c multiplication   71 c division    71  c
remainder    71  c  quotient    71  c  exponentiation   71 c
string operators   72 c operators, string   72 c  concatena-
tion    72 c comparison expressions   73 c expressions, com-
parison   73 c relational operators   73 c operators,  rela-
tional    73  c regexp operators   73 c regexp as expression
75 c expressions, boolean   75 c boolean expressions   75  c
operators,  boolean    75 c boolean operators   75 c logical
operations   75 c and operator   75 c or operator   75 c not
operator    75  c  assignment  operators    76  c operators,
assignment   76 c expressions, assignment   76 c side effect
77  c  lvalue    77  c increment operators   79 c operators,
increment   79 c conversion of strings and  numbers    80  v
OFMT   80 c conditional expression   81 c expression, condi-
tional   81 c function call   82 c calling a function   82 c
arguments in function call   82 c precedence   83 c operator
precedence   83 c control statement   85 c if statement   85
c  while  statement   86 c loop   86 c body of a loop   86 c
for statement   88 c break statement   90 c  loops,  exiting
90  c  continue  statement   91 c next statement   92 c exit
statement   93 c arrays   94 c arrays, definition of   95  c
associative  arrays   95 c array reference   96 c element of
array   96 c reference to array   96 c  arrays,  determining
presence  of elements   96 c array assignment   97 c element
assignment   97 c for (x in ...)   99 c arrays, special  for
statement    99  c scanning an array   99 c delete statement
100 c deleting elements of arrays   100 c removing  elements
of  arrays    100 c arrays, deleting an element   100 c sub-
scripts, multi-dimensional in arrays   101 c arrays,  multi-
dimensional  subscripts   101 c multi-dimensional subscripts
101 v SUBSEP   101 c built-in functions   103 f match    106
f  length   107 f match   107 v RSTART   107 v RLENGTH   107
f split   108 f sprintf   108 f sub   109  f  gsub    110  f
substr    111 f tolower   111 f toupper   111 f system   111
c interaction of awk  with  other  programs    111  c  user-
defined  functions    112  c functions, user-defined   112 c


defining functions   112 c function definition   112 c  call
by  value   115 c call by reference   116 c return statement
116 c built-in variables   118 c  built-in  variables,  user
modifiable    118  v  ENVIRON    121  c command line   122 c
invocation of gawk   122 c arguments, command line    122  c
options,  command  line    122 c -v option   122 c -c option
123 c -V option   123 c -C option   123 v ARGV   124 c  mul-
tiple passes over data   124 c passes, multiple   124 c AWK-
PATH environment variable   125 c search path   125 c direc-
tory search   125 c path, search   125