freebsd-nq/contrib/awk/doc/awkcard.in

.\" AWK Reference Card --- Arnold Robbins, arnold@gnu.org
.\"
.\" Copyright (C) 1996-2001 Free Software Foundation, Inc.
.\" 
.\" Permission is granted to make and distribute verbatim copies of
.\" this reference card provided the copyright notice and this permission
.\" notice are preserved on all copies.
.\" 
.\" Permission is granted to process this file through troff and print the
.\" results, provided the printed document carries copying permission
.\" notice identical to this one except for the removal of this paragraph
.\" (this paragraph not being relevant to the printed reference card).
.\" 
.\" Permission is granted to copy and distribute modified versions of this
.\" reference card 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 translations of this
.\" reference card into another language, under the above conditions for
.\" modified versions, except that this permission notice may be stated in
.\" a translation approved by the Foundation.
.\"
.\" Strings to save typing
.ds AK \*(FCawk\*(FR
.ds GK \*(FCgawk\*(FR
.ds NK Bell Labs \*(FCawk\*(FR
.ds MK \*(FCmawk\*(FR
.\"
.\"
.de TD\" tab defaults
.ta .2i .78i 1i 1.2i 1.4i 1.7i
..
.de TE
.TD
..

.sp
.ce
\*(CD\f(HB\s+8AWK REFERENCE\s0\*(FR
.sp
.\" --- Table Of Contents
.ta 2.4i 2.6iR
.lc .
.ES
.in +.2i
.nf
\*(FRAction Statements
	7
Arrays
	11
Awk Program Execution
	4
Bit Manipulation Functions (\*(GK)
	16
Bug Reports
	2
Closing Redirections
	12
Command Line Arguments (standard)
	2
Command Line Arguments (\*(GK)
	3
Command Line Arguments (\*(MK)
	4
Conversions And Comparisons
	9
Copying Permissions
	18
Definitions
	2
Dynamic Extensions (\*(GK)
	18
Environment Variables (\*(GK)
	18
Escape Sequences
	8
Expressions
	11
Fields
	6
FTP/HTTP Information
	18
Historical Features (\*(GK)
	18
Input Control
	12
Internationalization (\*(GK)
	16
Lines And Statements
	5
Localization (\*(GK)
	17
Numeric Functions
	14
Output Control
	12
Pattern Elements
	7
POSIX Character Classes (\*(GK)
	6
Printf Formats
	13
Records
	6
Regular Expressions
	5
Special Filenames
	14
String Functions
	15
Time Functions (\*(GK)
	16
User-defined Functions
	17
Variables
	8\*(CX
.in -.2i
.EB "\s+2\f(HBCONTENTS\*(FR\s0"
.sp .4
.TD
.fi
\*(CD\*(FRArnold Robbins wrote this reference card.
We thank
Brian Kernighan and Michael Brennan who reviewed it.
.sp .4
.SL
.sp .4
.so SRCDIR/ad.block
.\" a subtlety here; this line changes color. We rely on it
.\" also to provide a blank line.
\*(CD
.SL
.nf
\*(FR\(co Copyright 1996-2001, Free Software Foundation
59 Temple Place \(em Suite 330
Boston, MA  02111-1307 USA
.nf
.BT


.\"
.\"
.\" --- Definitions
.fi
.ES
\*(CDThis card describes POSIX AWK, as well as the three
freely available \*(AK implementations
(see \fHFTP Information\fP below).
\*(CLCommon extensions (in two or more versions) are printed in light blue.
\*(CBFeatures specific to just one version\(emusually GNU AWK (\*(GK)\(emare
printed in dark blue.
\*(CRExceptions and deprecated features are printed in red.
\*(CDFeatures mandated by POSIX are printed in black.
.sp .5
Several type faces are used to clarify the meaning:
.br
.nr IN \w'\(bu '
\(bu \*(FC\*(CN\fP is used for computer input.
.br
.fi
.in +\n(INu
.ti -\n(INu
\(bu\|\^\*(FI\*(IN\fP is used for emphasis, to indicate user input and for syntactic
placeholders, such as \*(FIvariable\fP or \*(FIaction\fP.
.in -\n(INu
.br
\(bu \*(RN is used for explanatory text.
.sp .5
\*(FInumber\fP \- a floating point number as in ANSI C, such as
\*(FC3\*(FR,
\*(FC2.3\*(FR,
\*(FC.4\*(FR,
\*(FC1.4e2\*(FR
or
\*(FC4.1E5\*(FR.
\*(CBNumbers may also be given in octal or hexadecimal: e.g.,
\*(FC011\*(FR or \*(FC0x11\*(FR.\*(CD
.sp .5
\*(FIescape sequences\fP \- a special sequence of characters beginning
with a backslash, used to describe otherwise unprintable characters.
(See \fHEscape Sequences\fP below.)
.sp .5
\*(FIstring\fP \- a group of characters enclosed in double quotes.
Strings may contain \*(FIescape sequences\*(FR.
.sp .5
\*(FIregexp\fP \- a regular expression, either a regexp constant
enclosed in forward slashes, or a dynamic regexp computed at run-time.
Regexp constants may contain \*(FIescape sequences\*(FR.
.sp .5
\*(FIname\fP \- a variable, array or function name.
.sp .5
\*(FIentry\fP(\*(FIN\fP) \- entry \*(FIentry\fP in section \*(FIN\fP of the
UNIX reference manual.
.sp .5
\*(FIpattern\fP \- an expression describing an input record to be matched.
.sp .5
\*(FIaction\fP \- statements to execute when an input record is matched.
.sp .5
\*(FIrule\fP \- a pattern-action pair, where the pattern or action may
be missing.\*(CX
.EB "\s+2\f(HBDEFINITIONS\*(FR\s0"

.\"
.\"
.\" --- Command Line Arguments
.ES
.fi
\*(CDCommand line arguments control setting the field separator,
setting variables before the \*(FCBEGIN\fP rule is run, and
the location of AWK program source code.
Implementation-specific command line arguments change
the behavior of the running interpreter.
.sp .5
.TS
expand;
l lw(2.2i).
\*(FC\-F \*(FIfs\*(FR	use \*(FIfs\fP for the input field separator.
\*(FC\-v\*(FI var\*(FC\^=\^\*(FIval\*(FR	T{
assign the value \*(FIval\*(FR to the variable \*(FIvar\*(FR
before execution of the program begins. Such
variable values are available to the \*(FCBEGIN\fP rule.
T}
\*(FC\-f \*(FIprog-file\*(FR	T{
read the AWK program source from the file
\*(FIprog-file\*(FR, instead of from the first command
line argument. Multiple \*(FC\-f\*(FR options may be used.
T}
\*(FC\-\^\-\*(FR	signal the end of options.
.TE
.sp .5
.fi
\*(CLThe following options are accepted by both \*(NK and \*(GK
\*(CR(ignored by \*(GK, not in \*(MK).\*(CL
.sp .5
.nf
.TS
expand, tab(%);
l lw(2.2i).
\*(FC\-mf \*(FIval\*(FR%set the maximum number of fields to \*(FIval\fP
\*(FC\-mr \*(FIval\*(FR%set the maximum record size to \*(FIval\fP\*(CX
.TE
.EB "\s+2\f(HBCOMMAND LINE ARGUMENTS (standard)\*(FR\s0"

.\" --- Bug Reports
.ES
.fi
\*(CDIf you find a bug in this reference card, please report it via electronic
mail to \*(FCbug-gawk@gnu.org\*(FR.\*(CX
.EB "\s+2\f(HBBUG REPORTS\*(FR\s0"

.BT

.\"
.\"
.\" --- Command Line Arguments (gawk)
.ES
.fi
\*(CDThe following options are specific to \*(GK.
You may also use ``\*(FC\-W \*(FIoption\*(FR''
for full POSIX compliance.
Long options may abbreviated as long as the abbreviation
remains unique.
.sp .5
.ig
.\" This option is left undocumented, on purpose.
\*(FC\-\^\-nostalgia\*(FR%T{
provide a moment of nostalgia for
long time \*(AK users.
T}
..
.TS
expand, tab(%);
l lw(1.3i).
\*(FC\-\^\-assign \*(FIvar\*(FC\^=\^\*(FIval\*(FR%just like \*(FC\-v\fP.
\*(FC\-\^\-field-separator \*(FIfs\*(FR%just like \*(FC\-F\fP.
\*(FC\-\^\-file \*(FIprog-file%\*(FRjust like \*(FC\-f\fP.
.TE
.TS
expand, tab(%);
ls
l lw(2.2i).
\*(FC\-\^\-compat\*(FR, \*(FC\-\^\-traditional\*(FR
%T{
disable \*(GK-specific extensions
(the use of \*(FC\-\^\-traditional\*(FR is preferred).
T}
.T&
ls
l lw(2.2i).
\*(FC\-\^\-copyleft\*(FR, \*(FC\-\^\-copyright\*(FR
%T{
print the short version of the GNU
copyright information on \*(FCstdout\*(FR.
T}
.T&
ls
l lw(2.2i).
\*(FC\-\^\-dump-variables\*(FR[\*(FC=\*(FIfile\*(FR]
%T{
Print a sorted list of global variables,
their types and final values to
\*(FIfile\*(FR.
If no \*(FIfile\*(FR
is provided, \*(FCgawk\*(FR
uses \*(FCawkvars.out\*(FR.
T}
\*(FC\-\^\-gen\-po\*(FR%T{
process the program and print a GNU \*(FCgettext\*(FR
format \*(FC\&.po\*(FR format file on standard output,
containing the text of all strings that were marked
for localization.
T}
.T&
ls
l lw(2.2i).
\*(FC\-\^\-help\*(FR, \*(FC\-\^\-usage\*(FR
%T{
print a short summary of the available
options on \*(FCstdout\*(FR, then exit zero.
T}
.T&
ls
l lw(2.2i).
\*(FC\-\^\-lint\*(FR[\*(FC=fatal\*(FR]
%T{
warn about constructs that are dubious
or non-portable to other \*(AKs.
With an optional argument of \*(FCfatal\*(FR,
lint warnings become fatal errors.
T}
.T&
l lw(2.2i).
\*(FC\-\^\-lint\-old\*(FR%T{
warn about constructs that are not
portable to the original version of
Unix \*(AK.
T}
.T&
ls
l lw(2.2i).
\*(FC\-\^\-non\-decimal\-data\*(FR
%T{
recognize octal and hexadecimal values in input data.
\*(FIUse this option with great caution!\*(FR
T}
.T&
l lw(2.2i).
\*(FC\-\^\-posix\*(FR%T{
disable common and GNU extensions.
Enable \*(FIinterval expressions\*(FR in regular
expression matching (see \fHRegular
Expressions\fP below).
T}
.T&
ls
l lw(2.2i).
\*(FC\-\^\-profile\*(FR[\*(FC=\*(FIprof_file\*(FR]
%T{
send profiling data to \*(FIprof_file\*(FR
(default: \*(FCawkprof.out\*(FR).
With \*(FIgawk\*(FR,
the profile is just a ``pretty printed'' version of the program.
With \*(FIpgawk\*(FR,
the profile contains execution counts in the left margin
of each statement in the program.
T}
.T&
ls
l lw(2.2i).
\*(FC\-\^\-re\-interval\*(FR
%T{
enable \*(FIinterval expressions\*(FR in regular
expression matching (see \fHRegular
Expressions\fP below). Useful if
\*(FC\-\^\-posix\*(FR is not specified.
T}
.T&
ls
l lw(2.2i).
\*(FC\-\^\-source '\*(FItext\*(FC'\*(FR
%use \*(FItext\*(FR as AWK program source code.
\*(FC\-\^\-version\*(FR%T{
print version information on \*(FCstdout\fP
and exit zero.
T}
.TE
.sp .5
.fi
In compatibility mode,
any other options are flagged as invalid, but are otherwise ignored.
In normal operation, as long as program text has been supplied, unknown
options are passed on to the AWK program in
\*(FCARGV\*(FR
for processing. This is most useful for running AWK
programs via the \*(FC#!\*(FR executable interpreter mechanism.
.sp .5
\*(FIpgawk\fP accepts two signals.
\*(FCSIGUSR1\fP causes it to dump a profile and function call stack to the
profile file.  It then continues to run.
\*(FCSIGHUP\fP
causes it to dump the profile and function call stack and then exit.\*(CB
.EB "\s+2\f(HBCOMMAND LINE ARGUMENTS (\*(GK\f(HB)\*(FR\s0"

.BT

.\"
.\"
.\" --- Command Line Arguments (mawk)
.ES
.fi
\*(CDThe following options are specific to \*(MK.
.sp .5
.fi
.TS
expand;
l lw(1.8i).
\*(FC\-W dump\*(FR	T{
print an assembly listing of the program to
\*(FCstdout\fP and exit zero.
T}
\*(FC\-W exec \*(FIfile\*(FR	T{
read program text from \*(FIfile\fP. No other
options are processed. Useful with \*(FC#!\fP.
T}
\*(FC\-W interactive\*(FR	T{
unbuffer \*(FCstdout\fP and line buffer \*(FCstdin\fP.
Lines are always records, ignoring \*(FCRS\fP.
T}
\*(FC\-W posix_space\*(FR	T{
\*(FC\en\*(FR separates fields when \*(FCRS = "\^"\fP.
T}
\*(FC\-W sprintf=\*(FInum\*(FR	T{
adjust the size of \*(MK's internal
\*(FCsprintf\*(FR buffer.
T}
\*(FC\-W version\*(FR	T{
print version and copyright on
\*(FCstdout\fP and limit information on \*(FCstderr\fP
and exit zero.
T}
.TE
.sp .5
.fi
The options may be abbreviated using just the first letter, e.g.,
\*(FC\-We\*(FR,
\*(FC\-Wv\*(FR
and so on.\*(CB
.EB "\s+2\f(HBCOMMAND LINE ARGUMENTS (\*(MK\f(HB)\*(FR\s0"

.\" --- Awk Program Execution
.ES
.fi
\*(CDAWK programs are a sequence of pattern-action statements
and optional function definitions.
.sp .5
	\*(FIpattern\*(FC	{ \*(FIaction statements\*(FC }\*(FR
.br
	\*(FCfunction \*(FIname\*(FC(\*(FIparameter list\*(FC) { \*(FIstatements\*(FC }\*(FR
.sp .5
\*(AK first reads the program source from the
\*(FIprog-file\*(FR(s), if specified,
\*(CBfrom arguments to \*(FC\-\^\-source\*(FR,\*(CD
or from the first non-option argument on the command line.
The program text is read as if all the \*(FIprog-file\*(FR(s)
\*(CBand command line
source texts\*(CD had been concatenated.
.sp .5
AWK programs execute in the following order.
First, all variable assignments specified via the \*(FC\-v\fP
option are performed.
Next, \*(AK executes the code in the
\*(FCBEGIN\fP rules(s), if any, and then proceeds to read
the files \*(FC1\fP through \*(FCARGC \- 1\fP in the \*(FCARGV\fP array.
(Adjusting \*(FCARGC\fP and \*(FCARGV\fP thus provides control over
the input files that will be processed.)
If there are no files named on the command line,
\*(AK reads the standard input.
.sp .5
If a command line argument has the form
\*(FIvar\*(FC=\*(FIval\*(FR,
it is treated as a variable assignment. The variable
\*(FIvar\fP will be assigned the value \*(FIval\*(FR.
(This happens after any \*(FCBEGIN\fP rule(s) have been run.)
... delete this paragraph if no space
Command line variable assignment
is most useful for dynamically assigning values to the variables
\*(AK uses to control how input is broken into fields and records. It
is also useful for controlling state if multiple passes are needed over
a single data file.
.sp .5
If the value of a particular element of \*(FCARGV\fP is empty
(\*(FC"\^"\*(FR), \*(AK skips over it.
.sp .5
For each record in the input, \*(AK tests to see if it matches any
\*(FIpattern\fP in the AWK program.
For each pattern that the record matches, the associated
\*(FIaction\fP is executed.
The patterns are tested in the order they occur in the program.
.sp .5
Finally, after all the input is exhausted,
\*(AK executes the code in the \*(FCEND\fP rule(s), if any.
.sp .5
If a program only has a \*(FCBEGIN\fP rule, no input files are processed.
If a program only has an \*(FCEND\fP rule, the input will be read.
\*(CX
.EB "\s+2\f(HBAWK PROGRAM EXECUTION\*(FR\s0"


.BT

.\" --- Lines And Statements
.ES
.fi
\*(CDAWK is a line-oriented language. The pattern comes first, and then the
action. Action statements are enclosed in \*(FC{\fP and \*(FC}\*(FR.
Either the pattern  or the action may be missing, but
not both. If the pattern is missing, the action is
executed for every input record.
A missing action is equivalent to
.sp .5
	\*(FC{ print }\fP
.sp .5
which prints the entire record.
.sp .5
Comments begin with the \*(FC#\*(FR character, and continue until the
end of the line.
Normally, a statement ends with a newline, but lines ending in
a ``,'',
\*(FC{\*(FR,
\*(CB\*(FC?\*(FR,
\*(FC:\*(FR,\*(CD
\*(FC&&\*(FR
or
\*(FC||\*(FR
are automatically continued.
Lines ending in \*(FCdo\fP or \*(FCelse\fP
also have their statements automatically continued on the following line.
In other cases, a line can be continued by ending it with a ``\e'',
in which case the newline is ignored. However, a ``\e'' after a
\*(FC#\*(FR is not special.
.sp .5
Multiple statements may be put on one line by separating them with a ``;''.
This applies to both the statements within the action part of a
pattern-action pair (the usual case)
and to the pattern-action statements themselves.\*(CX
.EB "\s+2\f(HBLINES AND STATEMENTS\*(FR\s0"



.\" --- Regular Expressions
.ES
.fi
\*(CDRegular expressions are the extended kind originally defined by
\*(FCegrep\fP.
\*(CBAdditional GNU regexp operators are supported by \*(GK.
A \*(FIword-constituent\fP character is a letter, digit, or
underscore (\*(FC_\fP).\*(CD
.sp .5
.TS
center, tab(~);
cp8 sp8
cp8 sp8
lp8|lp8.
.\" .vs 10
_
Summary of Regular Expressions
In Decreasing Precedence
_
\*(FC(\^\*(FIr\*(FC)\*(FR~regular expression (for grouping)
\*(FIc\*(FR~if non-special char, matches itself
\*(FC\e\*(FI\^c\*(FR~turn off special meaning of \*(FIc\fP
\*(FC^\*(FR~beginning of string (note: \*(FInot\fP line)
\*(FC$\*(FR~end of string (note: \*(FInot\fP line)
\*(FC.\*(FR~any single character, including newline
\*(FC[\*(FR...\*(FC]\*(FR~any one character in ... or range
\*(FC[^\*(FR...\*(FC]\*(FR~any one character not in ... or range
\*(CB\*(FC\ey\*(FR~word boundary
\*(FC\eB\*(FR~middle of a word
\*(FC\e<\*(FR~beginning of a word
\*(FC\e>\*(FR~end of a word
\*(FC\ew\*(FR~any word-constituent character
\*(FC\eW\*(FR~any non-word-constituent character
\*(FC\e`\*(FR~beginning of a string
\*(FC\e'\*(FR~end of a string\*(CD
\*(FIr\*(FC*\*(FR~zero or more occurrences of \*(FIr\*(FR
\*(FIr\*(FC+\*(FR~one or more occurrences of \*(FIr\*(FR
\*(FIr\*(FC?\*(FR~zero or one occurrences of \*(FIr\*(FR
\*(FIr\*(FC{\*(FIn\*(FC,\*(FIm\*(FC}\*(FR~\*(FIn\fP to \*(FIm\fP occurrences of \*(FIr\*(FR \*(CR(POSIX: see note below)\*(CD
\*(FIr1\*(FC|\|\*(FIr2\*(FR~\*(FIr1\*(FR or \*(FIr2\*(FR
.TE
.sp .5
.fi
\*(CRThe \*(FIr\*(FC{\*(FIn\*(FC,\*(FIm\*(FC}\*(FR notation is called an
\*(FIinterval expression\fP. POSIX mandates it for AWK regexps, but
most \*(AKs don't implement it. \*(CBUse \*(FC\-\^\-re\-interval\*(FR
or \*(FC\-\^\-posix\*(FR to enable
this feature in \*(GK.\*(CX
.EB "\s+2\f(HBREGULAR EXPRESSIONS\*(FR\s0"


.BT

.\" --- POSIX Character Classes (gawk)
.ES
.fi
\*(CDIn regular expressions, within character ranges
(\*(FC[\*(FR...\*(FC]\*(FR),
the notation \*(FC[[:\*(FIclass\*(FC:]]\*(FR defines character classes:
.sp .5
.TS
center, tab(~);
lp8 lp8 lp8 lp8.
\*(FCalnum\*(FR~alphanumeric~\*(FClower\*(FR~lower-case
\*(FCalpha\*(FR~alphabetic~\*(FCprint\*(FR~printable
\*(FCblank\*(FR~space or tab~\*(FCpunct\*(FR~punctuation
\*(FCcntrl\*(FR~control~\*(FCspace\*(FR~whitespace
\*(FCdigit\*(FR~decimal~\*(FCupper\*(FR~upper-case
\*(FCgraph\*(FR~non-spaces~\*(FCxdigit\*(FR~hexadecimal
.TE
.fi
.sp .5
Recognition of these character classes is disabled
when \*(FC\-\-traditional\*(FR is supplied.\*(CB
.EB "\s+2\f(HBPOSIX CHARACTER CLASSES (\*(GK\f(HB)\*(FR\s0"

.\" --- Records
.ES
.fi
\*(CDNormally, records are separated by newline characters.
Assigning values to the built-in variable \*(FCRS\*(FR
controls how records are separated.
If \*(FCRS\fP is any single character, that character separates records.
\*(CLOtherwise, \*(FCRS\fP is a regular expression.
\*(CR(Not \*(NK.)\*(CL
Text in the input that matches this
regular expression separates the record.
\*(CB\*(GK sets \*(FCRT\*(FR to the value of the
input text that matched the regular expression.
The value of \*(FCIGNORECASE\fP
also affects how records are separated when
\*(FCRS\fP is a regular expression.\*(CD
If \*(FCRS\fP is set to the null string,
then records are separated by one or more blank lines.
When \*(FCRS\fP is set to the null string,
the newline character always acts as
a field separator, in addition to whatever value
\*(FCFS\fP may have.
\*(CB\*(MK does not apply exceptional rules to \*(FCFS\fP
when \*(FCRS = "\^"\fP.\*(CX
.EB "\s+2\f(HBRECORDS\*(FR\s0"

.\" --- Fields
.ES
.fi
\*(CDAs each input record is read, \*(AK splits the record into
\*(FIfields\*(FR, using the value of the \*(FCFS\fP
variable as the field separator.
If \*(FCFS\fP is a single character,
fields are separated by that character.
\*(CLIf \*(FCFS\fP is the null string,
then each individual character becomes a separate field.\*(CD
Otherwise, \*(FCFS\fP is expected to be a full regular expression.
In the special case that \*(FCFS\fP
is a single space, fields are separated
by runs of spaces and/or tabs
\*(CLand/or newlines\*(CD.
Leading and trailing whitespace are ignored.
\*(CBThe value of \*(FCIGNORECASE\fP
also affects how fields are split when
\*(FCFS\fP is a regular expression.\*(CD
.sp .5
\*(CBIf the \*(FCFIELDWIDTHS\fP
variable is set to a space-separated list of numbers, each field is
expected to have a fixed width, and \*(GK
splits up the record using the specified widths.
The value of \*(FCFS\fP is ignored.
Assigning a new value to \*(FCFS\fP
overrides the use of \*(FCFIELDWIDTHS\*(FR,
and restores the default behavior.\*(CD
.sp .5
Each field in the input record may be referenced by its position,
\*(FC$1\*(FR, \*(FC$2\*(FR and so on.
\*(FC$0\fP is the whole record.
Fields may also be assigned new values.
.sp .5
The variable \*(FCNF\fP
is set to the total number of fields in the input record.
.sp .5
References to non-existent fields (i.e., fields after \*(FC$NF\*(FR)
produce the null-string. However, assigning to a non-existent field
(e.g., \*(FC$(NF+2) = 5\*(FR) increases the value of
\*(FCNF\*(FR, creates any intervening fields with the null string as their value,
and causes the value of \*(FC$0\fP
to be recomputed with the fields being separated by the
value of \*(FCOFS\*(FR.
References to negative numbered fields cause a fatal error.
Decreasing the value of \*(FCNF\fP causes the trailing fields to be lost
\*(CR(not \*(NK).\*(CX
.EB "\s+2\f(HBFIELDS\*(FR\s0"

.BT

.\" --- Pattern Elements
.ES
.fi
\*(CDAWK patterns may be one of the following.
.sp .5
.nf
	\*(FCBEGIN
	END
	\*(FIexpression	
	pat1\*(FC,\*(FIpat2\*(FR
.sp .5
.fi
\*(FCBEGIN\fP and \*(FCEND\fP are special patterns that provide start-up
and clean-up actions respectively. They must have actions. There can
be multiple \*(FCBEGIN\fP and \*(FCEND\fP rules; they are merged and
executed as if there had just been one large rule. They may occur anywhere
in a program, including different source files.
.sp .5
Expression patterns can be any expression, as described
under \fHExpressions\fP.
.sp .5
The \*(FIpat1\*(FC,\*(FIpat2\*(FR pattern
is called a \*(FIrange pattern\*(FR.
It matches all input records starting with a record that matches
\*(FIpat1\*(FR, and continuing until a record that matches
\*(FIpat2\*(FR, inclusive.
It does not combine with any other pattern expression.\*(CX
.EB "\s+2\f(HBPATTERN ELEMENTS\*(FR\s0"


.\" --- Action Statements
.ES
.fi
.in +.2i
.ti -.2i
\*(CD\*(FCbreak\*(FR
.br
break out of the nearest enclosing \*(FCdo\*(FR, \*(FCfor\*(FR,
or \*(FCwhile\*(FR loop.
.ti -.2i
\*(FCcontinue\*(FR
.br
skip the rest of the loop body.
Evaluate the \*(FIcondition\*(FR
part of the nearest enclosing \*(FCdo\*(FR or \*(FCwhile\*(FR loop,
or go to the \*(FIincr\*(FR part of a \*(FCfor\*(FR loop.
.ti -.2i
\*(FCdelete \*(FIarray\^\*(FC[\^\*(FIindex\^\*(FC]\*(FR
.br
delete element \*(FIindex\*(FR from array \*(FIarray\*(FR.
.ti -.2i
\*(CL\*(FCdelete \*(FIarray\^\*(FR
.br
delete all elements from array \*(FIarray\*(FR.\*(CD
.ti -.2i
\*(FCdo \*(FIstatement  \*(FCwhile (\*(FIcondition\*(FC)\*(FR
.br
execute \*(FIstatement\*(FR while \*(FIcondition\*(FR is true.
The \*(FIstatement\*(FR is always executed at least once.
.ti -.2i
\*(FCexit\*(FR [ \*(FIexpression\*(FR ]
.br
terminate input record processing.
Execute the \*(FCEND\*(FR rule(s) if present.
If present, \*(FIexpression\*(FR becomes \*(AK's return value.
.ti -.2i
\*(FCfor (\*(FIinit\*(FC; \*(FIcond\*(FC; \*(FIincr\*(FC) \*(FIstatement\*(FR
.br
execute \*(FIinit\*(FR.
Evaluate \*(FIcond\*(FR.
If it is true, execute \*(FIstatement\*(FR.
Execute \*(FIincr\*(FR before going back to the top to
re-evaluate \*(FIcond\*(FR.
Any of the three may be omitted.
A missing \*(FIcond\*(FR is considered to be true.
.ti -.2i
\*(FCfor (\*(FIvar \*(FCin\*(FI array\*(FC) \*(FIstatement\*(FR
.br
execute \*(FIstatement\*(FR once for each subscript in \*(FIarray\*(FR,
with \*(FIvar\*(FR set to a different subscript each time through
the loop.
.ti -.2i
\*(CD\*(FCif (\*(FIcondition\*(FC) \*(FIstatement1\*(FR [ \*(FCelse\*(FI statement2\*(FR ]
.br
if \*(FIcondition\*(FR is true, execute \*(FIstatement1\*(FR,
otherwise execute \*(FIstatement2\*(FR. Each \*(FCelse\*(FR
matches the closest \*(FCif\*(FR.
.ti -.2i
\*(FCnext\*(FR	see \fHInput Control.\fP
.ti -.2i
\*(CL\*(FCnextfile\*(FR \*(CR(not \*(MK)	\*(CLsee \fHInput Control.\fP\*(CD
.ti -.2i
\*(FCwhile (\*(FIcondition\*(FC) \*(FIstatement \*(FR
.br
while \*(FIcondition\*(FR is true, execute \*(FIstatement\*(FR.
.ti -.2i
\*(FC{ \*(FIstatements \*(FC}\*(FR
.br
a list of statements enclosed in braces can be used anywhere
that a single statement would otherwise be used.\*(CX
.in -.2i
.EB "\s+2\f(HBACTION STATEMENTS\*(FR\s0"


.BT

.\" --- Escape Sequences
.ES
.fi
\*(CDWithin strings constants (\*(FC"..."\fP) and regexp
constants (\*(FC/.../\fP), escape sequences may be used to
generate otherwise unprintable characters. This table lists
the available escape sequences.
.sp .5
.TS
center, tab(~);
lp8 lp8 lp8 lp8.
\*(FC\ea\fP~alert (bell)~\*(FC\er\fP~carriage return
\*(FC\eb\fP~backspace~\*(FC\et\fP~horizontal tab
\*(FC\ef\fP~form feed~\*(FC\ev\fP~vertical tab
\*(FC\en\fP~newline~\*(FC\e\e\fP~backslash
\*(FC\e\*(FIddd\*(FR~octal value \*(FIddd\fP~\*(CL\*(FC\ex\*(FIhh\*(FR~hex value \*(FIhh\fP\*(CD
\*(FC\e"\fP~double quote~\*(FC\e/\fP~forward slash\*(CX
.TE
.EB "\s+2\f(HBESCAPE SEQUENCES\*(FR\s0"
.sp .7
.\" --- Variables
.ES
.fi
.TS
expand;
l lw(2i).
\*(CD\*(FCARGC\fP	T{
number of command line arguments.
T}
\*(CB\*(FCARGIND\fP	T{
index in \*(FCARGV\fP of current data file.\*(CD
T}
\*(FCARGV\fP	T{
array of command line arguments. Indexed from
0 to \*(FCARGC\fP \- 1. Dynamically changing the
contents of \*(FCARGV\fP can control the files used
for data.
T}
\*(CL\*(FCBINMODE\fP	T{
controls ``binary'' mode for all file I/O.  Values of 1, 2, or 3,
indicate input, output, or all files, respectively, should use binary
I/O.  \*(CR(Not \*(NK.)  \*(CLApplies only to non-POSIX systems.
\*(CBFor \*(GK, string values of \*(FC"r"\fP, or \*(FC"w"\fP specify
that input files, or output files, respectively, should use binary I/O.
String values of \*(FC"rw"\fP or \*(FC"wr"\fP specify that all files
should use binary I/O.  Any other string value is treated as \*(FC"rw"\fP,
but generates a warning message.\*(CD
T}
\*(FCCONVFMT\fP	T{
conversion format for numbers, default value
is \*(FC"%.6g"\*(FR.
T}
\*(FCENVIRON\fP	T{
array containing the current environment.
The array is indexed by the environment
variables, each element being the value of
that variable.
T}
\*(CB\*(FCERRNO\fP	T{
string describing the error if a
\*(FCgetline\*(FR
redirection or read
fails, or if
\*(FCclose()\*(FR fails.
T}
\*(FCFIELDWIDTHS\fP	T{
white-space separated list of fieldwidths. Used
to parse the input into fields of fixed width,
instead of the value of \*(FCFS\fP.\*(CD
T}
\*(FCFILENAME\fP	T{
name of the current input file. If no files given
on the command line, \*(FCFILENAME\fP is ``\-''.
\*(FCFILENAME\fP is undefined inside the \*(FCBEGIN\fP rule
(unless set by \*(FCgetline\fP).
T}
\*(FCFNR\fP	T{
record number in current input file.
T}
\*(FCFS\fP	T{
input field separator, a space by default
(see \fHFields\fP above).
T}
\*(CB\*(FCIGNORECASE\fP	T{
if non-zero, all regular expression and string
operations ignore case.
Array subscripting and \*(FCasort()\*(FR are \*(FInot\*(FR affected.
T}
\*(CB\*(FCLINT\fP	T{
provides dynamic control of the \*(FC\-\^\-lint\fP
option from within an AWK program.
When true, \*(GK
prints lint warnings.
When assigned the string value \*(FC"fatal"\*(FR,
lint warnings become fatal errors, exactly like
\*(FC\-\-lint=fatal\*(FR.
Any other true value just prints warnings.\*(CD
T}
\*(FCNF\fP	T{
number of fields in the current input record.
T}
\*(FCNR\fP	T{
total number of input records seen so far.
T}
\*(FCOFMT\fP	T{
output format for numbers, \*(FC"%.6g"\*(FR, by default.
\*(CROld versions of \*(AK used this for number
to string conversion.\*(CX
T}
.TE
.EB "\s+2\f(HBVARIABLES\*(FR\s0"
.BT

.\" --- Variables (continued)
.ES
.fi
.TS
expand;
l lw(2i).
\*(CD\*(FCOFS\fP	T{
output field separator, a space by default.
T}
\*(FCORS\fP	T{
output record separator, a newline by default.
T}
\*(CB\*(FCPROCINFO\fP	T{
elements of this array provide access to info
about the running AWK program. See
\*(AM for details.\*(CD
T}
\*(FCRLENGTH\fP	T{
length of the string matched by \*(FCmatch()\*(FR;
\-1 if no match.
T}
\*(FCRS\fP	T{
input record separator, a newline by default
(see \fHRecords\fP above).
T}
\*(FCRSTART\fP	T{
index of the first character matched by
\*(FCmatch()\*(FR; 0 if no match.
T}
\*(CB\*(FCRT\fP	T{
record terminator. \*(GK sets \*(FCRT\fP to the input
text that matched the character or regular
expression specified by \*(FCRS\*(FR.\*(CD
T}
\*(FCSUBSEP\fP	T{
character(s) used to separate multiple subscripts
in array elements, by default \*(FC"\e034"\*(FR. (See
\fHArrays\fP below).
T}
\*(CB\*(FCTEXTDOMAIN\fP	T{
the application's text domain for internationalization;
used to find the localized
translations for the program's strings.\*(CX
T}
.TE
.EB "\s+2\f(HBVARIABLES (continued)\*(FR\s0"

.\" --- Conversions and Comparisons
.ES
.fi
\*(CDVariables and fields may be (floating point) numbers, strings or both.
Context determines how the value of a variable is interpreted. If used in
a numeric expression, it will be treated as a number, if used as a string
it will be treated as a string.
.sp .5
To force a variable to be treated as a number, add 0 to it; to force it
to be treated as a string, concatenate it with the null string.
.sp .5
When a string must be converted to a number, the conversion is accomplished
using \*(FIstrtod\*(FR(3).
A number is converted to a string by using the value of \*(FCCONVFMT\fP
as a format string for \*(FIsprintf\*(FR(3),
with the numeric value of the variable as the argument.
However, even though all numbers in AWK are floating-point,
integral values are \*(FIalways\fP converted as integers.
.sp .5
Comparisons are performed as follows:
If two variables are numeric, they are compared numerically.
If one value is numeric and the other has a string value that is a
``numeric string,'' then comparisons are also done numerically.
Otherwise, the numeric value is converted to a string, and a string
comparison is performed.
Two strings are compared, of course, as strings.
.sp .5
Note that string constants, such as \*(FC"57"\fP, are \*(FInot\fP
numeric strings, they are string constants. The idea of ``numeric string''
only applies to fields, \*(FCgetline\fP input,
\*(FCFILENAME\*(FR, \*(FCARGV\fP elements, \*(FCENVIRON\fP
elements and the elements of an array created by
\*(FCsplit()\fP that are numeric strings.
The basic idea is that \*(FIuser input\*(FR,
and only user input, that looks numeric,
should be treated that way.
\*(CRNote that the POSIX standard applies the concept of
``numeric string'' everywhere, even to string constants.
However, this is
clearly incorrect, and none of the three free \*(AK\*(FRs do this.\*(CD
(Fortunately, this is fixed in the next version of the standard.)
.sp .5
Uninitialized variables have the numeric value 0 and the string value
\*(FC"\^"\fP
(the null, or empty, string).\*(CX
.EB "\s+2\f(HBCONVERSIONS AND COMPARISONS\*(FR\s0"

.BT

.ES
\*(CX
.sp 61
.EB "\s+2\f(HBNOTES\*(FR\s0"

.BT

.\" --- Arrays
.ES
.fi
\*(CDAn array subscript is an expression between square brackets
(\*(FC[ \*(FRand \*(FC]\*(FR).
If the expression is a list
(\*(FIexpr\*(FC, \*(FIexpr \*(FR...),
then the subscript is a string consisting of the
concatenation of the (string) value of each expression,
separated by the value of the \*(FCSUBSEP\fP variable.
This simulates multi-dimensional
arrays. For example:
.nf
.sp .5
	\*(FCi = "A";\^ j = "B";\^ k = "C"
	x[i, j, k] = "hello, world\en"\*(FR
.sp .5
.fi
assigns \*(FC"hello, world\en"\*(FR to the element of the array
\*(FCx\fP
indexed by the string \*(FC"A\e034B\e034C"\*(FR. All arrays in AWK
are associative, i.e., indexed by string values.
.sp .5
Use the special operator \*(FCin\fP in an \*(FCif\fP
or \*(FCwhile\fP statement to see if a particular value is
an array index.
.sp .5
.nf
	\*(FCif (val in array)
		print array[val]\*(FR
.sp .5
.fi
If the array has multiple subscripts, use
\*(FC(i, j) in array\*(FR.
.sp .5
Use the \*(FCin\fP construct in a \*(FCfor\fP
loop to iterate over all the elements of an array.
.sp .5
Use the \*(FCdelete\fP statement to delete an
element from an array.
\*(CLSpecifying just the array name without a subscript in
the \*(FCdelete\fP
statement deletes the entire contents of an array.\*(CX
.EB "\s+2\f(HBARRAYS\*(FR\s0"

.\" --- Expressions
.ES
.fi
\*(CDExpressions are used as patterns, for controlling conditional action
statements, and to produce parameter values when calling functions.
Expressions may also be used as simple statements,
particularly if they have side-effects such as assignment.
Expressions mix \*(FIoperands\fP and \*(FIoperators\fP. Operands are
constants, fields, variables, array elements, and the return
values from function calls (both built-in and user-defined).
.sp .5
Regexp constants (\*(FC/\*(FIpat\*(FC/\*(FR), when used as simple expressions,
i.e., not used on the right-hand side of
\*(FC~\fP and \*(FC!~\fP, or as arguments to the
\*(CB\*(FCgensub()\fP,\*(CD
\*(FCgsub()\fP,
\*(FCmatch()\fP,
\*(FCsplit()\fP,
and
\*(FCsub()\fP,
functions, mean \*(FC$0 ~ /\*(FIpat\*(FC/\*(FR.
.sp .5
The AWK operators, in order of decreasing precedence, are:
.sp .5
.fi
.TS
expand;
l lw(1.8i).
\*(FC(\&...)\*(FR	grouping
\*(FC$\fP	field reference
\*(FC++ \-\^\-\fP	T{
increment and decrement,
prefix and postfix
T}
\*(FC^\fP \*(CL\*(FC**\*(FR\*(CD	exponentiation
\*(FC+ \- !\fP	unary plus, unary minus, and logical negation
\*(FC* / %\fP	multiplication, division, and modulus
\*(FC+ \-\fP	addition and subtraction
\*(FIspace\fP	string concatenation
\*(FC< >\fP	less than, greater than
\*(FC<= >=\fP	less than or equal, greater than or equal
\*(FC!= ==\fP	not equal, equal
\*(FC~ !~\fP	regular expression match, negated match
\*(FCin\fP	array membership
\*(FC&&\fP	logical AND, short circuit
\*(FC||\fP	logical OR, short circuit
\*(FC?\^:\fP	in-line conditional expression
.T&
l s
l lw(1.8i).
\*(FC=\0+=\0\-=\0*=\0/=\0%=\0^=\0\*(CL**=\*(CD\fP
	assignment operators\*(CX
.TE
.EB "\s+2\f(HBEXPRESSIONS\*(FR\s0"

.BT

.\" --- Input Control
.ES
.fi
.TS
expand;
l lw(1.8i).
\*(FCgetline\fP	T{
set \*(FC$0\fP from next record;
set \*(FCNF\*(FR, \*(FCNR\*(FR, \*(FCFNR\*(FR.
T}
\*(FCgetline < \*(FIfile\*(FR	set \*(FC$0\fP from next record of \*(FIfile\*(FR; set \*(FCNF\*(FR.
\*(FCgetline \*(FIv\*(FR	T{
set \*(FIv\fP from next input record;
set \*(FCNR\*(FR, \*(FCFNR\*(FR.
T}
\*(FCgetline \*(FIv \*(FC< \*(FIfile\*(FR	set \*(FIv\fP from next record of \*(FIfile\*(FR.
\*(FIcmd \*(FC| getline\*(FR	pipe into \*(FCgetline\*(FR; set \*(FC$0\*(FR, \*(FCNF\*(FR.
\*(FIcmd \*(FC| getline \*(FIv\*(FR	pipe into \*(FCgetline\*(FR; set \*(FIv\*(FR.
\*(CB\*(FIcmd \*(FC|& getline\*(FR	co-process pipe into \*(FCgetline\*(FR; set \*(FC$0\*(FR, \*(FCNF\*(FR.
.TE
.fi
.in +.2i
.ti -.2i
\*(FIcmd \*(FC|& getline \*(FIv\*(FR
.br
co-process pipe into \*(FCgetline\*(FR; set \*(FIv\*(FR.
.ti -.2i
\*(FCnext\fP
.br
stop processing the current input
record. Read next input record and
start over with the first pattern in the
program. Upon end of the input data,
execute any \*(FCEND\fP rule(s).
.br
.ti -.2i
\*(CL\*(FCnextfile\fP
.br
stop processing the current input file.
The next input record comes from the
next input file. \*(FCFILENAME\fP \*(CBand
\*(FCARGIND\fP\*(CL are updated, \*(FCFNR\fP is reset to 1,
and processing starts over with the first
pattern in the AWK program. Upon end
of input data, execute any \*(FCEND\fP rule(s).
\*(CREarlier versions of \*(GK used
\*(FCnext file\*(FR, as two words.
This usage is no longer supported.
\*(CR\*(MK does not currently support \*(FCnextfile\*(FR.\*(CD
.in -.2i
.sp .5
.fi
\*(FCgetline\*(FR returns 0 on end of file and \-1 on an error.
\*(CBUpon an error, \*(FCERRNO\*(FR contains a string describing
the problem.\*(CX
.EB "\s+2\f(HBINPUT CONTROL\*(FR\s0"

.\" --- Output Control
.ES
.fi
.in +.2i
.ti -.2i
\*(CL\*(FCfflush(\*(FR[\*(FIfile\^\*(FR]\*(FC)\*(FR
.br
flush any buffers associated
with the open output file or pipe \*(FIfile\*(FR.\*(CD
\*(CBIf no \*(FIfile\fP, then flush standard output.
If \*(FIfile\fP is null, then flush all open output files and pipes
\*(CR(not \*(NK)\*(CD.
.ti -.2i
\*(FCprint\fP
.br
print the current record. Terminate output record
with \*(FCORS\fP.
.ti -.2i
\*(FCprint \*(FIexpr-list\*(FR
.br
print expressions. Each expression is separated
by the value of \*(FCOFS\fP. Terminate the output record
with \*(FCORS\fP.
.ti -.2i
\*(FCprintf \*(FIfmt\*(FC, \*(FIexpr-list\*(FR
.br
format and print (see \fHPrintf Formats\fP below).
.ti -.2i
\*(FCsystem(\*(FIcmd\*(FC)\*(FR
.br
execute the command \*(FIcmd\*(FR,
and return the exit status
\*(CR(may not be available on non-POSIX systems)\*(CD.
.sp .5
.in -.2i
I/O redirections may be used with both \*(FCprint\fP and \*(FCprintf\fP.
.sp .5
.in +.2i
.ti -.2i
\*(CD\*(FCprint "hello" > \*(FIfile\*(FR
.br
print data to \*(FIfile\fP. The first time the file is written to, it
is truncated. Subsequent commands append data.
.ti -.2i
\*(FCprint "hello" >> \*(FIfile\*(FR
.br
append data to \*(FIfile\fP. The previous contents of \*(FIfile\*(FR are not lost.
.ti -.2i
\*(FCprint "hello" | \*(FIcmd\*(FR
.br
print data down a pipeline to \*(FIcmd\*(FR.
.ti -.2i
\*(CB\*(FCprint "hello" |& \*(FIcmd\*(FR
.br
print data down a pipeline to co-process \*(FIcmd\*(FR.\*(CX
.in -.2i
.EB "\s+2\f(HBOUTPUT CONTROL\*(FR\s0"

.ES
.fi
.in +.2i
.ti -.2i
\*(CD\*(FCclose(\*(FIfile\*(FC)\*(FR
.br
close input or output file, pipe \*(CBor co-process.\*(CD
.ti -.2i
\*(CB\*(FCclose(\*(FIcommand\*(FC, \*(FIhow\*(FC)\*(FR
.br
close one end of co-process pipe.
Use \*(FC"to"\*(FR for the write end, or
\*(FC"from"\*(FR for the read end.\*(CD
.in -.2i
.sp .5
On success, \*(FCclose()\*(FR returns zero for a file, or the exit status for a process.
It returns \-1 if \*(FIfile\*(FR
was never opened, or
if there was a system problem.
\*(CB\*(FCERRNO\*(FR describes
the error.\*(CX
.EB "\s+2\f(HBCLOSING REDIRECTIONS\*(FR\s0"

.BT

.\" --- Printf Formats
.ES
.fi
\*(CDThe \*(FCprintf\fP statement and
\*(FCsprintf()\fP function
accept the following conversion specification formats:
.sp .5
.nf
\*(FC%c\fP		an \s-1ASCII\s+1 character
\*(FC%d\fP		a decimal number (the integer part)
\*(FC%i\fP		a decimal number (the integer part)
\*(FC%e\fP		a floating point number of the form
		\*(FC[\-]d.dddddde[+\^\-]dd\*(FR
\*(FC%E\fP		like \*(FC%e\fP, but use \*(FCE\fP instead of \*(FCe\*(FR
\*(FC%f\fP		a floating point number of the form
		\*(FC[\-]ddd.dddddd\*(FR
\*(FC%g\fP		use \*(FC%e\fP or \*(FC%f\fP, whichever is shorter, with
		nonsignificant zeros suppressed
\*(FC%G\fP		like \*(FC%g\fP, but use \*(FC%E\fP instead of \*(FC%e\*(FR
\*(FC%o\fP		an unsigned octal integer
\*(FC%u\fP		an unsigned decimal integer
\*(FC%s\fP		a character string
\*(FC%x\fP		an unsigned hexadecimal integer
\*(FC%X\fP		like \*(FC%x\fP, but use \*(FCABCDEF\fP for 10\(en15
\*(FC%%\fP		A literal \*(FC%\fP; no argument is converted
.sp .5
.fi
Optional, additional parameters may lie between the \*(FC%\fP
and the control letter:
.sp .5
.TS
expand;
l lw(2.2i).
\*(CB\*(FIcount\*(FC$\*(FR	T{
use the
\*(FIcount\*(FR'th
argument at this point in the formatting
(a \*(FIpositional specifier\*(FR).
Use in translated versions of
format strings, not in the original text of an AWK program.\*(CD
T}
\*(FC\-\fP	T{
left-justify the expression within its field.
T}
\*(FIspace\fP	T{
for numeric conversions, prefix positive values
with a space and negative values with a
minus sign.
T}
\*(FC+\fP	T{
used before the \*(FIwidth\fP modifier means to always
supply a sign for numeric conversions, even if
the data to be formatted is positive. The \*(FC+\fP
overrides the space modifier.
T}
\*(FC#\fP	T{
use an ``alternate form'' for some control letters.
T}
 \*(FC%o\*(FR	T{
supply a leading zero.
T}
 \*(FC%x\*(FR, \*(FC%X\*(FR	T{
supply a leading \*(FC0x\*(FR or \*(FC0X\*(FR for a nonzero result.
T}
 \*(FC%e\*(FR, \*(FC%E\*(FR, \*(FC%f\*(FR	T{
the result always has a decimal point.
T}
 \*(FC%g\*(FR, \*(FC%G\*(FR	T{
trailing zeros are not removed.
T}
\*(FC0\fP	T{
a leading zero acts as a flag, indicating output
should be padded with zeros instead of spaces.
This applies even to non-numeric output formats.
Only has an effect when the field width is wider
than the value to be printed.
T}
\*(FIwidth\fP	T{
pad the field to this width. The field is normally
padded with spaces. If the \*(FC0\fP flag has been used,
pad with zeros.
T}
\*(FC.\*(FIprec\*(FR	T{
precision.
The meaning of the \*(FIprec\*(FR varies by control letter:
T}
 \*(FC%d\*(FR, \*(FC%o\*(FR, \*(FC%i\*(FR,
 \*(FC%u\*(FR, \*(FC%x\*(FR, \*(FC%X\fP	T{
the minimum number of digits to print.
T}
 \*(FC%e\*(FR, \*(FC%E\*(FR, \*(FC%f\*(FR	T{
the number of digits to print to the right of the decimal point.
T}
 \*(FC%g\*(FR, \*(FC%G\fP	T{
the maximum number of significant digits.
T}
 \*(FC%s\fP	T{
the maximum number of characters to print.
T}
.TE
.sp .5
.fi
The dynamic \*(FIwidth\fP and \*(FIprec\fP capabilities of the ANSI C
\*(FCprintf()\fP routines are supported.
A \*(FC*\fP in place of either the \*(FIwidth\fP or \*(FIprec\fP
specifications causes their values to be taken from
the argument list to \*(FCprintf\fP or \*(FCsprintf()\*(FR.
\*(CBUse \*(FC*\*(FIn\*(FC$\*(FR to use positional specifiers
with a dynamic width or precision.\*(CX
.EB "\s+2\f(HBPRINTF FORMATS\*(FR\s0"


.BT

.\" --- Special Filenames
.ES
.fi
\*(CDWhen doing I/O redirection from either \*(FCprint\fP
or \*(FCprintf\fP into a file or via \*(FCgetline\fP
from a file, all three implementations of \*(FCawk\fP
recognize certain special filenames internally. These filenames
allow access to open file descriptors inherited from the
parent process (usually the shell).
These filenames may also be used on the command line to name data files.
The filenames are:
.sp .5
.TS
expand;
l lw(2i).
\*(FC"\-"\fP	standard input
\*(FC/dev/stdin\fP	standard input \*(CR(not \*(MK)\*(CD
\*(FC/dev/stdout\fP	standard output
\*(FC/dev/stderr\fP	standard error output
.TE
.sp .5
.fi
\*(CBThe following names are specific to \*(GK.
.sp .5
.in +.2i
.ti -.2i
\*(FC/dev/fd/\^\*(FIn\*(FR
.br
File associated with the open file descriptor \*(FIn\*(FR.
.ti -.2i
\*(FC/inet/tcp/\*(FIlport\*(FC/\*(FIrhost\*(FC/\*(FIrport\*(FR
.br
File for TCP/IP connection on local port \*(FIlport\*(FR to
remote host \*(FIrhost\*(FR on remote port \*(FIrport\*(FR.
Use a port of \*(FC0\*(FR to have the system pick a port.
Usable only with the \*(FC|&\*(FR two-way I/O operator.
.ti -.2i
\*(FC/inet/udp/\*(FIlport\*(FC/\*(FIrhost\*(FC/\*(FIrport\*(FR
.br
Similar, but use UDP/IP instead of TCP/IP.
.ti -.2i
\*(CR\*(FC/inet/raw/\*(FIlport\*(FC/\*(FIrhost\*(FC/\*(FIrport\*(FR
.br
.\" Similar, but use raw IP sockets.
Reserved for future use.\*(CB
.in -.2i
.sp .5
.fi
Other special filenames provide access to information about the running
\*(FCgawk\fP process.
Reading from these files returns a single record.
The filenames and what they return are:\*(FR
.sp .5
.TS
expand;
l lw(2i).
\*(FC/dev/pid\fP	process ID of current process
\*(FC/dev/ppid\fP	parent process ID of current process
\*(FC/dev/pgrpid\fP	process group ID of current process
\*(FC/dev/user\fP	T{
.nf
a single newline-terminated record.
The fields are separated with spaces.
\*(FC$1\fP is the return value of \*(FIgetuid\*(FR(2),
\*(FC$2\fP is the return value of \*(FIgeteuid\*(FR(2),
\*(FC$3\fP is the return value of \*(FIgetgid\*(FR(2) , and
\*(FC$4\fP is the return value of \*(FIgetegid\*(FR(2).
.fi
Any additional fields are the group IDs returned
by \*(FIgetgroups\*(FR(2). Multiple groups may not be
supported on all systems.
T}
.TE
.sp .5
.fi
\*(CRThese filenames are now obsolete.
Use the \*(FCPROCINFO\fP array to obtain the information they provide.\*(CL
.EB "\s+2\f(HBSPECIAL FILENAMES\*(FR\s0"

.\" --- Builtin Numeric Functions
.ES
.fi
.TS
expand;
l lw(2i).
\*(CD\*(FCatan2(\*(FIy\*(FC, \*(FIx\*(FC)\*(FR	the arctangent of \*(FIy/x\fP in radians.
\*(FCcos(\*(FIexpr\*(FC)\*(FR	the cosine of \*(FIexpr\fP, which is in radians.
\*(FCexp(\*(FIexpr\*(FC)\*(FR	the exponential function (\*(FIe \*(FC^ \*(FIx\*(FR).
\*(FCint(\*(FIexpr\*(FC)\*(FR	truncates to integer.
\*(FClog(\*(FIexpr\*(FC)\*(FR	the natural logarithm function (base \*(FIe\^\*(FR).
\*(FCrand()\fP	a random number between 0 and 1.
\*(FCsin(\*(FIexpr\*(FC)\*(FR	the sine of \*(FIexpr\fP, which is in radians.
\*(FCsqrt(\*(FIexpr\*(FC)\*(FR	the square root function.
\&\*(FCsrand(\*(FR[\*(FIexpr\^\*(FR]\*(FC)\*(FR	T{
uses \*(FIexpr\fP as a new seed for the random number
generator. If no \*(FIexpr\fP, the time of day is used.
Returns previous seed for the random number
generator.\*(CX
T}
.TE
.EB "\s+2\f(HBNUMERIC FUNCTIONS\*(FR\s0"


.BT

.\" --- Builtin String Functions
.ES
.fi
.in +.2i
.ti -.2i
\*(CB\*(FCasort(\*(FIs\*(FC \*(FR[\*(FC, \*(FId\*(FR]\*(FC)\*(FR
.br
sorts the source array \*(FIs\*(FR, replacing the indices with numeric
values 1 through \*(FIn\*(FR (the number of elements in the array),
and returns the number of elements.
If destination \*(FId\*(FR is supplied, \*(FIs\*(FR is copied to \*(FId\*(FR,
\*(FId\*(FR is sorted, and \*(FIs\*(FR is unchanged.\*(CD
.ti -.2i
\*(CB\*(FCgensub(\*(FIr\*(FC, \*(FIs\*(FC, \*(FIh \*(FR[\*(FC, \*(FIt\*(FR]\*(FC)\*(FR
.br
search the target string
\*(FIt\fP for matches of the regular expression \*(FIr\*(FR. If
\*(FIh\fP is a string beginning with \*(FCg\fP or \*(FCG\*(FR,
replace all matches of \*(FIr\fP with \*(FIs\*(FR. Otherwise, \*(FIh\fP
is a number indicating which match of \*(FIr\fP to replace.
If \*(FIt\fP is not supplied, \*(FC$0\fP is used instead. Within the
replacement text \*(FIs\*(FR, the sequence \*(FC\e\*(FIn\*(FR,
where \*(FIn\fP is a digit from 1 to 9, may be used to indicate just
the text that matched the \*(FIn\*(FRth parenthesized subexpression.
The sequence \*(FC\e0\fP represents the entire matched text, as does
the character \*(FC&\*(FR. Unlike \*(FCsub()\fP and \*(FCgsub()\*(FR,
the modified string is returned as the result of the function,
and the original target string is \*(FInot\fP changed.\*(CD
.ti -.2i
\*(FCgsub(\*(FIr\*(FC, \*(FIs \*(FR[\*(FC, \*(FIt\*(FR]\*(FC)\*(FR
.br
for each substring matching the
regular expression \*(FIr\fP in the string \*(FIt\*(FR, substitute the
string \*(FIs\*(FR, and return the number of substitutions. If
\*(FIt\fP is not supplied, use \*(FC$0\*(FR. An \*(FC&\fP in the
replacement text is replaced with the text that was actually matched.
Use \*(FC\e&\fP to get a literal \*(FC&\*(FR. See \*(AM
for a fuller discussion of the rules for \*(FC&\*(FR's and backslashes
in the replacement text of \*(CB\*(FCgensub()\*(FR,\*(CD \*(FCsub()\*(FR
and \*(FCgsub()\*(FR
.ti -.2i
\*(FCindex(\*(FIs\*(FC, \*(FIt\*(FC)\*(FR
.br
returns the index of the string
\*(FIt\fP in the string \*(FIs\*(FR, or 0 if \*(FIt\fP is not present.
.ti -.2i
\*(FClength(\*(FR[\*(FIs\*(FR]\*(FC)\*(FR
.br
returns the length of the string
\*(FIs\*(FR, or the length of \*(FC$0\fP if \*(FIs\fP is not supplied.
.ti -.2i
\*(FCmatch(\*(FIs\*(FC, \*(FIr \*(CB\*(FR[\*(FC, \*(FIa\*(FR]\*(CD\*(FC)\*(FR
.br
returns the position in
\*(FIs\fP where the regular expression \*(FIr\fP occurs, or 0 if
\*(FIr\fP is not present, and sets the values of variables
\*(FCRSTART\fP
and \*(FCRLENGTH\*(FR.
\*(CBIf \*(FIa\*(FR is supplied, the text matching all of \*(FIr\*(FR
is placed in \*(FIa\*(FC[0]\*(FR.  If there were parenthesized
subexpressions, the matching texts are placed
in \*(FIa\*(FC[1]\*(FR, \*(FIa\*(FC[2]\*(FR, and so on.\*(CD
.ti -.2i
\*(FCsplit(\*(FIs\*(FC, \*(FIa \*(FR[\*(FC, \*(FIr\*(FR]\*(FC)\*(FR
.br
splits the string
\*(FIs\fP into the array \*(FIa\fP using the regular expression \*(FIr\*(FR,
and returns the number of fields. If \*(FIr\fP is omitted, \*(FCFS\fP
is used instead. The array \*(FIa\fP is cleared first.
Splitting behaves identically to field splitting.
(See \fHFields\fP, above.)
.ti -.2i
\*(FCsprintf(\*(FIfmt\*(FC, \*(FIexpr-list\*(FC)\*(FR
.br
prints \*(FIexpr-list\fP
according to \*(FIfmt\*(FR, and returns the resulting string.
.ti -.2i
\*(CB\*(FCstrtonum(\*(FIs\*(FC)\*(FR
.br
examines \*(FIs\*(FR, and returns its numeric value.
If \*(FIs\*(FR begins with a leading \*(FC0\*(FR,
\*(FCstrtonum()\*(FR assumes that \*(FIs\*(FR
is an octal number.
If \*(FIs\*(FR begins with a leading \*(FC0x\*(FR
or \*(FC0X\*(FR, \*(FCstrtonum()\*(FR assumes that
\*(FIs\*(FR is a hexadecimal number.\*(CD
.ti -.2i
\*(FCsub(\*(FIr\*(FC, \*(FIs \*(FR[\*(FC, \*(FIt\*(FR]\*(FC)\*(FR
.br
just like
\*(FCgsub()\*(FR, but only the first matching substring is replaced.
.ti -.2i
\*(FCsubstr(\*(FIs\*(FC, \*(FIi \*(FR[\*(FC, \*(FIn\*(FR]\*(FC)\*(FR
.br
returns the at most
\*(FIn\*(FR-character substring of \*(FIs\fP starting at \*(FIi\*(FR.
If \*(FIn\fP is omitted, the rest of \*(FIs\fP is used.
.ti -.2i
\*(FCtolower(\*(FIstr\*(FC)\*(FR
.br
returns a copy of the string \*(FIstr\*(FR,
with all the upper-case characters in \*(FIstr\fP translated to their
corresponding lower-case counterparts. Non-alphabetic characters are
left unchanged.\*(CX
.in -.2i
.EB "\s+2\f(HBSTRING FUNCTIONS\*(FR\s0"

.BT

.\" --- Builtin String Functions
.ES
.fi
.in +.2i
.ti -.2i
\*(CD\*(FCtoupper(\*(FIstr\*(FC)\*(FR
.br
returns a copy of the string \*(FIstr\*(FR,
with all the lower-case characters in \*(FIstr\fP translated to their
corresponding upper-case counterparts. Non-alphabetic characters are
left unchanged.\*(CX
.in -.2i
.EB "\s+2\f(HBSTRING FUNCTIONS (continued)\*(FR\s0"

.\" --- Builtin Time Functions
.ES
.fi
\*(CD\*(GK
provides the following functions for obtaining time stamps and
formatting them.
.sp .5
.fi
.in +.2i
.ti -.2i
\*(FCmktime(\*(FIdatespec\*(FC)\*(FR
.br
turns \*(FIdatespec\fP into a time
stamp of the same form as returned by \*(FCsystime()\*(FR.
The \*(FIdatespec\fP is a string of the form
\*(FC"\*(FIYYYY MM DD HH MM SS[ DST]\*(FC"\*(FR.
.ti -.2i
\*(FCstrftime(\*(FR[\*(FIformat \*(FR[\*(FC, \*(FItimestamp\*(FR]]\*(FC)\*(FR
.br
formats \*(FItimestamp\fP
according to the specification in \*(FIformat\*(FR. The
\*(FItimestamp\fP should be of the same form as returned by
\*(FCsystime()\*(FR.
If \*(FItimestamp\fP is missing, the current time of day is used. If
\*(FIformat\fP is missing, a default format equivalent to the output
of \*(FIdate\*(FR(1) is used.
.ti -.2i
\*(FCsystime()\fP
.br
returns the current time of day as the number of
seconds since the Epoch.\*(CB
.in -.2i
.EB "\s+2\f(HBTIME FUNCTIONS (\*(GK\f(HB)\*(FR\s0"

.\" --- Builtin Bit Manipulation Functions
.ES
.fi
\*(CD\*(GK
provides the following functions for doing bitwise operations.
.sp .5
.fi
.in +.2i
.ti -.2i
\*(FCand(\*(FIv1\*(FC, \*(FIv2\*(FC)\*(FR
.br
returns the bitwise AND of the values provided by
\*(FIv1\*(FR and \*(FIv2\*(FR.
.ti -.2i
\*(FCcompl(\*(FIval\*(FC)\*(FR
.br
returns the bitwise complement of
\*(FIval\*(FR.
.ti -.2i
\*(FClshift(\*(FIval\*(FC, \*(FIcount\*(FC)\*(FR
.br
returns the value of \*(FIval\*(FR,
shifted left by \*(FIcount\*(FR bits.
.ti -.2i
\*(FCor(\*(FIv1\*(FC, \*(FIv2\*(FC)\*(FR
.br
returns the bitwise OR of the values provided by
\*(FIv1\*(FR and \*(FIv2\*(FR.
.ti -.2i
\*(FCrshift(\*(FIval\*(FC, \*(FIcount\*(FC)\*(FR
.br
returns the value of \*(FIval\*(FR,
shifted right by \*(FIcount\*(FR bits.
.ti -.2i
\*(FCxor(\*(FIv1\*(FC, \*(FIv2\*(FC)\*(FR
.br
teturns the bitwise XOR of the values provided by
\*(FIv1\*(FR and \*(FIv2\*(FR.\*(CB
.in -.2i
.EB "\s+2\f(HBBIT MANIPULATION FUNCTIONS (\*(GK\f(HB)\*(FR\s0"

.\" --- Builtin Internationalizatin Functions
.ES
.fi
\*(CD\*(GK
provides the following functions for runtime message translation.
.in +.2i
.sp .5
.ti -.2i
\*(FCbindtextdomain(\*(FIdirectory \*(FR[\*(FC, \*(FIdomain\*(FR]\*(FC)\*(FR
.br
specifies the directory where \*(GK looks for the \*(FC\&.mo\*(FR
files, in case they
will not or cannot be placed in the ``standard'' locations
(e.g., during testing.)
It returns the directory where \*(FIdomain\*(FR is ``bound.''
.sp .5
The default \*(FIdomain\*(FR is the value of \*(FCTEXTDOMAIN\*(FR.
When \*(FIdirectory\*(FR is the null string (\*(FC"\^"\*(FR),
\*(FCbindtextdomain()\*(FR returns the current binding for the
given \*(FIdomain\*(FR.
.ti -.2i
\*(FCdcgettext(\*(FIstring \*(FR[\*(FC, \*(FIdomain \*(FR[\*(FC, \*(FIcategory\*(FR]]\*(FC)\*(FR
.br
returns the translation of \*(FIstring\*(FR in text domain
\*(FIdomain\*(FR for locale category \*(FIcategory\*(FR.
The default value for \*(FIdomain\*(FR is the current value of \*(FCTEXTDOMAIN\*(FR.
The default value for \*(FIcategory\*(FR is \*(FC"LC_MESSAGES"\*(FR.
.sp .5
If you supply a value for \*(FIcategory\*(FR, it must be a string equal to
one of the known locale categories.
You must also supply a text domain.  Use \*(FCTEXTDOMAIN\*(FR
to use the current domain.\*(CB
.in -.2i
.EB "\s+2\f(HBINTERNATIONALIZATION (\*(GK\f(HB)\*(FR\s0"

.BT

.\" --- User-defined Functions
.ES
.fi
\*(CDFunctions in AWK are defined as follows:
.sp .5
.nf
	\*(FCfunction \*(FIname\*(FC(\*(FIparameter list\*(FC)
	{
		\*(FIstatements
	\*(FC}\*(FR
.sp .5
.fi
Functions are executed when they are called from within expressions
in either patterns or actions. Actual parameters supplied in the function
call instantiate the formal parameters declared in the function.
Arrays are passed by reference, other variables are passed by value.
.sp .5
Local variables 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:
.sp .5
.nf
	\*(FC# a and b are local
	function f(p, q,     a, b)
	{
		\&.....
	}
.sp .3
	/abc/	{ ... ; f(1, 2) ; ... }\*(FR
.fi
.sp .5
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.
.sp .5
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.
.sp .5
Use \*(FCreturn\fP to return a value from a function. The return value
is undefined if no value is provided, or if the function returns by
``falling off'' the end.
.sp .5
\*(CLThe word
\*(FCfunc\fP
may be used in place of
\*(FCfunction\*(FR.
\*(CRNote: This usage is deprecated.\*(CX
.EB "\s+2\f(HBUSER-DEFINED FUNCTIONS\*(FR\s0"

.\" --- Localization
.ES
.fi
\*(CDThere are several steps involved in producing and running a localizable
\*(AK program.
.sp .5
1.  Add a \*(FCBEGIN\*(FR action to assign a value to the
\*(FCTEXTDOMAIN\*(FR variable to set the text domain for
your program.
.sp .5
.ti +5n
\*(FCBEGIN { TEXTDOMAIN = "myprog" }\*(FR
.sp .5
This allows \*(GK to find the \*(FC\&.mo\*(FR
file associated with your program.
Without this step, \*(GK uses the \*(FCmessages\*(FR text domain,
which probably won't work.
.sp .5
2.  Mark all strings that should be translated with leading underscores.
.sp .5
3.  Use the \*(FCdcgettext()\*(FR
and/or \*(FCbindtextdomain()\*(FR
functions in your program, as necessary or appropriate.
.sp .5
4.  Run
.sp .5
.ti +5n
\*(FCgawk \-\^\-gen\-po \-f myprog.awk > myprog.po\*(FR
.sp .5
to generate a \*(FC\&.po\*(FR
file for your program.
.sp .5
5.  Provide appropriate translations, and build and install a corresponding
\*(FC\&.mo\*(FR file.
.sp .5
The internationalization features are described in full detail in \*(AM.\*(CB
.EB "\s+2\f(HBLOCALIZATION (\*(GK\f(HB)\*(FR\s0"


.BT

.\" --- Extensions
.ES
.fi
.in +.2i
.ti -.2i
\*(CD\*(FCextension(\*(FIlib\*(FC, \*(FIfunc\*(FC)\*(FR
.br
dynamically load the shared library
\*(FIlib\*(FR
and call
\*(FIfunc\*(FR
in it to initialize the library.
This adds new built-in functions to \*(GK.
It returns the value returned by
\*(FIfunc\*(FR.\*(CB
.in -.2i
.EB "\s+2\f(HBDYNAMIC EXTENSIONS (\*(GK\f(HB)\*(FR\s0"

.\" --- Environment Variables
.ES
.fi
\*(CDThe environment variable \*(FCAWKPATH\fP specifies a search path to use
when finding source files named with the \*(FC\-f\fP
option.
The default path is
\*(FC".:/usr/local/share/awk"\*(FR,
if this variable does not exist.
(The actual directory may vary,
depending upon how \*(GK was built and installed.)
If a file name given to the \*(FC\-f\fP option contains a ``/'' character,
no path search is performed.
.sp .5
If \*(FCPOSIXLY_CORRECT\fP exists in the environment, then \*(GK
behaves exactly as if \*(FC\-\^\-posix\fP had been specified on the
command line.\*(CB
.EB "\s+2\f(HBENVIRONMENT VARIABLES (\*(GK\f(HB)\*(FR\s0"

.\" --- Historical Features
.ES
.fi
\*(CD\*(GK supports two features of historical AWK implementations.
First, it is possible to call the \*(FClength()\fP
built-in function not only with no argument, but even without parentheses.
This feature is marked as ``deprecated'' in the POSIX standard, and \*(GK
issues a warning about its use if \*(FC\-\^\-lint\fP
is specified on the command line.
.sp .5
The other feature is the use of \*(FCcontinue\fP
or \*(FCbreak\fP statements outside the body of a
\*(FCwhile\*(FR, \*(FCfor\*(FR, or \*(FCdo\fP loop.
Historical AWK implementations have treated such usage as
equivalent to the \*(FCnext\fP statement.
\*(GK supports this usage if \*(FC\-\^\-traditional\fP
is specified.\*(CB
.EB "\s+2\f(HBHISTORICAL FEATURES (\*(GK\f(HB)\*(FR\s0"


.\" --- FTP Information
.ES
.nf
\*(CDHost: \*(FCgnudist.gnu.org\*(FR
File: \*(FC/gnu/gawk/gawk-3.1.0.tar.gz\fP
.in +.2i
.fi
GNU \*(AK (\*(GK). There may be a later version.
.in -.2i
.nf
.sp .5
\*(FChttp://cm.bell-labs.com/who/bwk/awk.tar.gz\fP
.in +.2i
.fi
\*(NK. This version requires an ANSI C compiler;
GCC (the GNU C compiler) works well.
.in -.2i
.nf
.sp .5
Host: \*(FCftp.whidbey.net\*(FR
File: \*(FC/pub/brennan/mawk1.3.3.tar.gz\fP
.in +.2i
.fi
Michael Brennan's \*(MK. There may be a newer version.\*(CX
.in -.2i
.EB "\s+2\f(HBFTP/HTTP INFORMATION\*(FR\s0"

.\" --- Copying Permissions
.ES
.fi
\*(CDCopyright \(co 1996-2001 Free Software Foundation, Inc.
.sp .5   
Permission is granted to make and distribute verbatim copies of this
reference card provided the copyright notice and this permission notice
are preserved on all copies.
.sp .5
Permission is granted to copy and distribute modified versions of this
reference card 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.
.sp .5
Permission is granted to copy and distribute translations of this
reference card into another language, under the above conditions for
modified versions, except that this permission notice may be stated in a
translation approved by the Foundation.\*(CX
.EB "\s+2\f(HBCOPYING PERMISSIONS\*(FR\s0"
.BT