path: root/doc/awkcard.in

.\" AWK Reference Card --- Arnold Robbins, arnold@skeeve.com
.\"
.\" Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2002,
.\" 2003, 2004, 2005, 2007, 2009, 2010 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 PK \*(FCpgawk\*(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
	9
Arrays
	7
Awk Program Execution
	5
Bit Manipulation Functions (\*(GK)
	17
Bug Reports
	2
Closing Redirections
	13
Command Line Arguments (standard)
	2
Command Line Arguments (\*(GK)
	3
Command Line Arguments (\*(MK)
	4
Conversions And Comparisons
	8
Copying Permissions
	18
Definitions
	2
Dynamic Extensions (\*(GK)
	17
Environment Variables (\*(GK)
	11
Escape Sequences
	9
Expressions
	7
Fields
	10
FTP/HTTP Information
	18
Historical Features (\*(GK)
	10
Input Control
	13
Internationalization (\*(GK)
	18
Lines And Statements
	4
Localization (\*(GK)
	12
Numeric Functions
	15
Output Control
	13
Pattern Elements
	8
Printf Formats
	14
Records
	10
Regular Expressions
	11
Signals (\*(PK)
	4
Special Filenames
	12
String Functions
	16
Time Functions (\*(GK)
	17
User-defined Functions
	15
Variables
	5\*(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
\*(FRCopyright \(co 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004,
2005, 2007, 2009, 2010 Free Software Foundation, Inc.
.nf
.BT


.\"
.\"
.\" --- Definitions
.fi
.ES
\*(CDThis card describes POSIX AWK, as well as three
freely available \*(AK implementations
(see \fHFTP/HTTP 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.0i).
\*(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.\*(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
\*(CDLong options may abbreviated as long as the abbreviation
remains unique.
You may use ``\*(FC\-W \*(FIoption\*(FR''
for full POSIX compliance.
.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}
..
.de TI \" table item
.ti -4n
\\$1
.br
..
.TS
expand, tab(%);
l lw(1.3i).
\*(FC\-\^\-assign \*(FIvar\*(FC\^=\^\*(FIval\*(FR%Same as \*(FC\-v\fP.
\*(FC\-\^\-field-separator \*(FIfs\*(FR%Same as \*(FC\-F\fP.
\*(FC\-\^\-file \*(FIprog-file%\*(FRSame as \*(FC\-f\fP.
.TE
.in +4n
.TI "\*(FC\-b\*(FR, \*(FC\-\^\-characters\-as\-bytes\*(FR
Treat all input data as single-byte characters. I.e.,
don't attempt to
process strings as multibyte characters.
Overridden by \*(FC\-\^\-posix\*(FR.
.TI "\*(FC\-c\*(FR, \*(FC\-\^\-traditional\*(FR
Disable \*(GK-specific extensions.
.TI "\*(FC\-C\*(FR, \*(FC\-\^\-copyright\*(FR
Print the short version of the GNU
copyright information on \*(FCstdout\*(FR.
.TI "\*(FC\-d \*(FIfile\*(FR, \*(FC\-\^\-dump-variables\*(FR[\*(FC=\*(FIfile\*(FR]
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.
.TI "\*(FC-e '\*(FItext\*(FC'\*(FR, \*(FC\-\^\-source '\*(FItext\*(FC'\*(FR
Use \*(FItext\*(FR as AWK program source code.
.TI "\*(FC\-E \*(FIfile\*(FR, \*(FC\-\^\-exec \*(FIfile\*(FR
Read program text from \*(FIfile\fP. No other
options are processed.
Also disables command-line variable assignments.
Useful with \*(FC#!\fP.
.TI "\*(FC\-g\*(FR, \*(FC\-\^\-gen\-pot\*(FR
Process the program and print a GNU \*(FCgettext\*(FR
format \*(FC\&.pot\*(FR file on standard output,
containing the text of all strings that were marked
for localization.
.TI "\*(FC\-h\*(FR, \*(FC\-\^\-help\*(FR
Print a short summary of the available
options on \*(FCstdout\*(FR, then exit zero.
.TI "\*(FC\-L \*(FR[\*(FC\*(FIvalue\*(FR], \*(FC\-\^\-lint\*(FR[\*(FC=\*(FIvalue\*(FR]
Warn about dubious or non-portable constructs.
If \*(FIvalue\*(FR is
\*(FCfatal\*(FR,
lint warnings become fatal errors.
If \*(FIvalue\*(FR is
\*(FCinvalid\*(FR,
only issue warnings about things that are
actually invalid (not fully implemented yet).
.TI "\*(FC\-n\*(FR, \*(FC\-\^\-non\-decimal\-data\*(FR
Recognize octal and hexadecimal values in input data.
\*(FIUse this option with great caution!\*(FR
.TI "\*(FC\-N\*(FR, \*(FC\-\^\-use\-lc\-numeric\*(FR
Force use of the locale's decimal point character when parsing input data.
.TI "\*(FC\-O\*(FR, \*(FC\-\^\-optimize\*(FR
Enable some internal optimizations.
.TI "\*(FC\-p \*(FR[\*(FC\*(FIfile\*(FR], \*(FC\-\^\-profile\*(FR[\*(FC=\*(FIfile\*(FR]
Send profiling data to \*(FIfile\*(FR
(default: \*(FCawkprof.out\*(FR).
With \*(GK,
the profile is just a ``pretty printed'' version of the program.
With \*(PK,
the profile contains execution counts in the left margin
of each statement in the program.
.TI "\*(FC\-P\*(FR, \*(FC\-\^\-posix\*(FR
Disable common and GNU extensions.
.TI "\*(FC\-R \*(FIfile\*(FR, \*(FC\-\^\-command \*(FIfile\*(FR"
\*(FCdgawk\*(FR only.
Read stored debugger commands from \*(FIfile\*(FR.
.TI "\*(FC\-r\*(FR, \*(FC\-\^\-re\-interval\*(FR
Enable \*(FIinterval expressions\*(FR in regular
expression matching (see \fHRegular
Expressions\fP below). Useful if
\*(FC\-\^\-traditional\*(FR is specified.
.TI "\*(FC\-S\*(FR, \*(FC\-\^\-sandbox\*(FR
Disable the \*(FCsystem()\*(FR function,
input redirection with \*(FCgetline\*(FR,
output redirection with \*(FCprint\*(FR and \*(FCprintf\*(FR,
and dynamic extensions loading.\*(CB
.in -4n
.EB "\s+2\f(HBCOMMAND LINE ARGUMENTS (\*(GK\f(HB)\*(FR\s0"

.BT

.\"
.\"
.\" --- Command Line Arguments (gawk) continued
.ES
.fi
.in +4n
.TI "\*(FC-t\*(FR, \*(FC\-\^\-lint\-old\*(FR
Warn about constructs that are not
portable to the original version of
Unix \*(AK.
.TI "\*(FC\-V\*(FR, \*(FC\-\^\-version\*(FR
Print version \" information
info
on \*(FCstdout\fP
and exit zero.
.in -4n
.sp .5
.fi
In compatibility mode,
any other options are flagged as invalid, but are otherwise ignored.
Normally, if there is program text, unknown
options are passed on to the AWK program in
\*(FCARGV\*(FR
for processing.\*(CB
.EB "\s+2\f(HBCOMMAND LINE ARGUMENTS (\*(GK\f(HB)\*(FR\s0"

.\"
.\"
.\" --- 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"
.sp .7
.\" --- Signals (pgawk)
.ES
.fi
\*(CD\*(PK accepts two signals.
\*(FCSIGUSR1\fP dumps a profile and function call stack to the
profile file.  It then continues to run.
\*(FCSIGHUP\fP is similar, but exits.\*(CB
.EB "\s+2\f(HBSIGNALS (\*(PK\f(HB)\*(FR\s0"

.\" --- 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"
.BT

.\" --- Awk Program Execution
.ES
.fi
\*(CDAWK programs are a sequence of pattern-action statements
and optional function definitions.
.sp .5
	\*(CB\*(FC@include "\*(FIfilename\*(FC"\*(CD
.br
	\*(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
\*(GK includes files named on \*(FC@include\*(FR lines.
Nested includes are allowed.\*(CD
.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
\*(CBFor each input file,
if a \*(FCBEGINFILE\fP rule exists, \*(GK executes the associated code
before processing the contents of the file. Similarly, \*(GK executes
the code associated with \*(FCENDFILE\fP after processing the file.\*(CD
.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 is read.
\*(CX
.EB "\s+2\f(HBAWK PROGRAM EXECUTION\*(FR\s0"
.sp .5
.\" --- 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.
Use \*(FC"rw"\fP or \*(FC"wr"\fP for all files.\*(CX
T}
.TE
.EB "\s+2\f(HBVARIABLES\*(FR\s0"
.BT

.\" --- Variables (continued)
.ES
.fi
.TS
expand;
l lw(2i).
\*(FCCONVFMT\fP	T{
Conversion format for numbers, default value
is \*(FC"%.6g"\*(FR.
T}
\*(FCENVIRON\fP	T{
Array containing the current environment.
it 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{
Whitespace 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}
\*(CB\*(FCFPAT\fP	T{
Regular expression describing field contents.
Used to parse the input based on the fields
instead of the field separator.\*(CD
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
is \*(FInot\*(FR affected.
However, the
\*(FCasort()\*(FR
and
\*(FCasorti()\*(FR
function are 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.
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.\*(CX
T}
\*(CD\*(FCOFMT\fP	T{
Output format for numbers, \*(FC"%.6g"\*(FR, by default.
T}
\*(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 information
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 internationalization text domain,
for finding the localized
translations of the program's strings.\*(CX
T}
.TE
.EB "\s+2\f(HBVARIABLES (continued)\*(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,
\*(CB\*(FCpatsplit()\fP,\*(CD
\*(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

.\" --- Conversions and Comparisons
.ES
.fi
\*(CDVariables and fields may be (floating point) numbers, strings or both.
Context determines how a variable's value 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
\*(CBor \*(FCpatsplit()\fP\*(CD that are numeric strings.
The basic idea is that \*(FIuser input\*(FR,
and only user input, that looks numeric,
should be treated that way.\*(CD
.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"

.\" --- Pattern Elements
.ES
.fi
\*(CDAWK patterns may be one of the following.
.sp .5
.nf
	\*(FCBEGIN
	END
	\*(CBBEGINFILE
	ENDFILE\*(CD
	\*(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
\*(CB\*(FCBEGINFILE\*(FR and \*(FCENDFILE\*(FR are special patterns that
execute before the first record of each file and after the last record
of each file, respectively. In the \*(FCBEGINFILE\*(FR rule, the \*(FCERRNO\*(FR
variable is non-null if there is a problem with the file; the code should use
\*(FCnextfile\*(FR to skip the file if desired. Otherwise \*(GK exits with
its usual fatal error.  The actions for multiple
\*(FCBEGINFILE\*(FR and \*(FCENDFILE\*(FR patterns are merged.\*(CD
.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"

.BT

.\" --- Action Statements
.ES
.fi
.in +.2i
.ti -.2i
\*(CD\*(FCbreak\*(FR
.br
Break out of the nearest enclosing
\*(CB\*(FCswitch\fP statement, or\*(CD
\*(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	See \fHInput Control.\fP\*(CD
.in -.2i
.\" --- Start switch statement
\*(CB\*(FCswitch (\*(FIexpression\*(FC) {
.br
case \*(FIconstant\*(FC|\*(FIregular expression\*(FC: \*(FIstatement(s)
.br
\*(FCdefault: \*(FIstatement(s)
.br
\*(FC}\*(FR
.in +.2i
.br
Switch on \*(FIexpression\*(FR,
execute \*(FIcase\*(FR if matched, default if not.
The \*(FCdefault\fP label and associated statements are optional.\*(CD
.ti -.2i
.\" --- End switch statement
\*(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"

.\" --- 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"
.BT

.\" --- 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 or \*(FCFPAT\fP
overrides the use of \*(FCFIELDWIDTHS\*(FR.
and restores the default behavior.
.sp .5
Similarly, if the
\*(FCFPAT\fP
variable is set to a string representing a regular expression,
each field is made up of text that matches that regular expression. In
this case, the regular expression describes the fields themselves,
instead of the text that separates the fields.
Assigning a new value to
\*(FCFS\fP
or
\*(FCFIELDWIDTHS\fP
overrides the use of
\*(FCFPAT\fP.\*(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"

.\" --- Historical Features
.ES
.fi
\*(CDIt is possible to call the \*(FClength()\fP
built-in function not only with no argument, but even without parentheses.
Doing so, however, is poor practice,
and \*(GK
issues a warning about its use if \*(FC\-\^\-lint\fP
is specified on the command line.\*(CB
.EB "\s+2\f(HBHISTORICAL FEATURES (\*(GK\f(HB)\*(FR\s0"
.BT

.\" --- Regular Expressions
.ES
.fi
\*(CDRegular expressions are the extended kind originally defined by
\*(FCegrep\fP.
\*(CB\*(GK supports additional GNU operators.
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\es\*(FR~any whitespace character
\*(FC\eS\*(FR~any non-whitespace character
\*(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.\*(CX
.sp .5
\*(CDIn regular expressions, within character ranges
(\*(FC[\*(FR...\*(FC]\*(FR),
the notation \*(FC[[:\*(FIclass\*(FC:]]\*(FR defines character classes\*(CD:
.sp .5
.TS
center, tab(~);
lp8 lp8 lp8 lp8.
\*(FCalnum\*(FR~alphanumeric~\*(FClower\*(FR~lowercase
\*(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~uppercase
\*(FCgraph\*(FR~non-spaces~\*(FCxdigit\*(FR~hexadecimal\*(CX
.TE
.fi
.EB "\s+2\f(HBREGULAR EXPRESSIONS\*(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
.PP
For socket communication,
\*(FCGAWK_SOCK_RETRIES\fP
controls the number of retries, and
\*(FCGAWK_MSEC_SLEEP\fP controls
the interval between retries.
The interval is in milliseconds. On systems that do not support
\*(FIusleep\fP(3),
the value is rounded up to an integral number of seconds.
.sp .5
If \*(FCPOSIXLY_CORRECT\fP exists
.\" in the environment,
then \*(GK
behaves exactly as if the \*(FC\-\^\-posix\fP option had been given.\*(CB
.EB "\s+2\f(HBENVIRONMENT VARIABLES (\*(GK\f(HB)\*(FR\s0"
.BT

.\" --- 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 .3
.ti +5n
\*(FCBEGIN { TEXTDOMAIN = "myprog" }\*(FR
.sp .3
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
\*(FCbindtextdomain()\*(FR,
\*(FCdcgettext()\*(FR,
and/or
\*(FCdcngettext()\*(FR
functions in your program, as appropriate.
.sp .5
4. Run
.sp .3
.ti +3n
\*(FCgawk\0\-\^\-gen\-pot\0\-f\0myprog.awk\0>\0myprog.pot\*(FR
.sp .3
to generate a \*(FC\&.pot\*(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"

.\" --- Special Filenames
.ES
.fi
\*(CDAll three \*(FCawk\fP implementations
recognize certain special filenames internally
when doing I/O redirection from either \*(FCprint\fP
or \*(FCprintf\fP into a file or via \*(FCgetline\fP
from a file.
These filenames
provide access to open file descriptors inherited from the
parent process.  They
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
.ti -.2i
\*(FC/inet4/tcp/\*(FIlport\*(FC/\*(FIrhost\*(FC/\*(FIrport\*(FR
.br
.ti -.2i
\*(FC/inet6/tcp/\*(FIlport\*(FC/\*(FIrhost\*(FC/\*(FIrport\*(FR
.br
Files for TCP/IP connections 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.
Use \*(FC/inet4\fP to force an IPv4 connection,
and \*(FC/inet6\fP to force an IPv6 connection.
Plain \*(FC/inet\fP uses the system default (probably IPv4).
Usable only with the \*(FC|&\*(FR two-way I/O operator.
.ti -.2i
\*(FC/inet/udp/\*(FIlport\*(FC/\*(FIrhost\*(FC/\*(FIrport\*(FR
.br
.ti -.2i
\*(FC/inet4/udp/\*(FIlport\*(FC/\*(FIrhost\*(FC/\*(FIrport\*(FR
.br
.ti -.2i
\*(FC/inet6/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
.ti -.2i
\*(FC/inet4/raw/\*(FIlport\*(FC/\*(FIrhost\*(FC/\*(FIrport\*(FR
.br
.ti -.2i
\*(FC/inet6/raw/\*(FIlport\*(FC/\*(FIrhost\*(FC/\*(FIrport\*(FR
.br
.\" Similar, but use raw IP sockets.
Reserved for future use.\*(CL
.in -.2i
.EB "\s+2\f(HBSPECIAL FILENAMES\*(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
\*(CD\*(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).\*(CD
.in -.2i
.sp .5
.fi
\*(FCgetline\*(FR returns 1 on success, 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
(\*(GK and \*(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"

.\" --- Closing Redirections
.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, \*(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%F\fP		Like \*(FC%f\fP, but use capital letters for infinity and
		not-a-number values.
\*(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{
Use before the \*(FIwidth\fP modifier 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{
Pad output with zeros instead of spaces.
This applies only to the numeric output formats.
Only has an effect when the field width is wider
than the value to be printed.
T}
\*(CB\*(FC'\*(FR	T{
Use the locale's thousands separator for \*(FC%d\fP, \*(FC%i\fP, and \*(FC%u\fP.\*(CD
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
Use a
\*(FC*\fP in place of either the \*(FIwidth\fP or \*(FIprec\fP
specifications to take their values from
the \*(FCprintf\fP or \*(FCsprintf()\*(FR argument list.
\*(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

.\" --- 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 whitespace.
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
\*(CBFunctions may be called indirectly. To do this, assign
the name of the function to be called, as a string, to a variable.
Then use the variable as if it were the name of a function, prefixed with
an ``at'' sign, like so:\*(FC
.nf
.sp .5
	function myfunc()
	{
		print "myfunc called"
	}
.sp .3
	{
		the_func = "myfunc"
		@the_func()
	}
.fi
.sp .5
\*(FR\*(CDUse \*(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.
\*(CRThis usage is deprecated.\*(CX
.EB "\s+2\f(HBUSER-DEFINED FUNCTIONS\*(FR\s0"
.sp .6
.\" --- 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	Truncate to integer.
\*(FClog(\*(FIexpr\*(FC)\*(FR	The natural logarithm function (base \*(FIe\^\*(FR).
\*(FCrand()\fP	A random number between 0 and 1 (0 \(<= \*(FIN\fP < 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{
Use \*(FIexpr\fP as the new seed for the random number
generator. If no \*(FIexpr\fP, the time of day is used.
Return the random number
generator's previous seed.\*(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
Sort the source array \*(FIs\*(FR, replacing the indices with numeric
values 1 through \*(FIn\*(FR (the number of elements in the array),
and return the number of elements.
If destination \*(FId\*(FR is supplied, copy \*(FIs\*(FR to \*(FId\*(FR,
sort \*(FId\*(FR, and leave \*(FIs\*(FR unchanged.\*(CD
.ti -.2i
\*(CB\*(FCasorti(\*(FIs\*(FC \*(FR[\*(FC, \*(FId\*(FR]\*(FC)\*(FR
.br
Like \*(FCasort()\*(FR, but sort on the indices, not
the values.  The original values are thrown array, so provide a
second array to preserve the first.\*(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, use \*(FC$0\fP 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
Return 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
Return the length of the string
\*(FIs\*(FR, or the length of \*(FC$0\fP if \*(FIs\fP is not supplied.
\*(CLWith an array argument, return the number of elements
in the array.\*(CD
.ti -.2i
\*(FCmatch(\*(FIs\*(FC, \*(FIr \*(CB\*(FR[\*(FC, \*(FIa\*(FR]\*(CD\*(FC)\*(FR
.br
Return the position in
\*(FIs\fP where the regular expression \*(FIr\fP occurs, or 0 if
\*(FIr\fP is not present, and set 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.
Subscripts
\*(FCa[\*(FIn\^\*(FC, "start"]\*(FR,
and
\*(FCa[\*(FIn\^\*(FC, "length"]\*(FR
provide the starting index in the string and length
respectively, of each matching substring.\*(CD
.ti -.2i
\*(CB\*(FCpatsplit(\*(FIs\*(FC, \*(FIa \*(FR[\*(FC, \*(FIr \*(CB\*(FR[\*(FC, \*(FIseps \*(FR] \*(FR] \*(FC)\*(FR
.br
Split the string
\*(FIs\fP into the array \*(FIa\fP
and the array \*(FIseps\fP of separator strings
using the regular expression \*(FIr\*(FR,
and return the number of fields.
Element values are the portions of \*(FIs\fP that matched \*(FIr\fP.
The value of \*(FIseps\fP[\*(FIi\fP] is the separator that appeared in
front of \*(FIa\fP[\*(FIi\fP+1].
If \*(FIr\fP is omitted, use \*(FCFPAT\fP instead.
Clear the arrays \*(FIa\fP and \*(FIseps\fP first.
Splitting behaves identically to field splitting with \*(FCFPAT\fP.\*(CD
.ti -.2i
\*(FCsplit(\*(FIs\*(FC, \*(FIa \*(FR[\*(FC, \*(FIr \*(CB\*(FR[\*(FC, \*(FIseps \*(FR]\*(CD \*(FR] \*(FC)\*(FR
.br
Split the string
\*(FIs\fP into the array \*(FIa\fP \*(CBand the array \*(FIseps\fP of separator strings\*(CD 
using the regular expression \*(FIr\*(FR,
and return the number of fields. If \*(FIr\fP is omitted, use \*(FCFS\fP
instead.
Clear the \*(FIa\fP \*(CBand \*(FIseps\fP\*(CD first.
Splitting behaves identically to field splitting.
(See \fHFields\fP, above.)
.ti -.2i
\*(FCsprintf(\*(FIfmt\*(FC, \*(FIexpr-list\*(FC)\*(FR
.br
Print \*(FIexpr-list\fP
according to \*(FIfmt\*(FR, and return the result.\*(CX
.in -.2i
.EB "\s+2\f(HBSTRING FUNCTIONS\*(FR\s0"

.BT

.\" --- Builtin String Functions
.ES
.fi
.in +.2i
.ti -.2i
\*(CB\*(FCstrtonum(\*(FIs\*(FC)\*(FR
.br
Examine \*(FIs\*(FR, and return 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. Otherwise, the
number is treated as decimal.\*(CD
.ti -.2i
\*(FCsub(\*(FIr\*(FC, \*(FIs \*(FR[\*(FC, \*(FIt\*(FR]\*(FC)\*(FR
.br
Just like
\*(FCgsub()\*(FR, but replace only the first matching substring.\*(CX
.ti -.2i
\*(CD\*(FCsubstr(\*(FIs\*(FC, \*(FIi \*(FR[\*(FC, \*(FIn\*(FR]\*(FC)\*(FR
.br
Return the at most
\*(FIn\*(FR-character substring of \*(FIs\fP starting at \*(FIi\*(FR.
If \*(FIn\fP is omitted, use the rest of \*(FIs\fP.
.ti -.2i
\*(FCtolower(\*(FIstr\*(FC)\*(FR
.br
Return a copy of the string \*(FIstr\*(FR,
with all the uppercase characters in \*(FIstr\fP translated to their
corresponding lowercase counterparts. Non-alphabetic characters are
left unchanged.
.ti -.2i
\*(FCtoupper(\*(FIstr\*(FC)\*(FR
.br
Return a copy of the string \*(FIstr\*(FR,
with all the lowercase characters in \*(FIstr\fP translated to their
corresponding uppercase counterparts. Non-alphabetic characters are
left unchanged.\*(CX
.in -.2i
.EB "\s+2\f(HBSTRING FUNCTIONS (continued)\*(FR\s0"
.sp .6
.\" --- 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
Convert \*(FIdatespec\fP into a time
stamp of the same form as returned by \*(FCsystime()\*(FR
and return it.
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, \*(FIutc-flag\*(FR]]]\*(FC)\*(FR
.br
Format \*(FItimestamp\fP
according to the specification in \*(FIformat\*(FR. The
\*(FItimestamp\fP should be of the same form as returned by
\*(FCsystime()\*(FR.
If \*(FIutc-flag\*(FR
is present and is non-zero or non-null, the result
is in UTC, otherwise the result is in local time.
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
Return 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"
.sp .6
.\" --- 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
Return the bitwise AND of the values provided by
\*(FIv1\*(FR and \*(FIv2\*(FR.
.ti -.2i
\*(FCcompl(\*(FIval\*(FC)\*(FR
.br
Return the bitwise complement of
\*(FIval\*(FR.
.ti -.2i
\*(FClshift(\*(FIval\*(FC, \*(FIcount\*(FC)\*(FR
.br
Return the value of \*(FIval\*(FR,
shifted left by \*(FIcount\*(FR bits.
.ti -.2i
\*(FCor(\*(FIv1\*(FC, \*(FIv2\*(FC)\*(FR
.br
Return the bitwise OR of the values provided by
\*(FIv1\*(FR and \*(FIv2\*(FR.
.ti -.2i
\*(FCrshift(\*(FIval\*(FC, \*(FIcount\*(FC)\*(FR
.br
Return the value of \*(FIval\*(FR,
shifted right by \*(FIcount\*(FR bits.
.ti -.2i
\*(FCxor(\*(FIv1\*(FC, \*(FIv2\*(FC)\*(FR
.br
Return 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"
.sp .6
.\" --- 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"
.BT

.\" --- Builtin Internationalization 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
Specify 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).
Return 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
Return 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.
.ti -.2i
\*(FCdcngettext(\*(FIstring1\*(FC, \*(FIstring2\*(FC, \*(FInumber\*(FR [\*(FC, \*(FIdom \*(FR[\*(FC, \*(FIcat\*(FR]]\*(FC)\*(FR
.br
Return the plural form used for \*(FInumber\*(FR of the translation of
\*(FIstring1\*(FR and \*(FIstring2\*(FR in text domain
\*(FIdom\*(FR for locale category \*(FIcat\*(FR.
The default value for \*(FIdom\*(FR is the current value of \*(FCTEXTDOMAIN\*(FR.
\*(FC"LC_MESSAGES"\*(FR
is the default value for \*(FIcat\*(FR.
.sp .5
If you supply a value for \*(FIcat\*(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"

.\" --- FTP/HTTP Information
.ES
.nf
\*(CDHost: \*(FCftp.gnu.org\*(FR
File: \*(FC/gnu/gawk/gawk-4.0.0.tar.gz\fP
.in +.2i
.fi
GNU \*(AK (\*(GK). There may be a later version.
.in -.2i
.nf
.sp .5
\*(FChttp://www.cs.princeton.edu/~bwk/btl.mirror/
awk.tar.gz\fP
.in +.2i
.fi
\*(NK. This version requires an ANSI C compiler;
GCC (the GNU Compiler Collection) works well.
.in -.2i
.nf
.sp .5
... Host: \*(FCftp.whidbey.net\*(FR
... File: \*(FC/pub/brennan/mawk1.3.3.tar.gz\fP
... \*(FChttp://www.skeeve.com/gawk/mawk1.3.3.tar.gz\fP
Host: \*(FCinvisible-island.net\*(FR
File: \*(FC/mawk/mawk.tar.gz\fP
.in +.2i
.fi
Michael Brennan's \*(MK. Thomas Dickey now
maintains it.\*(CX
.in -.2i
.EB "\s+2\f(HBFTP/HTTP INFORMATION\*(FR\s0"


.\" --- Copying Permissions
.ES
.fi
\*(CDCopyright \(co 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
2007, 2009, 2010 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"
.\" Need the BT here to get the final page number

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

.BT