diff options
Diffstat (limited to 'contrib/awk/doc/awkcard.in')
| -rw-r--r-- | contrib/awk/doc/awkcard.in | 1550 |
1 files changed, 1550 insertions, 0 deletions
diff --git a/contrib/awk/doc/awkcard.in b/contrib/awk/doc/awkcard.in new file mode 100644 index 0000000..ac1e8e5 --- /dev/null +++ b/contrib/awk/doc/awkcard.in @@ -0,0 +1,1550 @@ +.\" 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 |
