path: root/contrib/awk/doc/awkcard.in

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

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


.\"
.\"
.\" --- Definitions
.fi
.ES
\*(CDThis card describes POSIX AWK, as well as the three
freely available \*(AK implementations
(see \fHFTP Information\fP below).
\*(CLCommon extensions (in two or more versions) are printed in light blue.
\*(CBFeatures specific to just one version\(emusually GNU AWK (\*(GK)\(emare
printed in dark blue.
\*(CRExceptions and deprecated features are printed in red.
\*(CDFeatures mandated by POSIX are printed in black.
.sp .5
Several type faces are used to clarify the meaning:
.br
.nr IN \w'\(bu '
\(bu \*(FC\*(CN\fP is used for computer input.
.br
.fi
.in +\n(INu
.ti -\n(INu
\(bu\|\^\*(FI\*(IN\fP is used 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.
.sp .5
\*(FIescape sequences\fP \- a special sequence of characters beginning
with a backslash, used to describe otherwise unprintable characters.
(See \fHEscape Sequences\fP below.)
.sp .5
\*(FIstring\fP \- a group of characters enclosed in double quotes.
Strings may contain \*(FIescape sequences\*(FR.
.sp .5
\*(FIregexp\fP \- a regular expression, either a regexp constant
enclosed in forward slashes, or a dynamic regexp computed at run-time.
Regexp constants may contain \*(FIescape sequences\*(FR.
.sp .5
\*(FIname\fP \- a variable, array or function name.
.sp .5
\*(FIentry\fP(\*(FIN\fP) \- entry \*(FIentry\fP in section \*(FIN\fP of the
UNIX reference manual.
.sp .5
\*(FIpattern\fP \- an expression describing an input record to be matched.
.sp .5
\*(FIaction\fP \- statements to execute when an input record is matched.
.sp .5
\*(FIrule\fP \- a pattern-action pair, where the pattern or action may
be missing.\*(CX
.EB \s+2\f(HBDEFINITIONS\*(FR\s0

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

.BT

.ES
.fi
\*(CDThe following options are specific to \*(GK. The \*(FC\-W\*(FR
forms are for full POSIX compliance.
.sp .5
.ig
.\" This option is left undocumented, on purpose.
\*(FC\-\^\-nostalgia\*(FR
\*(FC\-W nostalgia\*(FR%T{
provide a moment of nostalgia for
long time \*(AK users.
T}
..
.TS
expand, tab(%);
ls
l lw(1.8i).
\*(FC\-\^\-field-separator \*(FIfs\*(FR
%just like \*(FC\-F\fP
\*(FC\-\^\-assign \*(FIvar\*(FC\^=\^\*(FIval\*(FR%just like \*(FC\-v\fP
\*(FC\-\^\-file \*(FIprog-file%\*(FRjust like \*(FC\-f\fP
\*(FC\-\^\-traditional\*(FR
\*(FC\-\^\-compat\*(FR
\*(FC\-W compat\*(FR
\*(FC\-W traditional\*(FR%T{
turn off \*(GK-specific extensions
(\*(FC\-\^\-traditional\*(FR preferred).
T}
\*(FC\-\^\-copyleft\*(FR
\*(FC\-\^\-copyright\*(FR
\*(FC\-W copyleft\*(FR
\*(FC\-W copyright\*(FR%T{
print the short version of the GNU
copyright information on \*(FCstdout\*(FR.
T}
\*(FC\-\^\-help\*(FR
\*(FC\-\^\-usage\*(FR
\*(FC\-W help\*(FR
\*(FC\-W usage\*(FR%T{
print a short summary of the available
options on \*(FCstdout\*(FR, then exit zero.
T}
\*(FC\-\^\-lint\*(FR
\*(FC\-W lint\*(FR%T{
warn about constructs that are dubious
or non-portable to other \*(AKs.
T}
\*(FC\-\^\-lint\-old\*(FR
\*(FC\-W lint\-old\*(FR%T{
warn about constructs that are not
portable to the original version of
Unix \*(AK.
T}
\*(FC\-\^\-posix\*(FR
\*(FC\-W posix\*(FR%T{
disable common and GNU extensions.
Enable \*(FIinterval expressions\*(FR in regular
expression matching (see \fHRegular
Expressions\fP below).
T}
\*(FC\-\^\-re\-interval\*(FR
\*(FC\-W re\-interval\*(FR%T{
enable \*(FIinterval expressions\*(FR in regular
expression matching (see \fHRegular
Expressions\fP below). Useful if
\*(FC\-\^\-posix\*(FR is not specified.
T}
\*(FC\-\^\-source '\*(FItext\*(FC'\*(FR
\*(FC\-W source '\*(FItext\*(FC'\*(FR%use \*(FItext\*(FR as AWK program source code.
\*(FC\-\^\-version\*(FR
\*(FC\-W version\*(FR%T{
print version information on \*(FCstdout\fP
and exit zero.
T}
.TE
.sp .5
.fi
In compatibility mode,
any other options are flagged as illegal, but are otherwise ignored.
In normal operation, as long as program text has been supplied, unknown
options are passed on to the AWK program in
\*(FCARGV\*(FR
for processing. This is most useful for running AWK
programs via the \*(FC#!\*(FR executable interpreter mechanism.\*(CB
.EB "\s+2\f(HBCOMMAND LINE ARGUMENTS (\*(GK\f(HB)\*(FR\s0"

.BT

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

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


.BT

.\" --- Lines And Statements
.ES
.fi
\*(CDAWK is a line oriented language. The pattern comes first, and then the
action. Action statements are enclosed in \*(FC{\fP and \*(FC}\*(FR.
Either the pattern  or the action may be missing, but
not both. If the pattern is missing, the action will be
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 will be ignored. However, a ``\e'' after a
\*(FC#\*(FR is not special.
.sp .5
Multiple statements may be put on one line by separating them with a ``;''.
This applies to both the statements within the action part of a
pattern-action pair (the usual case)
and to the pattern-action statements themselves.\*(CX
.EB "\s+2\f(HBLINES AND STATEMENTS\*(FR\s0"



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


.BT

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

.\" --- Records
.ES
.fi
\*(CDNormally, records are separated by newline characters.
Assigning values to the built-in variable \*(FCRS\*(FR
controls how records are separated.
If \*(FCRS\fP is any single character, that character separates records.
\*(CLOtherwise, \*(FCRS\fP is a regular expression.
\*(CR(Not \*(NK.)\*(CL
Text in the input that matches this
regular expression will separate the record.
\*(CB\*(GK sets \*(FCRT\*(FR to the value of the
input text that matched the regular expression.
The value of \*(FCIGNORECASE\fP
will also affect 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
will also affect 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
will split up the record using the specified widths.
The value of \*(FCFS\fP is ignored.
Assigning a new value to \*(FCFS\fP
overrides the use of \*(FCFIELDWIDTHS\*(FR,
and restores the default behavior.\*(CD
.sp .5
Each field in the input record may be referenced by its position,
\*(FC$1\*(FR, \*(FC$2\*(FR and so on.
\*(FC$0\fP is the whole record.
Fields may also be assigned new values.
.sp .5
The variable \*(FCNF\fP
is set to the total number of fields in the input record.
.sp .5
References to non-existent fields (i.e., fields after \*(FC$NF\*(FR)
produce the null-string. However, assigning to a non-existent field
(e.g., \*(FC$(NF+2) = 5\*(FR) will increase the value of
\*(FCNF\*(FR, create any intervening fields with the null string as their value,
and cause the value of \*(FC$0\fP
to be recomputed with the fields being separated by the
value of \*(FCOFS\*(FR.
References to negative numbered fields cause a fatal error.
Decreasing the value of \*(FCNF\fP causes the trailing fields to be lost
\*(CR(not \*(NK).\*(CX
.EB \s+2\f(HBFIELDS\*(FR\s0

.BT

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


.\" --- Action Statements
.ES
.nf
\*(CD\*(FCif (\*(FIcondition\*(FC) \*(FIstatement\*(FR [ \*(FCelse\*(FI statement \*(FR]
\*(FCwhile (\*(FIcondition\*(FC) \*(FIstatement \*(FR
\*(FCdo \*(FIstatement  \*(FCwhile (\*(FIcondition\*(FC)\*(FR
\*(FCfor (\*(FIexpr1\*(FC; \*(FIexpr2\*(FC; \*(FIexpr3\*(FC) \*(FIstatement\*(FR
\*(FCfor (\*(FIvar \*(FCin\*(FI array\*(FC) \*(FIstatement\*(FR
.ig
\*(CB\*(FCabort\*(FR [ \*(FIexpression\*(FR ]\*(CD
..
\*(FCbreak\*(FR
\*(FCcontinue\*(FR
\*(FCdelete \*(FIarray\^\*(FC[\^\*(FIindex\^\*(FC]\*(FR
\*(CL\*(FCdelete \*(FIarray\^\*(FR\*(CD
\*(FCexit\*(FR [ \*(FIexpression\*(FR ]
\*(FCnext\*(FR
\*(CL\*(FCnextfile\*(FR \*(CR(not \*(MK)\*(CD
\*(FC{ \*(FIstatements \*(FC}\*(CX
.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
.ig
\*(CB\*(FCPROCINFO\fP	T{
elements of this array provide access to info
about the running AWK program. See
\*(AM for details.\*(CD
T}
..
.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

.\" --- Variables
.ES
.fi
.TS
expand;
l lw(2i).
\*(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}
\*(FCCONVFMT\fP	T{
conversion format for numbers, default value
is \*(FC"%.6g"\*(FR.
T}
\*(FCENVIRON\fP	T{
array containing the the current environment.
The array is indexed by the environment
variables, each element being the value of
that variable.
T}
\*(CB\*(FCERRNO\fP	T{
contains a string describing the error when a
redirection or read for \*(FCgetline\*(FR fails, or if
\*(FCclose()\*(FR fails.
T}
\*(FCFIELDWIDTHS\fP	T{
white-space separated list of fieldwidths. Used
to parse the input into fields of fixed width,
instead of the value of \*(FCFS\fP.\*(CD
T}
\*(FCFILENAME\fP	T{
name of the current input file. If no files given
on the command line, \*(FCFILENAME\fP is ``\-''.
\*(FCFILENAME\fP is undefined inside the \*(FCBEGIN\fP rule
(unless set by \*(FCgetline\fP).
T}
\*(FCFNR\fP	T{
number of the input record in current input file.
T}
\*(FCFS\fP	T{
input field separator, a space by default
(see \fHFields\fP above).
T}
\*(CB\*(FCIGNORECASE\fP	T{
if non-zero, all regular expression and string
operations ignore case. \*(CRIn versions of \*(GK
prior to 3.0, \*(FCIGNORECASE\fP only affected
regular expression operations and \*(FCindex()\*(FR.\*(CD
T}
\*(FCNF\fP	T{
number of fields in the current input record.
T}
\*(FCNR\fP	T{
total number of input records seen so far.
T}
\*(FCOFMT\fP	T{
output format for numbers, \*(FC"%.6g"\*(FR, by default.
\*(CROld versions of \*(AK also used this for number
to string conversion instead of \*(FCCONVFMT\fP.\*(CD
T}
\*(FCOFS\fP	T{
output field separator, a space by default.
T}
\*(FCORS\fP	T{
output record separator, a newline by default.
T}
\*(FCRS\fP	T{
input record separator, a newline by default
(see \fHRecords\fP above).
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}
\*(FCRSTART\fP	T{
index of the first character matched by
\*(FCmatch()\*(FR; 0 if no match.
T}
\*(FCRLENGTH\fP	T{
length of the string matched by \*(FCmatch()\*(FR;
\-1 if no match.
T}
\*(FCSUBSEP\fP	T{
character(s) used to separate multiple subscripts
in array elements, by default \*(FC"\e034"\*(FR. (see
\fHArrays\fP below).\*(CX
T}
.TE
.EB \s+2\f(HBVARIABLES\*(FR\s0

.BT

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

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


.BT

.\" --- Conversions and Comparisons
.ES
.fi
\*(CDVariables and fields may be (floating point) numbers, strings or both.
Context determines how the value of a variable is interpreted. If used in
a numeric expression, it will be treated as a number, if used as a string
it will be treated as a string.
.sp .5
To force a variable to be treated as a number, add 0 to it; to force it
to be treated as a string, concatenate it with the null string.
.sp .5
When a string must be converted to a number, the conversion is accomplished
using \*(FIatof\*(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.
\*(CRAccording to the POSIX standard, even if two strings are
numeric strings, a numeric comparison is performed. However, this is
clearly incorrect, and none of the three free \*(AK\*(FRs do this.\*(CD
.sp .5
Note that string constants, such as \*(FC"57"\fP, are \*(FInot\fP
numeric strings, they are string constants. The idea of ``numeric string''
only applies to fields, \*(FCgetline\fP input,
\*(FCFILENAME\*(FR, \*(FCARGV\fP elements, \*(FCENVIRON\fP
elements and the elements of an array created by
\*(FCsplit()\fP that are numeric strings.
The basic idea is that \*(FIuser input\*(FR,
and only user input, that looks numeric,
should be treated that way.
.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"

.ig
.\" --- Localization
.ES
.nf
.ce 100
\*(CDThis
section
is
under
construction.
.sp .5
This
section
is
under
construction.\*(CB
.ce 0
.EB "\s+2\f(HBLOCALIZATION\*(FR\s0"
..

.ig
.ps +2
.ce 1
\*(CD\fHISBN: 0-916151-97-2\*(FR
.ps -2
..

.BT


.\" --- Input Control
.ES
.fi
.TS
expand;
l lw(1.8i).
\*(CD\*(FCclose(\*(FIfile\*(FC)\*(FR	close input file or pipe.
\*(FCgetline\fP	T{
set \*(FC$0\fP from next input 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
\*(FCnext\fP
.br
stop processing the current input
record. Read next input record and
start over with the first pattern in the
program. Upon end of the input data,
execute any \*(FCEND\fP rule(s).
.br
.ti -.2i
\*(CL\*(FCnextfile\fP
.br
stop processing the current input file.
The next input record comes from the
next input file. \*(FCFILENAME\fP \*(CBand
\*(FCARGIND\fP\*(CL are updated, \*(FCFNR\fP is reset to 1,
and processing starts over with the first
pattern in the AWK program. Upon end
of input data, execute any \*(FCEND\fP rule(s).
\*(CREarlier versions of \*(GK used
\*(FCnext file\*(FR, as two words. This
generates a warning message and will
eventually be removed. \*(CR\*(MK does not
currently support \*(FCnextfile\*(FR.\*(CD
.in -.2i
.sp .5
.fi
\*(FCgetline\*(FR returns 0 on end of file, and \-1 on an
error.\*(CX
.EB "\s+2\f(HBINPUT CONTROL\*(FR\s0"

.\" --- Output Control
.ES
.fi
.in +.2i
.ti -.2i
\*(CD\*(FCclose(\*(FIfile\*(FC)\*(FR
.br
close output file or pipe.
.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 \*(FIfile\fP is missing, then standard output is flushed.
If \*(FIfile\fP is the null string, then all open output files and pipes
are flushed \*(CR(not \*(NK)\*(CD.
.ti -.2i
\*(FCprint\fP
.br
print the current record. The output record is terminated
with the value of \*(FCORS\fP.
.ti -.2i
\*(FCprint \*(FIexpr-list\*(FR
.br
print expressions. Each expression is separated
by the value of \*(FCOFS\fP. The output record is
terminated with the value of \*(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
will be truncated. Subsequent commands append data.
.ti -.2i
\*(FCprint "hello" >> \*(FIfile\*(FR
.br
Append data to \*(FIfile\fP. The previous contents of the file are not lost.
.ti -.2i
\*(FCprint "hello" | \*(FIcmd\*(FR
.br
Print data down a pipeline to \*(FIcmd\*(FR.\*(CX
.in -.2i
.EB "\s+2\f(HBOUTPUT CONTROL\*(FR\s0"

.BT


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



.BT

.\" --- Special Filenames
.ES
.fi
\*(CDWhen doing I/O redirection from either \*(FCprint\fP
or \*(FCprintf\fP into a file or via \*(FCgetline\fP
from a file, all three implementations of \*(FCawk\fP
recognize certain special filenames internally. These filenames
allow access to open file descriptors inherited from the
parent process (usually the shell).
These filenames may also be used on the command line to name data files.
The filenames are:
.sp .5
.TS
expand;
l lw(2i).
\*(FC"\-"\fP	standard input
\*(FC/dev/stdin\fP	standard input \*(CR(not \*(MK)\*(CD
\*(FC/dev/stdout\fP	standard output
\*(FC/dev/stderr\fP	standard error output
.TE
.sp .5
.fi
\*(CBThe following names are specific to \*(GK.
.sp .5
.TS
expand;
l lw(2i).
\*(FC/dev/fd/\^\*(FIn\*(FR	T{
file associated with the open file descriptor \*(FIn\*(FR
T}
.TE
.sp .5
.fi
Other special filenames provide access to information about the running
\*(FCgawk\fP process.
Reading from these files returns a single record.
The filenames and what they return are:\*(FR
.sp .5
.TS
expand;
l lw(2i).
\*(FC/dev/pid\fP	process ID of current process
\*(FC/dev/ppid\fP	parent process ID of current process
\*(FC/dev/pgrpid\fP	process group ID of current process
\*(FC/dev/user\fP	T{
.nf
a single newline-terminated record.
The fields are separated with spaces.
\*(FC$1\fP is the return value of \*(FIgetuid\*(FR(2),
\*(FC$2\fP is the return value of \*(FIgeteuid\*(FR(2),
\*(FC$3\fP is the return value of \*(FIgetgid\*(FR(2) , and
\*(FC$4\fP is the return value of \*(FIgetegid\*(FR(2).
.fi
Any additional fields are the group IDs returned
by \*(FIgetgroups\*(FR(2). Multiple groups may not be
supported on all systems.
T}
.TE
.sp .5
.fi
.ig
\*(CRThese filenames are now obsolete.
Use the \*(FCPROCINFO\fP array to obtain the information they provide.\*(CL
..
.\" BEGIN FOR 3.0.x
\*(CRThese filenames will become obsolete in \*(GK 3.1.
Be aware that you will have to change your programs.\*(CL
.\" END FOR 3.0.x
.EB "\s+2\f(HBSPECIAL FILENAMES\*(FR\s0"




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


.BT


.\" --- Builtin String Functions
.ES
.fi
.in +.2i
.ti -.2i
\*(CB\*(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 no
\*(FIt\fP is supplied, \*(FC$0\fP is used instead. Within the
replacement text \*(FIs\*(FR, the sequence \*(FC\e\*(FIn\*(FR,
where \*(FIn\fP is a digit from 1 to 9, may be used to indicate just
the text that matched the \*(FIn\*(FRth parenthesized subexpression.
The sequence \*(FC\e0\fP represents the entire matched text, as does
the character \*(FC&\*(FR. Unlike \*(FCsub()\fP and \*(FCgsub()\*(FR,
the modified string is returned as the result of the function,
and the original target string is \*(FInot\fP changed.\*(CD
.ti -.2i
\*(FCgsub(\*(FIr\*(FC, \*(FIs \*(FR[\*(FC, \*(FIt\*(FR]\*(FC)\*(FR
.br
for each substring matching the
regular expression \*(FIr\fP in the string \*(FIt\*(FR, substitute the
string \*(FIs\*(FR, and return the number of substitutions. If
\*(FIt\fP is not supplied, use \*(FC$0\*(FR. An \*(FC&\fP in the
replacement text is replaced with the text that was actually matched.
Use \*(FC\e&\fP to get a literal \*(FC&\*(FR. See \*(AM
for a fuller discussion of the rules for \*(FC&\*(FR's and backslashes
in the replacement text of \*(CB\*(FCgensub()\*(FR,\*(CD \*(FCsub()\*(FR
and \*(FCgsub()\*(FR
.ti -.2i
\*(FCindex(\*(FIs\*(FC, \*(FIt\*(FC)\*(FR
.br
returns the index of the string
\*(FIt\fP in the string \*(FIs\*(FR, or 0 if \*(FIt\fP is not present.
.ti -.2i
\*(FClength(\*(FR[\*(FIs\*(FR]\*(FC)\*(FR
.br
returns the length of the string
\*(FIs\*(FR, or the length of \*(FC$0\fP if \*(FIs\fP is not supplied.
.ti -.2i
\*(FCmatch(\*(FIs\*(FC, \*(FIr\*(FC)\*(FR
.br
returns the position in
\*(FIs\fP where the regular expression \*(FIr\fP occurs, or 0 if
\*(FIr\fP is not present, and sets the values of variables
\*(FCRSTART\fP
and \*(FCRLENGTH\*(FR.
.ti -.2i
\*(FCsplit(\*(FIs\*(FC, \*(FIa \*(FR[\*(FC, \*(FIr\*(FR]\*(FC)\*(FR
.br
splits the string
\*(FIs\fP into the array \*(FIa\fP using the regular expression \*(FIr\*(FR,
and returns the number of fields. If \*(FIr\fP is omitted, \*(FCFS\fP
is used instead. The array \*(FIa\fP is cleared first.
Splitting behaves identically to field splitting.
(See \fHFields\fP, above.)
.ti -.2i
\*(FCsprintf(\*(FIfmt\*(FC, \*(FIexpr-list\*(FC)\*(FR
.br
prints \*(FIexpr-list\fP
according to \*(FIfmt\*(FR, and returns the resulting string.
.ti -.2i
\*(FCsub(\*(FIr\*(FC, \*(FIs \*(FR[\*(FC, \*(FIt\*(FR]\*(FC)\*(FR
.br
just like
\*(FCgsub()\*(FR, but only the first matching substring is replaced.
.ti -.2i
\*(FCsubstr(\*(FIs\*(FC, \*(FIi \*(FR[\*(FC, \*(FIn\*(FR]\*(FC)\*(FR
.br
returns the at most
\*(FIn\*(FR-character substring of \*(FIs\fP starting at \*(FIi\*(FR.
If \*(FIn\fP is omitted, the rest of \*(FIs\fP is used.
.ti -.2i
\*(FCtolower(\*(FIstr\*(FC)\*(FR
.br
returns a copy of the string \*(FIstr\*(FR,
with all the upper-case characters in \*(FIstr\fP translated to their
corresponding lower-case counterparts. Non-alphabetic characters are
left unchanged.
.ti -.2i
\*(FCtoupper(\*(FIstr\*(FC)\*(FR
.br
returns a copy of the string \*(FIstr\*(FR,
with all the lower-case characters in \*(FIstr\fP translated to their
corresponding upper-case counterparts. Non-alphabetic characters are
left unchanged.\*(CX
.in -.2i
.EB "\s+2\f(HBSTRING FUNCTIONS\*(FR\s0"



.BT


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



.\" --- 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 & b are local
	function f(p, q,     a, b)
	{
		\&.....
	}
.sp .3
	/abc/	{ ... ; f(1, 2) ; ... }\*(FR
.fi
.sp .5
The left parenthesis in a function call is required
to immediately follow the function name
without any intervening white space.
This is to avoid a syntactic ambiguity with the concatenation operator.
This restriction does not apply to the built-in functions.
.sp .5
Functions may call each other and may be recursive.
Function parameters used as local variables are initialized
to the null string and the number zero upon function invocation.
.sp .5
Use \*(FCreturn\fP to return a value from a function. The return value
is undefined if no value is provided, or if the function returns by
``falling off'' the end.
.sp .5
\*(CLThe word
\*(FCfunc\fP
may be used in place of
\*(FCfunction\*(FR.
\*(CRNote: This usage is deprecated.\*(CX
.EB "\s+2\f(HBUSER-DEFINED FUNCTIONS\*(FR\s0"



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

.BT

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

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


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

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