diff options
Diffstat (limited to 'usr/src/man/man1/oawk.1')
| -rw-r--r-- | usr/src/man/man1/oawk.1 | 597 |
1 files changed, 597 insertions, 0 deletions
diff --git a/usr/src/man/man1/oawk.1 b/usr/src/man/man1/oawk.1 new file mode 100644 index 0000000000..da7626418c --- /dev/null +++ b/usr/src/man/man1/oawk.1 @@ -0,0 +1,597 @@ +.\" +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for +.\" permission to reproduce portions of its copyrighted documentation. +.\" Original documentation from The Open Group can be obtained online at +.\" http://www.opengroup.org/bookstore/. +.\" +.\" The Institute of Electrical and Electronics Engineers and The Open +.\" Group, have given us permission to reprint portions of their +.\" documentation. +.\" +.\" In the following statement, the phrase ``this text'' refers to portions +.\" of the system documentation. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition, +.\" Standard for Information Technology -- Portable Operating System +.\" Interface (POSIX), The Open Group Base Specifications Issue 6, +.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics +.\" Engineers, Inc and The Open Group. In the event of any discrepancy +.\" between these versions and the original IEEE and The Open Group +.\" Standard, the original IEEE and The Open Group Standard is the referee +.\" document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.\" This notice shall appear on any product containing this material. +.\" +.\" The contents of this file are subject to the terms of the +.\" Common Development and Distribution License (the "License"). +.\" You may not use this file except in compliance with the License. +.\" +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE +.\" or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions +.\" and limitations under the License. +.\" +.\" When distributing Covered Code, include this CDDL HEADER in each +.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. +.\" If applicable, add the following below this CDDL HEADER, with the +.\" fields enclosed by brackets "[]" replaced with your own identifying +.\" information: Portions Copyright [yyyy] [name of copyright owner] +.\" +.\" +.\" Copyright 1989 AT&T +.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright 2020 Joyent, Inc. +.\" +.TH OAWK 1 "Apr 20, 2020" +.SH NAME +oawk \- (older) pattern scanning and processing language +.SH SYNOPSIS +.nf +\fB/usr/bin/oawk\fR [\fB-f\fR \fIprogfile\fR] [\fB-F\fIc\fR\fR] [' \fIprog\fR '] [\fIparameters\fR] + [\fIfilename\fR]... +.fi + +.SH DESCRIPTION +This command is now obsolete, and will be removed from illumos at some point. +.sp +.LP +The \fB/usr/bin/oawk\fR utility scans each input \fIfilename\fR for lines that +match any of a set of patterns specified in \fIprog\fR. The \fIprog\fR string +must be enclosed in single quotes (\fB a\'\fR) to protect it from the shell. +For each pattern in \fIprog\fR there can be an associated action performed when +a line of a \fIfilename\fR matches the pattern. The set of pattern-action +statements can appear literally as \fIprog\fR or in a file specified with the +\fB-f\fR\fI progfile\fR option. Input files are read in order; if there are no +files, the standard input is read. The file name \fB\&'\(mi'\fR means the +standard input. +.SH OPTIONS +The following options are supported: +.sp +.ne 2 +.na +\fB\fB-f\fR\fI progfile\fR \fR +.ad +.RS 16n +\fBoawk\fR uses the set of patterns it reads from \fIprogfile\fR. +.RE + +.sp +.ne 2 +.na +\fB\fB-F\fR\fIc\fR \fR +.ad +.RS 16n +Uses the character \fIc\fR as the field separator (FS) character. See the +discussion of \fBFS\fR below. +.RE + +.SH USAGE +.SS "Input Lines" +Each input line is matched against the pattern portion of every pattern-action +statement; the associated action is performed for each matched pattern. Any +\fIfilename\fR of the form \fIvar=value\fR is treated as an assignment, not a +filename, and is executed at the time it would have been opened if it were a +filename. \fIVariables\fR assigned in this manner are not available inside a +\fBBEGIN\fR rule, and are assigned after previously specified files have been +read. +.sp +.LP +An input line is normally made up of fields separated by white spaces. (This +default can be changed by using the \fBFS\fR built-in variable or the +\fB-F\fR\fIc\fR option.) The default is to ignore leading blanks and to +separate fields by blanks and/or tab characters. However, if \fBFS\fR is +assigned a value that does not include any of the white spaces, then leading +blanks are not ignored. The fields are denoted \fB$1\fR, \fB$2\fR, +\fB\&.\|.\|.\fR\|; \fB$0\fR refers to the entire line. +.SS "Pattern-action Statements" +A pattern-action statement has the form: +.sp +.in +2 +.nf +\fIpattern\fR\fB { \fR\fIaction\fR\fB } \fR +.fi +.in -2 +.sp + +.sp +.LP +Either pattern or action can be omitted. If there is no action, the matching +line is printed. If there is no pattern, the action is performed on every input +line. Pattern-action statements are separated by newlines or semicolons. +.sp +.LP +Patterns are arbitrary Boolean combinations ( \fB!\fR, ||, \fB&&\fR, and +parentheses) of relational expressions and regular expressions. A relational +expression is one of the following: +.sp +.in +2 +.nf +\fIexpression relop expression +expression matchop regular_expression\fR +.fi +.in -2 + +.sp +.LP +where a \fIrelop\fR is any of the six relational operators in C, and a +\fImatchop\fR is either \fB~\fR (contains) or \fB!~\fR (does not contain). An +\fIexpression\fR is an arithmetic expression, a relational expression, the +special expression +.sp +.in +2 +.nf +\fIvar \fRin \fIarray\fR +.fi +.in -2 + +.sp +.LP +or a Boolean combination of these. +.sp +.LP +Regular expressions are as in \fBegrep\fR(1). In patterns they must be +surrounded by slashes. Isolated regular expressions in a pattern apply to the +entire line. Regular expressions can also occur in relational expressions. A +pattern can consist of two patterns separated by a comma; in this case, the +action is performed for all lines between the occurrence of the first pattern +to the occurrence of the second pattern. +.sp +.LP +The special patterns \fBBEGIN\fR and \fBEND\fR can be used to capture control +before the first input line has been read and after the last input line has +been read respectively. These keywords do not combine with any other patterns. +.SS "Built-in Variables" +Built-in variables include: +.sp +.ne 2 +.na +\fB\fBFILENAME\fR \fR +.ad +.RS 13n +name of the current input file +.RE + +.sp +.ne 2 +.na +\fB\fBFS\fR \fR +.ad +.RS 13n +input field separator regular expression (default blank and tab) +.RE + +.sp +.ne 2 +.na +\fB\fBNF\fR \fR +.ad +.RS 13n +number of fields in the current record +.RE + +.sp +.ne 2 +.na +\fB\fBNR\fR \fR +.ad +.RS 13n +ordinal number of the current record +.RE + +.sp +.ne 2 +.na +\fB\fBOFMT\fR \fR +.ad +.RS 13n +output format for numbers (default \fB%.6g\fR) +.RE + +.sp +.ne 2 +.na +\fB\fBOFS\fR \fR +.ad +.RS 13n +output field separator (default blank) +.RE + +.sp +.ne 2 +.na +\fB\fBORS\fR \fR +.ad +.RS 13n +output record separator (default new-line) +.RE + +.sp +.ne 2 +.na +\fB\fBRS\fR \fR +.ad +.RS 13n +input record separator (default new-line) +.RE + +.sp +.LP +An action is a sequence of statements. A statement can be one of the following: +.sp +.in +2 +.nf +if ( \fIexpression\fR ) \fIstatement\fR [ else \fIstatement\fR ] +while ( \fIexpression\fR ) \fIstatement\fR +do \fIstatement\fR while ( \fIexpression\fR ) +for ( \fIexpression\fR ; \fIexpression\fR ; \fIexpression\fR ) \fIstatement\fR +for ( \fIvar\fR in \fIarray\fR ) \fIstatement\fR +break +continue +{ [ \fIstatement\fR ] .\|.\|. } +\fIexpression\fR # commonly variable = expression +print [ \fIexpression-list\fR ] [ >\fIexpression\fR ] +printf format [ ,\fIexpression-list\fR ] [ >\fIexpression\fR ] +next # skip remaining patterns on this input line +exit [expr] # skip the rest of the input; exit status is expr +.fi +.in -2 + +.sp +.LP +Statements are terminated by semicolons, newlines, or right braces. An empty +expression-list stands for the whole input line. Expressions take on string or +numeric values as appropriate, and are built using the operators \fB+\fR, +\fB\(mi\fR, \fB*\fR, \fB/\fR, \fB%\fR, \fB^\fR and concatenation (indicated by +a blank). The operators \fB++\fR, \fB\(mi\(mi\fR, \fB+=\fR, \fB\(mi=\fR, +\fB*=\fR, \fB/=\fR, \fB%=\fR, \fB^=\fR, \fB>\fR, \fB>=\fR, \fB<\fR, \fB<=\fR, +\fB==\fR, \fB!=\fR, and \fB?:\fR are also available in expressions. Variables +can be scalars, array elements (denoted x[i]), or fields. Variables are +initialized to the null string or zero. Array subscripts can be any string, not +necessarily numeric; this allows for a form of associative memory. String +constants are quoted (\fB""\fR), with the usual C escapes recognized within. +.sp +.LP +The \fBprint\fR statement prints its arguments on the standard output, or on a +file if \fB>\fR\fIexpression\fR is present, or on a pipe if '\fB|\fR\fIcmd\fR' +is present. The output resulted from the print statement is terminated by the +output record separator with each argument separated by the current output +field separator. The \fBprintf\fR statement formats its expression list +according to the format (see \fBprintf\fR(3C)). +.SS "Built-in Functions" +The arithmetic functions are as follows: +.sp +.ne 2 +.na +\fB\fBexp\fR(\fIx\fR)\fR +.ad +.RS 11n +Return the exponential function of \fIx\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBlog\fR(\fIx\fR)\fR +.ad +.RS 11n +Return the natural logarithm of \fIx\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBsqrt\fR(\fIx\fR)\fR +.ad +.RS 11n +Return the square root of \fIx\fR. +.RE + +.sp +.ne 2 +.na +\fB\fBint\fR(\fIx\fR)\fR +.ad +.RS 11n +Truncate its argument to an integer. It is truncated toward \fB0\fR when +\fIx\fR >\fB 0\fR. +.RE + +.sp +.LP +The string functions are as follows: +.sp +.ne 2 +.na +\fB\fBindex(\fR\fIs\fR\fB, \fR\fIt\fR\fB)\fR\fR +.ad +.sp .6 +.RS 4n +Return the position in string \fIs\fR where string \fIt\fR first occurs, or +\fB0\fR if it does not occur at all. +.RE + +.sp +.ne 2 +.na +\fB\fBint(\fR\fIs\fR\fB)\fR\fR +.ad +.sp .6 +.RS 4n +truncates \fIs\fR to an integer value. If \fIs\fR is not specified, $0 is used. +.RE + +.sp +.ne 2 +.na +\fB\fBlength(\fR\fIs\fR\fB)\fR\fR +.ad +.sp .6 +.RS 4n +Return the length of its argument taken as a string, or of the whole line if +there is no argument. +.RE + +.sp +.ne 2 +.na +\fB\fBsplit(\fR\fIs\fR, \fIa\fR, \fIfs\fR\fB)\fR\fR +.ad +.sp .6 +.RS 4n +Split the string \fIs\fR into array elements \fIa\fR[\fI1\fR], +\fIa\fR[\fI2\fR], \|.\|.\|. \fIa\fR[\fIn\fR], and returns \fIn\fR. The +separation is done with the regular expression \fIfs\fR or with the field +separator \fBFS\fR if \fIfs\fR is not given. +.RE + +.sp +.ne 2 +.na +\fB\fBsprintf(\fR\fIfmt\fR, \fIexpr\fR, \fIexpr\fR,\|.\|.\|.\|\fB)\fR\fR +.ad +.sp .6 +.RS 4n +Format the expressions according to the \fBprintf\fR(3C) format given by +\fIfmt\fR and returns the resulting string. +.RE + +.sp +.ne 2 +.na +\fB\fBsubstr(\fR\fIs\fR, \fIm\fR, \fIn\fR\fB)\fR\fR +.ad +.sp .6 +.RS 4n +returns the \fIn\fR-character substring of \fIs\fR that begins at position +\fIm\fR. +.RE + +.sp +.LP +The input/output function is as follows: +.sp +.ne 2 +.na +\fB\fBgetline\fR\fR +.ad +.RS 11n +Set \fB$0\fR to the next input record from the current input file. +\fBgetline\fR returns \fB1\fR for successful input, \fB0\fR for end of file, +and \fB\(mi1\fR for an error. +.RE + +.SS "Large File Behavior" +See \fBlargefile\fR(5) for the description of the behavior of \fBoawk\fR when +encountering files greater than or equal to 2 Gbyte ( 2^31 bytes). +.SH EXAMPLES +\fBExample 1 \fRPrinting Lines Longer Than 72 Characters +.sp +.LP +The following example is an \fBoawk\fR script that can be executed by an +\fBoawk -f examplescript\fR style command. It prints lines longer than +seventy two characters: + +.sp +.in +2 +.nf +\fBlength > 72\fR +.fi +.in -2 +.sp + +.LP +\fBExample 2 \fRPrinting Fields in Opposite Order +.sp +.LP +The following example is an \fBoawk\fR script that can be executed by an +\fBoawk -f examplescript\fR style command. It prints the first two fields in +opposite order: + +.sp +.in +2 +.nf +\fB{ print $2, $1 }\fR +.fi +.in -2 +.sp + +.LP +\fBExample 3 \fRPrinting Fields in Opposite Order with the Input Fields +Separated +.sp +.LP +The following example is an \fBoawk\fR script that can be executed by an +\fBoawk -f examplescript\fR style command. It prints the first two input +fields in opposite order, separated by a comma, blanks or tabs: + +.sp +.in +2 +.nf +\fBBEGIN { FS = ",[ \et]*|[ \et]+" } + { print $2, $1 }\fR +.fi +.in -2 +.sp + +.LP +\fBExample 4 \fRAdding Up the First Column, Printing the Sum and Average +.sp +.LP +The following example is an \fBoawk\fR script that can be executed by an +\fBoawk -f examplescript\fR style command. It adds up the first column, and +prints the sum and average: + +.sp +.in +2 +.nf +\fB{ s += $1 } +END { print "sum is", s, " average is", s/NR }\fR +.fi +.in -2 +.sp + +.LP +\fBExample 5 \fRPrinting Fields in Reverse Order +.sp +.LP +The following example is an \fBoawk\fR script that can be executed by an +\fBoawk -f examplescript\fR style command. It prints fields in reverse order: + +.sp +.in +2 +.nf +\fB{ for (i = NF; i > 0; \(mi\(mii) print $i }\fR +.fi +.in -2 +.sp + +.LP +\fBExample 6 \fRPrinting All lines Between \fBstart/stop\fR Pairs +.sp +.LP +The following example is an \fBoawk\fR script that can be executed by an +\fBoawk -f examplescript\fR style command. It prints all lines between +start/stop pairs. + +.sp +.in +2 +.nf +\fB/start/, /stop/\fR +.fi +.in -2 +.sp + +.LP +\fBExample 7 \fRPrinting All Lines Whose First Field is Different from the +Previous One +.sp +.LP +The following example is an \fBoawk\fR script that can be executed by an +\fBoawk -f examplescript\fR style command. It prints all lines whose first +field is different from the previous one. + +.sp +.in +2 +.nf +\fB$1 != prev { print; prev = $1 }\fR +.fi +.in -2 +.sp + +.LP +\fBExample 8 \fRPrinting a File and Filling in Page numbers +.sp +.LP +The following example is an \fBoawk\fR script that can be executed by an +\fBoawk -f examplescript\fR style command. It prints a file and fills in page +numbers starting at 5: + +.sp +.in +2 +.nf +\fB/Page/ { $2 = n++; } + { print }\fR +.fi +.in -2 +.sp + +.LP +\fBExample 9 \fRPrinting a File and Numbering Its Pages +.sp +.LP +Assuming this program is in a file named \fBprog\fR, the following example +prints the file \fBinput\fR numbering its pages starting at \fB5\fR: + +.sp +.in +2 +.nf +example% \fBoawk -f prog n=5 input\fR +.fi +.in -2 +.sp + +.SH ENVIRONMENT VARIABLES +See \fBenviron\fR(5) for descriptions of the following environment variables +that affect the execution of \fBoawk\fR: \fBLANG\fR, \fBLC_ALL\fR, +\fBLC_COLLATE\fR, \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, \fBNLSPATH\fR, and +\fBPATH\fR. +.sp +.ne 2 +.na +\fB\fBLC_NUMERIC\fR\fR +.ad +.RS 14n +Determine the radix character used when interpreting numeric input, +performing conversions between numeric and string values and formatting +numeric output. Regardless of locale, the period character (the +decimal-point character of the POSIX locale) is the decimal-point character +recognized in processing \fBoawk\fR programs (including assignments in +command-line arguments). +.RE + +.SH ATTRIBUTES +See \fBattributes\fR(5) for descriptions of the following attributes: +.SS "/usr/bin/oawk" + +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +CSI Not Enabled +.TE + +.SH SEE ALSO +\fBegrep\fR(1), \fBgrep\fR(1), \fBawk\fR(1), \fBsed\fR(1), \fBprintf\fR(3C), +\fBattributes\fR(5), \fBenviron\fR(5), \fBlargefile\fR(5), \fBstandards\fR(5) +.SH NOTES +Input white space is not preserved on output if fields are involved. +.sp +.LP +There are no explicit conversions between numbers and strings. To force an +expression to be treated as a number, add \fB0\fR to it. To force an expression +to be treated as a string, concatenate the null string (\fB""\fR) to it. |