gawk.1

早期freebsd实现

print "You blew it!" > "/dev/stderr"
.ft R
.RE
.PP
whereas you would otherwise have to use
.PP
.RS
.ft B
print "You blew it!" | "cat 1>&2"
.ft R
.RE
.PP
These file names may also be used on the command line to name data files.
.SS Numeric Functions
.PP
AWK has the following pre-defined arithmetic functions:
.PP
.TP \w'\fBsrand(\^\fIexpr\^\fB)\fR'u+1n
.BI atan2( y , " x" )
returns the arctangent of
.I y/x
in radians.
.TP
.BI cos( expr )
returns the cosine in radians.
.TP
.BI exp( expr )
the exponential function.
.TP
.BI int( expr )
truncates to integer.
.TP
.BI log( expr )
the natural logarithm function.
.TP
.B rand()
returns a random number between 0 and 1.
.TP
.BI sin( expr )
returns the sine in radians.
.TP
.BI sqrt( expr )
the square root function.
.TP
.BI srand( expr )
use
.I expr
as a new seed for the random number generator. If no
.I expr
is provided, the time of day will be used.
The return value is the previous seed for the random
number generator.
.SS String Functions
.PP
AWK has the following pre-defined string functions:
.PP
.TP "\w'\fBsprintf(\^\fIfmt\fB\^, \fIexpr-list\^\fB)\fR'u+1n"
\fBgsub(\fIr\fB, \fIs\fB, \fIt\fB)\fR
for each substring matching the regular expression
.I r
in the string
.IR t ,
substitute the string
.IR s ,
and return the number of substitutions.
If
.I t
is not supplied, use
.BR $0 .
.TP
.BI index( s , " t" )
returns the index of the string
.I t
in the string
.IR s ,
or 0 if
.I t
is not present.
.TP
.BI length( s )
returns the length of the string
.IR s ,
or the length of
.B $0
if
.I s
is not supplied.
.TP
.BI match( s , " r" )
returns the position in
.I s
where the regular expression
.I r
occurs, or 0 if
.I r
is not present, and sets the values of
.B RSTART
and
.BR RLENGTH .
.TP
\fBsplit(\fIs\fB, \fIa\fB, \fIr\fB)\fR
splits the string
.I s
into the array
.I a
on the regular expression
.IR r ,
and returns the number of fields. If
.I r
is omitted,
.B FS
is used.
.TP
.BI sprintf( fmt , " expr-list" )
prints
.I expr-list
according to
.IR fmt ,
and returns the resulting string.
.TP
\fBsub(\fIr\fB, \fIs\fB, \fIt\fB)\fR
just like
.BR gsub() ,
but only the first matching substring is replaced.
.TP
\fBsubstr(\fIs\fB, \fIi\fB, \fIn\fB)\fR
returns the
.IR n -character
substring of
.I s
starting at
.IR i .
If
.I n
is omitted, the rest of
.I s
is used.
.TP
.BI tolower( str )
returns a copy of the string
.IR str ,
with all the upper-case characters in
.I str
translated to their corresponding lower-case counterparts.
Non-alphabetic characters are left unchanged.
.TP
.BI toupper( str )
returns a copy of the string
.IR str ,
with all the lower-case characters in
.I str
translated to their corresponding upper-case counterparts.
Non-alphabetic characters are left unchanged.
.SS Time Functions
.PP
Since one of the primary uses of AWK programs is processing log files
that contain time stamp information,
.I gawk
provides the following two functions for obtaining time stamps and
formatting them.
.PP
.TP "\w'\fBsystime()\fR'u+1n"
.B systime()
returns the current time of day as the number of seconds since the Epoch
(Midnight UTC, January 1, 1970 on \*(PX systems).
.TP
\fBstrftime(\fIformat\fR, \fItimestamp\fB)\fR
formats
.I timestamp
according to the specification in
.IR format.
The
.I timestamp
should be of the same form as returned by
.BR systime() .
If
.I timestamp
is missing, the current time of day is used.
See the specification for the
.B strftime()
function in \*(AN C for the format conversions that are
guaranteed to be available.
A public-domain version of
.IR strftime (3)
and a man page for it are shipped with
.IR gawk ;
if that version was used to build
.IR gawk ,
then all of the conversions described in that man page are available to
.IR gawk.
.SS String Constants
.PP
String constants in AWK are sequences of characters enclosed
between double quotes (\fB"\fR). Within strings, certain
.I "escape sequences"
are recognized, as in C. These are:
.PP
.TP \w'\fB\e\^\fIddd\fR'u+1n
.B \e\e
A literal backslash.
.TP
.B \ea
The ``alert'' character; usually the \s-1ASCII\s+1 \s-1BEL\s+1 character.
.TP
.B \eb
backspace.
.TP
.B \ef
form-feed.
.TP
.B \en
newline.
.TP
.B \er
carriage return.
.TP
.B \et
horizontal tab.
.TP
.B \ev
vertical tab.
.TP
.BI \ex "\^hex digits"
The character represented by the string of hexadecimal digits following
the
.BR \ex .
As in \*(AN C, all following hexadecimal digits are considered part of
the escape sequence.
(This feature should tell us something about language design by committee.)
E.g., "\ex1B" is the \s-1ASCII\s+1 \s-1ESC\s+1 (escape) character.
.TP
.BI \e ddd
The character represented by the 1-, 2-, or 3-digit sequence of octal
digits. E.g. "\e033" is the \s-1ASCII\s+1 \s-1ESC\s+1 (escape) character.
.TP
.BI \e c
The literal character
.IR c\^ .
.PP
The escape sequences may also be used inside constant regular expressions
(e.g.,
.B "/[\ \et\ef\en\er\ev]/"
matches whitespace characters).
.SH FUNCTIONS
Functions in AWK are defined as follows:
.PP
.RS
\fBfunction \fIname\fB(\fIparameter list\fB) { \fIstatements \fB}\fR
.RE
.PP
Functions are executed when called from within the action parts of regular
pattern-action statements. 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.
.PP
Since functions were not originally part of the AWK language, the provision
for local variables is rather clumsy: they are declared as extra parameters
in the parameter list. The convention is to separate local variables from
real parameters by extra spaces in the parameter list. For example:
.PP
.RS
.ft B
.nf
function  f(p, q,     a, b) {	# a & b are local
			..... }

/abc/	{ ... ; f(1, 2) ; ... }
.fi
.ft R
.RE
.PP
The left parenthesis in a function call is required
to immediately follow the function name,
without any intervening white space.
This is to avoid a syntactic ambiguity with the concatenation operator.
This restriction does not apply to the built-in functions listed above.
.PP
Functions may call each other and may be recursive.
Function parameters used as local variables are initialized
to the null string and the number zero upon function invocation.
.PP
The word
.B func
may be used in place of
.BR function .
.SH EXAMPLES
.nf
Print and sort the login names of all users:

.ft B
	BEGIN	{ FS = ":" }
		{ print $1 | "sort" }

.ft R
Count lines in a file:

.ft B
		{ nlines++ }
	END	{ print nlines }

.ft R
Precede each line by its number in the file:

.ft B
	{ print FNR, $0 }

.ft R
Concatenate and line number (a variation on a theme):

.ft B
	{ print NR, $0 }
.ft R
.fi
.SH SEE ALSO
.IR egrep (1)
.PP
.IR "The AWK Programming Language" ,
Alfred V. Aho, Brian W. Kernighan, Peter J. Weinberger,
Addison-Wesley, 1988. ISBN 0-201-07981-X.
.PP
.IR "The GAWK Manual" ,
Edition 0.15, published by the Free Software Foundation, 1993.
.SH POSIX COMPATIBILITY
A primary goal for
.I gawk
is compatibility with the \*(PX standard, as well as with the
latest version of \*(UX
.IR awk .
To this end,
.I gawk
incorporates the following user visible
features which are not described in the AWK book,
but are part of
.I awk
in System V Release 4, and are in the \*(PX standard.
.PP
The
.B \-v
option for assigning variables before program execution starts is new.
The book indicates that command line variable assignment happens when
.I awk
would otherwise open the argument as a file, which is after the
.B BEGIN
block is executed.  However, in earlier implementations, when such an
assignment appeared before any file names, the assignment would happen
.I before
the
.B BEGIN
block was run.  Applications came to depend on this ``feature.''
When
.I awk
was changed to match its documentation, this option was added to
accomodate applications that depended upon the old behavior.
(This feature was agreed upon by both the AT&T and GNU developers.)
.PP
The
.B \-W
option for implementation specific features is from the \*(PX standard.
.PP
When processing arguments,
.I gawk
uses the special option ``\fB\-\^\-\fP'' to signal the end of
arguments, and warns about, but otherwise ignores, undefined options.
.PP
The AWK book does not define the return value of
.BR srand() .
The System V Release 4 version of \*(UX
.I awk
(and the \*(PX standard)
has it return the seed it was using, to allow keeping track
of random number sequences. Therefore
.B srand()
in
.I gawk
also returns its current seed.
.PP
Other new features are:
The use of multiple
.B \-f
options (from MKS
.IR awk );
the
.B ENVIRON
array; the
.BR \ea ,
and
.BR \ev
escape sequences (done originally in
.I gawk
and fed back into AT&T's version); the
.B tolower()
and
.B toupper()
built-in functions (from AT&T); and the \*(AN C conversion specifications in
.B printf
(done first in AT&T's version).
.SH GNU EXTENSIONS
.I Gawk
has some extensions to \*(PX
.IR awk .
They are described in this section.  All the extensions described here
can be disabled by
invoking
.I gawk
with the
.B "\-W compat"
option.
.PP
The following features of
.I gawk
are not available in
\*(PX
.IR awk .
.RS
.TP \w'\(bu'u+1n
\(bu
The
.B \ex
escape sequence.
.TP
\(bu
The
.B systime()
and
.B strftime()
functions.
.TP
\(bu
The special file names available for I/O redirection are not recognized.
.TP
\(bu
The
.B ARGIND
and
.B ERRNO
variables are not special.
.TP
\(bu
The
.B IGNORECASE
variable and its side-effects are not available.
.TP
\(bu
The
.B FIELDWIDTHS
variable and fixed width field splitting.
.TP
\(bu
No path search is performed for files named via the
.B \-f
option.  Therefore the
.B AWKPATH
environment variable is not special.
.TP
\(bu
The use of
.B "next file"
to abandon processing of the current input file.
.RE
.PP
The AWK book does not define the return value of the
.B close()
function.
.IR Gawk\^ 's
.B close()
returns the value from
.IR fclose (3),
or
.IR pclose (3),
when closing a file or pipe, respectively.
.PP
When
.I gawk
is invoked with the
.B "\-W compat"
option,
if the
.I fs
argument to the
.B \-F
option is ``t'', then
.B FS
will be set to the tab character.
Since this is a rather ugly special case, it is not the default behavior.
This behavior also does not occur if
.B \-W posix
has been specified.
.ig
.PP
If
.I gawk
was compiled for debugging, it will
accept the following additional options:
.TP
.PD 0
.B \-Wparsedebug
.TP
.PD
.B \-\^\-parsedebug
Turn on
.IR yacc (1)
or
.IR bison (1)
debugging output during program parsing.
This option should only be of interest to the
.I gawk
maintainers, and may not even be compiled into
.IR gawk .
..
.SH HISTORICAL FEATURES
There are two features of historical AWK implementations that
.I gawk
supports.
First, it is possible to call the
.B length()
built-in function not only with no argument, but even without parentheses!
Thus,
.RS
.PP
.ft B
a = length
.ft R
.RE
.PP
is the same as either of
.RS
.PP
.ft B
a = length()
.br
a = length($0)
.ft R
.RE
.PP
This feature is marked as ``deprecated'' in the \*(PX standard, and
.I gawk
will issue a warning about its use if
.B \-W lint
is specified on the command line.
.PP
The other feature is the use of the
.B continue
statement outside the body of a
.BR while ,
.BR for ,
or
.B do
loop.  Traditional AWK implementations have treated such usage as
equivalent to the
.B next
statement.
.I Gawk
will support this usage if
.B \-W posix
has not been specified.
.SH BUGS
The
.B \-F
option is not necessary given the command line variable assignment feature;
it remains only for backwards compatibility.
.PP
If your system actually has support for
.B /dev/fd
and the associated
.BR /dev/stdin ,
.BR /dev/stdout ,
and
.B /dev/stderr
files, you may get different output from
.I gawk
than you would get on a system without those files.  When
.I gawk
interprets these files internally, it synchronizes output to the standard
output with output to
.BR /dev/stdout ,
while on a system with those files, the output is actually to different
open files.
Caveat Emptor.
.SH VERSION INFORMATION
This man page documents
.IR gawk ,
version 2.15.
.PP
Starting with the 2.15 version of
.IR gawk ,
the
.BR \-c ,
.BR \-V ,
.BR \-C ,
.ig
.BR \-D ,
..
.BR \-a ,
and
.B \-e
options of the 2.11 version are no longer recognized.
.SH AUTHORS
The original version of \*(UX
.I awk
was designed and implemented by Alfred Aho,
Peter Weinberger, and Brian Kernighan of AT&T Bell Labs. Brian Kernighan
continues to maintain and enhance it.
.PP
Paul Rubin and Jay Fenlason,
of the Free Software Foundation, wrote
.IR gawk ,
to be compatible with the original version of
.I awk
distributed in Seventh Edition \*(UX.
John Woods contributed a number of bug fixes.
David Trueman, with contributions
from Arnold Robbins, made
.I gawk
compatible with the new version of \*(UX
.IR awk .
.PP
The initial DOS port was done by Conrad Kwok and Scott Garfinkle.
Scott Deifik is the current DOS maintainer.  Pat Rankin did the
port to VMS, and Michal Jaegermann did the port to the Atari ST.
.SH ACKNOWLEDGEMENTS
Brian Kernighan of Bell Labs
provided valuable assistance during testing and debugging.
We thank him.