diff options
Diffstat (limited to 'contrib/awk/doc/awkcard.in')
| -rw-r--r-- | contrib/awk/doc/awkcard.in | 1883 |
1 files changed, 0 insertions, 1883 deletions
diff --git a/contrib/awk/doc/awkcard.in b/contrib/awk/doc/awkcard.in deleted file mode 100644 index 43f73fb..0000000 --- a/contrib/awk/doc/awkcard.in +++ /dev/null @@ -1,1883 +0,0 @@ -.\" AWK Reference Card --- Arnold Robbins, arnold@gnu.org -.\" -.\" Copyright (C) 1996-2001 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 -\*(FRAction Statements 7 -Arrays 11 -Awk Program Execution 4 -Bit Manipulation Functions (\*(GK) 16 -Bug Reports 2 -Closing Redirections 12 -Command Line Arguments (standard) 2 -Command Line Arguments (\*(GK) 3 -Command Line Arguments (\*(MK) 4 -Conversions And Comparisons 9 -Copying Permissions 18 -Definitions 2 -Dynamic Extensions (\*(GK) 18 -Environment Variables (\*(GK) 18 -Escape Sequences 8 -Expressions 11 -Fields 6 -FTP/HTTP Information 18 -Historical Features (\*(GK) 18 -Input Control 12 -Internationalization (\*(GK) 16 -Lines And Statements 5 -Localization (\*(GK) 17 -Numeric Functions 14 -Output Control 12 -Pattern Elements 7 -POSIX Character Classes (\*(GK) 6 -Printf Formats 13 -Records 6 -Regular Expressions 5 -Special Filenames 14 -String Functions 15 -Time Functions (\*(GK) 16 -User-defined Functions 17 -Variables 8\*(CX -.in -.2i -.EB "\s+2\f(HBCONTENTS\*(FR\s0" -.sp .4 -.TD -.fi -\*(CD\*(FRArnold Robbins wrote this reference card. -We thank -Brian Kernighan and Michael Brennan who reviewed it. -.sp .4 -.SL -.sp .4 -.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-2001, 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 for emphasis, 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. -\*(CBNumbers may also be given in octal or hexadecimal: e.g., -\*(FC011\*(FR or \*(FC0x11\*(FR.\*(CD -.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" - -.\" --- Bug Reports -.ES -.fi -\*(CDIf you find a bug in this reference card, please report it via electronic -mail to \*(FCbug-gawk@gnu.org\*(FR.\*(CX -.EB "\s+2\f(HBBUG REPORTS\*(FR\s0" - -.BT - -.\" -.\" -.\" --- Command Line Arguments (gawk) -.ES -.fi -\*(CDThe following options are specific to \*(GK. -You may also use ``\*(FC\-W \*(FIoption\*(FR'' -for full POSIX compliance. -Long options may abbreviated as long as the abbreviation -remains unique. -.sp .5 -.ig -.\" This option is left undocumented, on purpose. -\*(FC\-\^\-nostalgia\*(FR%T{ -provide a moment of nostalgia for -long time \*(AK users. -T} -.. -.TS -expand, tab(%); -l lw(1.3i). -\*(FC\-\^\-assign \*(FIvar\*(FC\^=\^\*(FIval\*(FR%just like \*(FC\-v\fP. -\*(FC\-\^\-field-separator \*(FIfs\*(FR%just like \*(FC\-F\fP. -\*(FC\-\^\-file \*(FIprog-file%\*(FRjust like \*(FC\-f\fP. -.TE -.TS -expand, tab(%); -ls -l lw(2.2i). -\*(FC\-\^\-compat\*(FR, \*(FC\-\^\-traditional\*(FR -%T{ -disable \*(GK-specific extensions -(the use of \*(FC\-\^\-traditional\*(FR is preferred). -T} -.T& -ls -l lw(2.2i). -\*(FC\-\^\-copyleft\*(FR, \*(FC\-\^\-copyright\*(FR -%T{ -print the short version of the GNU -copyright information on \*(FCstdout\*(FR. -T} -.T& -ls -l lw(2.2i). -\*(FC\-\^\-dump-variables\*(FR[\*(FC=\*(FIfile\*(FR] -%T{ -Print a sorted list of global variables, -their types and final values to -\*(FIfile\*(FR. -If no \*(FIfile\*(FR -is provided, \*(FCgawk\*(FR -uses \*(FCawkvars.out\*(FR. -T} -\*(FC\-\^\-gen\-po\*(FR%T{ -process the program and print a GNU \*(FCgettext\*(FR -format \*(FC\&.po\*(FR format file on standard output, -containing the text of all strings that were marked -for localization. -T} -.T& -ls -l lw(2.2i). -\*(FC\-\^\-help\*(FR, \*(FC\-\^\-usage\*(FR -%T{ -print a short summary of the available -options on \*(FCstdout\*(FR, then exit zero. -T} -.T& -ls -l lw(2.2i). -\*(FC\-\^\-lint\*(FR[\*(FC=fatal\*(FR] -%T{ -warn about constructs that are dubious -or non-portable to other \*(AKs. -With an optional argument of \*(FCfatal\*(FR, -lint warnings become fatal errors. -T} -.T& -l lw(2.2i). -\*(FC\-\^\-lint\-old\*(FR%T{ -warn about constructs that are not -portable to the original version of -Unix \*(AK. -T} -.T& -ls -l lw(2.2i). -\*(FC\-\^\-non\-decimal\-data\*(FR -%T{ -recognize octal and hexadecimal values in input data. -\*(FIUse this option with great caution!\*(FR -T} -.T& -l lw(2.2i). -\*(FC\-\^\-posix\*(FR%T{ -disable common and GNU extensions. -Enable \*(FIinterval expressions\*(FR in regular -expression matching (see \fHRegular -Expressions\fP below). -T} -.T& -ls -l lw(2.2i). -\*(FC\-\^\-profile\*(FR[\*(FC=\*(FIprof_file\*(FR] -%T{ -send profiling data to \*(FIprof_file\*(FR -(default: \*(FCawkprof.out\*(FR). -With \*(FIgawk\*(FR, -the profile is just a ``pretty printed'' version of the program. -With \*(FIpgawk\*(FR, -the profile contains execution counts in the left margin -of each statement in the program. -T} -.T& -ls -l lw(2.2i). -\*(FC\-\^\-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} -.T& -ls -l lw(2.2i). -\*(FC\-\^\-source '\*(FItext\*(FC'\*(FR -%use \*(FItext\*(FR as AWK program source code. -\*(FC\-\^\-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 invalid, 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. -.sp .5 -\*(FIpgawk\fP accepts two signals. -\*(FCSIGUSR1\fP causes it to dump a profile and function call stack to the -profile file. It then continues to run. -\*(FCSIGHUP\fP -causes it to dump the profile and function call stack and then exit.\*(CB -.EB "\s+2\f(HBCOMMAND LINE ARGUMENTS (\*(GK\f(HB)\*(FR\s0" - -.BT - -.\" -.\" -.\" --- Command Line Arguments (mawk) -.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 is -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 is 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 string -\*(FC\e'\*(FR~end of a 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 character 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 -.TE -.fi -.sp .5 -Recognition of these character classes is disabled -when \*(FC\-\-traditional\*(FR is supplied.\*(CB -.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 separates the record. -\*(CB\*(GK sets \*(FCRT\*(FR to the value of the -input text that matched the regular expression. -The value of \*(FCIGNORECASE\fP -also affects 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 -also affects 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 -splits 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) increases the value of -\*(FCNF\*(FR, creates any intervening fields with the null string as their value, -and causes 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 -.fi -.in +.2i -.ti -.2i -\*(CD\*(FCbreak\*(FR -.br -break out of the nearest enclosing \*(FCdo\*(FR, \*(FCfor\*(FR, -or \*(FCwhile\*(FR loop. -.ti -.2i -\*(FCcontinue\*(FR -.br -skip the rest of the loop body. -Evaluate the \*(FIcondition\*(FR -part of the nearest enclosing \*(FCdo\*(FR or \*(FCwhile\*(FR loop, -or go to the \*(FIincr\*(FR part of a \*(FCfor\*(FR loop. -.ti -.2i -\*(FCdelete \*(FIarray\^\*(FC[\^\*(FIindex\^\*(FC]\*(FR -.br -delete element \*(FIindex\*(FR from array \*(FIarray\*(FR. -.ti -.2i -\*(CL\*(FCdelete \*(FIarray\^\*(FR -.br -delete all elements from array \*(FIarray\*(FR.\*(CD -.ti -.2i -\*(FCdo \*(FIstatement \*(FCwhile (\*(FIcondition\*(FC)\*(FR -.br -execute \*(FIstatement\*(FR while \*(FIcondition\*(FR is true. -The \*(FIstatement\*(FR is always executed at least once. -.ti -.2i -\*(FCexit\*(FR [ \*(FIexpression\*(FR ] -.br -terminate input record processing. -Execute the \*(FCEND\*(FR rule(s) if present. -If present, \*(FIexpression\*(FR becomes \*(AK's return value. -.ti -.2i -\*(FCfor (\*(FIinit\*(FC; \*(FIcond\*(FC; \*(FIincr\*(FC) \*(FIstatement\*(FR -.br -execute \*(FIinit\*(FR. -Evaluate \*(FIcond\*(FR. -If it is true, execute \*(FIstatement\*(FR. -Execute \*(FIincr\*(FR before going back to the top to -re-evaluate \*(FIcond\*(FR. -Any of the three may be omitted. -A missing \*(FIcond\*(FR is considered to be true. -.ti -.2i -\*(FCfor (\*(FIvar \*(FCin\*(FI array\*(FC) \*(FIstatement\*(FR -.br -execute \*(FIstatement\*(FR once for each subscript in \*(FIarray\*(FR, -with \*(FIvar\*(FR set to a different subscript each time through -the loop. -.ti -.2i -\*(CD\*(FCif (\*(FIcondition\*(FC) \*(FIstatement1\*(FR [ \*(FCelse\*(FI statement2\*(FR ] -.br -if \*(FIcondition\*(FR is true, execute \*(FIstatement1\*(FR, -otherwise execute \*(FIstatement2\*(FR. Each \*(FCelse\*(FR -matches the closest \*(FCif\*(FR. -.ti -.2i -\*(FCnext\*(FR see \fHInput Control.\fP -.ti -.2i -\*(CL\*(FCnextfile\*(FR \*(CR(not \*(MK) \*(CLsee \fHInput Control.\fP\*(CD -.ti -.2i -\*(FCwhile (\*(FIcondition\*(FC) \*(FIstatement \*(FR -.br -while \*(FIcondition\*(FR is true, execute \*(FIstatement\*(FR. -.ti -.2i -\*(FC{ \*(FIstatements \*(FC}\*(FR -.br -a list of statements enclosed in braces can be used anywhere -that a single statement would otherwise be used.\*(CX -.in -.2i -.EB "\s+2\f(HBACTION STATEMENTS\*(FR\s0" - - -.BT - -.\" --- 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" -.sp .7 -.\" --- Variables -.ES -.fi -.TS -expand; -l lw(2i). -\*(CD\*(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} -\*(CL\*(FCBINMODE\fP T{ -controls ``binary'' mode for all file I/O. Values of 1, 2, or 3, -indicate input, output, or all files, respectively, should use binary -I/O. \*(CR(Not \*(NK.) \*(CLApplies only to non-POSIX systems. -\*(CBFor \*(GK, string values of \*(FC"r"\fP, or \*(FC"w"\fP specify -that input files, or output files, respectively, should use binary I/O. -String values of \*(FC"rw"\fP or \*(FC"wr"\fP specify that all files -should use binary I/O. Any other string value is treated as \*(FC"rw"\fP, -but generates a warning message.\*(CD -T} -\*(FCCONVFMT\fP T{ -conversion format for numbers, default value -is \*(FC"%.6g"\*(FR. -T} -\*(FCENVIRON\fP T{ -array containing the current environment. -The array is indexed by the environment -variables, each element being the value of -that variable. -T} -\*(CB\*(FCERRNO\fP T{ -string describing the error if a -\*(FCgetline\*(FR -redirection or read -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{ -record number 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. -Array subscripting and \*(FCasort()\*(FR are \*(FInot\*(FR affected. -T} -\*(CB\*(FCLINT\fP T{ -provides dynamic control of the \*(FC\-\^\-lint\fP -option from within an AWK program. -When true, \*(GK -prints lint warnings. -When assigned the string value \*(FC"fatal"\*(FR, -lint warnings become fatal errors, exactly like -\*(FC\-\-lint=fatal\*(FR. -Any other true value just prints warnings.\*(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 used this for number -to string conversion.\*(CX -T} -.TE -.EB "\s+2\f(HBVARIABLES\*(FR\s0" -.BT - -.\" --- Variables (continued) -.ES -.fi -.TS -expand; -l lw(2i). -\*(CD\*(FCOFS\fP T{ -output field separator, a space by default. -T} -\*(FCORS\fP T{ -output record separator, a newline by default. -T} -\*(CB\*(FCPROCINFO\fP T{ -elements of this array provide access to info -about the running AWK program. See -\*(AM for details.\*(CD -T} -\*(FCRLENGTH\fP T{ -length of the string matched by \*(FCmatch()\*(FR; -\-1 if no match. -T} -\*(FCRS\fP T{ -input record separator, a newline by default -(see \fHRecords\fP above). -T} -\*(FCRSTART\fP T{ -index of the first character matched by -\*(FCmatch()\*(FR; 0 if no match. -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} -\*(FCSUBSEP\fP T{ -character(s) used to separate multiple subscripts -in array elements, by default \*(FC"\e034"\*(FR. (See -\fHArrays\fP below). -T} -\*(CB\*(FCTEXTDOMAIN\fP T{ -the application's text domain for internationalization; -used to find the localized -translations for the program's strings.\*(CX -T} -.TE -.EB "\s+2\f(HBVARIABLES (continued)\*(FR\s0" - -.\" --- 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 \*(FIstrtod\*(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. -.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. -\*(CRNote that the POSIX standard applies the concept of -``numeric string'' everywhere, even to string constants. -However, this is -clearly incorrect, and none of the three free \*(AK\*(FRs do this.\*(CD -(Fortunately, this is fixed in the next version of the standard.) -.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" - -.BT - -.ES -\*(CX -.sp 61 -.EB "\s+2\f(HBNOTES\*(FR\s0" - -.BT - -.\" --- Arrays -.ES -.fi -\*(CDAn array subscript is an expression between square brackets -(\*(FC[ \*(FRand \*(FC]\*(FR). -If the expression is a list -(\*(FIexpr\*(FC, \*(FIexpr \*(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 - -.\" --- Input Control -.ES -.fi -.TS -expand; -l lw(1.8i). -\*(FCgetline\fP T{ -set \*(FC$0\fP from next 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. -\*(CB\*(FIcmd \*(FC|& getline\*(FR co-process pipe into \*(FCgetline\*(FR; set \*(FC$0\*(FR, \*(FCNF\*(FR. -.TE -.fi -.in +.2i -.ti -.2i -\*(FIcmd \*(FC|& getline \*(FIv\*(FR -.br -co-process pipe into \*(FCgetline\*(FR; set \*(FIv\*(FR. -.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 usage is no longer supported. -\*(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. -\*(CBUpon an error, \*(FCERRNO\*(FR contains a string describing -the problem.\*(CX -.EB "\s+2\f(HBINPUT CONTROL\*(FR\s0" - -.\" --- Output Control -.ES -.fi -.in +.2i -.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 no \*(FIfile\fP, then flush standard output. -If \*(FIfile\fP is null, then flush all open output files and pipes -\*(CR(not \*(NK)\*(CD. -.ti -.2i -\*(FCprint\fP -.br -print the current record. Terminate output record -with \*(FCORS\fP. -.ti -.2i -\*(FCprint \*(FIexpr-list\*(FR -.br -print expressions. Each expression is separated -by the value of \*(FCOFS\fP. Terminate the output record -with \*(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 -is truncated. Subsequent commands append data. -.ti -.2i -\*(FCprint "hello" >> \*(FIfile\*(FR -.br -append data to \*(FIfile\fP. The previous contents of \*(FIfile\*(FR are not lost. -.ti -.2i -\*(FCprint "hello" | \*(FIcmd\*(FR -.br -print data down a pipeline to \*(FIcmd\*(FR. -.ti -.2i -\*(CB\*(FCprint "hello" |& \*(FIcmd\*(FR -.br -print data down a pipeline to co-process \*(FIcmd\*(FR.\*(CX -.in -.2i -.EB "\s+2\f(HBOUTPUT CONTROL\*(FR\s0" - -.ES -.fi -.in +.2i -.ti -.2i -\*(CD\*(FCclose(\*(FIfile\*(FC)\*(FR -.br -close input or output file, pipe \*(CBor co-process.\*(CD -.ti -.2i -\*(CB\*(FCclose(\*(FIcommand\*(FC, \*(FIhow\*(FC)\*(FR -.br -close one end of co-process pipe. -Use \*(FC"to"\*(FR for the write end, or -\*(FC"from"\*(FR for the read end.\*(CD -.in -.2i -.sp .5 -On success, \*(FCclose()\*(FR returns zero for a file, or the exit status for a process. -It returns \-1 if \*(FIfile\*(FR -was never opened, or -if there was a system problem. -\*(CB\*(FCERRNO\*(FR describes -the error.\*(CX -.EB "\s+2\f(HBCLOSING REDIRECTIONS\*(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). -\*(CB\*(FIcount\*(FC$\*(FR T{ -use the -\*(FIcount\*(FR'th -argument at this point in the formatting -(a \*(FIpositional specifier\*(FR). -Use in translated versions of -format strings, not in the original text of an AWK program.\*(CD -T} -\*(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 zeros 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 zeros. -T} -\*(FC.\*(FIprec\*(FR T{ -precision. -The meaning of the \*(FIprec\*(FR 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 causes their values to be taken from -the argument list to \*(FCprintf\fP or \*(FCsprintf()\*(FR. -\*(CBUse \*(FC*\*(FIn\*(FC$\*(FR to use positional specifiers -with a dynamic width or precision.\*(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 -.in +.2i -.ti -.2i -\*(FC/dev/fd/\^\*(FIn\*(FR -.br -File associated with the open file descriptor \*(FIn\*(FR. -.ti -.2i -\*(FC/inet/tcp/\*(FIlport\*(FC/\*(FIrhost\*(FC/\*(FIrport\*(FR -.br -File for TCP/IP connection on local port \*(FIlport\*(FR to -remote host \*(FIrhost\*(FR on remote port \*(FIrport\*(FR. -Use a port of \*(FC0\*(FR to have the system pick a port. -Usable only with the \*(FC|&\*(FR two-way I/O operator. -.ti -.2i -\*(FC/inet/udp/\*(FIlport\*(FC/\*(FIrhost\*(FC/\*(FIrport\*(FR -.br -Similar, but use UDP/IP instead of TCP/IP. -.ti -.2i -\*(CR\*(FC/inet/raw/\*(FIlport\*(FC/\*(FIrhost\*(FC/\*(FIrport\*(FR -.br -.\" Similar, but use raw IP sockets. -Reserved for future use.\*(CB -.in -.2i -.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 -\*(CRThese filenames are now obsolete. -Use the \*(FCPROCINFO\fP array to obtain the information they provide.\*(CL -.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\*(FCasort(\*(FIs\*(FC \*(FR[\*(FC, \*(FId\*(FR]\*(FC)\*(FR -.br -sorts the source array \*(FIs\*(FR, replacing the indices with numeric -values 1 through \*(FIn\*(FR (the number of elements in the array), -and returns the number of elements. -If destination \*(FId\*(FR is supplied, \*(FIs\*(FR is copied to \*(FId\*(FR, -\*(FId\*(FR is sorted, and \*(FIs\*(FR is unchanged.\*(CD -.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 \*(FIt\fP is not 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 \*(CB\*(FR[\*(FC, \*(FIa\*(FR]\*(CD\*(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. -\*(CBIf \*(FIa\*(FR is supplied, the text matching all of \*(FIr\*(FR -is placed in \*(FIa\*(FC[0]\*(FR. If there were parenthesized -subexpressions, the matching texts are placed -in \*(FIa\*(FC[1]\*(FR, \*(FIa\*(FC[2]\*(FR, and so on.\*(CD -.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 -\*(CB\*(FCstrtonum(\*(FIs\*(FC)\*(FR -.br -examines \*(FIs\*(FR, and returns its numeric value. -If \*(FIs\*(FR begins with a leading \*(FC0\*(FR, -\*(FCstrtonum()\*(FR assumes that \*(FIs\*(FR -is an octal number. -If \*(FIs\*(FR begins with a leading \*(FC0x\*(FR -or \*(FC0X\*(FR, \*(FCstrtonum()\*(FR assumes that -\*(FIs\*(FR is a hexadecimal number.\*(CD -.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.\*(CX -.in -.2i -.EB "\s+2\f(HBSTRING FUNCTIONS\*(FR\s0" - -.BT - -.\" --- Builtin String Functions -.ES -.fi -.in +.2i -.ti -.2i -\*(CD\*(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 (continued)\*(FR\s0" - -.\" --- Builtin Time Functions -.ES -.fi -\*(CD\*(GK -provides the following functions for obtaining time stamps and -formatting them. -.sp .5 -.fi -.in +.2i -.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[ DST]\*(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) is 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" - -.\" --- Builtin Bit Manipulation Functions -.ES -.fi -\*(CD\*(GK -provides the following functions for doing bitwise operations. -.sp .5 -.fi -.in +.2i -.ti -.2i -\*(FCand(\*(FIv1\*(FC, \*(FIv2\*(FC)\*(FR -.br -returns the bitwise AND of the values provided by -\*(FIv1\*(FR and \*(FIv2\*(FR. -.ti -.2i -\*(FCcompl(\*(FIval\*(FC)\*(FR -.br -returns the bitwise complement of -\*(FIval\*(FR. -.ti -.2i -\*(FClshift(\*(FIval\*(FC, \*(FIcount\*(FC)\*(FR -.br -returns the value of \*(FIval\*(FR, -shifted left by \*(FIcount\*(FR bits. -.ti -.2i -\*(FCor(\*(FIv1\*(FC, \*(FIv2\*(FC)\*(FR -.br -returns the bitwise OR of the values provided by -\*(FIv1\*(FR and \*(FIv2\*(FR. -.ti -.2i -\*(FCrshift(\*(FIval\*(FC, \*(FIcount\*(FC)\*(FR -.br -returns the value of \*(FIval\*(FR, -shifted right by \*(FIcount\*(FR bits. -.ti -.2i -\*(FCxor(\*(FIv1\*(FC, \*(FIv2\*(FC)\*(FR -.br -teturns the bitwise XOR of the values provided by -\*(FIv1\*(FR and \*(FIv2\*(FR.\*(CB -.in -.2i -.EB "\s+2\f(HBBIT MANIPULATION FUNCTIONS (\*(GK\f(HB)\*(FR\s0" - -.\" --- Builtin Internationalizatin Functions -.ES -.fi -\*(CD\*(GK -provides the following functions for runtime message translation. -.in +.2i -.sp .5 -.ti -.2i -\*(FCbindtextdomain(\*(FIdirectory \*(FR[\*(FC, \*(FIdomain\*(FR]\*(FC)\*(FR -.br -specifies the directory where \*(GK looks for the \*(FC\&.mo\*(FR -files, in case they -will not or cannot be placed in the ``standard'' locations -(e.g., during testing.) -It returns the directory where \*(FIdomain\*(FR is ``bound.'' -.sp .5 -The default \*(FIdomain\*(FR is the value of \*(FCTEXTDOMAIN\*(FR. -When \*(FIdirectory\*(FR is the null string (\*(FC"\^"\*(FR), -\*(FCbindtextdomain()\*(FR returns the current binding for the -given \*(FIdomain\*(FR. -.ti -.2i -\*(FCdcgettext(\*(FIstring \*(FR[\*(FC, \*(FIdomain \*(FR[\*(FC, \*(FIcategory\*(FR]]\*(FC)\*(FR -.br -returns the translation of \*(FIstring\*(FR in text domain -\*(FIdomain\*(FR for locale category \*(FIcategory\*(FR. -The default value for \*(FIdomain\*(FR is the current value of \*(FCTEXTDOMAIN\*(FR. -The default value for \*(FIcategory\*(FR is \*(FC"LC_MESSAGES"\*(FR. -.sp .5 -If you supply a value for \*(FIcategory\*(FR, it must be a string equal to -one of the known locale categories. -You must also supply a text domain. Use \*(FCTEXTDOMAIN\*(FR -to use the current domain.\*(CB -.in -.2i -.EB "\s+2\f(HBINTERNATIONALIZATION (\*(GK\f(HB)\*(FR\s0" - -.BT - -.\" --- 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 and 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" - -.\" --- Localization -.ES -.fi -\*(CDThere are several steps involved in producing and running a localizable -\*(AK program. -.sp .5 -1. Add a \*(FCBEGIN\*(FR action to assign a value to the -\*(FCTEXTDOMAIN\*(FR variable to set the text domain for -your program. -.sp .5 -.ti +5n -\*(FCBEGIN { TEXTDOMAIN = "myprog" }\*(FR -.sp .5 -This allows \*(GK to find the \*(FC\&.mo\*(FR -file associated with your program. -Without this step, \*(GK uses the \*(FCmessages\*(FR text domain, -which probably won't work. -.sp .5 -2. Mark all strings that should be translated with leading underscores. -.sp .5 -3. Use the \*(FCdcgettext()\*(FR -and/or \*(FCbindtextdomain()\*(FR -functions in your program, as necessary or appropriate. -.sp .5 -4. Run -.sp .5 -.ti +5n -\*(FCgawk \-\^\-gen\-po \-f myprog.awk > myprog.po\*(FR -.sp .5 -to generate a \*(FC\&.po\*(FR -file for your program. -.sp .5 -5. Provide appropriate translations, and build and install a corresponding -\*(FC\&.mo\*(FR file. -.sp .5 -The internationalization features are described in full detail in \*(AM.\*(CB -.EB "\s+2\f(HBLOCALIZATION (\*(GK\f(HB)\*(FR\s0" - - -.BT - -.\" --- Extensions -.ES -.fi -.in +.2i -.ti -.2i -\*(CD\*(FCextension(\*(FIlib\*(FC, \*(FIfunc\*(FC)\*(FR -.br -dynamically load the shared library -\*(FIlib\*(FR -and call -\*(FIfunc\*(FR -in it to initialize the library. -This adds new built-in functions to \*(GK. -It returns the value returned by -\*(FIfunc\*(FR.\*(CB -.in -.2i -.EB "\s+2\f(HBDYNAMIC EXTENSIONS (\*(GK\f(HB)\*(FR\s0" - -.\" --- 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 -issues 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 supports this usage if \*(FC\-\^\-traditional\fP -is 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.1.0.tar.gz\fP -.in +.2i -.fi -GNU \*(AK (\*(GK). There may be a later version. -.in -.2i -.nf -.sp .5 -\*(FChttp://cm.bell-labs.com/who/bwk/awk.tar.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/HTTP INFORMATION\*(FR\s0" - -.\" --- Copying Permissions -.ES -.fi -\*(CDCopyright \(co 1996-2001 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 |
