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