home *** CD-ROM | disk | FTP | other *** search
/ Frostbyte's 1980s DOS Shareware Collection / floppyshareware.zip / floppyshareware / USCX / GAWK_SRC.ZIP / GAWK.DOC < prev    next >
Text File  |  1989-04-13  |  35KB  |  1,057 lines

  1.  
  2.  
  3.  
  4. GAWK(1)                  USER COMMANDS                    GAWK(1)
  5.  
  6.  
  7.  
  8. NAME
  9.      gawk - pattern scanning and processing language
  10.  
  11. SYNOPSIS
  12.      gawk [ -Ffs ] -f program-file [ -f program-file ... ] [ -- ]
  13.      file ...
  14.      gawk [ -Ffs ] [ -- ] program-text file ...
  15.  
  16. DESCRIPTION
  17.      Gawk is the GNU Project's implementation of the AWK program-
  18.      ming  language.   It conforms to the definition and descrip-
  19.      tion of the language in The  AWK  Programming  Language,  by
  20.      Aho, Kernighan, and Weinberger, with the additional features
  21.      defined in the System V Release 4 version of UNIX awk.
  22.  
  23.      The command line consists of options to gawk itself, the AWK
  24.      program text (if not supplied via the -f option), and values
  25.      to be made available in the ARGC and  ARGV  pre-defined  AWK
  26.      variables.
  27.  
  28.      The options that gawk accepts are:
  29.  
  30.      -Ffs Use fs for the input field separator (the value of  the
  31.           FS predefined variable).
  32.  
  33.      -f program-file
  34.           Read the AWK program source from the file program-file,
  35.           instead of from the first command line argument.
  36.  
  37.      --   Signal the end of options.  This  is  useful  to  allow
  38.           further  arguments  to  the AWK program itself to start
  39.           with a ``-''.  This is mainly for consistency with  the
  40.           argument parsing convention used by most other System V
  41.           programs.
  42.  
  43.      Any other options are flagged as illegal, but are  otherwise
  44.      ignored.  (However, see the GNU EXTENSIONS section, below.)
  45.  
  46.      An AWK program consists  of  a  sequence  of  pattern-action
  47.      statements and optional function definitions.
  48.  
  49.           pattern   { action statements }
  50.           function name(parameter list) { statements }
  51.  
  52.      Gawk first reads the program source from the program-file(s)
  53.      if  specified,  or from the first non-option argument on the
  54.      command line.  The -f option may be used multiple  times  on
  55.      the command line.  Gawk will read the program text as if all
  56.      the program-files had been concatenated together.   This  is
  57.      useful for building libraries of AWK functions, without hav-
  58.      ing to include them in each new AWK program that uses  them.
  59.      To  use a library function in a file from a program typed in
  60.  
  61.  
  62.  
  63. Sun Release 4.0 Last change: Free Software Foundation             1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. GAWK(1)                  USER COMMANDS                    GAWK(1)
  71.  
  72.  
  73.  
  74.      on  the  command  line,  specify  /dev/tty  as  one  of  the
  75.      program-files,  type  your  program,  and  end  it with a ^D
  76.      (control-d).
  77.  
  78.      The environment variable AWKPATH specifies a search path  to
  79.      use  when finding source files named with the -f option.  If
  80.      this  variable  does  not  exist,  the   default   path   is
  81.      ".:/usr/lib/awk:/usr/local/lib/awk".   If  a file name given
  82.      to the -f option contains a ``/'' character, no path  search
  83.      is performed.
  84.  
  85.      Gawk compiles the program into an internal  form,  and  then
  86.      proceeds  to  read  each  file  named in the ARGV array.  If
  87.      there are no files named on the command line, gawk reads the
  88.      standard input.
  89.  
  90.      If a ``file'' named on the command line has the form var=val
  91.      it  is  treated  as  a variable assignment. The variable var
  92.      will be assigned the value val.  This  is  most  useful  for
  93.      dynamically  assigning  values  to the variables AWK uses to
  94.      control how input is broken into fields and records.  It  is
  95.      also  useful  for  controlling  state if multiple passes are
  96.      needed over a single data file.
  97.  
  98.      For each line in the input, gawk tests to see if it  matches
  99.      any  pattern  in the AWK program.  For each pattern that the
  100.      line matches, the associated action is executed.
  101.  
  102. VARIABLES AND FIELDS
  103.      AWK variables are dynamic; they  come  into  existence  when
  104.      they  are first used. Their values are either floating-point
  105.      numbers or strings, depending upon how they  are  used.  AWK
  106.      also  has  single  dimension  arrays;  multiply  dimensioned
  107.      arrays may be  simulated.   There  are  several  pre-defined
  108.      variables  that  AWK  sets  as a program runs; these will be
  109.      described as needed and summarized below.
  110.  
  111.      As each input line  is  read,  gawk  splits  the  line  into
  112.      fields,  using  the  value  of  the FS variable as the field
  113.      separator.   If  FS  is  a  single  character,  fields   are
  114.      separated  by  that character.  Otherwise, FS is expected to
  115.      be a full regular expression.  In the special case  that  FS
  116.      is  a  single  blank, fields are separated by runs of blanks
  117.      and/or tabs.  Note that the value of IGNORECASE (see  below)
  118.      will  also  affect how fields are split when FS is a regular
  119.      expression.
  120.  
  121.      Each field in the input line may be referenced by its  posi-
  122.      tion, $1, $2, and so on.  $0 is the whole line. The value of
  123.      a field may be assigned to as  well.   Fields  need  not  be
  124.      referenced by constants:
  125.  
  126.  
  127.  
  128.  
  129. Sun Release 4.0 Last change: Free Software Foundation             2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. GAWK(1)                  USER COMMANDS                    GAWK(1)
  137.  
  138.  
  139.  
  140.           n = 5
  141.           print $n
  142.  
  143.      prints the fifth field in the input line.  The  variable  NF
  144.      is set to the total number of fields in the input line.
  145.  
  146.      References to non-existent fields (i.e. fields  after  $NF),
  147.      produce  the  null-string.  However,  assigning  to  a  non-
  148.      existent field (e.g., $(NF+2) = 5) will increase  the  value
  149.      of NF, create any intervening fields with the null string as
  150.      their value, and cause the value of  $0  to  be  recomputed,
  151.      with the fields being separated by the value of OFS.
  152.  
  153.   Built-in Variables
  154.      AWK's built-in variables are:
  155.  
  156.           ARGC the number of command  line  arguments  (does  not
  157.                include options to gawk, or the program source).
  158.  
  159.           ARGV array of command  line  arguments.  The  array  is
  160.                indexed  from 0 to ARGC - 1.  Dynamically changing
  161.                the contents of ARGV can control  the  files  used
  162.                for data.
  163.  
  164.           ENVIRON
  165.                An array containing  the  values  of  the  current
  166.                environment.  The array is indexed by the environ-
  167.                ment variables, each element being  the  value  of
  168.                that  variable  (e.g.,  ENVIRON["HOME"]  might  be
  169.                /u/arnold).  Changing this array does  not  affect
  170.                the environment seen by programs which gawk spawns
  171.                via redirection or the system function.
  172.  
  173.           FILENAME
  174.                the name of the current input file.  If  no  files
  175.                are  specified  on  the command line, the value of
  176.                FILENAME is ``-''.
  177.  
  178.           FNR  the input record number in the current input file.
  179.  
  180.           FS   the input field separator, a blank by default.
  181.  
  182.           IGNORECASE
  183.                Controls  the  case-sensitivity  of  all   regular
  184.                expression  operations.  If  IGNORECASE has a non-
  185.                zero value, then pattern matching in rules,  field
  186.                splitting  with  FS,  regular  expression matching
  187.                with ~ and !~, and the gsub(),  match(),  split(),
  188.                and  sub()  pre-defined  functions will all ignore
  189.                case when  doing  regular  expression  operations.
  190.                Thus,  if  IGNORECASE  is  not equal to zero, /aB/
  191.                matches all of the strings "ab", "aB",  "Ab",  and
  192.  
  193.  
  194.  
  195. Sun Release 4.0 Last change: Free Software Foundation             3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. GAWK(1)                  USER COMMANDS                    GAWK(1)
  203.  
  204.  
  205.  
  206.                "AB".   As  with  all  AWK  variables, the initial
  207.                value  of  IGNORECASE  is  zero,  so  all  regular
  208.                expression operations are normally case-sensitive.
  209.  
  210.           NF   the number of fields in the current input record.
  211.  
  212.           NR   the total number of input records seen so far.
  213.  
  214.           OFMT the output format for numbers, %.6g by default.
  215.  
  216.           OFS  the output field separator, a blank by default.
  217.  
  218.           ORS  the output record separator, by default a newline.
  219.  
  220.           RS   the input record separator, by default a  newline.
  221.                RS is exceptional in that only the first character
  222.                of  its  string  value  is  used  for   separating
  223.                records.  If  RS  is  set to the null string, then
  224.                records are separated by blank lines.  When RS  is
  225.                set to the null string, then the newline character
  226.                always acts as a field separator, in  addition  to
  227.                whatever value FS may have.
  228.  
  229.           RSTART
  230.                the  index  of  the  first  character  matched  by
  231.                match(); 0 if no match.
  232.  
  233.           RLENGTH
  234.                the length of the string matched by match(); -1 if
  235.                no match.
  236.  
  237.           SUBSEP
  238.                the character used to separate multiple subscripts
  239.                in array elements, by default "\034".
  240.  
  241.   Arrays
  242.      Arrays are subscripted with  an  expression  between  square
  243.      brackets ([ and ]).  If the expression is an expression list
  244.      (expr, expr ...) then the array subscript is a  string  con-
  245.      sisting  of  the concatenation of the (string) value of each
  246.      expression, separated by the value of the  SUBSEP  variable.
  247.      This  facility  is  used  to  simulate  multiply dimensioned
  248.      arrays. For example:
  249.  
  250.           i = "A" ; j = "B" ; k = "C"
  251.           x[i,j,k] = "hello, world\n"
  252.  
  253.      assigns the string "hello, world\n" to the  element  of  the
  254.      array  x  which  is indexed by the string "A\034B\034C". All
  255.      arrays in  AWK  are  associative,  i.e.  indexed  by  string
  256.      values.
  257.  
  258.  
  259.  
  260.  
  261. Sun Release 4.0 Last change: Free Software Foundation             4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. GAWK(1)                  USER COMMANDS                    GAWK(1)
  269.  
  270.  
  271.  
  272.      The special operator in may be used in an if or while state-
  273.      ment to see if an array has an index consisting of a partic-
  274.      ular value.
  275.  
  276.           if (val in array)
  277.                print array[val]
  278.  
  279.      If the array has multiple subscripts, use (i, j) in array.
  280.  
  281.      The in construct may also be used in a for loop  to  iterate
  282.      over all the elements of an array.
  283.  
  284.      An element may be deleted from an  array  using  the  delete
  285.      statement.
  286.  
  287.   Variable Typing
  288.      Variables and fields may be  (floating  point)  numbers,  or
  289.      strings, or both. How the value of a variable is interpreted
  290.      depends upon its context. If used in a  numeric  expression,
  291.      it  will be treated as a number, if used as a string it will
  292.      be treated as a string.
  293.  
  294.      To force a variable to be treated as a number, add 0 to  it;
  295.      to  force  it to be treated as a string, concatenate it with
  296.      the null string.
  297.  
  298.      The AWK language defines comparisons as being  done  numeri-
  299.      cally  if  possible, otherwise one or both operands are con-
  300.      verted to strings and a string comparison is performed.
  301.  
  302.      Uninitialized variables have the numeric  value  0  and  the
  303.      string value "" (the null, or empty, string).
  304.  
  305. PATTERNS AND ACTIONS
  306.      AWK is a line oriented language. The  pattern  comes  first,
  307.      and then the action. Action statements are enclosed in { and
  308.      }.  Either the pattern may be missing, or the action may  be
  309.      missing,  but,  of course, not both. If the pattern is miss-
  310.      ing, the action will be executed for every  single  line  of
  311.      input.  A missing action is equivalent to
  312.  
  313.           { print }
  314.  
  315.      which prints the entire line.
  316.  
  317.      Comments begin with the ``#'' character, and continue  until
  318.      the  end  of  the line.  Blank lines may be used to separate
  319.      statements.  Normally, a statement ends with a newline, how-
  320.      ever,  this  is  not  the  case for lines ending in a ``,'',
  321.      ``{'', ``?'', ``:'', ``&&'', or ``||''.  Lines ending in  do
  322.      or  else  also have their statements automatically continued
  323.      on the following line.   In  other  cases,  a  line  can  be
  324.  
  325.  
  326.  
  327. Sun Release 4.0 Last change: Free Software Foundation             5
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. GAWK(1)                  USER COMMANDS                    GAWK(1)
  335.  
  336.  
  337.  
  338.      continued  by ending it with a ``\'', in which case the new-
  339.      line will be ignored.
  340.  
  341.      Multiple statements may be put on  one  line  by  separating
  342.      them  with  a  ``;''.   This  applies to both the statements
  343.      within the action part of a pattern-action pair  (the  usual
  344.      case), and to the pattern-action statements themselves.
  345.  
  346.   Patterns
  347.      AWK patterns may be one of the following:
  348.  
  349.           BEGIN
  350.           END
  351.           /regular expression/
  352.           relational expression
  353.           pattern && pattern
  354.           pattern || pattern
  355.           pattern ? pattern : pattern
  356.           (pattern)
  357.           ! pattern
  358.           pattern1, pattern2
  359.  
  360.      BEGIN and END are two special kinds of  patterns  which  are
  361.      not tested against the input.  The action parts of all BEGIN
  362.      patterns are merged as if all the statements had been  writ-
  363.      ten in a single BEGIN block. They are executed before any of
  364.      the input is read. Similarly, all the END blocks are merged,
  365.      and  executed  when  all  the input is exhausted (or when an
  366.      exit statement is executed).  BEGIN and END patterns  cannot
  367.      be  combined  with  other  patterns  in pattern expressions.
  368.      BEGIN and END patterns cannot have missing action parts.
  369.  
  370.      For /regular expression/ patterns, the associated  statement
  371.      is  executed  for  each  input line that matches the regular
  372.      expression.  Regular expressions are the same  as  those  in
  373.      egrep(1), and are summarized below.
  374.  
  375.      A relational expression may use any of the operators defined
  376.      below  in  the  section  on  actions.   These generally test
  377.      whether certain fields match certain regular expressions.
  378.  
  379.      The &&, ||, and ! operators are logical AND, logical OR, and
  380.      logical  NOT,  respectively, as in C.  They do short-circuit
  381.      evaluation, also as in C, and are used  for  combining  more
  382.      primitive   pattern   expressions.  As  in  most  languages,
  383.      parentheses may be used to change the order of evaluation.
  384.  
  385.      The ?: operator is like the same operator in C. If the first
  386.      pattern  is  true  then  the pattern used for testing is the
  387.      second pattern, otherwise it is the third. Only one  of  the
  388.      second and third patterns is evaluated.
  389.  
  390.  
  391.  
  392.  
  393. Sun Release 4.0 Last change: Free Software Foundation             6
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400. GAWK(1)                  USER COMMANDS                    GAWK(1)
  401.  
  402.  
  403.  
  404.      The pattern1, pattern2 form of an  expression  is  called  a
  405.      range  pattern.   It matches all input lines starting with a
  406.      line that matches pattern1, and continuing until a line that
  407.      matches  pattern2,  inclusive.  It does not combine with any
  408.      other sort of pattern expression.
  409.  
  410.   Regular Expressions
  411.      Regular expressions are the extended kind  found  in  egrep.
  412.      They are composed of characters as follows:
  413.  
  414.           c    matches the non-metacharacter c.
  415.  
  416.           \c   matches the literal character c.
  417.  
  418.           .    matches any character except newline.
  419.  
  420.           ^    matches the beginning of a line or a string.
  421.  
  422.           $    matches the end of a line or a string.
  423.  
  424.           [abc...]
  425.                character class, matches  any  of  the  characters
  426.                abc....
  427.  
  428.           [^abc...]
  429.                negated character  class,  matches  any  character
  430.                except abc... and newline.
  431.  
  432.           r1|r2
  433.                alternation: matches either r1 or r2.
  434.  
  435.           r1r2 concatenation: matches r1, and then r2.
  436.  
  437.           r+   matches one or more r's.
  438.  
  439.           r*   matches zero or more r's.
  440.  
  441.           r?   matches zero or one r's.
  442.  
  443.           (r)  grouping: matches r.
  444.  
  445.   Actions
  446.      Action statements are enclosed in braces, { and  }.   Action
  447.      statements consist of the usual assignment, conditional, and
  448.      looping statements found in most languages.  The  operators,
  449.      control  statements,  and  input/output statements available
  450.      are patterned after those in C.
  451.  
  452.      The operators in AWK, in order of increasing precedence, are
  453.  
  454.           = += -= *= /= %= ^=
  455.                Assignment. Both absolute assignment (var = value)
  456.  
  457.  
  458.  
  459. Sun Release 4.0 Last change: Free Software Foundation             7
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466. GAWK(1)                  USER COMMANDS                    GAWK(1)
  467.  
  468.  
  469.  
  470.                and operator-assignment (the other forms) are sup-
  471.                ported.
  472.  
  473.           ?:   The C conditional expression. This  has  the  form
  474.                expr1 ? expr2 : expr3. If expr1 is true, the value
  475.                of the expression is expr2, otherwise it is expr3.
  476.                Only one of expr2 and expr3 is evaluated.
  477.  
  478.           ||   logical OR.
  479.  
  480.           &&   logical AND.
  481.  
  482.           ~ !~ regular expression match, negated match.
  483.  
  484.           < <= > >= != ==
  485.                the regular relational operators.
  486.  
  487.           blank
  488.                string concatenation.
  489.  
  490.           + -  addition and subtraction.
  491.  
  492.           * / %
  493.                multiplication, division, and modulus.
  494.  
  495.           + - !
  496.                unary plus, unary minus, and logical negation.
  497.  
  498.           ^    exponentiation (** may also be used, and  **=  for
  499.                the assignment operator).
  500.  
  501.           ++ --
  502.                increment and decrement, both prefix and postfix.
  503.  
  504.           $    field reference.
  505.  
  506.      The control statements are as follows:
  507.  
  508.           if (condition) statement [ else statement ]
  509.           while (condition) statement
  510.           do statement while (condition)
  511.           for (expr1; expr2; expr3) statement
  512.           for (var in array) statement
  513.           break
  514.           continue
  515.           delete array[index]
  516.           exit [ expression ]
  517.           { statements }
  518.  
  519.      The input/output statements are as follows:
  520.  
  521.  
  522.  
  523.  
  524.  
  525. Sun Release 4.0 Last change: Free Software Foundation             8
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532. GAWK(1)                  USER COMMANDS                    GAWK(1)
  533.  
  534.  
  535.  
  536.           close(filename)
  537.                close file (or pipe, see below).
  538.  
  539.           getline
  540.                set $0 from next input record; set NF, NR, FNR.
  541.  
  542.           getline <file
  543.                set $0 from next record of file; set NF.
  544.  
  545.           getline var
  546.                set var from next input record; set NF, FNR.
  547.  
  548.           getline var <file
  549.                set var from next record of file.
  550.  
  551.           next Stop processing the current input record. The next
  552.                input  record  is  read and processing starts over
  553.                with the first pattern in the AWK program. If  the
  554.                end   of  the  input  data  is  reached,  the  END
  555.                block(s), if any, are executed.
  556.  
  557.           print
  558.                prints the current record.
  559.  
  560.           print expr-list
  561.                prints expressions.
  562.  
  563.           print expr-list >file
  564.                prints expressions on file.
  565.  
  566.           printf fmt, expr-list
  567.                format and print.
  568.  
  569.           printf fmt, expr-list >file
  570.                format and print on file.
  571.  
  572.           system(cmd-line)
  573.                execute the command cmd-line, and return the  exit
  574.                status.   (This  may  not  be available on systems
  575.                besides UNIX and GNU.)
  576.  
  577.      Other input/output redirections are also allowed. For  print
  578.      and  printf, >>file appends output to the file, while | com-
  579.      mand writes on a pipe.  In a similar fashion, command | get-
  580.      line  pipes  into  getline.  Getline will return 0 on end of
  581.      file, and -1 on an error.
  582.  
  583.      The AWK versions of the printf and sprintf (see below) func-
  584.      tions accept the following conversion specification formats:
  585.  
  586.           %c   An ASCII character.  If the argument used  for  %c
  587.                is  numeric,  it  is  treated  as  a character and
  588.  
  589.  
  590.  
  591. Sun Release 4.0 Last change: Free Software Foundation             9
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598. GAWK(1)                  USER COMMANDS                    GAWK(1)
  599.  
  600.  
  601.  
  602.                printed.  Otherwise, the argument is assumed to be
  603.                a  string,  and  the  only first character of that
  604.                string is printed.
  605.  
  606.           %d   A decimal number (the integer part).
  607.  
  608.           %e   A   floating   point   number    of    the    form
  609.                [-]d.ddddddE[+-]dd.
  610.  
  611.           %f   A floating point number of the form [-]ddd.dddddd.
  612.  
  613.           %g   Use e or f conversion, whichever is shorter,  with
  614.                nonsignificant zeros suppressed.
  615.  
  616.           %o   An unsigned octal number (again, an integer).
  617.  
  618.           %s   A character string.
  619.  
  620.           %x   An unsigned hexadecimal number (an integer).
  621.  
  622.           %%   A single % character; no argument is converted.
  623.  
  624.      There are  optional,  additional  parameters  that  may  lie
  625.      between the % and the control letter:
  626.  
  627.           -    The expression should be left-justified within its
  628.                field.
  629.  
  630.           width
  631.                The field should be padded to this width.  If  the
  632.                number  has a leading zero, then the field will be
  633.                padded with zeros.  Otherwise it  is  padded  with
  634.                blanks.
  635.  
  636.           .prec
  637.                A number indicating the maximum width  of  strings
  638.                or digits to the right of the decimal point.
  639.  
  640.      The dynamic width and prec capabilities  of  the  C  library
  641.      printf  routines  are  not  supported.  However, they may be
  642.      simulated by using the AWK concatenation operation to  build
  643.      up a format specification dynamically.
  644.  
  645.      When doing I/O redirection from either print or printf  into
  646.      a  file, or via getline from a file, gawk recognizes certain
  647.      special filenames internally.  These filenames allow  access
  648.      to  open  file descriptors inherited from gawk's parent pro-
  649.      cess (usually the shell).  The filenames are:
  650.  
  651.           /dev/stdin
  652.                The standard input.
  653.  
  654.  
  655.  
  656.  
  657. Sun Release 4.0 Last change: Free Software Foundation            10
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664. GAWK(1)                  USER COMMANDS                    GAWK(1)
  665.  
  666.  
  667.  
  668.           /dev/stdout
  669.                The standard output.
  670.  
  671.           /dev/stderr
  672.                The standard error output.
  673.  
  674.           /dev/fd/n
  675.                The file denoted by the open file descriptor n.
  676.  
  677.      These are particularly useful for error messages. For  exam-
  678.      ple:
  679.  
  680.           print "You blew it!" > "/dev/stderr"
  681.  
  682.      whereas you would otherwise have to use
  683.  
  684.           print "You blew it!" | "cat 1>&2"
  685.  
  686.      These file names may also be used on  the  command  line  to
  687.      name data files.
  688.  
  689.      AWK has the following pre-defined arithmetic functions:
  690.  
  691.           atan2(y, x)
  692.                returns the arctangent of y/x in radians.
  693.  
  694.           cos(expr)
  695.                returns the cosine in radians.
  696.  
  697.           exp(expr)
  698.                the exponential function.
  699.  
  700.           int(expr)
  701.                truncates to integer.
  702.  
  703.           log(expr)
  704.                the natural logarithm function.
  705.  
  706.           rand()
  707.                returns a random number between 0 and 1.
  708.  
  709.           sin(expr)
  710.                returns the sine in radians.
  711.  
  712.           sqrt(expr)
  713.                the square root function.
  714.  
  715.           srand(expr)
  716.                use expr as a new seed for the random number  gen-
  717.                erator.  If  no  expr is provided, the time of day
  718.                will be used.  The return value  is  the  previous
  719.                seed for the random number generator.
  720.  
  721.  
  722.  
  723. Sun Release 4.0 Last change: Free Software Foundation            11
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730. GAWK(1)                  USER COMMANDS                    GAWK(1)
  731.  
  732.  
  733.  
  734.      AWK has the following pre-defined string functions:
  735.  
  736.           gsub(r, s, t)
  737.                for each substring matching the regular expression
  738.                r  in  the  string t, substitute the string s, and
  739.                return the number of substitutions.  If t  is  not
  740.                supplied, use $0.
  741.  
  742.           index(s, t)
  743.                returns the index of the string t in the string s,
  744.                or 0 if t is not present.
  745.  
  746.           length(s)
  747.                returns the length of the string s.
  748.  
  749.           match(s, r)
  750.                returns  the  position  in  s  where  the  regular
  751.                expression r occurs, or 0 if r is not present, and
  752.                sets the values of RSTART and RLENGTH.
  753.  
  754.           split(s, a, r)
  755.                splits the string s into the array a on the  regu-
  756.                lar  expression  r,  and  returns  the  number  of
  757.                fields. If r is omitted, FS is used instead.
  758.  
  759.           sprintf(fmt, expr-list)
  760.                prints expr-list according to fmt, and returns the
  761.                resulting string.
  762.  
  763.           sub(r, s, t)
  764.                this is just like gsub, but only the first  match-
  765.                ing substring is replaced.
  766.  
  767.           substr(s, i, n)
  768.                returns the n-character substring of s starting at
  769.                i.  If n is omitted, the rest of s is used.
  770.  
  771.           tolower(str)
  772.                returns a copy of the string  str,  with  all  the
  773.                upper-case  characters  in str translated to their
  774.                corresponding   lower-case   counterparts.    Non-
  775.                alphabetic characters are left unchanged.
  776.  
  777.           toupper(str)
  778.                returns a copy of the string  str,  with  all  the
  779.                lower-case  characters  in str translated to their
  780.                corresponding   upper-case   counterparts.    Non-
  781.                alphabetic characters are left unchanged.
  782.  
  783.      String constants in AWK are sequences of characters enclosed
  784.      between  double  quotes  ("). Within strings, certain escape
  785.      sequences are recognized, as in C. These are:
  786.  
  787.  
  788.  
  789. Sun Release 4.0 Last change: Free Software Foundation            12
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796. GAWK(1)                  USER COMMANDS                    GAWK(1)
  797.  
  798.  
  799.  
  800.           \\   A literal backslash.
  801.  
  802.           \a   The ``alert'' character;  usually  the  ASCII  BEL
  803.                character.
  804.  
  805.           \b   backspace.
  806.  
  807.           \f   form-feed.
  808.  
  809.           \n   new line.
  810.  
  811.           \r   carriage return.
  812.  
  813.           \t   horizontal tab.
  814.  
  815.           \v   vertical tab.
  816.  
  817.           \xhex digits
  818.                The character represented by the string of hexade-
  819.                cimal  digits following the \x.  As in ANSI C, all
  820.                following hexadecimal digits are  considered  part
  821.                of the escape sequence.  (This feature should tell
  822.                us something about language design by  committee.)
  823.                E.g., "\x1B" is the ASCII ESC (escape) character.
  824.  
  825.           \ddd The character represented by the  1-,  2-,  or  3-
  826.                digit sequence of octal digits. E.g. "\033" is the
  827.                ASCII ESC (escape) character.
  828.  
  829.           \c   The literal character c.
  830.  
  831.      The escape sequences may also be used inside constant  regu-
  832.      lar  expressions  (e.g.,  /[ \t\f\n\r\v]/ matches whitespace
  833.      characters).
  834.  
  835. FUNCTIONS
  836.      Functions in AWK are defined as follows:
  837.  
  838.           function name(parameter list) { statements }
  839.  
  840.      Functions are executed when called from  within  the  action
  841.      parts  of  regular pattern-action statements. Actual parame-
  842.      ters supplied in the function call are used  to  instantiate
  843.      the  formal parameters declared in the function.  Arrays are
  844.      passed by reference, other variables are passed by value.
  845.  
  846.      Since  functions  were  not  originally  part  of  the   AWK
  847.      language,  the  provision  for  local  variables  is  rather
  848.      clumsy: they are declared as extra parameters in the parame-
  849.      ter list. The convention is to separate local variables from
  850.      real parameters by extra spaces in the parameter  list.  For
  851.      example:
  852.  
  853.  
  854.  
  855. Sun Release 4.0 Last change: Free Software Foundation            13
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862. GAWK(1)                  USER COMMANDS                    GAWK(1)
  863.  
  864.  
  865.  
  866.           function  f(p, q,     a, b) { # a & b are local
  867.                          ..... }
  868.  
  869.           /abc/     { ... ; f(1, 2) ; ... }
  870.  
  871.      The left parenthesis in  a  function  call  is  required  to
  872.      immediately  follow the function name, without any interven-
  873.      ing white space.  This is to  avoid  a  syntactic  ambiguity
  874.      with  the concatenation operator.  This restriction does not
  875.      apply to the built-in functions listed above.
  876.  
  877.      Functions may call each other and may be  recursive.   Func-
  878.      tion  parameters  used as local variables are initialized to
  879.      the null string and the number zero  upon  function  invoca-
  880.      tion.
  881.  
  882.      The word func may be used in place of function.
  883.  
  884. EXAMPLES
  885.      Print and sort the login names of all users:
  886.  
  887.           BEGIN     { FS = ":" }
  888.                { print $1 | "sort" }
  889.  
  890.      Count lines in a file:
  891.  
  892.                { nlines++ }
  893.           END  { print nlines }
  894.  
  895.      Precede each line by its number in the file:
  896.  
  897.           { print FNR, $0 }
  898.  
  899.      Concatenate and line number (a variation on a theme):
  900.  
  901.           { print NR, $0 }
  902.  
  903. SEE ALSO
  904.      The AWK Programming Language, Alfred V. Aho, Brian  W.  Ker-
  905.      nighan,  Peter  J. Weinberger, Addison-Wesley, 1988. ISBN 0-
  906.      201-07981-X.
  907.  
  908. SYSTEM V RELEASE 4 COMPATIBILITY
  909.      A primary goal for gawk is  compatibility  with  the  latest
  910.      version  of  UNIX  awk.   To this end, gawk incorporates the
  911.      following user visible features which are not  described  in
  912.      the AWK book, but are part of awk in System V Release 4.
  913.  
  914.      When processing arguments,  gawk  uses  the  special  option
  915.      ``--''  to signal the end of arguments, and warns about, but
  916.      otherwise ignores, undefined options.
  917.  
  918.  
  919.  
  920.  
  921. Sun Release 4.0 Last change: Free Software Foundation            14
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928. GAWK(1)                  USER COMMANDS                    GAWK(1)
  929.  
  930.  
  931.  
  932.      The AWK book does not define the return  value  of  srand().
  933.      The System V Release 4 version of UNIX awk has it return the
  934.      seed it was using, to allow keeping track of  random  number
  935.      sequences.  Therefore  srand()  in  gawk  also  returns  its
  936.      current seed.
  937.  
  938.      The use of multiple -f options is a new feature, as  is  the
  939.      ENVIRON array.
  940.  
  941. GNU EXTENSIONS
  942.      Gawk  has  some  extensions  to  System  V  awk.   They  are
  943.      described  in  this  section.   All the extensions described
  944.      here can be disabled by compiling gawk with -DSTRICT, or  by
  945.      invoking  gawk with the name awk.  If the underlying operat-
  946.      ing system supports the /dev/fd directory and  corresponding
  947.      files, then gawk can be compiled with -DNO_DEV_FD to disable
  948.      the special filename processing.
  949.  
  950.      The following features of gawk are not available in System V
  951.      awk.
  952.  
  953.           o    The \a, \v, or \x escape sequences are not  recog-
  954.                nized.
  955.  
  956.           o    The special file names available for I/O  redirec-
  957.                tion are not recognized.
  958.  
  959.           o    The tolower and toupper built-in string  functions
  960.                are not available.
  961.  
  962.           o    The IGNORECASE variable and its  side-effects  are
  963.                not available.
  964.  
  965.           o    No path search is performed for  files  named  via
  966.                the  -f option.  Therefore the AWKPATH environment
  967.                variable is not special.
  968.  
  969.      The AWK book does not define the return value of  the  close
  970.      function.  Gawk's close returns the value from fclose(3), or
  971.      pclose(3), when closing a file or pipe, respectively.
  972.  
  973.      When gawk is invoked as awk, if the fs argument  to  the  -F
  974.      option  is  ``t'', then FS will be set to the tab character.
  975.      Since this is a rather ugly special  case,  it  is  not  the
  976.      default behavior.
  977.  
  978.      The rest of the  features  described  in  this  section  may
  979.      change  at some time in the future, or may go away entirely.
  980.      You should not write programs that depend upon them.
  981.  
  982.      Gawk accepts the following additional options:
  983.  
  984.  
  985.  
  986.  
  987. Sun Release 4.0 Last change: Free Software Foundation            15
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994. GAWK(1)                  USER COMMANDS                    GAWK(1)
  995.  
  996.  
  997.  
  998.      -v   Print version information for this particular  copy  of
  999.           gawk  on  the  error output.  This is useful mainly for
  1000.           knowing if the current copy of gawk on your  system  is
  1001.           up  to  date with respect to whatever the Free Software
  1002.           Foundation is distributing.
  1003.  
  1004.      -V   Print the GNU  copyright  information  message  on  the
  1005.           error output.
  1006.  
  1007. BUGS
  1008.      The -F option is not necessary given the command line  vari-
  1009.      able  assignment feature; it remains only for backwards com-
  1010.      patibility.
  1011.  
  1012. AUTHORS
  1013.      The original version of UNIX awk  was  designed  and  imple-
  1014.      mented  by Alfred Aho, Peter Weinberger, and Brian Kernighan
  1015.      of AT&T Bell Labs. Brian Kernighan continues to maintain and
  1016.      enhance it.
  1017.  
  1018.      Paul Rubin and Jay Fenlason, of the  Free  Software  Founda-
  1019.      tion, wrote gawk, to be compatible with the original version
  1020.      of awk distributed in Seventh Edition UNIX.  John Woods con-
  1021.      tributed  a number of bug fixes.  David Trueman of Dalhousie
  1022.      University, with contributions from Arnold Robbins at  Emory
  1023.      University,  made  gawk  compatible  with the new version of
  1024.      UNIX awk.
  1025.  
  1026. ACKNOWLEDGEMENTS
  1027.      Brian Kernighan of Bell Labs  provided  valuable  assistance
  1028.      during testing and debugging.  We thank him.
  1029.  
  1030.  
  1031.  
  1032.  
  1033.  
  1034.  
  1035.  
  1036.  
  1037.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.  
  1043.  
  1044.  
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.  
  1052.  
  1053. Sun Release 4.0 Last change: Free Software Foundation            16
  1054.  
  1055.  
  1056.  
  1057.