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, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018,
.\" 2019, 2020, 2021
.\" 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 Brian Kernighan's \*(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
\*(FRAcknowledgements
	9
Action 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/GIT Information
	18
Historical Features (\*(GK)
	10
Input Control
	13
Internationalization (\*(GK)
	18
Lines And Statements
	4
Localization (\*(GK)
	12
Namespaces (\*(GK)
	12
Numeric Functions
	15
Output Control
	13
Pattern Elements
	8
Printf Formats
	14
Records
	10
Regular Expressions
	11
Signals (\*(GK \*(FC\-\^\-profile\*(FR)
	4
Special Filenames
	12
String Functions
	16
Time Functions
	17
Type Functions (\*(GK)
	18
User-defined Functions
	15
Variables
	5\*(CX
.in -.2i
.EB "\s+2\f(HBCONTENTS\*(FR\s0"
.sp .4
.TD
.fi
.sp .4
.SL
.sp .4
.so SRCDIR/ad.block
.\" a subtlety here; this line changes color. We rely on it
.\" also to provide a empty line.
\*(CD
.SL
.nf
\*(FRCopyright \(co 1996\(en2005, 2007, 2009\(en2021
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/GIT Information\fP).
\*(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.)
.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
\*(CB\*(FIstrongly typed regexp\fP \- a regular expression constant with
a leading \*(FC@\*(FR. E.g., \*(FC@/stuff/\*(FR. Such constants may
be assigned to variables and passed to user-defined functions.\*(CD
.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 runs, 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 use
\*(FCgawkbug\*(FR to report it.\*(CX
.EB "\s+2\f(HBBUG REPORTS\*(FR\s0"

.BT

.\"
.\"
.\" --- Command Line Arguments (gawk)
.ES
.fi
\*(CDLong options may be abbreviated as long as the abbreviation
remains unique.
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.
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 GNU
copyright information on \*(FCstdout\*(FR.
.TI "\*(FC\-d\*(FR[\*(FIfile\*(FR], \*(FC\-\^\-dump-variables\*(FR[\*(FC=\*(FIfile\*(FR]
Print a sorted list of global variables,
their types and final values to
\*(FIfile\*(FR (default: \*(FCawkvars.out\*(FR).
.TI "\*(FC\-D\*(FR[\*(FC\*(FIfile\*(FR], \*(FC\-\^\-debug\*(FR[\*(FC=\*(FIfile\*(FR]
Enable debugging of program. Optionally read stored commands
from \*(FIfile\*(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 disable 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 \*(FCstdout\*(FR,
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\-i \*(FIfile\*(FR, \*(FC\-\^\-include \*(FIfile\*(FR
Include library AWK code in \*(FIfile\*(FR.
See \fHAwk Program Execution\*(FR.
.TI "\*(FC\-I\*(FR, \*(FC\-\^\-trace\*(FR
Print the internal byte code names as they are executed.
.TI "\*(FC\-l \*(FIlib\*(FR, \*(FC\-\^\-load \*(FIlib\*(FR
Load dynamic extension \*(FIlib\fP.
See \fHDynamic Extensions\*(FR.
.TI "\*(FC\-L \*(FR[\*(FC\*(FIvalue\*(FR], \*(FC\-\^\-lint\*(FR[\*(FC=\*(FIvalue\*(FR]
Warn about dubious or non-portable constructs. Possible optional
\*(FIvalue\*(FRs are
\*(FCfatal\*(FR,
\*(FCinvalid\*(FR, and
\*(FCno-ext\*(FR.
See \*(AM for the details.
.TI "\*(FC\-M\*(FR, \*(FC\-\^\-bignum\*(FR
Enable arbitrary-precision arithmetic.
.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\*(FIfile\*(FR], \*(FC\-\^\-pretty-print\*(FR[\*(FC=\*(FIfile\*(FR]
Output a pretty printed version of the program to \*(FIfile\*(FR
(default: \*(FCawkprof.out\*(FR).
.TI "\*(FC\-O\*(FR, \*(FC\-\^\-optimize\*(FR
Enable internal optimizations (default is on).
.TI "\*(FC\-p\*(FR[\*(FC\*(FIfile\*(FR], \*(FC\-\^\-profile\*(FR[\*(FC=\*(FIfile\*(FR]
Send profiling data to \*(FIfile\*(FR
(default: \*(FCawkprof.out\*(FR).
The profile contains execution counts in the left margin.
.TI "\*(FC\-P\*(FR, \*(FC\-\^\-posix\*(FR
Disable common and GNU extensions.
.TI "\*(FC\-r\*(FR, \*(FC\-\^\-re\-interval\*(FR
Does nothing; for backwards compatibility only.\*(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\-s\*(FR, \*(FC\-\^\-no\-optimize\*(FR
Disable internal optimizations.
.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 loading dynamic extensions.
.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
Normally, if there is program text, unknown
options are passed on to the AWK program in
\*(FCARGV\*(FR
for processing.
In compatibility mode,
unknown options are flagged as invalid, but are otherwise ignored.\*(CB
.EB "\s+2\f(HBCOMMAND LINE ARGUMENTS (\*(GK\f(HB)\*(FR\s0"
.sp .4
.\"
.\"
.\" --- 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, 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 (gawk --profile)
.ES
.fi
\*(CD\*(GK accepts two signals while profiling.
\*(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 (\*(GK \f(HB\-\^\-profile)\*(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, statements end 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
\*(CBoptional directives,\*(CD
pattern-action statements
and optional function definitions.
.sp .5
	\*(CB\*(FC@include "\*(FIfilename\*(FC"
.br
	\*(FC@load "\*(FIfilename\*(FC"
.br
	\*(FC@namespace "\*(FInamespace\*(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
\*(CB\*(GK includes files named on \*(FC@include\*(FR lines.
Nested includes are allowed.
\*(GK loads extensions named on \*(FC@load\*(FR lines;
see \fHDynamic Extensions\*(FR.\*(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.
If there are no files named on the command line,
\*(AK reads the standard input.
.sp .5
A command line argument of the form
\*(FIvar\*(FC=\*(FIval\*(FR,
is treated as a variable assignment. The variable
\*(FIvar\fP is assigned the value \*(FIval\*(FR.
(This happens after any \*(FCBEGIN\fP rule(s) have been run.)
.sp .5
If the value of a particular element of \*(FCARGV\fP is empty
(\*(FC"\^"\*(FR), \*(AK skips over it.
.sp .5
Naming directories on the command-line is generally a fatal error.
\*(CB\*(GK skips them, with a warning, unless invoked with
\*(FC\-\^\-posix\*(FR
or
\*(FC\-\^\-traditional.\*(CK\*(FR
.sp .5
\*(CBFor each input file,
if a \*(FCBEGINFILE\fP rule exists, \*(GK executes the associated \*(FIaction\*(FR
before processing the contents of the file. Similarly, \*(GK executes
the \*(FIaction\*(FR 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,
it executes the associated \*(FIaction\fP.
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(2.3i).
\*(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
zero 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.)  \*(CLOnly for 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
variable names, each element being the value of
that variable.
T}
\*(CB\*(FCERRNO\fP	T{
String error value if a
\*(FCgetline\*(FR
redirection or read
fails, or if
\*(FCclose()\*(FR fails.
T}
\*(FCFIELDWIDTHS\fP	T{
Whitespace-separated list of field widths.
Used to parse the input into fields of fixed width,
instead of the value of \*(FCFS\fP
(see \fHFields\*(FR).\*(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
(see \fHFields\*(FR).\*(CD
T}
\*(FCFS\fP	T{
Input field separator, a space by default
(see \fHFields\fP).
T}
\*(CB\*(FCFUNCTAB\fP	T{
An array indexed by the names of all user-defined
and extension functions.\*(CD
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.
T}
\*(CD\*(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\*(FCPREC\fP	T{
The working precision of arbitrary precision floating-point
numbers, 53 by default.
T}
\*(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}
\*(CB\*(FCROUNDMODE\fP	T{
The rounding mode to use for arbitrary precision arithmetic,
by default \*(FC"N"\fP.\*(CD
T}
\*(FCRS\fP	T{
Input record separator, a newline by default
(see \fHRecords\fP).
T}
\*(FCRSTART\fP	T{
Index of the first character matched by
\*(FCmatch()\*(FR; zero 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).
T}
\*(CB\*(FCSYMTAB\fP	T{
An array indexed by the names of all global
variables and arrays. May be used to indirectly
set variable and array values.\*(CD
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 \*(FCSUBSEP\fP.
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.
Specifying just the array name without a subscript in
the \*(FCdelete\fP
statement deletes the entire contents of an array.
\*(CBYou cannot use \*(FCdelete\fP with \*(FCFUNCTAB\fP
or \*(FCSYMTAB\fP.\*(CD
.sp .5
\*(CB\*(GK provides true multidimensional arrays.
Such arrays need not be ``rectangular'' as in C or C++. For example:
.sp .5
.nf
	\*(FCa[1] = 5; a[2][1] = 6; a[2][2] = 7\*(FR\*(CX
.fi
.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	Equal, not 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.
\*(CBAssigning a strongly typed regexp constant to a scalar makes it
a regexp.\*(CD
.sp .5
To force a variable to be treated as a number, add zero to it; to force it
to be treated as a string, concatenate it with the null string.
.sp .5
Uninitialized variables have the numeric value zero and the string value
\*(FC"\^"\fP
(the null, or empty, 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.\*(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 rule 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
\*(FCdelete \*(FIarray\^\*(FR
.br
Delete all elements from array \*(FIarray\*(FR.
.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
\*(FCnextfile\*(FR	See \fHInput Control.\fP
.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"
.sp
.\" --- Acknowledgements
.ES
.fi
\*(CD\*(FRArnold Robbins wrote this reference card.
We thank
Brian Kernighan and Michael Brennan who reviewed it.\*(CX
.EB "\s+2\f(HBACKNOWLEDGMENTS\*(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.
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 empty 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 is set to \*(FC"\^"\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
and/or newlines.
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 \*(FCFIELDWIDTHS\fP
is set to a space-separated list of numbers, each field is
expected to have a fixed width, and \*(GK
splits the record using the specified widths.
Each field width may optionally be preceded by a colon-separated
value specifying the number of characters to skip before the field starts.
The value of \*(FCFS\fP is ignored.
Assigning a new value to \*(FCFS\fP or \*(FCFPAT\fP
overrides the use of \*(FCFIELDWIDTHS\*(FR.
.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.\*(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.
\*(CB\*(GK
issues a warning about its use if \*(FC\-\^\-lint\fP
is specified on the command line.\*(CL
.EB "\s+2\f(HBHISTORICAL FEATURES\*(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 character, 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
The \*(FIr\*(FC{\*(FIn\*(FC,\*(FIm\*(FC}\*(FR notation is called an
\*(FIinterval expression\fP.
\*(CRNot supported by
\*(MK.\*(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 and \*(FC\-i\fP
options.
The default path is
\*(FC".:/usr/local/share/awk"\*(FR.
If a source file name contains a ``/'' character,
no path search is performed.
.sp .5
The variable \*(FCAWKLIBPATH\fP
specifies the search path for dynamic extensions to use
with \*(FC@load\fP and the \*(FC\-l\fP option.
.sp .5
For socket communication,
\*(FCGAWK_SOCK_RETRIES\fP
controls the number of connection 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
The value of \*(FCGAWK_READ_TIMEOUT\fP specifies the time, in milliseconds,
for \*(GK to
wait for input before returning with an error.
.sp .5
If \*(FCPOSIXLY_CORRECT\fP exists
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\&.gmo\*(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\&.gmo\*(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
\*(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.\*(CL
.in -.2i
.EB "\s+2\f(HBSPECIAL FILENAMES\*(FR\s0"
.sp .5
.\" --- Namespaces
.ES
.fi
\*(CDA
\*(FIqualified name\fP
consists of a two simple identifiers joined by a double colon
(\*(FC::\fP).
The left identifier is the namespace and the right one
is the variable within it.
All non-qualified names are treated as if in the
``current'' namespace; the default namespace is \*(FCawk\fP.
However, simple identifiers consisting solely of uppercase
letters are forced into the
\*(FCawk\fP
namespace.
You change the current namespace with an
\*(FC@namespace "\*(FIname\^\*(FC"\*(FR
directive.\*(CB
.EB "\s+2\f(HBNAMESPACES (\*(GK\f(HB)\*(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.
.TE
.fi
.in +.2i
.ti -.2i
\*(CB\*(FIcmd \*(FC|& getline\*(FR
.br
Coprocess pipe into \*(FCgetline\*(FR; set \*(FC$0\*(FR, \*(FCNF\*(FR.
.br
.ti -.2i
\*(FIcmd \*(FC|& getline \*(FIv\*(FR
.br
Coprocess 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
\*(FCnextfile\fP
.br
Stop processing the current input file.
The next input record comes from the
next input file. Update \*(FCFILENAME\fP \*(CBand
\*(FCARGIND\fP\*(CD, reset \*(FCFNR\fP to 1,
and start over with the first
pattern. At end
of file, execute any \*(CB\*(FCENDFILE\fP and\*(CD \*(FCEND\fP rule(s).
.in -.2i
.sp .5
.fi
\*(FCgetline\*(FR returns 1 on success, zero on end of file,
and \-1 on an error.
\*(CBFor retryable I/O, \*(FCgetline\*(FR returns \-2.
All versions set \*(FCRT\fP.
Upon an error, \*(FCERRNO\*(FR describes
the problem.\*(CX
.EB "\s+2\f(HBINPUT CONTROL\*(FR\s0"
.sp .6
.\" --- Output Control
.ES
.fi
.in +.2i
.ti -.2i
\*(CD\*(FCfflush(\*(FR[\*(FIfile\^\*(FR]\*(FC)\*(FR
.br
Flush any buffers associated
with the open output file or pipe \*(FIfile\*(FR.
If no \*(FIfile\fP, or if
\*(FIfile\fP is null, then flush all open output files and pipes.
.ti -.2i
\*(FCprint\fP
.br
Print \*(FC$0\*(FR. Terminate the 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).
.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 coprocess \*(FIcmd\*(FR.\*(CX
.in -.2i
.EB "\s+2\f(HBOUTPUT CONTROL\*(FR\s0"
.sp .6
.\" --- Closing Redirections
.ES
.fi
.in +.2i
.ti -.2i
\*(CD\*(FCclose(\*(FIfile\*(FC)\*(FR
.br
Close input or output file, pipe \*(CBor coprocess.\*(CD
.ti -.2i
\*(CB\*(FCclose(\*(FIcommand\*(FC, \*(FIhow\*(FC)\*(FR
.br
Close one end of coprocess 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
\*(CB\*(FC%a\fP, \*(FC%A\fP	A C99 floating point hexadecimal number.\*(CD
\*(FC%c\fP		A single 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).
For 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 and decimal
point characters.\*(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\fP,	\0
  \*(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 execute 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
Declare local variables 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
.\" --- Built-in Numeric Functions
.ES
.fi
.TS
expand;
l lw(1.9i).
\*(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.
.\" \*(CB\*(FCintdiv(\*(FIn\*(FR\*(FC,\*(FI d\*(FR\*(FC,\*(FI r\*(FR\*(FC)\*(FR	T{
.\" Return result of integer division in \*(FIr\*(FR.\*(CD
.\" T}
\*(FClog(\*(FIexpr\*(FC)\*(FR	The natural logarithm function (base \*(FIe\^\*(FR).
\*(FCrand()\fP	A random number \*(FIN\fP such that 0 \(<= \*(FIN\fP < 1.
\*(FCsin(\*(FIexpr\*(FC)\*(FR	The sine of \*(FIexpr\fP, which is in radians.
\*(FCsqrt(\*(FIexpr\*(FC)\*(FR	The square root of \*(FIexpr\fP.
\&\*(FCsrand(\*(FR[\*(FIexpr\^\*(FR]\*(FC)\*(FR	T{
Use \*(FIexpr\fP as the new seed for the random number
generator. If no \*(FIexpr\fP, use the time of day.
Return the \" random number generator's
previous seed.\*(CX
T}
.TE
.EB "\s+2\f(HBNUMERIC FUNCTIONS\*(FR\s0"
.BT

.\" --- Built-in String Functions
.ES
.fi
.in +.2i
.ti -.2i
\*(CB\*(FCasort(\*(FIs \*(FR[\*(FC,\*(FI d \*(FR[\*(FC,\*(FI comp\*(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.
Use \*(FIcomp\*(FR to compare indices and elements.\*(CD
.ti -.2i
\*(CB\*(FCasorti(\*(FIs \*(FR[\*(FC,\*(FI d \*(FR[\*(FC,\*(FI comp\*(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, indicates 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 function returns the modified string;
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 zero 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 zero 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
\*(FIa\*(FC[\*(FIn\^\*(FC, "start"]\*(FR,
and
\*(FIa\*(FC[\*(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\*(FC[\*(FIi\^\fP]\*(FR is the separator that appeared in
front of \*(FIa\*(FC[\*(FIi\fP+1]\*(FR.
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 arrays \*(FIa\fP \*(CBand \*(FIseps\fP\*(CD first.
Splitting behaves identically to field splitting.
(See \fHFields\fP.)
.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

.\" --- Built-in 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,
treat it as an octal number.
If \*(FIs\*(FR begins with a leading \*(FC0x\*(FR
or \*(FC0X\*(FR, treat
\*(FIs\*(FR as a hexadecimal number. Otherwise,
treat \*(FIs\*(FR 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
.\" --- Built-in Time Functions
.ES
.fi
\*(CD\*(GK and \*(MK
provide the following functions for obtaining time stamps and
formatting them.
.sp .5
.fi
.in +.2i
.ti -.2i
\*(FCmktime(\*(FIdatespec \*(CB\*(FR[\*(FC, \*(FIutc-flag\*(FR]\*(FC\*(CD)\*(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.
\*(CBIf \*(FIutc-flag\*(FR
is present and is non-zero or non-null, the result
is in UTC, otherwise it is in local time.\*(CD
.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 it is in local time.
If \*(FItimestamp\fP is missing, use the current time of day. If
\*(FIformat\fP is missing, use \*(FCPROCINFO["strftime"]\fP.
The default value is
equivalent to the output
of \*(FIdate\*(FR\^(1).
.ti -.2i
\*(FCsystime()\fP
.br
Return the current time of day as the number of
seconds since the Epoch.\*(CL
.in -.2i
.EB "\s+2\f(HBTIME FUNCTIONS\*(FR\s0"
.sp .6
.\" --- Built-in Bit Manipulation Functions
.ES
.fi
\*(CD\*(GK
provides the following bit manipulation functions.
.sp .5
.fi
.in +.2i
.ti -.2i
\*(FCand(\*(FIv1\*(FC, \*(FIv2\*(FR [\*(FC,\*(FR ... ]\*(FC)\*(FR
.br
Return the bitwise AND of the arguments.
.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\*(FR [\*(FC,\*(FR ... ]\*(FC)\*(FR
.br
Return the bitwise OR of the arguments.
.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\*(FR [\*(FC,\*(FR ... ]\*(FC)\*(FR
.br
Return the bitwise XOR of the arguments.\*(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\*(FC@load "\*(FIextension\*(FC"\*(FR
.br
Dynamically load the named \*(FIextension\*(FR.
This adds new built-in functions to \*(GK.
The extension is loaded during the parsing of the program.
See the manual for details.\*(CB
.in -.2i
.EB "\s+2\f(HBDYNAMIC EXTENSIONS (\*(GK\f(HB)\*(FR\s0"
.BT

.\" --- Generator Functions
.ES
.fi
.in +.2i
.ti -.2i
\*(CD\*(FCmkbool(\*(FIexpression\*(FC)\*(FR
.br
Return a Boolean-typed value based on the Boolean value
of \*(FIexpression\fP. True values have a numeric value of one.
False values have a numeric value of zero.\*(CB
.in -.2i
.EB "\s+2\f(HBGENERATOR FUNCTIONS (\*(GK\f(HB)\*(FR\s0"
.sp .5
.\" --- Type Functions
.ES
.fi
.in +.2i
.ti -.2i
\*(CD\*(FCisarray(\*(FIx\*(FC)\*(FR
.br
Return true if \*(FIx\fP is an array, false otherwise.
.br
.ti -.2i
\*(FCtypeof(\*(FIx\*(FC)\*(FR
.br
Return a string indicating the type of \*(FIx\fP.\*(CB
.in -.2i
.EB "\s+2\f(HBTYPE FUNCTIONS (\*(GK\f(HB)\*(FR\s0"
.sp .5
.\" --- Built-in 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\&.gmo\*(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.
.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.
The default for \*(FIcat\*(FR is \*(FC"LC_MESSAGES"\*(FR.\*(CB
.in -.2i
.EB "\s+2\f(HBINTERNATIONALIZATION (\*(GK\f(HB)\*(FR\s0"
.sp .5
.\" --- FTP/HTTP/GIT Information
.ES
.nf
\*(CDHost: \*(FCftp.gnu.org\*(FR
File: \*(FC/gnu/gawk/gawk-5.1.1.tar.gz\fP
.in +.2i
.fi
GNU \*(AK (\*(GK). There may be a later version.
.in -.2i
.nf
.sp .4
\*(FCgit clone git://github.com/onetrueawk/awk\fP
.in +.2i
.fi
\*(NK. This version requires an ANSI C compiler;
GCC (the GNU Compiler Collection) works well.
.in -.2i
.nf
.sp .4
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/GIT INFORMATION\*(FR\s0"
.sp .5
.\" --- Copying Permissions
.ES
.fi
\*(CDCopyright \(co 1996\(en2005,
2007, 2009\(en2021 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