1 .\"
   2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
   3 .\" permission to reproduce portions of its copyrighted documentation.
   4 .\" Original documentation from The Open Group can be obtained online at
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\"
   7 .\" The Institute of Electrical and Electronics Engineers and The Open
   8 .\" Group, have given us permission to reprint portions of their
   9 .\" documentation.
  10 .\"
  11 .\" In the following statement, the phrase ``this text'' refers to portions
  12 .\" of the system documentation.
  13 .\"
  14 .\" Portions of this text are reprinted and reproduced in electronic form
  15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
  16 .\" Standard for Information Technology -- Portable Operating System
  17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
  18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
  19 .\" Engineers, Inc and The Open Group.  In the event of any discrepancy
  20 .\" between these versions and the original IEEE and The Open Group
  21 .\" Standard, the original IEEE and The Open Group Standard is the referee
  22 .\" document.  The original Standard can be obtained online at
  23 .\" http://www.opengroup.org/unix/online.html.
  24 .\"
  25 .\" This notice shall appear on any product containing this material.
  26 .\"
  27 .\" The contents of this file are subject to the terms of the
  28 .\" Common Development and Distribution License (the "License").
  29 .\" You may not use this file except in compliance with the License.
  30 .\"
  31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  32 .\" or http://www.opensolaris.org/os/licensing.
  33 .\" See the License for the specific language governing permissions
  34 .\" and limitations under the License.
  35 .\"
  36 .\" When distributing Covered Code, include this CDDL HEADER in each
  37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  38 .\" If applicable, add the following below this CDDL HEADER, with the
  39 .\" fields enclosed by brackets "[]" replaced with your own identifying
  40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  41 .\"
  42 .\"
  43 .\" Copyright 1989 AT&T
  44 .\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
  45 .\" Copyright (c) 2005, Sun Microsystems, Inc.  All Rights Reserved
  46 .\" Copyright 2020 Joyent, Inc.
  47 .\"
  48 .TH OAWK 1 "Apr 20, 2020"
  49 .SH NAME
  50 oawk \- (older) pattern scanning and processing language
  51 .SH SYNOPSIS
  52 .nf
  53 \fB/usr/bin/oawk\fR [\fB-f\fR \fIprogfile\fR] [\fB-F\fIc\fR\fR] [' \fIprog\fR '] [\fIparameters\fR]
  54      [\fIfilename\fR]...
  55 .fi
  56 
  57 .SH DESCRIPTION
  58 This command is now obsolete, and will be removed from illumos at some point.
  59 .sp
  60 .LP
  61 The \fB/usr/bin/oawk\fR utility scans each input \fIfilename\fR for lines that
  62 match any of a set of patterns specified in \fIprog\fR. The \fIprog\fR string
  63 must be enclosed in single quotes (\fB a\'\fR) to protect it from the shell.
  64 For each pattern in \fIprog\fR there can be an associated action performed when
  65 a line of a \fIfilename\fR matches the pattern. The set of pattern-action
  66 statements can appear literally as \fIprog\fR or in a file specified with the
  67 \fB-f\fR\fI progfile\fR option. Input files are read in order; if there are no
  68 files, the standard input is read. The file name \fB\&'\(mi'\fR means the
  69 standard input.
  70 .SH OPTIONS
  71 The following options are supported:
  72 .sp
  73 .ne 2
  74 .na
  75 \fB\fB-f\fR\fI progfile\fR \fR
  76 .ad
  77 .RS 16n
  78 \fBoawk\fR uses the set of patterns it reads from \fIprogfile\fR.
  79 .RE
  80 
  81 .sp
  82 .ne 2
  83 .na
  84 \fB\fB-F\fR\fIc\fR \fR
  85 .ad
  86 .RS 16n
  87 Uses the character \fIc\fR as the field separator (FS) character.  See the
  88 discussion of \fBFS\fR below.
  89 .RE
  90 
  91 .SH USAGE
  92 .SS "Input Lines"
  93 Each input line is matched against the pattern portion of every pattern-action
  94 statement; the associated action is performed for each matched pattern. Any
  95 \fIfilename\fR of the form \fIvar=value\fR is treated as an assignment, not a
  96 filename, and is executed at the time it would have been opened if it were a
  97 filename. \fIVariables\fR assigned in this manner are not available inside a
  98 \fBBEGIN\fR rule, and are assigned after previously specified files have been
  99 read.
 100 .sp
 101 .LP
 102 An input line is normally made up of fields separated by white spaces. (This
 103 default can be changed by using the \fBFS\fR built-in variable or the
 104 \fB-F\fR\fIc\fR option.) The default is to ignore leading blanks and to
 105 separate fields by blanks and/or tab characters. However, if \fBFS\fR is
 106 assigned a value that does not include any of the white spaces, then leading
 107 blanks are not ignored. The fields are denoted \fB$1\fR, \fB$2\fR,
 108 \fB\&.\|.\|.\fR\|; \fB$0\fR refers to the entire line.
 109 .SS "Pattern-action Statements"
 110 A pattern-action statement has the form:
 111 .sp
 112 .in +2
 113 .nf
 114 \fIpattern\fR\fB { \fR\fIaction\fR\fB } \fR
 115 .fi
 116 .in -2
 117 .sp
 118 
 119 .sp
 120 .LP
 121 Either pattern or action can be omitted. If there is no action, the matching
 122 line is printed. If there is no pattern, the action is performed on every input
 123 line. Pattern-action statements are separated by newlines or semicolons.
 124 .sp
 125 .LP
 126 Patterns are arbitrary Boolean combinations ( \fB!\fR, ||, \fB&&\fR, and
 127 parentheses) of relational expressions and regular expressions. A relational
 128 expression is one of the following:
 129 .sp
 130 .in +2
 131 .nf
 132 \fIexpression relop expression
 133 expression matchop regular_expression\fR
 134 .fi
 135 .in -2
 136 
 137 .sp
 138 .LP
 139 where a \fIrelop\fR is any of the six relational operators in C, and a
 140 \fImatchop\fR is either \fB~\fR (contains) or \fB!~\fR (does not contain). An
 141 \fIexpression\fR is an arithmetic expression, a relational expression, the
 142 special expression
 143 .sp
 144 .in +2
 145 .nf
 146 \fIvar \fRin \fIarray\fR
 147 .fi
 148 .in -2
 149 
 150 .sp
 151 .LP
 152 or a Boolean combination of these.
 153 .sp
 154 .LP
 155 Regular expressions are as in \fBegrep\fR(1). In patterns they must be
 156 surrounded by slashes. Isolated regular expressions in a pattern apply to the
 157 entire line. Regular expressions can also occur in relational expressions. A
 158 pattern can consist of two patterns separated by a comma; in this case, the
 159 action is performed for all lines between the occurrence of the first pattern
 160 to the occurrence of the second pattern.
 161 .sp
 162 .LP
 163 The special patterns \fBBEGIN\fR and \fBEND\fR can be used to capture control
 164 before the first input line has been read and after the last input line has
 165 been read respectively. These keywords do not combine with any other patterns.
 166 .SS "Built-in Variables"
 167 Built-in variables include:
 168 .sp
 169 .ne 2
 170 .na
 171 \fB\fBFILENAME\fR \fR
 172 .ad
 173 .RS 13n
 174 name of the current input file
 175 .RE
 176 
 177 .sp
 178 .ne 2
 179 .na
 180 \fB\fBFS\fR \fR
 181 .ad
 182 .RS 13n
 183 input field separator regular expression (default blank and tab)
 184 .RE
 185 
 186 .sp
 187 .ne 2
 188 .na
 189 \fB\fBNF\fR \fR
 190 .ad
 191 .RS 13n
 192 number of fields in the current record
 193 .RE
 194 
 195 .sp
 196 .ne 2
 197 .na
 198 \fB\fBNR\fR \fR
 199 .ad
 200 .RS 13n
 201 ordinal number of the current record
 202 .RE
 203 
 204 .sp
 205 .ne 2
 206 .na
 207 \fB\fBOFMT\fR \fR
 208 .ad
 209 .RS 13n
 210 output format for numbers (default \fB%.6g\fR)
 211 .RE
 212 
 213 .sp
 214 .ne 2
 215 .na
 216 \fB\fBOFS\fR \fR
 217 .ad
 218 .RS 13n
 219 output field separator (default blank)
 220 .RE
 221 
 222 .sp
 223 .ne 2
 224 .na
 225 \fB\fBORS\fR \fR
 226 .ad
 227 .RS 13n
 228 output record separator (default new-line)
 229 .RE
 230 
 231 .sp
 232 .ne 2
 233 .na
 234 \fB\fBRS\fR \fR
 235 .ad
 236 .RS 13n
 237 input record separator (default new-line)
 238 .RE
 239 
 240 .sp
 241 .LP
 242 An action is a sequence of statements. A statement can be one of the following:
 243 .sp
 244 .in +2
 245 .nf
 246 if ( \fIexpression\fR ) \fIstatement\fR [ else \fIstatement\fR ]
 247 while ( \fIexpression\fR ) \fIstatement\fR
 248 do \fIstatement\fR while ( \fIexpression\fR )
 249 for ( \fIexpression\fR ; \fIexpression\fR ; \fIexpression\fR ) \fIstatement\fR
 250 for ( \fIvar\fR in \fIarray\fR ) \fIstatement\fR
 251 break
 252 continue
 253 { [ \fIstatement\fR ] .\|.\|. }
 254 \fIexpression\fR      # commonly variable = expression
 255 print [ \fIexpression-list\fR ] [ >\fIexpression\fR ]
 256 printf format [ ,\fIexpression-list\fR ] [ >\fIexpression\fR ]
 257 next            # skip remaining patterns on this input line
 258 exit [expr]     # skip the rest of the input; exit status is expr
 259 .fi
 260 .in -2
 261 
 262 .sp
 263 .LP
 264 Statements are terminated by semicolons, newlines, or right braces. An empty
 265 expression-list stands for the whole input line. Expressions take on string or
 266 numeric values as appropriate, and are built using the operators \fB+\fR,
 267 \fB\(mi\fR, \fB*\fR, \fB/\fR, \fB%\fR, \fB^\fR and concatenation (indicated by
 268 a blank). The operators \fB++\fR, \fB\(mi\(mi\fR, \fB+=\fR, \fB\(mi=\fR,
 269 \fB*=\fR, \fB/=\fR, \fB%=\fR, \fB^=\fR, \fB>\fR, \fB>=\fR, \fB<\fR, \fB<=\fR,
 270 \fB==\fR, \fB!=\fR, and \fB?:\fR are also available in expressions. Variables
 271 can be scalars, array elements (denoted x[i]), or fields. Variables are
 272 initialized to the null string or zero. Array subscripts can be any string, not
 273 necessarily numeric; this allows for a form of associative memory. String
 274 constants are quoted (\fB""\fR), with the usual C escapes recognized within.
 275 .sp
 276 .LP
 277 The \fBprint\fR statement prints its arguments on the standard output, or on a
 278 file if \fB>\fR\fIexpression\fR is present, or on a pipe if '\fB|\fR\fIcmd\fR'
 279 is present. The output resulted from the print statement is terminated by the
 280 output record separator with each argument separated by the current output
 281 field separator. The \fBprintf\fR statement formats its expression list
 282 according to the format (see \fBprintf\fR(3C)).
 283 .SS "Built-in Functions"
 284 The arithmetic functions are as follows:
 285 .sp
 286 .ne 2
 287 .na
 288 \fB\fBexp\fR(\fIx\fR)\fR
 289 .ad
 290 .RS 11n
 291 Return the exponential function of \fIx\fR.
 292 .RE
 293 
 294 .sp
 295 .ne 2
 296 .na
 297 \fB\fBlog\fR(\fIx\fR)\fR
 298 .ad
 299 .RS 11n
 300 Return the natural logarithm of \fIx\fR.
 301 .RE
 302 
 303 .sp
 304 .ne 2
 305 .na
 306 \fB\fBsqrt\fR(\fIx\fR)\fR
 307 .ad
 308 .RS 11n
 309 Return the square root of \fIx\fR.
 310 .RE
 311 
 312 .sp
 313 .ne 2
 314 .na
 315 \fB\fBint\fR(\fIx\fR)\fR
 316 .ad
 317 .RS 11n
 318 Truncate its argument to an integer. It is truncated toward \fB0\fR when
 319 \fIx\fR >\fB 0\fR.
 320 .RE
 321 
 322 .sp
 323 .LP
 324 The string functions are as follows:
 325 .sp
 326 .ne 2
 327 .na
 328 \fB\fBindex(\fR\fIs\fR\fB, \fR\fIt\fR\fB)\fR\fR
 329 .ad
 330 .sp .6
 331 .RS 4n
 332 Return the position in string \fIs\fR where string \fIt\fR first occurs, or
 333 \fB0\fR if it does not occur at all.
 334 .RE
 335 
 336 .sp
 337 .ne 2
 338 .na
 339 \fB\fBint(\fR\fIs\fR\fB)\fR\fR
 340 .ad
 341 .sp .6
 342 .RS 4n
 343 truncates \fIs\fR to an integer value. If \fIs\fR is not specified, $0 is used.
 344 .RE
 345 
 346 .sp
 347 .ne 2
 348 .na
 349 \fB\fBlength(\fR\fIs\fR\fB)\fR\fR
 350 .ad
 351 .sp .6
 352 .RS 4n
 353 Return the length of its argument taken as a string, or of the whole line if
 354 there is no argument.
 355 .RE
 356 
 357 .sp
 358 .ne 2
 359 .na
 360 \fB\fBsplit(\fR\fIs\fR, \fIa\fR, \fIfs\fR\fB)\fR\fR
 361 .ad
 362 .sp .6
 363 .RS 4n
 364 Split the string \fIs\fR into array elements \fIa\fR[\fI1\fR],
 365 \fIa\fR[\fI2\fR], \|.\|.\|. \fIa\fR[\fIn\fR], and returns \fIn\fR. The
 366 separation is done with the regular expression \fIfs\fR or with the field
 367 separator \fBFS\fR if \fIfs\fR is not given.
 368 .RE
 369 
 370 .sp
 371 .ne 2
 372 .na
 373 \fB\fBsprintf(\fR\fIfmt\fR, \fIexpr\fR, \fIexpr\fR,\|.\|.\|.\|\fB)\fR\fR
 374 .ad
 375 .sp .6
 376 .RS 4n
 377 Format the expressions according to the \fBprintf\fR(3C) format given by
 378 \fIfmt\fR and returns the resulting string.
 379 .RE
 380 
 381 .sp
 382 .ne 2
 383 .na
 384 \fB\fBsubstr(\fR\fIs\fR, \fIm\fR, \fIn\fR\fB)\fR\fR
 385 .ad
 386 .sp .6
 387 .RS 4n
 388 returns the \fIn\fR-character substring of \fIs\fR that begins at position
 389 \fIm\fR.
 390 .RE
 391 
 392 .sp
 393 .LP
 394 The input/output function is as follows:
 395 .sp
 396 .ne 2
 397 .na
 398 \fB\fBgetline\fR\fR
 399 .ad
 400 .RS 11n
 401 Set \fB$0\fR to the next input record from the current input file.
 402 \fBgetline\fR returns \fB1\fR for successful input, \fB0\fR for end of file,
 403 and \fB\(mi1\fR for an error.
 404 .RE
 405 
 406 .SS "Large File Behavior"
 407 See \fBlargefile\fR(5) for the description of the behavior of \fBoawk\fR when
 408 encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
 409 .SH EXAMPLES
 410 \fBExample 1 \fRPrinting Lines Longer Than 72 Characters
 411 .sp
 412 .LP
 413 The following example is an \fBoawk\fR script that can be executed by an
 414 \fBoawk -f examplescript\fR style command. It prints lines longer than
 415 seventy two characters:
 416 
 417 .sp
 418 .in +2
 419 .nf
 420 \fBlength > 72\fR
 421 .fi
 422 .in -2
 423 .sp
 424 
 425 .LP
 426 \fBExample 2 \fRPrinting Fields in Opposite Order
 427 .sp
 428 .LP
 429 The following example is an \fBoawk\fR script that can be executed by an
 430 \fBoawk -f examplescript\fR style command. It prints the first two fields in
 431 opposite order:
 432 
 433 .sp
 434 .in +2
 435 .nf
 436 \fB{ print $2, $1 }\fR
 437 .fi
 438 .in -2
 439 .sp
 440 
 441 .LP
 442 \fBExample 3 \fRPrinting Fields in Opposite Order with the Input Fields
 443 Separated
 444 .sp
 445 .LP
 446 The following example is an \fBoawk\fR script that can be executed by an
 447 \fBoawk -f examplescript\fR style command. It prints the first two input
 448 fields in opposite order, separated by a comma, blanks or tabs:
 449 
 450 .sp
 451 .in +2
 452 .nf
 453 \fBBEGIN { FS = ",[ \et]*|[ \et]+" }
 454       { print $2, $1 }\fR
 455 .fi
 456 .in -2
 457 .sp
 458 
 459 .LP
 460 \fBExample 4 \fRAdding Up the First Column, Printing the Sum and Average
 461 .sp
 462 .LP
 463 The following example is an \fBoawk\fR script that can be executed by an
 464 \fBoawk -f examplescript\fR style command.  It adds up the first column, and
 465 prints the sum and average:
 466 
 467 .sp
 468 .in +2
 469 .nf
 470 \fB{ s += $1 }
 471 END  { print "sum is", s, " average is", s/NR }\fR
 472 .fi
 473 .in -2
 474 .sp
 475 
 476 .LP
 477 \fBExample 5 \fRPrinting Fields in Reverse Order
 478 .sp
 479 .LP
 480 The following example is an \fBoawk\fR script that can be executed by an
 481 \fBoawk -f examplescript\fR style command. It prints fields in reverse order:
 482 
 483 .sp
 484 .in +2
 485 .nf
 486 \fB{ for (i = NF; i > 0; \(mi\(mii) print $i }\fR
 487 .fi
 488 .in -2
 489 .sp
 490 
 491 .LP
 492 \fBExample 6 \fRPrinting All lines Between \fBstart/stop\fR Pairs
 493 .sp
 494 .LP
 495 The following example is an \fBoawk\fR script that can be executed by an
 496 \fBoawk -f examplescript\fR style command. It prints all lines between
 497 start/stop pairs.
 498 
 499 .sp
 500 .in +2
 501 .nf
 502 \fB/start/, /stop/\fR
 503 .fi
 504 .in -2
 505 .sp
 506 
 507 .LP
 508 \fBExample 7 \fRPrinting All Lines Whose First Field is Different from the
 509 Previous One
 510 .sp
 511 .LP
 512 The following example is an \fBoawk\fR script that can be executed by an
 513 \fBoawk -f examplescript\fR style command. It prints all lines whose first
 514 field is different from the previous one.
 515 
 516 .sp
 517 .in +2
 518 .nf
 519 \fB$1 != prev { print; prev = $1 }\fR
 520 .fi
 521 .in -2
 522 .sp
 523 
 524 .LP
 525 \fBExample 8 \fRPrinting a File and Filling in Page numbers
 526 .sp
 527 .LP
 528 The following example is an \fBoawk\fR script that can be executed by an
 529 \fBoawk -f examplescript\fR style command. It prints a file and fills in page
 530 numbers starting at 5:
 531 
 532 .sp
 533 .in +2
 534 .nf
 535 \fB/Page/       { $2 = n++; }
 536            { print }\fR
 537 .fi
 538 .in -2
 539 .sp
 540 
 541 .LP
 542 \fBExample 9 \fRPrinting a File and Numbering Its Pages
 543 .sp
 544 .LP
 545 Assuming this program is in a file named \fBprog\fR, the following example
 546 prints the file \fBinput\fR numbering its pages starting at \fB5\fR:
 547 
 548 .sp
 549 .in +2
 550 .nf
 551 example% \fBoawk -f prog n=5 input\fR
 552 .fi
 553 .in -2
 554 .sp
 555 
 556 .SH ENVIRONMENT VARIABLES
 557 See \fBenviron\fR(5) for descriptions of the following environment variables
 558 that affect the execution of \fBoawk\fR: \fBLANG\fR, \fBLC_ALL\fR,
 559 \fBLC_COLLATE\fR, \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, \fBNLSPATH\fR, and
 560 \fBPATH\fR.
 561 .sp
 562 .ne 2
 563 .na
 564 \fB\fBLC_NUMERIC\fR\fR
 565 .ad
 566 .RS 14n
 567 Determine the radix character used when interpreting numeric input,
 568 performing conversions between numeric and string values and formatting
 569 numeric output.  Regardless of locale, the period character (the
 570 decimal-point character of the POSIX locale) is the decimal-point character
 571 recognized in processing \fBoawk\fR programs (including assignments in
 572 command-line arguments).
 573 .RE
 574 
 575 .SH ATTRIBUTES
 576 See \fBattributes\fR(5) for descriptions of the following attributes:
 577 .SS "/usr/bin/oawk"
 578 
 579 .TS
 580 box;
 581 c | c
 582 l | l .
 583 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 584 _
 585 CSI     Not Enabled
 586 .TE
 587 
 588 .SH SEE ALSO
 589 \fBegrep\fR(1), \fBgrep\fR(1), \fBawk\fR(1), \fBsed\fR(1), \fBprintf\fR(3C),
 590 \fBattributes\fR(5), \fBenviron\fR(5), \fBlargefile\fR(5), \fBstandards\fR(5)
 591 .SH NOTES
 592 Input white space is not preserved on output if fields are involved.
 593 .sp
 594 .LP
 595 There are no explicit conversions between numbers and strings. To force an
 596 expression to be treated as a number, add \fB0\fR to it. To force an expression
 597 to be treated as a string, concatenate the null string (\fB""\fR) to it.