1551 lines
46 KiB
Plaintext
1551 lines
46 KiB
Plaintext
.\" 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
|