[BACK]Return to awk.1 CVS log [TXT][DIR] Up to [local] / src / usr.bin / awk

Diff for /src/usr.bin/awk/awk.1 between version 1.16 and 1.17

version 1.16, 2003/12/12 19:50:55 version 1.17, 2003/12/16 11:18:37
Line 87 
Line 87 
 instead of from the command line.  instead of from the command line.
 .It Fl safe  .It Fl safe
 Disable file output  Disable file output
 .Pf ( Ic print > ,  .Pf ( Ic print No > ,
 .Ic print >> ) ,  .Ic print No >> ) ,
 process creation  process creation
 .Po  .Po
 .Ar cmd Ic \&| getline ,  .Ar cmd | Ic getline ,
 .Ic print \&| , system  .Ic print No \&| ,
   .Ic system
 .Pc  .Pc
 and access to the environment  and access to the environment
 .Pq Va ENVIRON .  .Pf ( Va ENVIRON ;
 This  see
 is a first  .Sx VARIABLES
   below).
   This is a first
 .Pq and not very reliable  .Pq and not very reliable
 approximation to a  approximation to a
 .Dq safe  .Dq safe
Line 166 
Line 169 
 .Xc  .Xc
 .Ic print Xo  .Ic print Xo
 .Op Ar expression-list  .Op Ar expression-list
 .Op Ic > Ns Ar expression  .Op > Ns Ar expression
 .Xc  .Xc
 .Ic printf Ar format Xo  .Ic printf Ar format Xo
 .Op Ar ... , expression-list  .Op Ar ... , expression-list
 .Op Ic > Ns Ar expression  .Op > Ns Ar expression
 .Xc  .Xc
 .Ic return Op Ar expression  .Ic return Op Ar expression
 .Ic next Xo  .Ic next Xo
Line 221 
Line 224 
 .Li [i,j,k]  .Li [i,j,k]
 are permitted; the constituents are concatenated,  are permitted; the constituents are concatenated,
 separated by the value of  separated by the value of
 .Va SUBSEP .  .Va SUBSEP
   (see
   .Sx VARIABLES
   below).
 .Pp  .Pp
 The  The
 .Ic print  .Ic print
 statement prints its arguments on the standard output  statement prints its arguments on the standard output
 (or on a file if  (or on a file if
 .Ic > Ns Ar file  .Pf > Ns Ar file
 or  or
 .Ic >> Ns Ar file  .Pf >> Ns Ar file
 is present or on a pipe if  is present or on a pipe if
 .Ic \&| Ar cmd  .Pf |\ \& Ar cmd
 is present), separated by the current output field separator,  is present), separated by the current output field separator,
 and terminated by the output record separator.  and terminated by the output record separator.
 .Ar file  .Ar file
Line 245 
Line 251 
 statement formats its expression list according to the format  statement formats its expression list according to the format
 (see  (see
 .Xr printf 3 ) .  .Xr printf 3 ) .
 The built-in function  .Sh FUNCTIONS
 .Fn close expr  The awk language has a variety of built-in functions:
 closes the file or pipe  arithmetic, string, input/output and general.
 .Fa expr .  .Ss Arithmetic Functions
 The built-in function  .Bl -tag -width "atan2(y, x)"
 .Fn fflush expr  .It Fn atan2 y x
 flushes any buffered output for the file or pipe  Return the arctangent of
 .Fa expr .  .Fa y Ns / Ns Fa x
 .Pp  in radians.
 The mathematical functions  .It Fn cos x
 .Fn exp ,  Return the cosine of
 .Fn log ,  .Fa x ,
 .Fn sqrt ,  where
 .Fn sin ,  .Fa x
 .Fn cos ,  is in radians.
 and  .It Fn exp x
 .Fn atan2  Return the exponential of
 are built in.  .Fa x .
 Other built-in functions:  .It Fn int x
 .Bl -tag -width Fn  Return
 .It Fn length  .Fa x
 The length of its argument  truncated to an integer value.
 taken as a string,  .It Fn log x
 or of  Return the natural logarithm of
 .Va $0  .Fa x .
 if no argument.  
 .It Fn rand  .It Fn rand
 Random number on (0,1).  Return a random number,
 .It Fn srand  .Fa n ,
   such that
   .Sm off
   .Pf 0 \*(Le Fa n No \*(Lt 1 .
   .Sm on
   .It Fn sin x
   Return the sine of
   .Fa x ,
   where
   .Fa x
   is in radians.
   .It Fn sqrt x
   Return the square root of
   .Fa x .
   .It Fn srand expr
 Sets seed for  Sets seed for
 .Fn rand  .Fn rand
   to
   .Fa expr
 and returns the previous seed.  and returns the previous seed.
 .It Fn int  If
 Truncates to an integer value.  .Fa expr
 .It Fn substr s m n  is omitted, the time of day is used instead.
 The  .El
 .Fa n Ns No -character  .Ss String Functions
 substring of  .Bl -tag -width "split(s, a, fs)"
 .Fa s  .It Fn gsub r t s
 that begins at position  The same as
 .Fa m  .Fn sub
 counted from 1.  except that all occurrences of the regular expression are replaced.
   .Fn gsub
   returns the number of replacements.
 .It Fn index s t  .It Fn index s t
 The position in  The position in
 .Fa s  .Fa s
 where the string  where the string
 .Fa t  .Fa t
 occurs, or 0 if it does not.  occurs, or 0 if it does not.
   .It Fn length s
   The length of
   .Fa s
   taken as a string,
   or of
   .Va $0
   if no argument is given.
 .It Fn match s r  .It Fn match s r
 The position in  The position in
 .Fa s  .Fa s
 where the regular expression  where the regular expression
 .Fa r  .Fa r
 occurs, or 0 if it does not.  occurs, or 0 if it does not.
 The variables  The variable
 .Va RSTART  .Va RSTART
 and  is set to the starting position of the matched string
   .Pq which is the same as the returned value
   or zero if no match is found.
   The variable
 .Va RLENGTH  .Va RLENGTH
 are set to the position and length of the matched string.  is set to the length of the matched string,
   or \-1 if no match is found.
 .It Fn split s a fs  .It Fn split s a fs
 Splits the string  Splits the string
 .Fa s  .Fa s
Line 320 
Line 354 
 is not given.  is not given.
 An empty string as field separator splits the string  An empty string as field separator splits the string
 into one array element per character.  into one array element per character.
   .It Fn sprintf fmt expr ...
   The string resulting from formatting
   .Fa expr , ...
   according to the
   .Xr printf 3
   format
   .Fa fmt .
 .It Fn sub r t s  .It Fn sub r t s
 Substitutes  Substitutes
 .Fa t  .Fa t
Line 332 
Line 373 
 is not given,  is not given,
 .Va $0  .Va $0
 is used.  is used.
 .It Fn gsub r t s  An ampersand
 Same as  .Pq Sq &
   in
   .Fa t
   is replaced in string
   .Fa s
   with regular expression
   .Fa r .
   A literal ampersand can be specified by preceding it with two backslashes
   .Pq Sq \e\e .
   A literal backslash can be specified by preceding it with another backslash
   .Pq Sq \e\e .
 .Fn sub  .Fn sub
 except that all occurrences of the regular expression  returns the number of replacements.
 are replaced;  .It Fn substr s m n
 .Fn sub  Return at most the
 and  .Fa n Ns -character
 .Fn gsub  substring of
 return the number of replacements.  .Fa s
 .It Fn sprintf fmt expr ...  that begins at position
 The string resulting from formatting  .Fa m
 .Fa expr , ...  counted from 1.
 according to the  If
 .Xr printf 3  .Fa n
 format  is omitted, or if
 .Fa fmt .  .Fa n
 .It Fn system cmd  specifies more characters than are left in the string,
 Executes  the length of the substring is limited by the length of
 .Fa cmd  .Fa s .
 and returns its exit status.  
 .It Fn tolower str  .It Fn tolower str
 Returns a copy of  Returns a copy of
 .Fa str  .Fa str
Line 363 
Line 413 
 with all lower-case characters translated to their  with all lower-case characters translated to their
 corresponding upper-case equivalents.  corresponding upper-case equivalents.
 .El  .El
 .Pp  .Ss Input/Output and General Functions
 The  .Bl -tag -width "getline [var] < file"
 .Sq function  .It Fn close expr
   Closes the file or pipe
   .Fa expr .
   .Fa expr
   should match the string that was used to open the file or pipe.
   .It Ar cmd | Ic getline Op Va var
   Read a record of input from a stream piped from the output of
   .Ar cmd .
   If
   .Va var
   is omitted, the variables
   .Va $0
   and
   .Va NF
   are set.
   Otherwise
   .Va var
   is set.
   If the stream is not open, it is opened.
   As long as the stream remains open, subsequent calls
   will read subsequent records from the stream.
   The stream remains open until explicitly closed with a call to
   .Fn close .
   .It Fn fflush expr
   Flushes any buffered output for the file or pipe
   .Fa expr .
   .Fa expr
   should match the string that was used to open the file or pipe.
   .It Ic getline
   Sets
   .Va $0
   to the next input record from the current input file.
   This form of
 .Ic getline  .Ic getline
 sets  sets the variables
   .Va NF ,
   .Va NR ,
   and
   .Va FNR .
   .Ic getline
   returns 1 for a successful input, 0 for end of file, and \-1 for an error.
   .It Ic getline Va var
   Sets
 .Va $0  .Va $0
 to the next input record from the current input file;  to variable
 .Ic getline < Ar file  .Va var .
 sets  This form of
   .Ic getline
   sets the variables
   .Va NR
   and
   .Va FNR .
   .Ic getline
   returns 1 for a successful input, 0 for end of file, and \-1 for an error.
   .It Xo
   .Ic getline Op Va var
   .Pf \ \&< Ar file
   .Xc
   Sets
 .Va $0  .Va $0
 to the next record from  to the next record from
 .Ar file .  .Ar file .
 .Ic getline Va x  If
 sets variable  .Va var
 .Va x  is omitted, the variables
 instead.  .Va $0
 Finally,  and
 .Ar cmd Ic \&| getline  .Va NF
 pipes the output of  are set.
 .Ar cmd  Otherwise
 into  .Va var
 .Ic getline ;  is set.
 each call of  If
 .Ic getline  .Ar file
 returns the next line of output from  is not open, it is opened.
 .Ar cmd .  As long as the stream remains open, subsequent calls will read subsequent
 In all cases,  records from
 .Ic getline  .Ar file .
 returns 1 for a successful input,  .Ar file
 0 for end of file, and \-1 for an error.  remains open until explicitly closed with a call to
   .Fn close .
   .It Fn system cmd
   Executes
   .Fa cmd
   and returns its exit status.
   .El
 .Pp  .Pp
   Functions may be defined (at the position of a pattern-action statement)
   thusly:
   .Pp
   .Dl function foo(a, b, c) { ...; return x }
   .Pp
   Parameters are passed by value if scalar, and by reference if array name;
   functions may be called recursively.
   Parameters are local to the function; all other variables are global.
   Thus local variables may be created by providing excess parameters in
   the function definition.
   .Sh PATTERNS
 Patterns are arbitrary Boolean combinations  Patterns are arbitrary Boolean combinations
 (with  (with
 .Ic "\&! || &&" )  .Ic "\&! || &&" )
Line 408 
Line 527 
 .Ic ~  .Ic ~
 and  and
 .Ic !~ .  .Ic !~ .
 .Ic / Ns Ar re Ns Ic /  .Pf / Ns Ar re Ns /
 is a constant regular expression;  is a constant regular expression;
 any string (constant or variable) may be used  any string (constant or variable) may be used
 as a regular expression, except in the position of an isolated regular expression  as a regular expression, except in the position of an isolated regular expression
Line 455 
Line 574 
 and  and
 .Ic END  .Ic END
 do not combine with other patterns.  do not combine with other patterns.
 .Pp  .Sh VARIABLES
 Variable names with special meanings:  Variable names with special meanings:
 .Pp  .Pp
 .Bl -tag -width "FILENAME" -compact  .Bl -tag -width "FILENAME" -compact
Line 489 
Line 608 
 Output field separator (default blank).  Output field separator (default blank).
 .It Va ORS  .It Va ORS
 Output record separator (default newline).  Output record separator (default newline).
   .It Va RLENGTH
   The length of the string matched by the
   .Fn match
   function.
 .It Va RS  .It Va RS
 Input record separator (default newline).  Input record separator (default newline).
   .It Va RSTART
   The starting position of the string matched by the
   .Fn match
   function.
 .It Va SUBSEP  .It Va SUBSEP
 Separates multiple subscripts (default 034).  Separates multiple subscripts (default 034).
 .El  .El
 .Pp  
 Functions may be defined (at the position of a pattern-action statement)  
 thusly:  
 .Pp  
 .Dl function foo(a, b, c) { ...; return x }  
 .Pp  
 Parameters are passed by value if scalar, and by reference if array name;  
 functions may be called recursively.  
 Parameters are local to the function; all other variables are global.  
 Thus local variables may be created by providing excess parameters in  
 the function definition.  
 .Sh EXAMPLES  .Sh EXAMPLES
 Print lines longer than 72 characters:  Print lines longer than 72 characters:
 .Pp  .Pp
Legend:
Removed from v.1.16  
changed lines
  Added in v.1.17