diff options
Diffstat (limited to 'doc/awkcard.in')
| -rw-r--r-- | doc/awkcard.in | 1353 |
1 files changed, 1353 insertions, 0 deletions
diff --git a/doc/awkcard.in b/doc/awkcard.in new file mode 100644 index 00000000..50af4aae --- /dev/null +++ b/doc/awkcard.in @@ -0,0 +1,1353 @@ +.\" AWK Reference Card --- Arnold Robbins, arnold@gnu.ai.mit.edu +.\" +.\" Copyright (C) 1996 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 +.\" +.\" + + +.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 (\*(GK) 16 +Escape Sequences 7 +Expressions 9 +Fields 6 +FTP Information 16 +Historical Features 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 15 +User-defined Functions 15 +Variables 8\*(CX +.in -.2i +.EB "\s+2\f(HBCONTENTS\*(FR\s0" +.sp +.ta .2i .78i 1i 1.2i 1.4i 1.7i +.fi +\*(CD\*(FRThis reference card was written by Arnold Robbins. +Brian Kernighan and Michael Brennan reviewed it; we thank them +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 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 +\(bu \*(FC\*(CN\fP is used for computer input. +.br +\(bu\|\^\*(FI\*(IN\fP is used to indicate user input and for syntactic +.br +\0\|\^placeholders, such as \*(FIvariable\fP or \*(FIaction\fP. +.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 behaviour of the running interpreter. +.sp .5 +.nf +\*(FC\-F \*(FIfs\*(FR use \*(FIfs\fP for the input field separator +\*(FC\-v\*(FI var\*(FC\^=\^\*(FIval\*(FR 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 +\*(FC\-f \*(FIprog-file\*(FR 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 +\*(FC\-\^\-\*(FR signal the end of options +.sp .5 +.fi +\*(CLThe following options are accepted by both \*(NK and \*(GK +\*(CR(ignored by \*(GK, not in \*(MK).\*(CL +.sp .5 +.nf +\*(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 +.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 +.nf +\*(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 turn off \*(GK-specific extensions + (\*(FC\-\^\-traditional\*(FR preferred) +\*(FC\-\^\-copyleft\*(FR +\*(FC\-\^\-copyright\*(FR +\*(FC\-W copyleft\*(FR +\*(FC\-W copyright\*(FR print the short version of the GNU + copyright information on \*(FCstdout\*(FR +\*(FC\-\^\-help\*(FR +\*(FC\-\^\-usage\*(FR +\*(FC\-W help\*(FR +\*(FC\-W usage\*(FR Print a short summary of the available + options on \*(FCstdout\*(FR, then exit zero +\*(FC\-\^\-lint\*(FR +\*(FC\-W lint\*(FR warn about constructs that are dubious + or non-portable to other \*(AKs +\*(FC\-\^\-lint\-old\*(FR +\*(FC\-W lint\-old\*(FR warn about constructs that are not + portable to the original version of + Unix \*(AK +.ig +.\" This option is left undocumented, on purpose. +\*(FC\-\^\-nostalgia\*(FR +\*(FC\-W nostalgia\*(FR provide a moment of nostalgia for + long time \*(AK users +.. +\*(FC\-\^\-posix\*(FR +\*(FC\-W posix\*(FR disable common and GNU extensions. + Enable \*(FIinterval expressions\*(FR in regular + expression matching (see \fHRegular + Expressions\fP, below) +\*(FC\-\^\-re\-interval\*(FR +\*(FC\-W re\-interval\*(FR enable \*(FIinterval expressions\*(FR in regular + expression matching (see \fHRegular + Expressions\fP, below). Useful if + \*(FC\-\^\-posix\*(FR is not specified +\*(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 print version information on \*(FCstdout\fP + and exit zero +.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 +.nf +\*(FC\-W dump\*(FR print an assembly listing of the program to + \*(FCstdout\fP and exit zero +\*(FC\-W exec \*(FIfile\*(FR read program text from \*(FIfile\fP. No other + options are processed. Useful with \*(FC#!\fP +\*(FC\-W interactive\*(FR unbuffer \*(FCstdout\fP and line buffer \*(FCstdin\fP. + Lines are always records, ignoriing \*(FCRS\fP +\*(FC\-W posix_space\*(FR make \*(FC\en\*(FR separate fields when \*(FCRS = "\^"\fP +\*(FC\-W sprintf=\*(FInum\*(FR adjust the size of \*(MK's internal + \*(FCsprintf\*(FR buffer +\*(FC\-W version\*(FR print version and copyright information on + \*(FCstdout\fP and limit information on \*(FCstderr\fP + and exit zero +.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 together. +.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 may be missing, 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" +.ta .2i .78i 1i 1.2i 1.4i 1.7i + + +.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" +.ta .2i .78i 1i 1.2i 1.4i 1.7i + + + +.\" --- 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. +The value of a field may be assigned to as well. +.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 +.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" +.ta .2i .78i 1i 1.2i 1.4i 1.7i + + +.BT + +.\" --- Variables +.ES +.nf +\*(FCARGC\fP number of command line arguments +\*(CB\*(FCARGIND\fP index in \*(FCARGV\fP of current data file\*(CD +\*(FCARGV\fP 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 +\*(FCCONVFMT\fP conversion format for numbers, default value + is \*(FC"%.6g"\*(FR +\*(FCENVIRON\fP array containing the the current environment. + The array is indexed by the environment + variables, each element being the value of + that variable +\*(CB\*(FCERRNO\fP contains a string describing the error when a + redirection or read for \*(FCgetline\*(FR fails, or if + \*(FCclose()\*(FR fails +\*(CB\*(FCFIELDWIDTHS\fP white-space separated list of fieldwidths. Used + to parse the input into fields of fixed width, + instead of the value of \*(FCFS\fP\*(CD +\*(FCFILENAME\fP 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) +\*(FCFNR\fP number of the input record in current input file +\*(FCFS\fP input field separator, a space by default. + See \fHFields\fP, above +\*(CB\*(FCIGNORECASE\fP 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 +\*(FCNF\fP number of fields in the current input record +\*(FCNR\fP total number of input records seen so far +\*(FCOFMT\fP 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 +\*(FCOFS\fP output field separator, a space by default +\*(FCORS\fP output record separator, a newline by default +.ig +\*(CB\*(FCPROCINFO\fP elements of this array provide access to info + about the running AWK program. See + \*(AM for details\*(CD +.. +\*(FCRS\fP input record separator, a newline by default. + See \fHRecords\fP, above +\*(CB\*(FCRT\fP record terminator. \*(GK sets \*(FCRT\fP to the input + text that matched the character or regular + expression specified by \*(FCRS\*(FR\*(CD +\*(FCRSTART\fP index of the first character matched by + \*(FCmatch()\*(FR; 0 if no match +\*(FCRLENGTH\fP length of the string matched by \*(FCmatch()\*(FR; + \-1 if no match +\*(FCSUBSEP\fP character(s) used to separate multiple subscripts + in array elements, by default \*(FC"\e034"\*(FR. See + \fHArrays\fP, below\*(CX +.EB \s+2\f(HBVARIABLES\*(FR\s0 + +.BT + +.\" --- Arrays +.ES +.fi +\*(CDArrays are subscripted with an expression between square brackets +(\*(FC[ \*(FRand \*(FC]\*(FR). +If the expression is an expression list +\*(FC(\*(FIexpr\*(FC, \*(FIexpr \*(FC...)\*(FR +then the array 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 facility simulates multiply dimensioned +arrays. For example: +.nf +.sp .5 + \*(FCi = "A";\^ j = "B";\^ k = "C" + x[i, j, k] = "hello, world\en"\*(FR +.sp .5 +.fi +assigns the string \*(FC"hello, world\en"\*(FR to the element of the array +\*(FCx\fP +which is indexed by the string \*(FC"A\e034B\e034C"\*(FR. All arrays in AWK +are associative, i.e. indexed by string values. +.sp .5 +The special operator \*(FCin\fP may be used in an \*(FCif\fP +or \*(FCwhile\fP statement to see if an array has an index consisting +of a particular value. +.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 +The \*(FCin\fP construct may also be used in a \*(FCfor\fP +loop to iterate over all the elements of an array. +.sp .5 +An element may be deleted from an array using the +\*(FCdelete\fP statement. +\*(CLThe \*(FCdelete\fP +statement can also delete the entire contents of an array, +just by specifying the array name without a subscript.\*(CX +.EB \s+2\f(HBARRAYS\*(FR\s0 + + +.\" --- Expressions +.ES +.fi +\*(CDExpressions are used as patterns, for controlling conditional +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 +.nf +\*(FC(\&...)\*(FR grouping +\*(FC$\fP field reference +\*(FC++ \-\^\-\fP increment and decrement, both prefix and postfix +\*(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 +\*(FC=\0+=\0\-=\0*=\0/=\0%=\0^=\0\*(CL**=\*(CD\fP + assignment operators\*(CX +.EB \s+2\f(HBEXPRESSIONS\*(FR\s0 + + +.BT + +.\" --- Conversions and Comparisons +.ES +.fi +\*(CDVariables and fields may be (floating point) numbers, or 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" +.. + +.BT + + +.\" --- Input Control +.ES +.nf +\*(CD\*(FCclose(\*(FIfile\*(FC)\*(FR close input file or pipe +\*(FCgetline\fP set \*(FC$0\fP from next input record; + set \*(FCNF\*(FR, \*(FCNR\*(FR, \*(FCFNR\*(FR +\*(FCgetline < \*(FIfile\*(FR set \*(FC$0\fP from next record of \*(FIfile\*(FR; set \*(FCNF\*(FR +\*(FCgetline \*(FIv\*(FR set \*(FIv\fP from next input record; + set \*(FCNR\*(FR, \*(FCFNR\*(FR +\*(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 +\*(FCnext\fP 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) +\*(CL\*(FCnextfile\fP 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 +.sp .5 +.fi +The \*(FCgetline\*(FR command 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 number (the integer part) +\*(FC%s\fP a character string +\*(FC%x\fP an unsigned hexadecimal number (integer part) +\*(FC%X\fP like \*(FC%x\fP, but use \*(FCABCDEF\fP instead of \*(FCabcdef\*(FR +\*(FC%%\fP A single \*(FC%\fP character; no argument is converted +.sp .5 +.fi +Optional, additional parameters may lie between the \*(FC%\fP +and the control letter: +.sp .5 +.nf +\*(FC\-\fP left-justify the expression within its field +\*(FIspace\fP for numeric conversions, prefix positive values + with a space, and negative values with a + minus sign +\*(FC+\fP 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 +\*(FC#\fP use an ``alternate form'' for some control letters. + For \*(FC%o\*(FR, supply a leading zero. + For \*(FC%x\*(FR, and \*(FC%X\*(FR, supply a leading \*(FC0x\*(FR or \*(FC0X\*(FR for a + nonzero result. + For \*(FC%e\*(FR, \*(FC%E\*(FR, and \*(FC%f\*(FR, the result will always + contain a decimal point. + For \*(FC%g\*(FR, and \*(FC%G\*(FR, trailing zeros are not removed +\*(FC0\fP 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 +\*(FIwidth\fP pad the field to this width. The field is normally + padded with spaces. If the \*(FC0\fP flag has been used, + pad with zeroes +\*(FC\&.\*(FIprec\*(FR specifies the precision to use when printing. + For the \*(FC%e\*(FR, \*(FC%E\*(FR, and \*(FC%f\*(FR formats, the number of + digits to print to the right of the decimal point. + For the \*(FC%g\*(FR and \*(FC%G\fP formats, the maximum + number of significant digits. + For the \*(FC%d\*(FR, \*(FC%o\*(FR, \*(FC%i\*(FR, \*(FC%u\*(FR, \*(FC%x\*(FR, and \*(FC%X\fP formats, the + minimum number of digits to print. + For the \*(FC%s\fP format, the maximum number of + characters to print +.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 file names may also be used on the command line to name data files. +The filenames are: +.sp .5 +.nf +\*(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 +.sp .5 +.fi +\*(CBThe following names are specific to \*(GK. +.sp .5 +.nf +\*(FC/dev/fd/\^\*(FIn\*(FR file associated with the open file descriptor \*(FIn\*(FR +.sp .5 +.fi +Other special filenames provide access to information about the running +\*(FCgawk\fP process. +The filenames are:\*(FR +.sp .5 +.nf +\*(FC/dev/pid\fP returns process ID of current process +\*(FC/dev/ppid\fP returns parent process ID of current process +\*(FC/dev/pgrpid\fP returns process group ID of current process +\*(FC/dev/user\fP returns 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). + Any additional fields are the group IDs returned + by \*(FIgetgroups\*(FR(2). Multiple groups may not be + supported on all systems +.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 +.nf +\*(CD\*(FCatan2(\*(FIy\*(FC, \*(FIx\*(FC)\*(FR returns 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 returns 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 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 +.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\*(FR'th 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 \*(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 on 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\*(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 +\*(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.ai.mit.edu\*(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\*(FR\s0" + + +.\" --- FTP Information +.ES +.nf +\*(CDHost: \*(FCftp.gnu.ai.mit.edu\*(FR +File: \*(FC/pub/gnu/gawk-3.0.1.tar.gz\fP + GNU \*(AK (\*(GK). There may be a later version +.sp .5 +Host: \*(FCnetlib.bell-labs.com\*(FR +File: \*(FC/netlib/research/awk.bundle.Z\fP + \*(NK. This version requires an ANSI C compiler; + GCC (the GNU C compiler) works well +.sp .5 +Host: \*(FCftp.whidbey.net\*(FR +File: \*(FC/pub/brennan/mawk1.3.3.tar.gz\fP + Michael Brennan's \*(MK. There may be a newer version\*(CX +.EB "\s+2\f(HBFTP INFORMATION\*(FR\s0" + +.\" --- Copying Permissions +.ES +.fi +\*(CDCopyright \(co 1996 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 |