logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

awk.1p (108240B)

    

  1. '\" et
  2. .TH AWK "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. awk
  12. \(em pattern scanning and processing language
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. awk \fB[\fR-F \fIsepstring\fB] [\fR-v \fIassignment\fB]\fR... \fIprogram\fB [\fIargument\fR...\fB]\fR
  17. .P
  18. awk \fB[\fR-F \fIsepstring\fB] \fR-f \fIprogfile \fB[\fR-f \fIprogfile\fB]\fR... \fB[\fR-v \fIassignment\fB]\fR...
  19.      \fB[\fIargument\fR...\fB]\fR
  20. .fi
  21. .SH DESCRIPTION
  22. The
  23. .IR awk
  24. utility shall execute programs written in the
  25. .IR awk
  26. programming language, which is specialized for textual data
  27. manipulation. An
  28. .IR awk
  29. program is a sequence of patterns and corresponding actions. When
  30. input is read that matches a pattern, the action associated with that
  31. pattern is carried out.
  32. .P
  33. Input shall be interpreted as a sequence of records. By default, a
  34. record is a line, less its terminating
  35. <newline>,
  36. but this can be changed by using the
  37. .BR RS
  38. built-in variable. Each record of input shall be matched in turn
  39. against each pattern in the program. For each pattern matched, the
  40. associated action shall be executed.
  41. .P
  42. The
  43. .IR awk
  44. utility shall interpret each input record as a sequence of fields
  45. where, by default, a field is a string of non-\c
  46. <blank>
  47. non-\c
  48. <newline>
  49. characters. This default
  50. <blank>
  51. and
  52. <newline>
  53. field delimiter can be changed by using the
  54. .BR FS
  55. built-in variable or the
  56. .BR \-F
  57. .IR sepstring
  58. option. The
  59. .IR awk
  60. utility shall denote the first field in a record $1, the second $2, and
  61. so on. The symbol $0 shall refer to the entire record; setting any
  62. other field causes the re-evaluation of $0. Assigning to $0 shall reset
  63. the values of all other fields and the
  64. .BR NF
  65. built-in variable.
  66. .SH OPTIONS
  67. The
  68. .IR awk
  69. utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
  70. .IR "Section 12.2" ", " "Utility Syntax Guidelines".
  71. .P
  72. The following options shall be supported:
  73. .IP "\fB\-F\ \fIsepstring\fR" 10
  74. Define the input field separator. This option shall be equivalent to:
  75. .RS 10 
  76. .sp
  77. .RS 4
  78. .nf
  80. -v FS=\fIsepstring
  81. .fi
  82. .P
  83. .RE
  84. .P
  85. except that if
  86. .BR \-F
  87. .IR sepstring
  88. and
  89. .BR \-v
  90. .IR \fRFS=\fPsepstring\fR
  91. are both used, it is unspecified whether the
  92. .BR FS
  93. assignment resulting from
  94. .BR \-F
  95. .IR sepstring
  96. is processed in command line order or is processed after the last
  97. .BR \-v
  98. .IR \fRFS=\fPsepstring\fR .
  99. See the description of the
  100. .BR FS
  101. built-in variable, and how it is used, in the EXTENDED DESCRIPTION
  102. section.
  103. .RE
  104. .IP "\fB\-f\ \fIprogfile\fR" 10
  105. Specify the pathname of the file
  106. .IR progfile
  107. containing an
  108. .IR awk
  109. program. A pathname of
  110. .BR '\-' 
  111. shall denote the standard input. If multiple instances of this option
  112. are specified, the concatenation of the files specified as
  113. .IR progfile
  114. in the order specified shall be the
  115. .IR awk
  116. program. The
  117. .IR awk
  118. program can alternatively be specified in the command line as a single
  119. argument.
  120. .IP "\fB\-v\ \fIassignment\fR" 10
  121. .br
  122. The application shall ensure that the
  123. .IR assignment
  124. argument is in the same form as an
  125. .IR assignment
  126. operand. The specified variable assignment shall occur prior to
  127. executing the
  128. .IR awk
  129. program, including the actions associated with
  130. .BR BEGIN
  131. patterns (if any). Multiple occurrences of this option can be
  132. specified.
  133. .SH OPERANDS
  134. The following operands shall be supported:
  135. .IP "\fIprogram\fR" 10
  136. If no
  137. .BR \-f
  138. option is specified, the first operand to
  139. .IR awk
  140. shall be the text of the
  141. .IR awk
  142. program. The application shall supply the
  143. .IR program
  144. operand as a single argument to
  145. .IR awk .
  146. If the text does not end in a
  147. <newline>,
  148. .IR awk
  149. shall interpret the text as if it did.
  150. .IP "\fIargument\fR" 10
  151. Either of the following two types of
  152. .IR argument
  153. can be intermixed:
  154. .RS 10 
  155. .IP "\fIfile\fR" 10
  156. A pathname of a file that contains the input to be read, which is
  157. matched against the set of patterns in the program. If no
  158. .IR file
  159. operands are specified, or if a
  160. .IR file
  161. operand is
  162. .BR '\-' ,
  163. the standard input shall be used.
  164. .IP "\fIassignment\fR" 10
  165. An operand that begins with an
  166. <underscore>
  167. or alphabetic character from the portable character set (see the table
  168. in the Base Definitions volume of POSIX.1\(hy2017,
  169. .IR "Section 6.1" ", " "Portable Character Set"),
  170. followed by a sequence of underscores, digits, and alphabetics from the
  171. portable character set, followed by the
  172. .BR '=' 
  173. character, shall specify a variable assignment rather than a pathname.
  174. The characters before the
  175. .BR '=' 
  176. represent the name of an
  177. .IR awk
  178. variable; if that name is an
  179. .IR awk
  180. reserved word (see
  181. .IR "Grammar")
  182. the behavior is undefined. The characters following the
  183. <equals-sign>
  184. shall be interpreted as if they appeared in the
  185. .IR awk
  186. program preceded and followed by a double-quote (\c
  187. .BR '\&"' )
  188. character, as a
  189. .BR STRING
  190. token (see
  191. .IR "Grammar"),
  192. except that if the last character is an unescaped
  193. <backslash>,
  194. it shall be interpreted as a literal
  195. <backslash>
  196. rather than as the first character of the sequence
  197. .BR \(dq\e"\(dq .
  198. The variable shall be assigned the value of that
  199. .BR STRING
  200. token and, if appropriate, shall be considered a
  201. .IR "numeric string"
  202. (see
  203. .IR "Expressions in awk"),
  204. the variable shall also be assigned its numeric value. Each such
  205. variable assignment shall occur just prior to the processing of the
  206. following
  207. .IR file ,
  208. if any. Thus, an assignment before the first
  209. .IR file
  210. argument shall be executed after the
  211. .BR BEGIN
  212. actions (if any), while an assignment after the last
  213. .IR file
  214. argument shall occur before the
  215. .BR END
  216. actions (if any). If there are no
  217. .IR file
  218. arguments, assignments shall be executed before processing the standard
  219. input.
  220. .RE
  221. .SH STDIN
  222. The standard input shall be used only if no
  223. .IR file
  224. operands are specified, or if a
  225. .IR file
  226. operand is
  227. .BR '\-' ,
  228. or if a
  229. .IR progfile
  230. option-argument is
  231. .BR '\-' ;
  232. see the INPUT FILES section. If the
  233. .IR awk
  234. program contains no actions and no patterns, but is otherwise a valid
  235. .IR awk
  236. program, standard input and any
  237. .IR file
  238. operands shall not be read and
  239. .IR awk
  240. shall exit with a return status of zero.
  241. .SH "INPUT FILES"
  242. Input files to the
  243. .IR awk
  244. program from any of the following sources shall be text files:
  245. .IP " *" 4
  246. Any
  247. .IR file
  248. operands or their equivalents, achieved by modifying the
  249. .IR awk
  250. variables
  251. .BR ARGV
  252. and
  253. .BR ARGC
  254. .IP " *" 4
  255. Standard input in the absence of any
  256. .IR file
  257. operands
  258. .IP " *" 4
  259. Arguments to the
  260. .BR getline
  261. function
  262. .P
  263. Whether the variable
  264. .BR RS
  265. is set to a value other than a
  266. <newline>
  267. or not, for these files, implementations shall support records
  268. terminated with the specified separator up to
  269. {LINE_MAX}
  270. bytes and may support longer records.
  271. .P
  272. If
  273. .BR \-f
  274. .IR progfile
  275. is specified, the application shall ensure that the files named by each
  276. of the
  277. .IR progfile
  278. option-arguments are text files and their concatenation, in the same
  279. order as they appear in the arguments, is an
  280. .IR awk
  281. program.
  282. .SH "ENVIRONMENT VARIABLES"
  283. The following environment variables shall affect the execution of
  284. .IR awk :
  285. .IP "\fILANG\fP" 10
  286. Provide a default value for the internationalization variables that are
  287. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  288. .IR "Section 8.2" ", " "Internationalization Variables"
  289. for the precedence of internationalization variables used to determine
  290. the values of locale categories.)
  291. .IP "\fILC_ALL\fP" 10
  292. If set to a non-empty string value, override the values of all the
  293. other internationalization variables.
  294. .IP "\fILC_COLLATE\fP" 10
  295. .br
  296. Determine the locale for the behavior of ranges, equivalence classes,
  297. and multi-character collating elements within regular expressions and
  298. in comparisons of string values.
  299. .IP "\fILC_CTYPE\fP" 10
  300. Determine the locale for the interpretation of sequences of bytes of
  301. text data as characters (for example, single-byte as opposed to
  302. multi-byte characters in arguments and input files), the behavior of
  303. character classes within regular expressions, the identification of
  304. characters as letters, and the mapping of uppercase and lowercase
  305. characters for the
  306. .BR toupper
  307. and
  308. .BR tolower
  309. functions.
  310. .IP "\fILC_MESSAGES\fP" 10
  311. .br
  312. Determine the locale that should be used to affect the format and
  313. contents of diagnostic messages written to standard error.
  314. .IP "\fILC_NUMERIC\fP" 10
  315. .br
  316. Determine the radix character used when interpreting numeric input,
  317. performing conversions between numeric and string values, and
  318. formatting numeric output. Regardless of locale, the
  319. <period>
  320. character (the decimal-point character of the POSIX locale) is the
  321. decimal-point character recognized in processing
  322. .IR awk
  323. programs (including assignments in command line arguments).
  324. .IP "\fINLSPATH\fP" 10
  325. Determine the location of message catalogs for the processing of
  326. .IR LC_MESSAGES .
  327. .IP "\fIPATH\fP" 10
  328. Determine the search path when looking for commands executed by
  329. \fIsystem\fR(\fIexpr\fR), or input and output pipes; see the Base Definitions volume of POSIX.1\(hy2017,
  330. .IR "Chapter 8" ", " "Environment Variables".
  331. .P
  332. In addition, all environment variables shall be visible via the
  333. .IR awk
  334. variable
  335. .BR ENVIRON .
  336. .SH "ASYNCHRONOUS EVENTS"
  337. Default.
  338. .SH STDOUT
  339. The nature of the output files depends on the
  340. .IR awk
  341. program.
  342. .SH STDERR
  343. The standard error shall be used only for diagnostic messages.
  344. .SH "OUTPUT FILES"
  345. The nature of the output files depends on the
  346. .IR awk
  347. program.
  348. .br
  349. .SH "EXTENDED DESCRIPTION"
  350. .SS "Overall Program Structure"
  351. .P
  352. An
  353. .IR awk
  354. program is composed of pairs of the form:
  355. .sp
  356. .RS 4
  357. .nf
  359. \fIpattern\fR { \fIaction\fR }
  360. .fi
  361. .P
  362. .RE
  363. .P
  364. Either the pattern or the action (including the enclosing brace
  365. characters) can be omitted.
  366. .P
  367. A missing pattern shall match any record of input, and a missing action
  368. shall be equivalent to:
  369. .sp
  370. .RS 4
  371. .nf
  373. { print }
  374. .fi
  375. .P
  376. .RE
  377. .P
  378. Execution of the
  379. .IR awk
  380. program shall start by first executing the actions associated with all
  381. .BR BEGIN
  382. patterns in the order they occur in the program. Then each
  383. .IR file
  384. operand (or standard input if no files were specified) shall be
  385. processed in turn by reading data from the file until a record
  386. separator is seen (\c
  387. <newline>
  388. by default). Before the first reference to a field in the record is
  389. evaluated, the record shall be split into fields, according to the
  390. rules in
  391. .IR "Regular Expressions",
  392. using the value of
  393. .BR FS
  394. that was current at the time the record was read. Each pattern in the
  395. program then shall be evaluated in the order of occurrence, and the
  396. action associated with each pattern that matches the current record
  397. executed. The action for a matching pattern shall be executed before
  398. evaluating subsequent patterns. Finally, the actions associated with
  399. all
  400. .BR END
  401. patterns shall be executed in the order they occur in the program.
  402. .SS "Expressions in awk"
  403. .P
  404. Expressions describe computations used in
  405. .IR patterns
  406. and
  407. .IR actions .
  408. In the following table, valid expression operations are given in groups
  409. from highest precedence first to lowest precedence last, with
  410. equal-precedence operators grouped between horizontal lines. In
  411. expression evaluation, where the grammar is formally ambiguous, higher
  412. precedence operators shall be evaluated before lower precedence
  413. operators. In this table
  414. .IR expr ,
  415. .IR expr1 ,
  416. .IR expr2 ,
  417. and
  418. .IR expr3
  419. represent any expression, while lvalue represents any entity that can
  420. be assigned to (that is, on the left side of an assignment operator).
  421. The precise syntax of expressions is given in
  422. .IR "Grammar".
  423. .sp
  424. .ce 1
  425. \fBTable 4-1: Expressions in Decreasing Precedence in \fIawk\fP\fR
  426. .TS
  427. box tab(@) center;
  428. cB | cB | cB | cB
  429. l1f5 | l1 | l1 | l.
  430. Syntax@Name@Type of Result@Associativity
  431. _
  432. ( \fIexpr\fP )@Grouping@Type of \fIexpr\fP@N/A
  433. _
  434. $\fIexpr\fP@Field reference@String@N/A
  435. _
  436. lvalue ++@Post-increment@Numeric@N/A
  437. lvalue \-\|\-@Post-decrement@Numeric@N/A
  438. _
  439. ++ lvalue@Pre-increment@Numeric@N/A
  440. \-\|\- lvalue@Pre-decrement@Numeric@N/A
  441. _
  442. \fIexpr\fP ^ \fIexpr\fP@Exponentiation@Numeric@Right
  443. _
  444. ! \fIexpr\fP@Logical not@Numeric@N/A
  445. + \fIexpr\fP@Unary plus@Numeric@N/A
  446. \- \fIexpr\fP@Unary minus@Numeric@N/A
  447. _
  448. \fIexpr\fP * \fIexpr\fP@Multiplication@Numeric@Left
  449. \fIexpr\fP / \fIexpr\fP@Division@Numeric@Left
  450. \fIexpr\fP % \fIexpr\fP@Modulus@Numeric@Left
  451. _
  452. \fIexpr\fP + \fIexpr\fP@Addition@Numeric@Left
  453. \fIexpr\fP \- \fIexpr\fP@Subtraction@Numeric@Left
  454. _
  455. \fIexpr\fP \fIexpr\fP@String concatenation@String@Left
  456. _
  457. \fIexpr\fP < \fIexpr\fP@Less than@Numeric@None
  458. \fIexpr\fP <= \fIexpr\fP@Less than or equal to@Numeric@None
  459. \fIexpr\fP != \fIexpr\fP@Not equal to@Numeric@None
  460. \fIexpr\fP == \fIexpr\fP@Equal to@Numeric@None
  461. \fIexpr\fP > \fIexpr\fP@Greater than@Numeric@None
  462. \fIexpr\fP >= \fIexpr\fP@Greater than or equal to@Numeric@None
  463. _
  464. \fIexpr\fP ~ \fIexpr\fP@ERE match@Numeric@None
  465. \fIexpr\fP !~ \fIexpr\fP@ERE non-match@Numeric@None
  466. _
  467. \fIexpr\fP in array@Array membership@Numeric@Left
  468. ( \fIindex\fP ) in \fIarray\fP@Multi-dimension array@Numeric@Left
  469. @membership
  470. _
  471. \fIexpr\fP && \fIexpr\fP@Logical AND@Numeric@Left
  472. _
  473. \fIexpr\fP || \fIexpr\fP@Logical OR@Numeric@Left
  474. _
  475. \fIexpr1\fP ? \fIexpr2\fP : \fIexpr3\fP@Conditional expression@Type of selected@Right
  476. @@\fIexpr2\fP or \fIexpr3\fP
  477. _
  478. lvalue ^= \fIexpr\fP@Exponentiation assignment@Numeric@Right
  479. lvalue %= \fIexpr\fP@Modulus assignment@Numeric@Right
  480. lvalue *= \fIexpr\fP@Multiplication assignment@Numeric@Right
  481. lvalue /= \fIexpr\fP@Division assignment@Numeric@Right
  482. lvalue += \fIexpr\fP@Addition assignment@Numeric@Right
  483. lvalue \-= \fIexpr\fP@Subtraction assignment@Numeric@Right
  484. lvalue = \fIexpr\fP@Assignment@Type of \fIexpr\fP@Right
  485. .TE
  486. .P
  487. Each expression shall have either a string value, a numeric value, or
  488. both. Except as stated for specific contexts, the value of an expression
  489. shall be implicitly converted to the type needed for the context in which
  490. it is used. A string value shall be converted to a numeric value either by
  491. the equivalent of the following calls to functions defined by the ISO\ C standard:
  492. .sp
  493. .RS 4
  494. .nf
  496. setlocale(LC_NUMERIC, "");
  497. \fInumeric_value\fR = atof(\fIstring_value\fR);
  498. .fi
  499. .P
  500. .RE
  501. .P
  502. or by converting the initial portion of the string to type
  503. .BR double
  504. representation as follows:
  505. .sp
  506. .RS
  507. The input string is decomposed into two parts: an initial, possibly empty,
  508. sequence of white-space characters (as specified by
  509. \fIisspace\fR())
  510. and a subject sequence interpreted as a floating-point constant.
  511. .P
  512. The expected form of the subject sequence is an optional
  513. .BR '+' 
  514. or
  515. .BR '\-' 
  516. sign, then a non-empty sequence of digits optionally containing a
  517. <period>,
  518. then an optional exponent part. An exponent part consists of
  519. .BR 'e' 
  520. or
  521. .BR 'E' ,
  522. followed by an optional sign, followed by one or more decimal digits.
  523. .P
  524. The sequence starting with the first digit or the
  525. <period>
  526. (whichever occurs first) is interpreted as a floating constant of the
  527. C language, and if neither an exponent part nor a
  528. <period>
  529. appears, a
  530. <period>
  531. is assumed to follow the last digit in the string. If the subject
  532. sequence begins with a
  533. <hyphen-minus>,
  534. the value resulting from the conversion is negated.
  535. .RE
  536. .P
  537. A numeric value that is exactly equal to the value of an integer (see
  538. .IR "Section 1.1.2" ", " "Concepts Derived from the ISO C Standard")
  539. shall be converted to a string by the equivalent of a call to the
  540. .BR sprintf
  541. function (see
  542. .IR "String Functions")
  543. with the string
  544. .BR \(dq%d\(dq 
  545. as the
  546. .IR fmt
  547. argument and the numeric value being converted as the first and only
  548. .IR expr
  549. argument. Any other numeric value shall be converted to a string by the
  550. equivalent of a call to the
  551. .BR sprintf
  552. function with the value of the variable
  553. .BR CONVFMT
  554. as the
  555. .IR fmt
  556. argument and the numeric value being converted as the first and only
  557. .IR expr
  558. argument. The result of the conversion is unspecified if the value of
  559. .BR CONVFMT
  560. is not a floating-point format specification. This volume of POSIX.1\(hy2017 specifies no
  561. explicit conversions between numbers and strings. An application can
  562. force an expression to be treated as a number by adding zero to it, or
  563. can force it to be treated as a string by concatenating the null string
  564. (\c
  565. .BR \(dq\^\(dq )
  566. to it.
  567. .P
  568. A string value shall be considered a
  569. .IR "numeric string"
  570. if it comes from one of the following:
  571. .IP " 1." 4
  572. Field variables
  573. .IP " 2." 4
  574. Input from the
  575. \fIgetline\fR()
  576. function
  577. .IP " 3." 4
  578. .BR FILENAME
  579. .IP " 4." 4
  580. .BR ARGV
  581. array elements
  582. .IP " 5." 4
  583. .BR ENVIRON
  584. array elements
  585. .IP " 6." 4
  586. Array elements created by the
  587. \fIsplit\fR()
  588. function
  589. .IP " 7." 4
  590. A command line variable assignment
  591. .IP " 8." 4
  592. Variable assignment from another numeric string variable
  593. .P
  594. and an implementation-dependent condition corresponding to either
  595. case (a) or (b) below is met.
  596. .IP " a." 4
  597. After the equivalent of the following calls to functions defined by
  598. the ISO\ C standard,
  599. .IR string_value_end
  600. would differ from
  601. .IR string_value ,
  602. and any characters before the terminating null character in
  603. .IR string_value_end
  604. would be
  605. <blank>
  606. characters:
  607. .RS 4 
  608. .sp
  609. .RS 4
  610. .nf
  612. char *string_value_end;
  613. setlocale(LC_NUMERIC, "");
  614. numeric_value = strtod (string_value, &string_value_end);
  615. .fi
  616. .P
  617. .RE
  618. .RE
  619. .IP " b." 4
  620. After all the following conversions have been applied, the resulting
  621. string would lexically be recognized as a
  622. .BR NUMBER
  623. token as described by the lexical conventions in
  624. .IR "Grammar":
  625. .RS 4 
  626. .IP -- 4
  627. All leading and trailing
  628. <blank>
  629. characters are discarded.
  630. .IP -- 4
  631. If the first non-\c
  632. <blank>
  633. is
  634. .BR '\(pl' 
  635. or
  636. .BR '\-' ,
  637. it is discarded.
  638. .IP -- 4
  639. Each occurrence of the decimal point character from the current locale
  640. is changed to a
  641. <period>.
  642. .RE
  643. In case (a) the numeric value of the
  644. .IR "numeric string"
  645. shall be the value that would be returned by the
  646. \fIstrtod\fR()
  647. call. In case (b) if the first non-\c
  648. <blank>
  649. is
  650. .BR '\-' ,
  651. the numeric value of the
  652. .IR "numeric string"
  653. shall be the negation of the numeric value of the recognized
  654. .BR NUMBER
  655. token; otherwise, the numeric value of the
  656. .IR "numeric string"
  657. shall be the numeric value of the recognized
  658. .BR NUMBER
  659. token. Whether or not a string is a
  660. .IR "numeric string"
  661. shall be relevant only in contexts where that term is used in this
  662. section.
  663. .P
  664. When an expression is used in a Boolean context, if it has a numeric
  665. value, a value of zero shall be treated as false and any other value
  666. shall be treated as true. Otherwise, a string value of the null string
  667. shall be treated as false and any other value shall be treated as true.
  668. A Boolean context shall be one of the following:
  669. .IP " *" 4
  670. The first subexpression of a conditional expression
  671. .IP " *" 4
  672. An expression operated on by logical NOT, logical AND, or logical OR
  673. .IP " *" 4
  674. The second expression of a
  675. .BR for
  676. statement
  677. .IP " *" 4
  678. The expression of an
  679. .BR if
  680. statement
  681. .IP " *" 4
  682. The expression of the
  683. .BR while
  684. clause in either a
  685. .BR while
  686. or
  687. .BR do .\|.\|.\c
  688. .BR while
  689. statement
  690. .IP " *" 4
  691. An expression used as a pattern (as in Overall Program Structure)
  692. .P
  693. All arithmetic shall follow the semantics of floating-point arithmetic as
  694. specified by the ISO\ C standard (see
  695. .IR "Section 1.1.2" ", " "Concepts Derived from the ISO C Standard").
  696. .P
  697. The value of the expression:
  698. .sp
  699. .RS 4
  700. .nf
  702. \fIexpr1\fR \(ha \fIexpr2\fR
  703. .fi
  704. .P
  705. .RE
  706. .P
  707. shall be equivalent to the value returned by the ISO\ C standard function call:
  708. .sp
  709. .RS 4
  710. .nf
  712. \fRpow(\fIexpr1\fR, \fIexpr2\fR)
  713. .fi
  714. .P
  715. .RE
  716. .P
  717. The expression:
  718. .sp
  719. .RS 4
  720. .nf
  722. lvalue \(ha= \fIexpr\fR
  723. .fi
  724. .P
  725. .RE
  726. .P
  727. shall be equivalent to the ISO\ C standard expression:
  728. .sp
  729. .RS 4
  730. .nf
  732. lvalue = pow(lvalue, \fIexpr\fR)
  733. .fi
  734. .P
  735. .RE
  736. .P
  737. except that lvalue shall be evaluated only once. The value of the
  738. expression:
  739. .sp
  740. .RS 4
  741. .nf
  743. \fIexpr1\fR % \fIexpr2\fR
  744. .fi
  745. .P
  746. .RE
  747. .P
  748. shall be equivalent to the value returned by the ISO\ C standard function call:
  749. .sp
  750. .RS 4
  751. .nf
  753. fmod(\fIexpr1\fR, \fIexpr2\fR)
  754. .fi
  755. .P
  756. .RE
  757. .P
  758. The expression:
  759. .sp
  760. .RS 4
  761. .nf
  763. lvalue %= \fIexpr\fR
  764. .fi
  765. .P
  766. .RE
  767. .P
  768. shall be equivalent to the ISO\ C standard expression:
  769. .sp
  770. .RS 4
  771. .nf
  773. lvalue = fmod(lvalue, \fIexpr\fR)
  774. .fi
  775. .P
  776. .RE
  777. .P
  778. except that lvalue shall be evaluated only once.
  779. .P
  780. Variables and fields shall be set by the assignment statement:
  781. .sp
  782. .RS 4
  783. .nf
  785. lvalue = \fIexpression\fR
  786. .fi
  787. .P
  788. .RE
  789. .P
  790. and the type of
  791. .IR expression
  792. shall determine the resulting variable type. The assignment includes
  793. the arithmetic assignments (\c
  794. .BR \(dq+=\(dq ,
  795. .BR \(dq-=\(dq ,
  796. .BR \(dq*=\(dq ,
  797. .BR \(dq/=\(dq ,
  798. .BR \(dq%=\(dq ,
  799. .BR \(dq\(ha=\(dq ,
  800. .BR \(dq++\(dq ,
  801. .BR \(dq--\(dq )
  802. all of which shall produce a numeric result. The left-hand side of an
  803. assignment and the target of increment and decrement operators can be
  804. one of a variable, an array with index, or a field selector.
  805. .P
  806. The
  807. .IR awk
  808. language supplies arrays that are used for storing numbers or strings.
  809. Arrays need not be declared. They shall initially be empty, and their
  810. sizes shall change dynamically. The subscripts, or element identifiers,
  811. are strings, providing a type of associative array capability. An array
  812. name followed by a subscript within square brackets can be used as an
  813. lvalue and thus as an expression, as described in the grammar; see
  814. .IR "Grammar".
  815. Unsubscripted array names can be used in only the following contexts:
  816. .IP " *" 4
  817. A parameter in a function definition or function call
  818. .IP " *" 4
  819. The
  820. .BR NAME
  821. token following any use of the keyword
  822. .BR in
  823. as specified in the grammar (see
  824. .IR "Grammar");
  825. if the name used in this context is not an array name, the behavior is
  826. undefined
  827. .P
  828. A valid array
  829. .IR index
  830. shall consist of one or more
  831. <comma>-separated
  832. expressions, similar to the way in which multi-dimensional arrays are
  833. indexed in some programming languages. Because
  834. .IR awk
  835. arrays are really one-dimensional, such a
  836. <comma>-separated
  837. list shall be converted to a single string by concatenating the string
  838. values of the separate expressions, each separated from the other by
  839. the value of the
  840. .BR SUBSEP
  841. variable. Thus, the following two index operations shall be
  842. equivalent:
  843. .sp
  844. .RS 4
  845. .nf
  847. \fIvar\fB[\fIexpr1\fR, \fIexpr2\fR, ... \fIexprn\fB]
  848. .P
  849. \fIvar\fB[\fIexpr1\fR SUBSEP \fIexpr2\fR SUBSEP ... \fRSUBSEP \fIexprn\fB]\fR
  850. .fi
  851. .P
  852. .RE
  853. .P
  854. The application shall ensure that a multi-dimensioned
  855. .IR index
  856. used with the
  857. .BR in
  858. operator is parenthesized. The
  859. .BR in
  860. operator, which tests for the existence of a particular array element,
  861. shall not cause that element to exist. Any other reference to a
  862. nonexistent array element shall automatically create it.
  863. .P
  864. Comparisons (with the
  865. .BR '<' ,
  866. .BR \(dq<=\(dq ,
  867. .BR \(dq!=\(dq ,
  868. .BR \(dq==\(dq ,
  869. .BR '>' ,
  870. and
  871. .BR \(dq>=\(dq 
  872. operators) shall be made numerically if both operands are numeric, if
  873. one is numeric and the other has a string value that is a numeric
  874. string, or if one is numeric and the other has the uninitialized value.
  875. Otherwise, operands shall be converted to strings as required and a
  876. string comparison shall be made as follows:
  877. .IP " *" 4
  878. For the
  879. .BR \(dq!=\(dq 
  880. and
  881. .BR \(dq==\(dq 
  882. operators, the strings should be compared to check if they are
  883. identical but may be compared using the locale-specific collation
  884. sequence to check if they collate equally.
  885. .IP " *" 4
  886. For the other operators, the strings shall be compared using the
  887. locale-specific collation sequence.
  888. .P
  889. The value of the comparison expression shall be 1 if the relation is
  890. true, or 0 if the relation is false.
  891. .SS "Variables and Special Variables"
  892. .P
  893. Variables can be used in an
  894. .IR awk
  895. program by referencing them. With the exception of function parameters
  896. (see
  897. .IR "User-Defined Functions"),
  898. they are not explicitly declared. Function parameter names shall be
  899. local to the function; all other variable names shall be global. The
  900. same name shall not be used as both a function parameter name and as
  901. the name of a function or a special
  902. .IR awk
  903. variable. The same name shall not be used both as a variable name with
  904. global scope and as the name of a function. The same name shall not be
  905. used within the same scope both as a scalar variable and as an array.
  906. Uninitialized variables, including scalar variables, array elements,
  907. and field variables, shall have an uninitialized value. An
  908. uninitialized value shall have both a numeric value of zero and a
  909. string value of the empty string. Evaluation of variables with an
  910. uninitialized value, to either string or numeric, shall be determined
  911. by the context in which they are used.
  912. .P
  913. Field variables shall be designated by a
  914. .BR '$' 
  915. followed by a number or numerical expression. The effect of the field
  916. number
  917. .IR expression
  918. evaluating to anything other than a non-negative integer is
  919. unspecified; uninitialized variables or string values need not be
  920. converted to numeric values in this context. New field variables can be
  921. created by assigning a value to them. References to nonexistent fields
  922. (that is, fields after $\fBNF\fP), shall evaluate to the uninitialized
  923. value. Such references shall not create new fields. However, assigning
  924. to a nonexistent field (for example, $(\fBNF\fP+2)=5) shall increase
  925. the value of
  926. .BR NF ;
  927. create any intervening fields with the uninitialized value; and cause
  928. the value of $0 to be recomputed, with the fields being separated by
  929. the value of
  930. .BR OFS .
  931. Each field variable shall have a string value or an uninitialized value
  932. when created. Field variables shall have the uninitialized value when
  933. created from $0 using
  934. .BR FS
  935. and the variable does not contain any characters. If appropriate, the
  936. field variable shall be considered a numeric string (see
  937. .IR "Expressions in awk").
  938. .P
  939. Implementations shall support the following other special variables
  940. that are set by
  941. .IR awk :
  942. .IP "\fBARGC\fR" 10
  943. The number of elements in the
  944. .BR ARGV
  945. array.
  946. .IP "\fBARGV\fR" 10
  947. An array of command line arguments, excluding options and the
  948. .IR program
  949. argument, numbered from zero to
  950. .BR ARGC \-1.
  951. .RS 10 
  952. .P
  953. The arguments in
  954. .BR ARGV
  955. can be modified or added to;
  956. .BR ARGC
  957. can be altered. As each input file ends,
  958. .IR awk
  959. shall treat the next non-null element of
  960. .BR ARGV ,
  961. up to the current value of
  962. .BR ARGC \-1,
  963. inclusive, as the name of the next input file. Thus, setting an element
  964. of
  965. .BR ARGV
  966. to null means that it shall not be treated as an input file. The name
  967. .BR '\-' 
  968. indicates the standard input. If an argument matches the format of an
  969. .IR assignment
  970. operand, this argument shall be treated as an
  971. .IR assignment
  972. rather than a
  973. .IR file
  974. argument.
  975. .RE
  976. .IP "\fBCONVFMT\fR" 10
  977. The
  978. .BR printf
  979. format for converting numbers to strings (except for output statements,
  980. where
  981. .BR OFMT
  982. is used);
  983. .BR \(dq%.6g\(dq 
  984. by default.
  985. .IP "\fBENVIRON\fR" 10
  986. An array representing the value of the environment, as described in the
  987. .IR exec
  988. functions defined in the System Interfaces volume of POSIX.1\(hy2017. The indices of the array shall be
  989. strings consisting of the names of the environment variables, and the
  990. value of each array element shall be a string consisting of the value
  991. of that variable. If appropriate, the environment variable shall be
  992. considered a
  993. .IR "numeric string"
  994. (see
  995. .IR "Expressions in awk");
  996. the array element shall also have its numeric value.
  997. .RS 10 
  998. .P
  999. In all cases where the behavior of
  1000. .IR awk
  1001. is affected by environment variables (including the environment of any
  1002. commands that
  1003. .IR awk
  1004. executes via the
  1005. .BR system
  1006. function or via pipeline redirections with the
  1007. .BR print
  1008. statement, the
  1009. .BR printf
  1010. statement, or the
  1011. .BR getline
  1012. function), the environment used shall be the environment at the time
  1013. .IR awk
  1014. began executing; it is implementation-defined whether any
  1015. modification of
  1016. .BR ENVIRON
  1017. affects this environment.
  1018. .RE
  1019. .IP "\fBFILENAME\fR" 10
  1020. A pathname of the current input file. Inside a
  1021. .BR BEGIN
  1022. action the value is undefined. Inside an
  1023. .BR END
  1024. action the value shall be the name of the last input file processed.
  1025. .IP "\fBFNR\fR" 10
  1026. The ordinal number of the current record in the current file. Inside a
  1027. .BR BEGIN
  1028. action the value shall be zero. Inside an
  1029. .BR END
  1030. action the value shall be the number of the last record processed in
  1031. the last file processed.
  1032. .IP "\fBFS\fR" 10
  1033. Input field separator regular expression; a
  1034. <space>
  1035. by default.
  1036. .IP "\fBNF\fR" 10
  1037. The number of fields in the current record. Inside a
  1038. .BR BEGIN
  1039. action, the use of
  1040. .BR NF
  1041. is undefined unless a
  1042. .BR getline
  1043. function without a
  1044. .IR var
  1045. argument is executed previously. Inside an
  1046. .BR END
  1047. action,
  1048. .BR NF
  1049. shall retain the value it had for the last record read, unless a
  1050. subsequent, redirected,
  1051. .BR getline
  1052. function without a
  1053. .IR var
  1054. argument is performed prior to entering the
  1055. .BR END
  1056. action.
  1057. .IP "\fBNR\fR" 10
  1058. The ordinal number of the current record from the start of input.
  1059. Inside a
  1060. .BR BEGIN
  1061. action the value shall be zero. Inside an
  1062. .BR END
  1063. action the value shall be the number of the last record processed.
  1064. .IP "\fBOFMT\fR" 10
  1065. The
  1066. .BR printf
  1067. format for converting numbers to strings in output statements (see
  1068. .IR "Output Statements");
  1069. .BR \(dq%.6g\(dq 
  1070. by default. The result of the conversion is unspecified if the value of
  1071. .BR OFMT
  1072. is not a floating-point format specification.
  1073. .IP "\fBOFS\fR" 10
  1074. The
  1075. .BR print
  1076. statement output field separator;
  1077. <space>
  1078. by default.
  1079. .IP "\fBORS\fR" 10
  1080. The
  1081. .BR print
  1082. statement output record separator; a
  1083. <newline>
  1084. by default.
  1085. .IP "\fBRLENGTH\fR" 10
  1086. The length of the string matched by the
  1087. .BR match
  1088. function.
  1089. .IP "\fBRS\fR" 10
  1090. The first character of the string value of
  1091. .BR RS
  1092. shall be the input record separator; a
  1093. <newline>
  1094. by default. If
  1095. .BR RS
  1096. contains more than one character, the results are unspecified. If
  1097. .BR RS
  1098. is null, then records are separated by sequences consisting of a
  1099. <newline>
  1100. plus one or more blank lines, leading or trailing blank lines shall not
  1101. result in empty records at the beginning or end of the input, and a
  1102. <newline>
  1103. shall always be a field separator, no matter what the value of
  1104. .BR FS
  1105. is.
  1106. .IP "\fBRSTART\fR" 10
  1107. The starting position of the string matched by the
  1108. .BR match
  1109. function, numbering from 1. This shall always be equivalent to the
  1110. return value of the
  1111. .BR match
  1112. function.
  1113. .IP "\fBSUBSEP\fR" 10
  1114. The subscript separator string for multi-dimensional arrays; the
  1115. default value is implementation-defined.
  1116. .SS "Regular Expressions"
  1117. .P
  1118. The
  1119. .IR awk
  1120. utility shall make use of the extended regular expression notation
  1121. (see the Base Definitions volume of POSIX.1\(hy2017,
  1122. .IR "Section 9.4" ", " "Extended Regular Expressions")
  1123. except that it shall allow the use of C-language conventions
  1124. for escaping special characters within the EREs, as specified in the
  1125. table in the Base Definitions volume of POSIX.1\(hy2017,
  1126. .IR "Chapter 5" ", " "File Format Notation"
  1127. (\c
  1128. .BR '\e\e' ,
  1129. .BR '\ea' ,
  1130. .BR '\eb' ,
  1131. .BR '\ef' ,
  1132. .BR '\en' ,
  1133. .BR '\er' ,
  1134. .BR '\et' ,
  1135. .BR '\ev' )
  1136. and the following table; these escape sequences shall be recognized
  1137. both inside and outside bracket expressions. Note that records need not
  1138. be separated by
  1139. <newline>
  1140. characters and string constants can contain
  1141. <newline>
  1142. characters, so even the
  1143. .BR \(dq\en\(dq 
  1144. sequence is valid in
  1145. .IR awk
  1146. EREs. Using a
  1147. <slash>
  1148. character within an ERE requires the escaping shown in the following
  1149. table.
  1150. .br
  1151. .sp
  1152. .ce 1
  1153. \fBTable 4-2: Escape Sequences in \fIawk\fP\fR
  1154. .ad l
  1155. .TS
  1156. center tab(@) box;
  1157. cB | cB | cB
  1158. cB | cB | cB
  1159. lf5 | lw(34) | lw(34).
  1160. Escape
  1161. Sequence@Description@Meaning
  1162. _
  1163. \e"@T{
  1164. <backslash> <quotation-mark>
  1165. T}@T{
  1166. <quotation-mark> character
  1167. T}
  1168. _
  1169. \e/@T{
  1170. <backslash> <slash>
  1171. T}@T{
  1172. <slash> character
  1173. T}
  1174. _
  1175. \eddd@T{
  1176. A
  1177. <backslash>
  1178. character followed by the longest sequence of one, two, or
  1179. three octal-digit characters (01234567). If all of the digits are 0
  1180. (that is, representation of the NUL character), the behavior is
  1181. undefined.
  1182. T}@T{
  1183. The character whose encoding is represented by the one, two, or
  1184. three-digit octal integer. Multi-byte characters require
  1185. multiple, concatenated escape sequences of this type, including the
  1186. leading
  1187. <backslash>
  1188. for each byte.
  1189. T}
  1190. _
  1191. \ec@T{
  1192. A
  1193. <backslash>
  1194. character followed by any character not described in this
  1195. table or in the table in the Base Definitions volume of POSIX.1\(hy2017,
  1196. .IR "Chapter 5" ", " "File Format Notation"
  1197. (\c
  1198. .BR '\e\e' ,
  1199. .BR '\ea' ,
  1200. .BR '\eb' ,
  1201. .BR '\ef' ,
  1202. .BR '\en' ,
  1203. .BR '\er' ,
  1204. .BR '\et' ,
  1205. .BR '\ev' ).
  1206. T}@Undefined
  1207. .TE
  1208. .ad b
  1209. .P
  1210. A regular expression can be matched against a specific field or string
  1211. by using one of the two regular expression matching operators,
  1212. .BR '\(ti' 
  1213. and
  1214. .BR \(dq!\(ti\(dq .
  1215. These operators shall interpret their right-hand operand as a regular
  1216. expression and their left-hand operand as a string. If the regular
  1217. expression matches the string, the
  1218. .BR '\(ti' 
  1219. expression shall evaluate to a value of 1, and the
  1220. .BR \(dq!\(ti\(dq 
  1221. expression shall evaluate to a value of 0. (The regular expression
  1222. matching operation is as defined by the term matched in the Base Definitions volume of POSIX.1\(hy2017,
  1223. .IR "Section 9.1" ", " "Regular Expression Definitions",
  1224. where a match occurs on any part of the string unless the regular
  1225. expression is limited with the
  1226. <circumflex>
  1227. or
  1228. <dollar-sign>
  1229. special characters.) If the regular expression does not match the
  1230. string, the
  1231. .BR '\(ti' 
  1232. expression shall evaluate to a value of 0, and the
  1233. .BR \(dq!\(ti\(dq 
  1234. expression shall evaluate to a value of 1. If the right-hand operand is
  1235. any expression other than the lexical token
  1236. .BR ERE ,
  1237. the string value of the expression shall be interpreted as an extended
  1238. regular expression, including the escape conventions described above.
  1239. Note that these same escape conventions shall also be applied in
  1240. determining the value of a string literal (the lexical token
  1241. .BR STRING ),
  1242. and thus shall be applied a second time when a string literal is used
  1243. in this context.
  1244. .P
  1245. When an
  1246. .BR ERE
  1247. token appears as an expression in any context other than as the
  1248. right-hand of the
  1249. .BR '\(ti' 
  1250. or
  1251. .BR \(dq!\(ti\(dq 
  1252. operator or as one of the built-in function arguments described below,
  1253. the value of the resulting expression shall be the equivalent of:
  1254. .sp
  1255. .RS 4
  1256. .nf
  1258. $0 \(ti /\fIere\fR/
  1259. .fi
  1260. .P
  1261. .RE
  1262. .P
  1263. The
  1264. .IR ere
  1265. argument to the
  1266. .BR gsub ,
  1267. .BR match ,
  1268. .BR sub
  1269. functions, and the
  1270. .IR fs
  1271. argument to the
  1272. .BR split
  1273. function (see
  1274. .IR "String Functions")
  1275. shall be interpreted as extended regular expressions. These can be
  1276. either
  1277. .BR ERE
  1278. tokens or arbitrary expressions, and shall be interpreted in the same
  1279. manner as the right-hand side of the
  1280. .BR '\(ti' 
  1281. or
  1282. .BR \(dq!\(ti\(dq 
  1283. operator.
  1284. .P
  1285. An extended regular expression can be used to separate fields by assigning
  1286. a string containing the expression to the built-in variable
  1287. .BR FS ,
  1288. either directly or as a consequence of using the
  1289. .BR \-F
  1290. .IR sepstring
  1291. option.
  1292. The default value of the
  1293. .BR FS
  1294. variable shall be a single
  1295. <space>.
  1296. The following describes
  1297. .BR FS
  1298. behavior:
  1299. .IP " 1." 4
  1300. If
  1301. .BR FS
  1302. is a null string, the behavior is unspecified.
  1303. .IP " 2." 4
  1304. If
  1305. .BR FS
  1306. is a single character:
  1307. .RS 4 
  1308. .IP " a." 4
  1309. If
  1310. .BR FS
  1311. is
  1312. <space>,
  1313. skip leading and trailing
  1314. <blank>
  1315. and
  1316. <newline>
  1317. characters; fields shall be delimited by sets of one or more
  1318. <blank>
  1319. or
  1320. <newline>
  1321. characters.
  1322. .IP " b." 4
  1323. Otherwise, if
  1324. .BR FS
  1325. is any other character
  1326. .IR c ,
  1327. fields shall be delimited by each single occurrence of
  1328. .IR c .
  1329. .RE
  1330. .IP " 3." 4
  1331. Otherwise, the string value of
  1332. .BR FS
  1333. shall be considered to be an extended regular expression. Each
  1334. occurrence of a sequence matching the extended regular expression shall
  1335. delimit fields.
  1336. .P
  1337. Except for the
  1338. .BR '\(ti' 
  1339. and
  1340. .BR \(dq!\(ti\(dq 
  1341. operators, and in the
  1342. .BR gsub ,
  1343. .BR match ,
  1344. .BR split ,
  1345. and
  1346. .BR sub
  1347. built-in functions, ERE matching shall be based on input records; that
  1348. is, record separator characters (the first character of the value of
  1349. the variable
  1350. .BR RS ,
  1351. <newline>
  1352. by default) cannot be embedded in the expression, and no expression
  1353. shall match the record separator character. If the record separator is
  1354. not
  1355. <newline>,
  1356. <newline>
  1357. characters embedded in the expression can be matched. For the
  1358. .BR '\(ti' 
  1359. and
  1360. .BR \(dq!\(ti\(dq 
  1361. operators, and in those four built-in functions, ERE matching shall be
  1362. based on text strings; that is, any character (including
  1363. <newline>
  1364. and the record separator) can be embedded in the pattern, and an
  1365. appropriate pattern shall match any character. However, in all
  1366. .IR awk
  1367. ERE matching, the use of one or more NUL characters in the pattern,
  1368. input record, or text string produces undefined results.
  1369. .SS "Patterns"
  1370. .P
  1371. A
  1372. .IR pattern
  1373. is any valid
  1374. .IR expression ,
  1375. a range specified by two expressions separated by a comma, or one of the
  1376. two special patterns
  1377. .BR BEGIN
  1378. or
  1379. .BR END .
  1380. .SS "Special Patterns"
  1381. .P
  1382. The
  1383. .IR awk
  1384. utility shall recognize two special patterns,
  1385. .BR BEGIN
  1386. and
  1387. .BR END .
  1388. Each
  1389. .BR BEGIN
  1390. pattern shall be matched once and its associated action executed before
  1391. the first record of input is read\(emexcept possibly by use of the
  1392. .BR getline
  1393. function (see
  1394. .IR "Input/Output and General Functions")
  1395. in a prior
  1396. .BR BEGIN
  1397. action\(emand before command line assignment is done. Each
  1398. .BR END
  1399. pattern shall be matched once and its associated action executed after
  1400. the last record of input has been read. These two patterns shall have
  1401. associated actions.
  1402. .P
  1403. .BR BEGIN
  1404. and
  1405. .BR END
  1406. shall not combine with other patterns. Multiple
  1407. .BR BEGIN
  1408. and
  1409. .BR END
  1410. patterns shall be allowed. The actions associated with the
  1411. .BR BEGIN
  1412. patterns shall be executed in the order specified in the program, as
  1413. are the
  1414. .BR END
  1415. actions. An
  1416. .BR END
  1417. pattern can precede a
  1418. .BR BEGIN
  1419. pattern in a program.
  1420. .P
  1421. If an
  1422. .IR awk
  1423. program consists of only actions with the pattern
  1424. .BR BEGIN ,
  1425. and the
  1426. .BR BEGIN
  1427. action contains no
  1428. .BR getline
  1429. function,
  1430. .IR awk
  1431. shall exit without reading its input when the last statement in the
  1432. last
  1433. .BR BEGIN
  1434. action is executed. If an
  1435. .IR awk
  1436. program consists of only actions with the pattern
  1437. .BR END
  1438. or only actions with the patterns
  1439. .BR BEGIN
  1440. and
  1441. .BR END ,
  1442. the input shall be read before the statements in the
  1443. .BR END
  1444. actions are executed.
  1445. .SS "Expression Patterns"
  1446. .P
  1447. An expression pattern shall be evaluated as if it were an expression in
  1448. a Boolean context. If the result is true, the pattern shall be
  1449. considered to match, and the associated action (if any) shall be
  1450. executed. If the result is false, the action shall not be executed.
  1451. .SS "Pattern Ranges"
  1452. .P
  1453. A pattern range consists of two expressions separated by a comma; in
  1454. this case, the action shall be performed for all records between a
  1455. match of the first expression and the following match of the second
  1456. expression, inclusive. At this point, the pattern range can be repeated
  1457. starting at input records subsequent to the end of the matched range.
  1458. .SS "Actions"
  1459. .P
  1460. An action is a sequence of statements as shown in the grammar in
  1461. .IR "Grammar".
  1462. Any single statement can be replaced by a statement list enclosed in
  1463. curly braces. The application shall ensure that statements in a
  1464. statement list are separated by
  1465. <newline>
  1466. or
  1467. <semicolon>
  1468. characters. Statements in a statement list shall be executed sequentially
  1469. in the order that they appear.
  1470. .P
  1471. The
  1472. .IR expression
  1473. acting as the conditional in an
  1474. .BR if
  1475. statement shall be evaluated and if it is non-zero or non-null, the
  1476. following statement shall be executed; otherwise, if
  1477. .BR else
  1478. is present, the statement following the
  1479. .BR else
  1480. shall be executed.
  1481. .P
  1482. The
  1483. .BR if ,
  1484. .BR while ,
  1485. .BR do .\|.\|.\c
  1486. .BR while ,
  1487. .BR for ,
  1488. .BR break ,
  1489. and
  1490. .BR continue
  1491. statements are based on the ISO\ C standard (see
  1492. .IR "Section 1.1.2" ", " "Concepts Derived from the ISO C Standard"),
  1493. except that the Boolean expressions shall be treated as described in
  1494. .IR "Expressions in awk",
  1495. and except in the case of:
  1496. .sp
  1497. .RS 4
  1498. .nf
  1500. for (\fIvariable\fR in \fIarray\fR)
  1501. .fi
  1502. .P
  1503. .RE
  1504. .P
  1505. which shall iterate, assigning each
  1506. .IR index
  1507. of
  1508. .IR array
  1509. to
  1510. .IR variable
  1511. in an unspecified order. The results of adding new elements to
  1512. .IR array
  1513. within such a
  1514. .BR for
  1515. loop are undefined. If a
  1516. .BR break
  1517. or
  1518. .BR continue
  1519. statement occurs outside of a loop, the behavior is undefined.
  1520. .P
  1521. The
  1522. .BR delete
  1523. statement shall remove an individual array element. Thus, the following
  1524. code deletes an entire array:
  1525. .sp
  1526. .RS 4
  1527. .nf
  1529. for (index in array)
  1530.     delete array[index]
  1531. .fi
  1532. .P
  1533. .RE
  1534. .P
  1535. The
  1536. .BR next
  1537. statement shall cause all further processing of the current input
  1538. record to be abandoned. The behavior is undefined if a
  1539. .BR next
  1540. statement appears or is invoked in a
  1541. .BR BEGIN
  1542. or
  1543. .BR END
  1544. action.
  1545. .P
  1546. The
  1547. .BR exit
  1548. statement shall invoke all
  1549. .BR END
  1550. actions in the order in which they occur in the program source and then
  1551. terminate the program without reading further input. An
  1552. .BR exit
  1553. statement inside an
  1554. .BR END
  1555. action shall terminate the program without further execution of
  1556. .BR END
  1557. actions. If an expression is specified in an
  1558. .BR exit
  1559. statement, its numeric value shall be the exit status of
  1560. .IR awk ,
  1561. unless subsequent errors are encountered or a subsequent
  1562. .BR exit
  1563. statement with an expression is executed.
  1564. .SS "Output Statements"
  1565. .P
  1566. Both
  1567. .BR print
  1568. and
  1569. .BR printf
  1570. statements shall write to standard output by default. The output shall
  1571. be written to the location specified by
  1572. .IR output_redirection
  1573. if one is supplied, as follows:
  1574. .sp
  1575. .RS 4
  1576. .nf
  1578. > \fIexpression\fR
  1579. >> \fIexpression\fR
  1580. | \fIexpression\fR
  1581. .fi
  1582. .P
  1583. .RE
  1584. .P
  1585. In all cases, the
  1586. .IR expression
  1587. shall be evaluated to produce a string that is used as a pathname
  1588. into which to write (for
  1589. .BR '>' 
  1590. or
  1591. .BR \(dq>>\(dq )
  1592. or as a command to be executed (for
  1593. .BR '|' ).
  1594. Using the first two forms, if the file of that name is not currently
  1595. open, it shall be opened, creating it if necessary and using the first
  1596. form, truncating the file. The output then shall be appended to the
  1597. file. As long as the file remains open, subsequent calls in which
  1598. .IR expression
  1599. evaluates to the same string value shall simply append output to the
  1600. file. The file remains open until the
  1601. .BR close
  1602. function (see
  1603. .IR "Input/Output and General Functions")
  1604. is called with an expression that evaluates to the same string value.
  1605. .P
  1606. The third form shall write output onto a stream piped to the input of a
  1607. command. The stream shall be created if no stream is currently open
  1608. with the value of
  1609. .IR expression
  1610. as its command name. The stream created shall be equivalent to one
  1611. created by a call to the
  1612. \fIpopen\fR()
  1613. function defined in the System Interfaces volume of POSIX.1\(hy2017 with the value of
  1614. .IR expression
  1615. as the
  1616. .IR command
  1617. argument and a value of
  1618. .IR w
  1619. as the
  1620. .IR mode
  1621. argument. As long as the stream remains open, subsequent calls in which
  1622. .IR expression
  1623. evaluates to the same string value shall write output to the existing
  1624. stream. The stream shall remain open until the
  1625. .BR close
  1626. function (see
  1627. .IR "Input/Output and General Functions")
  1628. is called with an expression that evaluates to the same string value.
  1629. At that time, the stream shall be closed as if by a call to the
  1630. \fIpclose\fR()
  1631. function defined in the System Interfaces volume of POSIX.1\(hy2017.
  1632. .P
  1633. As described in detail by the grammar in
  1634. .IR "Grammar",
  1635. these output statements shall take a
  1636. <comma>-separated
  1637. list of
  1638. .IR expression s
  1639. referred to in the grammar by the non-terminal symbols
  1640. .BR expr_list ,
  1641. .BR print_expr_list ,
  1642. or
  1643. .BR print_expr_list_opt .
  1644. This list is referred to here as the
  1645. .IR "expression list" ,
  1646. and each member is referred to as an
  1647. .IR "expression argument" .
  1648. .P
  1649. The
  1650. .BR print
  1651. statement shall write the value of each expression argument onto the
  1652. indicated output stream separated by the current output field separator
  1653. (see variable
  1654. .BR OFS
  1655. above), and terminated by the output record separator (see variable
  1656. .BR ORS
  1657. above). All expression arguments shall be taken as strings, being
  1658. converted if necessary; this conversion shall be as described in
  1659. .IR "Expressions in awk",
  1660. with the exception that the
  1661. .BR printf
  1662. format in
  1663. .BR OFMT
  1664. shall be used instead of the value in
  1665. .BR CONVFMT .
  1666. An empty expression list shall stand for the whole input record ($0).
  1667. .P
  1668. The
  1669. .BR printf
  1670. statement shall produce output based on a notation similar to the
  1671. File Format Notation used to describe file formats in this volume of POSIX.1\(hy2017 (see the Base Definitions volume of POSIX.1\(hy2017,
  1672. .IR "Chapter 5" ", " "File Format Notation").
  1673. Output shall be produced as specified with the first
  1674. .IR expression
  1675. argument as the string
  1676. .IR format
  1677. and subsequent
  1678. .IR expression
  1679. arguments as the strings
  1680. .IR arg1
  1681. to
  1682. .IR argn ,
  1683. inclusive, with the following exceptions:
  1684. .IP " 1." 4
  1685. The
  1686. .IR format
  1687. shall be an actual character string rather than a graphical
  1688. representation. Therefore, it cannot contain empty character
  1689. positions. The
  1690. <space>
  1691. in the
  1692. .IR format
  1693. string, in any context other than a
  1694. .IR flag
  1695. of a conversion specification, shall be treated as an ordinary
  1696. character that is copied to the output.
  1697. .IP " 2." 4
  1698. If the character set contains a
  1699. .BR ' ' 
  1700. character and that character appears in the
  1701. .IR format
  1702. string, it shall be treated as an ordinary character that is copied to
  1703. the output.
  1704. .IP " 3." 4
  1705. The
  1706. .IR "escape sequences"
  1707. beginning with a
  1708. <backslash>
  1709. character shall be treated as sequences of ordinary characters that are
  1710. copied to the output. Note that these same sequences shall be interpreted
  1711. lexically by
  1712. .IR awk
  1713. when they appear in literal strings, but they shall not be treated
  1714. specially by the
  1715. .BR printf
  1716. statement.
  1717. .IP " 4." 4
  1718. A
  1719. .IR "field width"
  1720. or
  1721. .IR precision
  1722. can be specified as the
  1723. .BR '*' 
  1724. character instead of a digit string. In this case the next argument
  1725. from the expression list shall be fetched and its numeric value taken
  1726. as the field width or precision.
  1727. .IP " 5." 4
  1728. The implementation shall not precede or follow output from the
  1729. .BR d
  1730. or
  1731. .BR u
  1732. conversion specifier characters with
  1733. <blank>
  1734. characters not specified by the
  1735. .IR format
  1736. string.
  1737. .IP " 6." 4
  1738. The implementation shall not precede output from the
  1739. .BR o
  1740. conversion specifier character with leading zeros not specified by the
  1741. .IR format
  1742. string.
  1743. .IP " 7." 4
  1744. For the
  1745. .BR c
  1746. conversion specifier character: if the argument has a numeric value, the
  1747. character whose encoding is that value shall be output. If the value is
  1748. zero or is not the encoding of any character in the character set, the
  1749. behavior is undefined. If the argument does not have a numeric value,
  1750. the first character of the string value shall be output; if the string
  1751. does not contain any characters, the behavior is undefined.
  1752. .IP " 8." 4
  1753. For each conversion specification that consumes an argument, the next
  1754. expression argument shall be evaluated. With the exception of the
  1755. .BR c
  1756. conversion specifier character, the value shall be converted (according
  1757. to the rules specified in
  1758. .IR "Expressions in awk")
  1759. to the appropriate type for the conversion specification.
  1760. .IP " 9." 4
  1761. If there are insufficient expression arguments to satisfy all the
  1762. conversion specifications in the
  1763. .IR format
  1764. string, the behavior is undefined.
  1765. .IP 10. 4
  1766. If any character sequence in the
  1767. .IR format
  1768. string begins with a
  1769. .BR '%' 
  1770. character, but does not form a valid conversion specification, the
  1771. behavior is unspecified.
  1772. .P
  1773. Both
  1774. .BR print
  1775. and
  1776. .BR printf
  1777. can output at least
  1778. {LINE_MAX}
  1779. bytes.
  1780. .SS "Functions"
  1781. .P
  1782. The
  1783. .IR awk
  1784. language has a variety of built-in functions: arithmetic, string,
  1785. input/output, and general.
  1786. .SS "Arithmetic Functions"
  1787. .P
  1788. The arithmetic functions, except for
  1789. .BR int ,
  1790. shall be based on the ISO\ C standard (see
  1791. .IR "Section 1.1.2" ", " "Concepts Derived from the ISO C Standard").
  1792. The behavior is undefined in cases where the ISO\ C standard specifies that an
  1793. error be returned or that the behavior is undefined. Although the
  1794. grammar (see
  1795. .IR "Grammar")
  1796. permits built-in functions to appear with no arguments or parentheses,
  1797. unless the argument or parentheses are indicated as optional in the
  1798. following list (by displaying them within the
  1799. .BR \(dq[]\(dq 
  1800. brackets), such use is undefined.
  1801. .IP "\fBatan2\fR(\fIy\fR,\fIx\fR)" 10
  1802. Return arctangent of \fIy\fP/\fIx\fR in radians in the range
  1803. [\-\(*p,\(*p].
  1804. .IP "\fBcos\fR(\fIx\fR)" 10
  1805. Return cosine of \fIx\fP, where \fIx\fP is in radians.
  1806. .IP "\fBsin\fR(\fIx\fR)" 10
  1807. Return sine of \fIx\fP, where \fIx\fP is in radians.
  1808. .IP "\fBexp\fR(\fIx\fR)" 10
  1809. Return the exponential function of \fIx\fP.
  1810. .IP "\fBlog\fR(\fIx\fR)" 10
  1811. Return the natural logarithm of \fIx\fP.
  1812. .IP "\fBsqrt\fR(\fIx\fR)" 10
  1813. Return the square root of \fIx\fP.
  1814. .IP "\fBint\fR(\fIx\fR)" 10
  1815. Return the argument truncated to an integer. Truncation shall
  1816. be toward 0 when \fIx\fP>0.
  1817. .IP "\fBrand\fP(\|)" 10
  1818. Return a random number \fIn\fP, such that 0\(<=\fIn\fP<1.
  1819. .IP "\fBsrand\fR(\fB[\fIexpr\fB]\fR)" 10
  1820. Set the seed value for
  1821. .IR rand
  1822. to
  1823. .IR expr
  1824. or use the time of day if
  1825. .IR expr
  1826. is omitted. The previous seed value shall be returned.
  1827. .SS "String Functions"
  1828. .P
  1829. The string functions in the following list shall be supported.
  1830. Although the grammar (see
  1831. .IR "Grammar")
  1832. permits built-in functions to appear with no arguments or parentheses,
  1833. unless the argument or parentheses are indicated as optional in the
  1834. following list (by displaying them within the
  1835. .BR \(dq[]\(dq 
  1836. brackets), such use is undefined.
  1837. .IP "\fBgsub\fR(\fIere\fR,\ \fIrepl\fB[\fR,\ \fIin\fB]\fR)" 10
  1838. .br
  1839. Behave like
  1840. .BR sub
  1841. (see below), except that it shall replace all occurrences of the
  1842. regular expression (like the
  1843. .IR ed
  1844. utility global substitute) in $0 or in the
  1845. .IR in
  1846. argument, when specified.
  1847. .IP "\fBindex\fR(\fIs\fR,\ \fIt\fR)" 10
  1848. Return the position, in characters, numbering from 1, in string
  1849. .IR s
  1850. where string
  1851. .IR t
  1852. first occurs, or zero if it does not occur at all.
  1853. .IP "\fBlength[\fR(\fB[\fIs\fB]\fR)\fB]\fR" 10
  1854. Return the length, in characters, of its argument taken as a string, or
  1855. of the whole record, $0, if there is no argument.
  1856. .IP "\fBmatch\fR(\fIs\fR,\ \fIere\fR)" 10
  1857. Return the position, in characters, numbering from 1, in string
  1858. .IR s
  1859. where the extended regular expression
  1860. .IR ere
  1861. occurs, or zero if it does not occur at all. RSTART shall be set to the
  1862. starting position (which is the same as the returned value), zero if no
  1863. match is found; RLENGTH shall be set to the length of the matched
  1864. string, \-1 if no match is found.
  1865. .IP "\fBsplit\fR(\fIs\fR,\ \fIa\fB[\fR,\ \fIfs\ \fB]\fR)" 10
  1866. .br
  1867. Split the string
  1868. .IR s
  1869. into array elements
  1870. .IR a [1],
  1871. .IR a [2],
  1872. \&.\|.\|.,
  1873. .IR a [ n ],
  1874. and return
  1875. .IR n .
  1876. All elements of the array shall be deleted before the split is
  1877. performed. The separation shall be done with the ERE
  1878. .IR fs
  1879. or with the field separator
  1880. .BR FS
  1881. if
  1882. .IR fs
  1883. is not given. Each array element shall have a string value when created
  1884. and, if appropriate, the array element shall be considered a numeric
  1885. string (see
  1886. .IR "Expressions in awk").
  1887. The effect of a null string as the value of
  1888. .IR fs
  1889. is unspecified.
  1890. .IP "\fBsprintf\fR(\fIfmt\fR,\ \fIexpr\fR,\ \fIexpr\fR,\ .\|.\|.)" 10
  1891. .br
  1892. Format the expressions according to the
  1893. .BR printf
  1894. format given by
  1895. .IR fmt
  1896. and return the resulting string.
  1897. .IP "\fBsub(\fIere\fR,\ \fIrepl\fB[\fR,\ \fIin\ \fB]\fR)" 10
  1898. .br
  1899. Substitute the string
  1900. .IR repl
  1901. in place of the first instance of the extended regular expression
  1902. .IR ERE
  1903. in string
  1904. .IR in
  1905. and return the number of substitutions. An
  1906. <ampersand>
  1907. (\c
  1908. .BR '&' )
  1909. appearing in the string
  1910. .IR repl
  1911. shall be replaced by the string from
  1912. .IR in
  1913. that matches the ERE. An
  1914. <ampersand>
  1915. preceded with a
  1916. <backslash>
  1917. shall be interpreted as the literal
  1918. <ampersand>
  1919. character. An occurrence of two consecutive
  1920. <backslash>
  1921. characters shall be interpreted as just a single literal
  1922. <backslash>
  1923. character. Any other occurrence of a
  1924. <backslash>
  1925. (for example, preceding any other character) shall be treated as a
  1926. literal
  1927. <backslash>
  1928. character. Note that if
  1929. .IR repl
  1930. is a string literal (the lexical token
  1931. .BR STRING ;
  1932. see
  1933. .IR "Grammar"),
  1934. the handling of the
  1935. <ampersand>
  1936. character occurs after any lexical processing, including any lexical
  1937. <backslash>-escape
  1938. sequence processing. If
  1939. .IR in
  1940. is specified and it is not an lvalue (see
  1941. .IR "Expressions in awk"),
  1942. the behavior is undefined. If
  1943. .IR in
  1944. is omitted,
  1945. .IR awk
  1946. shall use the current record ($0) in its place.
  1947. .IP "\fBsubstr\fR(\fIs\fR,\ \fIm\fB[\fR,\ \fIn\ \fB]\fR)" 10
  1948. .br
  1949. Return the at most
  1950. .IR n -character
  1951. substring of
  1952. .IR s
  1953. that begins at position
  1954. .IR m ,
  1955. numbering from 1. If
  1956. .IR n
  1957. is omitted, or if
  1958. .IR n
  1959. specifies more characters than are left in the string, the length of
  1960. the substring shall be limited by the length of the string
  1961. .IR s .
  1962. .IP "\fBtolower\fR(\fIs\fR)" 10
  1963. Return a string based on the string
  1964. .IR s .
  1965. Each character in
  1966. .IR s
  1967. that is an uppercase letter specified to have a
  1968. .BR tolower
  1969. mapping by the
  1970. .IR LC_CTYPE
  1971. category of the current locale shall be replaced in the returned string
  1972. by the lowercase letter specified by the mapping. Other characters in
  1973. .IR s
  1974. shall be unchanged in the returned string.
  1975. .IP "\fBtoupper\fR(\fIs\fR)" 10
  1976. Return a string based on the string
  1977. .IR s .
  1978. Each character in
  1979. .IR s
  1980. that is a lowercase letter specified to have a
  1981. .BR toupper
  1982. mapping by the
  1983. .IR LC_CTYPE
  1984. category of the current locale is replaced in the returned string by
  1985. the uppercase letter specified by the mapping. Other characters in
  1986. .IR s
  1987. are unchanged in the returned string.
  1988. .P
  1989. All of the preceding functions that take
  1990. .IR ERE
  1991. as a parameter expect a pattern or a string valued expression that is a
  1992. regular expression as defined in
  1993. .IR "Regular Expressions".
  1994. .SS "Input/Output and General Functions"
  1995. .P
  1996. The input/output and general functions are:
  1997. .IP "\fBclose\fR(\fIexpression\fR)" 10
  1998. .br
  1999. Close the file or pipe opened by a
  2000. .BR print
  2001. or
  2002. .BR printf
  2003. statement or a call to
  2004. .BR getline
  2005. with the same string-valued
  2006. .IR expression .
  2007. The limit on the number of open
  2008. .IR expression
  2009. arguments is implementation-defined. If the close was successful, the
  2010. function shall return zero; otherwise, it shall return non-zero.
  2011. .IP "\fIexpression\ |\ \fBgetline\ [\fIvar\fB]\fR" 10
  2012. .br
  2013. Read a record of input from a stream piped from the output of a
  2014. command. The stream shall be created if no stream is currently open
  2015. with the value of
  2016. .IR expression
  2017. as its command name. The stream created shall be equivalent to one
  2018. created by a call to the
  2019. \fIpopen\fR()
  2020. function with the value of
  2021. .IR expression
  2022. as the
  2023. .IR command
  2024. argument and a value of
  2025. .IR r
  2026. as the
  2027. .IR mode
  2028. argument. As long as the stream remains open, subsequent calls in which
  2029. .IR expression
  2030. evaluates to the same string value shall read subsequent records from
  2031. the stream. The stream shall remain open until the
  2032. .BR close
  2033. function is called with an expression that evaluates to the same string
  2034. value. At that time, the stream shall be closed as if by a call to the
  2035. \fIpclose\fR()
  2036. function. If
  2037. .IR var
  2038. is omitted, $0 and
  2039. .BR NF
  2040. shall be set; otherwise,
  2041. .IR var
  2042. shall be set and, if appropriate, it shall be considered a numeric
  2043. string (see
  2044. .IR "Expressions in awk").
  2045. .RS 10 
  2046. .P
  2047. The
  2048. .BR getline
  2049. operator can form ambiguous constructs when there are unparenthesized
  2050. operators (including concatenate) to the left of the
  2051. .BR '|' 
  2052. (to the beginning of the expression containing
  2053. .BR getline ).
  2054. In the context of the
  2055. .BR '$' 
  2056. operator,
  2057. .BR '|' 
  2058. shall behave as if it had a lower precedence than
  2059. .BR '$' .
  2060. The result of evaluating other operators is unspecified, and conforming
  2061. applications shall parenthesize properly all such usages.
  2062. .RE
  2063. .IP "\fBgetline\fR" 10
  2064. Set $0 to the next input record from the current input file. This form
  2065. of
  2066. .BR getline
  2067. shall set the
  2068. .BR NF ,
  2069. .BR NR ,
  2070. and
  2071. .BR FNR
  2072. variables.
  2073. .IP "\fBgetline\ \fIvar\fR" 10
  2074. Set variable
  2075. .IR var
  2076. to the next input record from the current input file and, if
  2077. appropriate,
  2078. .IR var
  2079. shall be considered a numeric string (see
  2080. .IR "Expressions in awk").
  2081. This form of
  2082. .BR getline
  2083. shall set the
  2084. .BR FNR
  2085. and
  2086. .BR NR
  2087. variables.
  2088. .IP "\fBgetline\ \fB[\fIvar\fB]\ \fR<\ \fIexpression\fR" 10
  2089. .br
  2090. Read the next record of input from a named file. The
  2091. .IR expression
  2092. shall be evaluated to produce a string that is used as a pathname.
  2093. If the file of that name is not currently open, it shall be opened. As
  2094. long as the stream remains open, subsequent calls in which
  2095. .IR expression
  2096. evaluates to the same string value shall read subsequent records from
  2097. the file. The file shall remain open until the
  2098. .BR close
  2099. function is called with an expression that evaluates to the same string
  2100. value. If
  2101. .IR var
  2102. is omitted, $0 and
  2103. .BR NF
  2104. shall be set; otherwise,
  2105. .IR var
  2106. shall be set and, if appropriate, it shall be considered a numeric
  2107. string (see
  2108. .IR "Expressions in awk").
  2109. .RS 10 
  2110. .P
  2111. The
  2112. .BR getline
  2113. operator can form ambiguous constructs when there are unparenthesized
  2114. binary operators (including concatenate) to the right of the
  2115. .BR '<' 
  2116. (up to the end of the expression containing the
  2117. .BR getline ).
  2118. The result of evaluating such a construct is unspecified, and conforming
  2119. applications shall parenthesize properly all such usages.
  2120. .RE
  2121. .IP "\fBsystem\fR(\fIexpression\fR)" 10
  2122. .br
  2123. Execute the command given by
  2124. .IR expression
  2125. in a manner equivalent to the
  2126. \fIsystem\fR()
  2127. function defined in the System Interfaces volume of POSIX.1\(hy2017 and return the exit status of the
  2128. command.
  2129. .P
  2130. All forms of
  2131. .BR getline
  2132. shall return 1 for successful input, zero for end-of-file, and \-1
  2133. for an error.
  2134. .P
  2135. Where strings are used as the name of a file or pipeline, the
  2136. application shall ensure that the strings are textually identical. The
  2137. terminology ``same string value'' implies that ``equivalent strings'',
  2138. even those that differ only by
  2139. <space>
  2140. characters, represent different files.
  2141. .SS "User-Defined Functions"
  2142. .P
  2143. The
  2144. .IR awk
  2145. language also provides user-defined functions. Such functions can be
  2146. defined as:
  2147. .sp
  2148. .RS 4
  2149. .nf
  2151. function \fIname\fR(\fB[\fIparameter\fR, ...\fB]\fR) { \fIstatements\fR }
  2152. .fi
  2153. .P
  2154. .RE
  2155. .P
  2156. A function can be referred to anywhere in an
  2157. .IR awk
  2158. program; in particular, its use can precede its definition. The scope
  2159. of a function is global.
  2160. .P
  2161. Function parameters, if present, can be either scalars or arrays; the
  2162. behavior is undefined if an array name is passed as a parameter that
  2163. the function uses as a scalar, or if a scalar expression is passed as a
  2164. parameter that the function uses as an array. Function parameters shall
  2165. be passed by value if scalar and by reference if array name.
  2166. .P
  2167. The number of parameters in the function definition need not match the
  2168. number of parameters in the function call. Excess formal parameters can
  2169. be used as local variables. If fewer arguments are supplied in a
  2170. function call than are in the function definition, the extra parameters
  2171. that are used in the function body as scalars shall evaluate to the
  2172. uninitialized value until they are otherwise initialized, and the extra
  2173. parameters that are used in the function body as arrays shall be
  2174. treated as uninitialized arrays where each element evaluates to the
  2175. uninitialized value until otherwise initialized.
  2176. .P
  2177. When invoking a function, no white space can be placed between the
  2178. function name and the opening parenthesis. Function calls can be nested
  2179. and recursive calls can be made upon functions. Upon return from any
  2180. nested or recursive function call, the values of all of the calling
  2181. function's parameters shall be unchanged, except for array parameters
  2182. passed by reference. The
  2183. .BR return
  2184. statement can be used to return a value. If a
  2185. .BR return
  2186. statement appears outside of a function definition, the behavior is
  2187. undefined.
  2188. .P
  2189. In the function definition,
  2190. <newline>
  2191. characters shall be optional before the opening brace and after the
  2192. closing brace. Function definitions can appear anywhere in the program
  2193. where a
  2194. .IR pattern-action
  2195. pair is allowed.
  2196. .SS "Grammar"
  2197. .P
  2198. The grammar in this section and the lexical conventions in the
  2199. following section shall together describe the syntax for
  2200. .IR awk
  2201. programs. The general conventions for this style of grammar are
  2202. described in
  2203. .IR "Section 1.3" ", " "Grammar Conventions".
  2204. A valid program can be represented as the non-terminal symbol
  2205. .IR program
  2206. in the grammar. This formal syntax shall take precedence over the
  2207. preceding text syntax description.
  2208. .sp
  2209. .RS 4
  2210. .nf
  2212. %token NAME NUMBER STRING ERE
  2213. %token FUNC_NAME   /* Name followed by \(aq(\(aq without white space. */
  2214. .P
  2215. /* Keywords */
  2216. %token       Begin   End
  2217. /*          \(aqBEGIN\(aq \(aqEND\(aq                            */
  2218. .P
  2219. %token       Break   Continue   Delete   Do   Else
  2220. /*          \(aqbreak\(aq \(aqcontinue\(aq \(aqdelete\(aq \(aqdo\(aq \(aqelse\(aq  */
  2221. .P
  2222. %token       Exit   For   Function   If   In
  2223. /*          \(aqexit\(aq \(aqfor\(aq \(aqfunction\(aq \(aqif\(aq \(aqin\(aq        */
  2224. .P
  2225. %token       Next   Print   Printf   Return   While
  2226. /*          \(aqnext\(aq \(aqprint\(aq \(aqprintf\(aq \(aqreturn\(aq \(aqwhile\(aq */
  2227. .P
  2228. /* Reserved function names */
  2229. %token BUILTIN_FUNC_NAME
  2230.             /* One token for the following:
  2231.              * atan2 cos sin exp log sqrt int rand srand
  2232.              * gsub index length match split sprintf sub
  2233.              * substr tolower toupper close system
  2234.              */
  2235. %token GETLINE
  2236.             /* Syntactically different from other built-ins. */
  2237. .P
  2238. /* Two-character tokens. */
  2239. %token ADD_ASSIGN SUB_ASSIGN MUL_ASSIGN DIV_ASSIGN MOD_ASSIGN POW_ASSIGN
  2240. /*     \(aq+=\(aq       \(aq-=\(aq       \(aq*=\(aq       \(aq/=\(aq       \(aq%=\(aq       \(aq\(ha=\(aq */
  2241. .P
  2242. %token OR   AND  NO_MATCH   EQ   LE   GE   NE   INCR  DECR  APPEND
  2243. /*     \(aq||\(aq \(aq&&\(aq \(aq!\^\(ti\(aq \(aq==\(aq \(aq<=\(aq \(aq>=\(aq \(aq!=\(aq \(aq++\(aq  \(aq--\(aq  \(aq>>\(aq   */
  2244. .P
  2245. /* One-character tokens. */
  2246. %token \(aq{\(aq \(aq}\(aq \(aq(\(aq \(aq)\(aq \(aq[\(aq \(aq]\(aq \(aq,\(aq \(aq;\(aq NEWLINE
  2247. %token \(aq+\(aq \(aq-\(aq \(aq*\(aq \(aq%\(aq \(aq\(ha\(aq \(aq!\(aq \(aq>\(aq \(aq<\(aq \(aq|\(aq \(aq?\(aq \(aq:\(aq \(aq\(ti\(aq \(aq$\(aq \(aq=\(aq
  2248. .P
  2249. %start program
  2250. %%
  2251. .P
  2252. program          : item_list
  2253.                  | item_list item
  2254.                  ;
  2255. .P
  2256. item_list        : /* empty */
  2257.                  | item_list item terminator
  2258.                  ;
  2259. .P
  2260. item             : action
  2261.                  | pattern action
  2262.                  | normal_pattern
  2263.                  | Function NAME      \(aq(\(aq param_list_opt \(aq)\(aq
  2264.                        newline_opt action
  2265.                  | Function FUNC_NAME \(aq(\(aq param_list_opt \(aq)\(aq
  2266.                        newline_opt action
  2267.                  ;
  2268. .P
  2269. param_list_opt   : /* empty */
  2270.                  | param_list
  2271.                  ;
  2272. .P
  2273. param_list       : NAME
  2274.                  | param_list \(aq,\(aq NAME
  2275.                  ;
  2276. .P
  2277. pattern          : normal_pattern
  2278.                  | special_pattern
  2279.                  ;
  2280. .P
  2281. normal_pattern   : expr
  2282.                  | expr \(aq,\(aq newline_opt expr
  2283.                  ;
  2284. .P
  2285. special_pattern  : Begin
  2286.                  | End
  2287.                  ;
  2288. .P
  2289. action           : \(aq{\(aq newline_opt                             \(aq}\(aq
  2290.                  | \(aq{\(aq newline_opt terminated_statement_list   \(aq}\(aq
  2291.                  | \(aq{\(aq newline_opt unterminated_statement_list \(aq}\(aq
  2292.                  ;
  2293. .P
  2294. terminator       : terminator NEWLINE
  2295.                  |            \(aq;\(aq
  2296.                  |            NEWLINE
  2297.                  ;
  2298. .P
  2299. terminated_statement_list : terminated_statement
  2300.                  | terminated_statement_list terminated_statement
  2301.                  ;
  2302. .P
  2303. unterminated_statement_list : unterminated_statement
  2304.                  | terminated_statement_list unterminated_statement
  2305.                  ;
  2306. .P
  2307. terminated_statement : action newline_opt
  2308.                  | If \(aq(\(aq expr \(aq)\(aq newline_opt terminated_statement
  2309.                  | If \(aq(\(aq expr \(aq)\(aq newline_opt terminated_statement
  2310.                        Else newline_opt terminated_statement
  2311.                  | While \(aq(\(aq expr \(aq)\(aq newline_opt terminated_statement
  2312.                  | For \(aq(\(aq simple_statement_opt \(aq;\(aq
  2313.                       expr_opt \(aq;\(aq simple_statement_opt \(aq)\(aq newline_opt
  2314.                       terminated_statement
  2315.                  | For \(aq(\(aq NAME In NAME \(aq)\(aq newline_opt
  2316.                       terminated_statement
  2317.                  | \(aq;\(aq newline_opt
  2318.                  | terminatable_statement NEWLINE newline_opt
  2319.                  | terminatable_statement \(aq;\(aq     newline_opt
  2320.                  ;
  2321. .P
  2322. unterminated_statement : terminatable_statement
  2323.                  | If \(aq(\(aq expr \(aq)\(aq newline_opt unterminated_statement
  2324.                  | If \(aq(\(aq expr \(aq)\(aq newline_opt terminated_statement
  2325.                       Else newline_opt unterminated_statement
  2326.                  | While \(aq(\(aq expr \(aq)\(aq newline_opt unterminated_statement
  2327.                  | For \(aq(\(aq simple_statement_opt \(aq;\(aq
  2328.                   expr_opt \(aq;\(aq simple_statement_opt \(aq)\(aq newline_opt
  2329.                       unterminated_statement
  2330.                  | For \(aq(\(aq NAME In NAME \(aq)\(aq newline_opt
  2331.                       unterminated_statement
  2332.                  ;
  2333. .P
  2334. terminatable_statement : simple_statement
  2335.                  | Break
  2336.                  | Continue
  2337.                  | Next
  2338.                  | Exit expr_opt
  2339.                  | Return expr_opt
  2340.                  | Do newline_opt terminated_statement While \(aq(\(aq expr \(aq)\(aq
  2341.                  ;
  2342. .P
  2343. simple_statement_opt : /* empty */
  2344.                  | simple_statement
  2345.                  ;
  2346. .P
  2347. simple_statement : Delete NAME \(aq[\(aq expr_list \(aq]\(aq
  2348.                  | expr
  2349.                  | print_statement
  2350.                  ;
  2351. .P
  2352. print_statement  : simple_print_statement
  2353.                  | simple_print_statement output_redirection
  2354.                  ;
  2355. .P
  2356. simple_print_statement : Print  print_expr_list_opt
  2357.                  | Print  \(aq(\(aq multiple_expr_list \(aq)\(aq
  2358.                  | Printf print_expr_list
  2359.                  | Printf \(aq(\(aq multiple_expr_list \(aq)\(aq
  2360.                  ;
  2361. .P
  2362. output_redirection : \(aq>\(aq    expr
  2363.                  | APPEND expr
  2364.                  | \(aq|\(aq    expr
  2365.                  ;
  2366. .P
  2367. expr_list_opt    : /* empty */
  2368.                  | expr_list
  2369.                  ;
  2370. .P
  2371. expr_list        : expr
  2372.                  | multiple_expr_list
  2373.                  ;
  2374. .P
  2375. multiple_expr_list : expr \(aq,\(aq newline_opt expr
  2376.                  | multiple_expr_list \(aq,\(aq newline_opt expr
  2377.                  ;
  2378. .P
  2379. expr_opt         : /* empty */
  2380.                  | expr
  2381.                  ;
  2382. .P
  2383. expr             : unary_expr
  2384.                  | non_unary_expr
  2385.                  ;
  2386. .P
  2387. unary_expr       : \(aq+\(aq expr
  2388.                  | \(aq-\(aq expr
  2389.                  | unary_expr \(aq\(ha\(aq      expr
  2390.                  | unary_expr \(aq*\(aq      expr
  2391.                  | unary_expr \(aq/\(aq      expr
  2392.                  | unary_expr \(aq%\(aq      expr
  2393.                  | unary_expr \(aq+\(aq      expr
  2394.                  | unary_expr \(aq-\(aq      expr
  2395.                  | unary_expr          non_unary_expr
  2396.                  | unary_expr \(aq<\(aq      expr
  2397.                  | unary_expr LE       expr
  2398.                  | unary_expr NE       expr
  2399.                  | unary_expr EQ       expr
  2400.                  | unary_expr \(aq>\(aq      expr
  2401.                  | unary_expr GE       expr
  2402.                  | unary_expr \(aq\(ti\(aq      expr
  2403.                  | unary_expr NO_MATCH expr
  2404.                  | unary_expr In NAME
  2405.                  | unary_expr AND newline_opt expr
  2406.                  | unary_expr OR  newline_opt expr
  2407.                  | unary_expr \(aq?\(aq expr \(aq:\(aq expr
  2408.                  | unary_input_function
  2409.                  ;
  2410. .P
  2411. non_unary_expr   : \(aq(\(aq expr \(aq)\(aq
  2412.                  | \(aq!\(aq expr
  2413.                  | non_unary_expr \(aq\(ha\(aq      expr
  2414.                  | non_unary_expr \(aq*\(aq      expr
  2415.                  | non_unary_expr \(aq/\(aq      expr
  2416.                  | non_unary_expr \(aq%\(aq      expr
  2417.                  | non_unary_expr \(aq+\(aq      expr
  2418.                  | non_unary_expr \(aq-\(aq      expr
  2419.                  | non_unary_expr          non_unary_expr
  2420.                  | non_unary_expr \(aq<\(aq      expr
  2421.                  | non_unary_expr LE       expr
  2422.                  | non_unary_expr NE       expr
  2423.                  | non_unary_expr EQ       expr
  2424.                  | non_unary_expr \(aq>\(aq      expr
  2425.                  | non_unary_expr GE       expr
  2426.                  | non_unary_expr \(aq\(ti\(aq      expr
  2427.                  | non_unary_expr NO_MATCH expr
  2428.                  | non_unary_expr In NAME
  2429.                  | \(aq(\(aq multiple_expr_list \(aq)\(aq In NAME
  2430.                  | non_unary_expr AND newline_opt expr
  2431.                  | non_unary_expr OR  newline_opt expr
  2432.                  | non_unary_expr \(aq?\(aq expr \(aq:\(aq expr
  2433.                  | NUMBER
  2434.                  | STRING
  2435.                  | lvalue
  2436.                  | ERE
  2437.                  | lvalue INCR
  2438.                  | lvalue DECR
  2439.                  | INCR lvalue
  2440.                  | DECR lvalue
  2441.                  | lvalue POW_ASSIGN expr
  2442.                  | lvalue MOD_ASSIGN expr
  2443.                  | lvalue MUL_ASSIGN expr
  2444.                  | lvalue DIV_ASSIGN expr
  2445.                  | lvalue ADD_ASSIGN expr
  2446.                  | lvalue SUB_ASSIGN expr
  2447.                  | lvalue \(aq=\(aq expr
  2448.                  | FUNC_NAME \(aq(\(aq expr_list_opt \(aq)\(aq
  2449.                       /* no white space allowed before \(aq(\(aq */
  2450.                  | BUILTIN_FUNC_NAME \(aq(\(aq expr_list_opt \(aq)\(aq
  2451.                  | BUILTIN_FUNC_NAME
  2452.                  | non_unary_input_function
  2453.                  ;
  2454. .P
  2455. print_expr_list_opt : /* empty */
  2456.                  | print_expr_list
  2457.                  ;
  2458. .P
  2459. print_expr_list  : print_expr
  2460.                  | print_expr_list \(aq,\(aq newline_opt print_expr
  2461.                  ;
  2462. .P
  2463. print_expr       : unary_print_expr
  2464.                  | non_unary_print_expr
  2465.                  ;
  2466. .P
  2467. unary_print_expr : \(aq+\(aq print_expr
  2468.                  | \(aq-\(aq print_expr
  2469.                  | unary_print_expr \(aq\(ha\(aq      print_expr
  2470.                  | unary_print_expr \(aq*\(aq      print_expr
  2471.                  | unary_print_expr \(aq/\(aq      print_expr
  2472.                  | unary_print_expr \(aq%\(aq      print_expr
  2473.                  | unary_print_expr \(aq+\(aq      print_expr
  2474.                  | unary_print_expr \(aq-\(aq      print_expr
  2475.                  | unary_print_expr          non_unary_print_expr
  2476.                  | unary_print_expr \(aq\(ti\(aq      print_expr
  2477.                  | unary_print_expr NO_MATCH print_expr
  2478.                  | unary_print_expr In NAME
  2479.                  | unary_print_expr AND newline_opt print_expr
  2480.                  | unary_print_expr OR  newline_opt print_expr
  2481.                  | unary_print_expr \(aq?\(aq print_expr \(aq:\(aq print_expr
  2482.                  ;
  2483. .P
  2484. non_unary_print_expr : \(aq(\(aq expr \(aq)\(aq
  2485.                  | \(aq!\(aq print_expr
  2486.                  | non_unary_print_expr \(aq\(ha\(aq      print_expr
  2487.                  | non_unary_print_expr \(aq*\(aq      print_expr
  2488.                  | non_unary_print_expr \(aq/\(aq      print_expr
  2489.                  | non_unary_print_expr \(aq%\(aq      print_expr
  2490.                  | non_unary_print_expr \(aq+\(aq      print_expr
  2491.                  | non_unary_print_expr \(aq-\(aq      print_expr
  2492.                  | non_unary_print_expr          non_unary_print_expr
  2493.                  | non_unary_print_expr \(aq\(ti\(aq      print_expr
  2494.                  | non_unary_print_expr NO_MATCH print_expr
  2495.                  | non_unary_print_expr In NAME
  2496.                  | \(aq(\(aq multiple_expr_list \(aq)\(aq In NAME
  2497.                  | non_unary_print_expr AND newline_opt print_expr
  2498.                  | non_unary_print_expr OR  newline_opt print_expr
  2499.                  | non_unary_print_expr \(aq?\(aq print_expr \(aq:\(aq print_expr
  2500.                  | NUMBER
  2501.                  | STRING
  2502.                  | lvalue
  2503.                  | ERE
  2504.                  | lvalue INCR
  2505.                  | lvalue DECR
  2506.                  | INCR lvalue
  2507.                  | DECR lvalue
  2508.                  | lvalue POW_ASSIGN print_expr
  2509.                  | lvalue MOD_ASSIGN print_expr
  2510.                  | lvalue MUL_ASSIGN print_expr
  2511.                  | lvalue DIV_ASSIGN print_expr
  2512.                  | lvalue ADD_ASSIGN print_expr
  2513.                  | lvalue SUB_ASSIGN print_expr
  2514.                  | lvalue \(aq=\(aq print_expr
  2515.                  | FUNC_NAME \(aq(\(aq expr_list_opt \(aq)\(aq
  2516.                      /* no white space allowed before \(aq(\(aq */
  2517.                  | BUILTIN_FUNC_NAME \(aq(\(aq expr_list_opt \(aq)\(aq
  2518.                  | BUILTIN_FUNC_NAME
  2519.                  ;
  2520. .P
  2521. lvalue           : NAME
  2522.                  | NAME \(aq[\(aq expr_list \(aq]\(aq
  2523.                  | \(aq$\(aq expr
  2524.                  ;
  2525. .P
  2526. non_unary_input_function : simple_get
  2527.                  | simple_get \(aq<\(aq expr
  2528.                  | non_unary_expr \(aq|\(aq simple_get
  2529.                  ;
  2530. .P
  2531. unary_input_function : unary_expr \(aq|\(aq simple_get
  2532.                  ;
  2533. .P
  2534. simple_get       : GETLINE
  2535.                  | GETLINE lvalue
  2536.                  ;
  2537. .P
  2538. newline_opt      : /* empty */
  2539.                  | newline_opt NEWLINE
  2540.                  ;
  2541. .fi
  2542. .P
  2543. .RE
  2544. .P
  2545. This grammar has several ambiguities that shall be resolved as
  2546. follows:
  2547. .IP " *" 4
  2548. Operator precedence and associativity shall be as described in
  2549. .IR "Table 4-1, Expressions in Decreasing Precedence in \fIawk\fP".
  2550. .IP " *" 4
  2551. In case of ambiguity, an
  2552. .BR else
  2553. shall be associated with the most immediately preceding
  2554. .BR if
  2555. that would satisfy the grammar.
  2556. .IP " *" 4
  2557. In some contexts, a
  2558. <slash>
  2559. (\c
  2560. .BR '/' )
  2561. that is used to surround an ERE could also be the division operator.
  2562. This shall be resolved in such a way that wherever the division
  2563. operator could appear, a
  2564. <slash>
  2565. is assumed to be the division operator. (There is no unary division
  2566. operator.)
  2567. .P
  2568. Each expression in an
  2569. .IR awk
  2570. program shall conform to the precedence and associativity rules, even
  2571. when this is not needed to resolve an ambiguity. For example, because
  2572. .BR '$' 
  2573. has higher precedence than
  2574. .BR '++' ,
  2575. the string
  2576. .BR \(dq$x++--\(dq 
  2577. is not a valid
  2578. .IR awk
  2579. expression, even though it is unambiguously parsed by the grammar as
  2580. .BR \(dq$(x++)--\(dq .
  2581. .P
  2582. One convention that might not be obvious from the formal grammar is
  2583. where
  2584. <newline>
  2585. characters are acceptable. There are several obvious placements such as
  2586. terminating a statement, and a
  2587. <backslash>
  2588. can be used to escape
  2589. <newline>
  2590. characters between any lexical tokens. In addition,
  2591. <newline>
  2592. characters without
  2593. <backslash>
  2594. characters can follow a comma, an open brace, logical AND operator (\c
  2595. .BR \(dq&&\(dq ),
  2596. logical OR operator (\c
  2597. .BR \(dq||\(dq ),
  2598. the
  2599. .BR do
  2600. keyword, the
  2601. .BR else
  2602. keyword, and the closing parenthesis of an
  2603. .BR if ,
  2604. .BR for ,
  2605. or
  2606. .BR while
  2607. statement. For example:
  2608. .sp
  2609. .RS 4
  2610. .nf
  2612. { print  $1,
  2613.          $2 }
  2614. .fi
  2615. .P
  2616. .RE
  2617. .SS "Lexical Conventions"
  2618. .P
  2619. The lexical conventions for
  2620. .IR awk
  2621. programs, with respect to the preceding grammar, shall be as follows:
  2622. .IP " 1." 4
  2623. Except as noted,
  2624. .IR awk
  2625. shall recognize the longest possible token or delimiter beginning at a
  2626. given point.
  2627. .IP " 2." 4
  2628. A comment shall consist of any characters beginning with the
  2629. <number-sign>
  2630. character and terminated by, but excluding the next occurrence of, a
  2631. <newline>.
  2632. Comments shall have no effect, except to delimit lexical tokens.
  2633. .IP " 3." 4
  2634. The
  2635. <newline>
  2636. shall be recognized as the token
  2637. .BR NEWLINE .
  2638. .IP " 4." 4
  2639. A
  2640. <backslash>
  2641. character immediately followed by a
  2642. <newline>
  2643. shall have no effect.
  2644. .IP " 5." 4
  2645. The token
  2646. .BR STRING
  2647. shall represent a string constant. A string constant shall begin with
  2648. the character
  2649. .BR '\&"' .
  2650. Within a string constant, a
  2651. <backslash>
  2652. character shall be considered to begin an escape sequence as specified
  2653. in the table in the Base Definitions volume of POSIX.1\(hy2017,
  2654. .IR "Chapter 5" ", " "File Format Notation"
  2655. (\c
  2656. .BR '\e\e' ,
  2657. .BR '\ea' ,
  2658. .BR '\eb' ,
  2659. .BR '\ef' ,
  2660. .BR '\en' ,
  2661. .BR '\er' ,
  2662. .BR '\et' ,
  2663. .BR '\ev' ).
  2664. In addition, the escape sequences in
  2665. .IR "Table 4-2, Escape Sequences in \fIawk\fP"
  2666. shall be recognized. A
  2667. <newline>
  2668. shall not occur within a string constant. A string constant shall be
  2669. terminated by the first unescaped occurrence of the character
  2670. .BR '\&"' 
  2671. after the one that begins the string constant. The value of the string
  2672. shall be the sequence of all unescaped characters and values of escape
  2673. sequences between, but not including, the two delimiting
  2674. .BR '\&"' 
  2675. characters.
  2676. .IP " 6." 4
  2677. The token
  2678. .BR ERE
  2679. represents an extended regular expression constant. An ERE constant
  2680. shall begin with the
  2681. <slash>
  2682. character. Within an ERE constant, a
  2683. <backslash>
  2684. character shall be considered to begin an escape sequence as
  2685. specified in the table in the Base Definitions volume of POSIX.1\(hy2017,
  2686. .IR "Chapter 5" ", " "File Format Notation".
  2687. In addition, the escape sequences in
  2688. .IR "Table 4-2, Escape Sequences in \fIawk\fP"
  2689. shall be recognized. The application shall ensure that a
  2690. <newline>
  2691. does not occur within an ERE constant. An ERE constant shall be
  2692. terminated by the first unescaped occurrence of the
  2693. <slash>
  2694. character after the one that begins the ERE constant. The extended regular
  2695. expression represented by the ERE constant shall be the sequence of all
  2696. unescaped characters and values of escape sequences between, but not
  2697. including, the two delimiting
  2698. <slash>
  2699. characters.
  2700. .IP " 7." 4
  2701. A
  2702. <blank>
  2703. shall have no effect, except to delimit lexical tokens or within
  2704. .BR STRING
  2705. or
  2706. .BR ERE
  2707. tokens.
  2708. .IP " 8." 4
  2709. The token
  2710. .BR NUMBER
  2711. shall represent a numeric constant. Its form and numeric value shall
  2712. either be equivalent to the
  2713. .BR decimal-floating-constant
  2714. token as specified by the ISO\ C standard, or it shall be a sequence of decimal
  2715. digits and shall be evaluated as an integer constant in decimal. In
  2716. addition, implementations may accept numeric constants with the form
  2717. and numeric value equivalent to the
  2718. .BR hexadecimal-constant
  2719. and
  2720. .BR hexadecimal-floating-constant
  2721. tokens as specified by the ISO\ C standard.
  2722. .RS 4 
  2723. .P
  2724. If the value is too large or too small to be representable (see
  2725. .IR "Section 1.1.2" ", " "Concepts Derived from the ISO C Standard"),
  2726. the behavior is undefined.
  2727. .RE
  2728. .IP " 9." 4
  2729. A sequence of underscores, digits, and alphabetics from the portable
  2730. character set (see the Base Definitions volume of POSIX.1\(hy2017,
  2731. .IR "Section 6.1" ", " "Portable Character Set"),
  2732. beginning with an
  2733. <underscore>
  2734. or alphabetic character, shall be considered a word.
  2735. .IP 10. 4
  2736. The following words are keywords that shall be recognized as individual
  2737. tokens; the name of the token is the same as the keyword:
  2738. .TS
  2739. tab(@);
  2740. lw(0.6i)eB leB leB leB leB leB.
  2741. T{
  2742. .nf
  2743. BEGIN
  2744. break
  2745. continue
  2746. T}@T{
  2747. .nf
  2748. delete
  2749. do
  2750. else
  2751. T}@T{
  2752. .nf
  2753. END
  2754. exit
  2755. for
  2756. T}@T{
  2757. .nf
  2758. function
  2759. getline
  2760. if
  2761. T}@T{
  2762. .nf
  2763. in
  2764. next
  2765. print
  2766. T}@T{
  2767. .nf
  2768. printf
  2769. return
  2770. while
  2771. T}
  2772. .TE
  2773. .IP 11. 4
  2774. The following words are names of built-in functions and shall be
  2775. recognized as the token
  2776. .BR BUILTIN_FUNC_NAME :
  2777. .TS
  2778. tab(@);
  2779. lw(0.6i)eB leB leB leB leB leB.
  2780. T{
  2781. .nf
  2782. atan2
  2783. close
  2784. cos
  2785. exp
  2786. T}@T{
  2787. .nf
  2788. gsub
  2789. index
  2790. int
  2791. length
  2792. T}@T{
  2793. .nf
  2794. log
  2795. match
  2796. rand
  2797. sin
  2798. T}@T{
  2799. .nf
  2800. split
  2801. sprintf
  2802. sqrt
  2803. srand
  2804. T}@T{
  2805. .nf
  2806. sub
  2807. substr
  2808. system
  2809. tolower
  2810. T}@T{
  2811. .nf
  2812. toupper
  2813. .fi
  2814. T}
  2815. .TE
  2816. .RS 4 
  2817. .P
  2818. The above-listed keywords and names of built-in functions are
  2819. considered reserved words.
  2820. .RE
  2821. .IP 12. 4
  2822. The token
  2823. .BR NAME
  2824. shall consist of a word that is not a keyword or a name of a built-in
  2825. function and is not followed immediately (without any delimiters) by
  2826. the
  2827. .BR '(' 
  2828. character.
  2829. .IP 13. 4
  2830. The token
  2831. .BR FUNC_NAME
  2832. shall consist of a word that is not a keyword or a name of a built-in
  2833. function, followed immediately (without any delimiters) by the
  2834. .BR '(' 
  2835. character. The
  2836. .BR '(' 
  2837. character shall not be included as part of the token.
  2838. .IP 14. 4
  2839. The following two-character sequences shall be recognized as the named
  2840. tokens:
  2841. .TS
  2842. box center tab(@);
  2843. cB | cB | cB | cB
  2844. lB | cf5 | lB | cf5.
  2845. Token Name@Sequence@Token Name@Sequence
  2846. _
  2847. ADD_ASSIGN@+=@NO_MATCH@!~
  2848. SUB_ASSIGN@\-=@EQ@==
  2849. MUL_ASSIGN@*=@LE@<=
  2850. DIV_ASSIGN@/=@GE@>=
  2851. MOD_ASSIGN@%=@NE@!=
  2852. POW_ASSIGN@^=@INCR@++
  2853. OR@||@DECR@\-\|\-
  2854. AND@&&@APPEND@>>
  2855. .TE
  2856. .IP 15. 4
  2857. The following single characters shall be recognized as tokens whose
  2858. names are the character:
  2859. .RS 4 
  2860. .sp
  2861. .RS 4
  2862. .nf
  2864. <newline> { } ( ) [ ] , ; + - * % \(ha ! > < | ? : \(ti $ =
  2865. .fi
  2866. .P
  2867. .RE
  2868. .RE
  2869. .P
  2870. There is a lexical ambiguity between the token
  2871. .BR ERE
  2872. and the tokens
  2873. .BR '/' 
  2874. and
  2875. .BR DIV_ASSIGN .
  2876. When an input sequence begins with a
  2877. <slash>
  2878. character in any syntactic context where the token
  2879. .BR '/' 
  2880. or
  2881. .BR DIV_ASSIGN
  2882. could appear as the next token in a valid program, the longer of those
  2883. two tokens that can be recognized shall be recognized. In any other
  2884. syntactic context where the token
  2885. .BR ERE
  2886. could appear as the next token in a valid program, the token
  2887. .BR ERE
  2888. shall be recognized.
  2889. .SH "EXIT STATUS"
  2890. The following exit values shall be returned:
  2891. .IP "\00" 6
  2892. All input files were processed successfully.
  2893. .IP >0 6
  2894. An error occurred.
  2895. .P
  2896. The exit status can be altered within the program by using an
  2897. .BR exit
  2898. expression.
  2899. .SH "CONSEQUENCES OF ERRORS"
  2900. If any
  2901. .IR file
  2902. operand is specified and the named file cannot be accessed,
  2903. .IR awk
  2904. shall write a diagnostic message to standard error and terminate
  2905. without any further action.
  2906. .P
  2907. If the program specified by either the
  2908. .IR program
  2909. operand or a
  2910. .IR progfile
  2911. operand is not a valid
  2912. .IR awk
  2913. program (as specified in the EXTENDED DESCRIPTION section), the
  2914. behavior is undefined.
  2915. .LP
  2916. .IR "The following sections are informative."
  2917. .SH "APPLICATION USAGE"
  2918. The
  2919. .BR index ,
  2920. .BR length ,
  2921. .BR match ,
  2922. and
  2923. .BR substr
  2924. functions should not be confused with similar functions in the ISO\ C standard;
  2925. the
  2926. .IR awk
  2927. versions deal with characters, while the ISO\ C standard deals with bytes.
  2928. .P
  2929. Because the concatenation operation is represented by adjacent
  2930. expressions rather than an explicit operator, it is often necessary to
  2931. use parentheses to enforce the proper evaluation precedence.
  2932. .P
  2933. When using
  2934. .IR awk
  2935. to process pathnames, it is recommended that LC_ALL, or at least
  2936. LC_CTYPE and LC_COLLATE, are set to POSIX or C in the environment,
  2937. since pathnames can contain byte sequences that do not form valid
  2938. characters in some locales, in which case the utility's behavior would
  2939. be undefined. In the POSIX locale each byte is a valid single-byte
  2940. character, and therefore this problem is avoided.
  2941. .P
  2942. On implementations where the
  2943. .BR \(dq==\(dq 
  2944. operator checks if strings collate equally, applications needing to
  2945. check whether strings are identical can use:
  2946. .sp
  2947. .RS 4
  2948. .nf
  2950. length(a) == length(b) && index(a,b) == 1
  2951. .fi
  2952. .P
  2953. .RE
  2954. .P
  2955. On implementations where the
  2956. .BR \(dq==\(dq 
  2957. operator checks if strings are identical, applications needing to
  2958. check whether strings collate equally can use:
  2959. .sp
  2960. .RS 4
  2961. .nf
  2963. a <= b && a >= b
  2964. .fi
  2965. .P
  2966. .RE
  2967. .SH EXAMPLES
  2968. The
  2969. .IR awk
  2970. program specified in the command line is most easily specified within
  2971. single-quotes (for example, \(aq\fIprogram\fP\(aq) for applications using
  2972. .IR sh ,
  2973. because
  2974. .IR awk
  2975. programs commonly contain characters that are special to the shell,
  2976. including double-quotes. In the cases where an
  2977. .IR awk
  2978. program contains single-quote characters, it is usually easiest to
  2979. specify most of the program as strings within single-quotes
  2980. concatenated by the shell with quoted single-quote characters. For
  2981. example:
  2982. .sp
  2983. .RS 4
  2984. .nf
  2986. awk \(aq/\(aq\e\(aq\(aq/ { print "quote:", $0 }\(aq
  2987. .fi
  2988. .P
  2989. .RE
  2990. .P
  2991. prints all lines from the standard input containing a single-quote
  2992. character, prefixed with
  2993. .IR quote :.
  2994. .P
  2995. The following are examples of simple
  2996. .IR awk
  2997. programs:
  2998. .IP " 1." 4
  2999. Write to the standard output all input lines for which field 3 is
  3000. greater than 5:
  3001. .RS 4 
  3002. .sp
  3003. .RS 4
  3004. .nf
  3006. $3 > 5
  3007. .fi
  3008. .P
  3009. .RE
  3010. .RE
  3011. .IP " 2." 4
  3012. Write every tenth line:
  3013. .RS 4 
  3014. .sp
  3015. .RS 4
  3016. .nf
  3018. (NR % 10) == 0
  3019. .fi
  3020. .P
  3021. .RE
  3022. .RE
  3023. .IP " 3." 4
  3024. Write any line with a substring matching the regular expression:
  3025. .RS 4 
  3026. .sp
  3027. .RS 4
  3028. .nf
  3030. /(G|D)(2[0-9][[:alpha:]]*)/
  3031. .fi
  3032. .P
  3033. .RE
  3034. .RE
  3035. .IP " 4." 4
  3036. Print any line with a substring containing a
  3037. .BR 'G' 
  3038. or
  3039. .BR 'D' ,
  3040. followed by a sequence of digits and characters. This example uses
  3041. character classes
  3042. .BR digit
  3043. and
  3044. .BR alpha
  3045. to match language-independent digit and alphabetic characters
  3046. respectively:
  3047. .RS 4 
  3048. .sp
  3049. .RS 4
  3050. .nf
  3052. /(G|D)([[:digit:][:alpha:]]*)/
  3053. .fi
  3054. .P
  3055. .RE
  3056. .RE
  3057. .IP " 5." 4
  3058. Write any line in which the second field matches the regular expression
  3059. and the fourth field does not:
  3060. .RS 4 
  3061. .sp
  3062. .RS 4
  3063. .nf
  3065. $2 \(ti /xyz/ && $4 !\(ti /xyz/
  3066. .fi
  3067. .P
  3068. .RE
  3069. .RE
  3070. .IP " 6." 4
  3071. Write any line in which the second field contains a
  3072. <backslash>:
  3073. .RS 4 
  3074. .sp
  3075. .RS 4
  3076. .nf
  3078. $2 \(ti /\e\e/
  3079. .fi
  3080. .P
  3081. .RE
  3082. .RE
  3083. .IP " 7." 4
  3084. Write any line in which the second field contains a
  3085. <backslash>.
  3086. Note that
  3087. <backslash>-escapes
  3088. are interpreted twice; once in lexical processing of the string and once
  3089. in processing the regular expression:
  3090. .RS 4 
  3091. .sp
  3092. .RS 4
  3093. .nf
  3095. $2 \(ti "\e\e\e\e"
  3096. .fi
  3097. .P
  3098. .RE
  3099. .RE
  3100. .IP " 8." 4
  3101. Write the second to the last and the last field in each line. Separate
  3102. the fields by a
  3103. <colon>:
  3104. .RS 4 
  3105. .sp
  3106. .RS 4
  3107. .nf
  3109. {OFS=":";print $(NF-1), $NF}
  3110. .fi
  3111. .P
  3112. .RE
  3113. .RE
  3114. .IP " 9." 4
  3115. Write the line number and number of fields in each line. The three
  3116. strings representing the line number, the
  3117. <colon>,
  3118. and the number of fields are concatenated and that string is written to
  3119. standard output:
  3120. .RS 4 
  3121. .sp
  3122. .RS 4
  3123. .nf
  3125. {print NR ":" NF}
  3126. .fi
  3127. .P
  3128. .RE
  3129. .RE
  3130. .IP 10. 4
  3131. Write lines longer than 72 characters:
  3132. .RS 4 
  3133. .sp
  3134. .RS 4
  3135. .nf
  3137. length($0) > 72
  3138. .fi
  3139. .P
  3140. .RE
  3141. .RE
  3142. .IP 11. 4
  3143. Write the first two fields in opposite order separated by
  3144. .BR OFS :
  3145. .RS 4 
  3146. .sp
  3147. .RS 4
  3148. .nf
  3150. { print $2, $1 }
  3151. .fi
  3152. .P
  3153. .RE
  3154. .RE
  3155. .IP 12. 4
  3156. Same, with input fields separated by a
  3157. <comma>
  3158. or
  3159. <space>
  3160. and
  3161. <tab>
  3162. characters, or both:
  3163. .RS 4 
  3164. .sp
  3165. .RS 4
  3166. .nf
  3168. BEGIN { FS = ",[ \et]*|[ \et]+" }
  3169.       { print $2, $1 }
  3170. .fi
  3171. .P
  3172. .RE
  3173. .RE
  3174. .IP 13. 4
  3175. Add up the first column, print sum, and average:
  3176. .RS 4 
  3177. .sp
  3178. .RS 4
  3179. .nf
  3181.       {s += $1 }
  3182. END   {print "sum is ", s, " average is", s/NR}
  3183. .fi
  3184. .P
  3185. .RE
  3186. .RE
  3187. .IP 14. 4
  3188. Write fields in reverse order, one per line (many lines out for each
  3189. line in):
  3190. .RS 4 
  3191. .sp
  3192. .RS 4
  3193. .nf
  3195. { for (i = NF; i > 0; --i) print $i }
  3196. .fi
  3197. .P
  3198. .RE
  3199. .RE
  3200. .IP 15. 4
  3201. Write all lines between occurrences of the strings
  3202. .BR start
  3203. and
  3204. .BR stop :
  3205. .RS 4 
  3206. .sp
  3207. .RS 4
  3208. .nf
  3210. /start/, /stop/
  3211. .fi
  3212. .P
  3213. .RE
  3214. .RE
  3215. .IP 16. 4
  3216. Write all lines whose first field is different from the previous one:
  3217. .RS 4 
  3218. .sp
  3219. .RS 4
  3220. .nf
  3222. $1 != prev { print; prev = $1 }
  3223. .fi
  3224. .P
  3225. .RE
  3226. .RE
  3227. .IP 17. 4
  3228. Simulate
  3229. .IR echo :
  3230. .RS 4 
  3231. .sp
  3232. .RS 4
  3233. .nf
  3235. BEGIN  {
  3236.         for (i = 1; i < ARGC; ++i)
  3237.         printf("%s%s", ARGV[i], i==ARGC-1?"\en":" ")
  3238. }
  3239. .fi
  3240. .P
  3241. .RE
  3242. .RE
  3243. .IP 18. 4
  3244. Write the path prefixes contained in the
  3245. .IR PATH
  3246. environment variable, one per line:
  3247. .RS 4 
  3248. .sp
  3249. .RS 4
  3250. .nf
  3252. BEGIN  {
  3253.         n = split (ENVIRON["PATH"], path, ":")
  3254.         for (i = 1; i <= n; ++i)
  3255.         print path[i]
  3256. }
  3257. .fi
  3258. .P
  3259. .RE
  3260. .RE
  3261. .IP 19. 4
  3262. If there is a file named
  3263. .BR input
  3264. containing page headers of the form:
  3265. Page #
  3266. .RS 4 
  3267. .P
  3268. and a file named
  3269. .BR program
  3270. that contains:
  3271. .sp
  3272. .RS 4
  3273. .nf
  3275. /Page/   { $2 = n++; }
  3276.          { print }
  3277. .fi
  3278. .P
  3279. .RE
  3280. then the command line:
  3281. .sp
  3282. .RS 4
  3283. .nf
  3285. awk -f program n=5 input
  3286. .fi
  3287. .P
  3288. .RE
  3289. .P
  3290. prints the file
  3291. .BR input ,
  3292. filling in page numbers starting at 5.
  3293. .RE
  3294. .SH RATIONALE
  3295. This description is based on the new
  3296. .IR awk ,
  3297. ``nawk'', (see the referenced \fIThe AWK Programming Language\fP), which introduced a number of new features to
  3298. the historical
  3299. .IR awk :
  3300. .IP " 1." 4
  3301. New keywords:
  3302. .BR delete ,
  3303. .BR do ,
  3304. .BR function ,
  3305. .BR return
  3306. .IP " 2." 4
  3307. New built-in functions:
  3308. .BR atan2 ,
  3309. .BR close ,
  3310. .BR cos ,
  3311. .BR gsub ,
  3312. .BR match ,
  3313. .BR rand ,
  3314. .BR sin ,
  3315. .BR srand ,
  3316. .BR sub ,
  3317. .BR system
  3318. .IP " 3." 4
  3319. New predefined variables:
  3320. .BR FNR ,
  3321. .BR ARGC ,
  3322. .BR ARGV ,
  3323. .BR RSTART ,
  3324. .BR RLENGTH ,
  3325. .BR SUBSEP
  3326. .IP " 4." 4
  3327. New expression operators:
  3328. .BR ? ,
  3329. .BR : ,
  3330. .BR , ,
  3331. .BR ^
  3332. .IP " 5." 4
  3333. The
  3334. .BR FS
  3335. variable and the third argument to
  3336. .BR split ,
  3337. now treated as extended regular expressions.
  3338. .IP " 6." 4
  3339. The operator precedence, changed to more closely match the C language.
  3340. Two examples of code that operate differently are:
  3341. .RS 4 
  3342. .sp
  3343. .RS 4
  3344. .nf
  3346. while ( n /= 10 > 1) ...
  3347. if (!"wk" \(ti /bwk/) ...
  3348. .fi
  3349. .P
  3350. .RE
  3351. .RE
  3352. .P
  3353. Several features have been added based on newer implementations of
  3354. .IR awk :
  3355. .IP " *" 4
  3356. Multiple instances of
  3357. .BR \-f
  3358. .IR progfile
  3359. are permitted.
  3360. .IP " *" 4
  3361. The new option
  3362. .BR \-v
  3363. .IR assignment.
  3364. .IP " *" 4
  3365. The new predefined variable
  3366. .BR ENVIRON .
  3367. .IP " *" 4
  3368. New built-in functions
  3369. .BR toupper
  3370. and
  3371. .BR tolower .
  3372. .IP " *" 4
  3373. More formatting capabilities are added to
  3374. .BR printf
  3375. to match the ISO\ C standard.
  3376. .P
  3377. Earlier versions of this standard required implementations to
  3378. support multiple adjacent
  3379. <semicolon>s,
  3380. lines with one or more
  3381. <semicolon>
  3382. before a rule (\c
  3383. .IR pattern-action
  3384. pairs), and lines with only
  3385. <semicolon>(s).
  3386. These are not required by this standard and are considered poor
  3387. programming practice, but can be accepted by an implementation of
  3388. .IR awk
  3389. as an extension.
  3390. .P
  3391. The overall
  3392. .IR awk
  3393. syntax has always been based on the C language, with a few features
  3394. from the shell command language and other sources. Because of this, it
  3395. is not completely compatible with any other language, which has caused
  3396. confusion for some users. It is not the intent of the standard
  3397. developers to address such issues. A few relatively minor changes
  3398. toward making the language more compatible with the ISO\ C standard were
  3399. made; most of these changes are based on similar changes in recent
  3400. implementations, as described above. There remain several C-language
  3401. conventions that are not in
  3402. .IR awk .
  3403. One of the notable ones is the
  3404. <comma>
  3405. operator, which is commonly used to specify multiple expressions in the
  3406. C language
  3407. .BR for
  3408. statement. Also, there are various places where
  3409. .IR awk
  3410. is more restrictive than the C language regarding the type of
  3411. expression that can be used in a given context. These limitations are
  3412. due to the different features that the
  3413. .IR awk
  3414. language does provide.
  3415. .P
  3416. Regular expressions in
  3417. .IR awk
  3418. have been extended somewhat from historical implementations to make
  3419. them a pure superset of extended regular expressions, as defined by
  3420. POSIX.1\(hy2008 (see the Base Definitions volume of POSIX.1\(hy2017,
  3421. .IR "Section 9.4" ", " "Extended Regular Expressions").
  3422. The main extensions are internationalization
  3423. features and interval expressions. Historical implementations of
  3424. .IR awk
  3425. have long supported
  3426. <backslash>-escape
  3427. sequences as an extension to extended regular expressions, and
  3428. this extension has been retained despite inconsistency with other
  3429. utilities. The number of escape sequences recognized in both extended
  3430. regular expressions and strings has varied (generally increasing with
  3431. time) among implementations. The set specified by POSIX.1\(hy2008 includes most
  3432. sequences known to be supported by popular implementations and by the
  3433. ISO\ C standard. One sequence that is not supported is hexadecimal value escapes
  3434. beginning with
  3435. .BR '\ex' .
  3436. This would allow values expressed in more than 9 bits to be used within
  3437. .IR awk
  3438. as in the ISO\ C standard. However, because this syntax has a non-deterministic
  3439. length, it does not permit the subsequent character to be a hexadecimal
  3440. digit. This limitation can be dealt with in the C language by the use
  3441. of lexical string concatenation. In the
  3442. .IR awk
  3443. language, concatenation could also be a solution for strings, but not
  3444. for extended regular expressions (either lexical ERE tokens or strings
  3445. used dynamically as regular expressions). Because of this limitation,
  3446. the feature has not been added to POSIX.1\(hy2008.
  3447. .P
  3448. When a string variable is used in a context where an extended regular
  3449. expression normally appears (where the lexical token ERE is used in the
  3450. grammar) the string does not contain the literal
  3451. <slash>
  3452. characters.
  3453. .P
  3454. Some versions of
  3455. .IR awk
  3456. allow the form:
  3457. .sp
  3458. .RS 4
  3459. .nf
  3461. func name(args, ... ) { statements }
  3462. .fi
  3463. .P
  3464. .RE
  3465. .P
  3466. This has been deprecated by the authors of the language, who asked that
  3467. it not be specified.
  3468. .P
  3469. Historical implementations of
  3470. .IR awk
  3471. produce an error if a
  3472. .BR next
  3473. statement is executed in a
  3474. .BR BEGIN
  3475. action, and cause
  3476. .IR awk
  3477. to terminate if a
  3478. .BR next
  3479. statement is executed in an
  3480. .BR END
  3481. action. This behavior has not been documented, and it was not believed
  3482. that it was necessary to standardize it.
  3483. .P
  3484. The specification of conversions between string and numeric values is
  3485. much more detailed than in the documentation of historical
  3486. implementations or in the referenced \fIThe AWK Programming Language\fP. Although most of the behavior is
  3487. designed to be intuitive, the details are necessary to ensure
  3488. compatible behavior from different implementations. This is especially
  3489. important in relational expressions since the types of the operands
  3490. determine whether a string or numeric comparison is performed. From the
  3491. perspective of an application developer, it is usually sufficient to
  3492. expect intuitive behavior and to force conversions (by adding zero or
  3493. concatenating a null string) when the type of an expression does not
  3494. obviously match what is needed. The intent has been to specify
  3495. historical practice in almost all cases. The one exception is that, in
  3496. historical implementations, variables and constants maintain both
  3497. string and numeric values after their original value is converted by
  3498. any use. This means that referencing a variable or constant can have
  3499. unexpected side-effects. For example, with historical implementations
  3500. the following program:
  3501. .sp
  3502. .RS 4
  3503. .nf
  3505. {
  3506.     a = "+2"
  3507.     b = 2
  3508.     if (NR % 2)
  3509.         c = a + b
  3510.     if (a == b)
  3511.         print "numeric comparison"
  3512.     else
  3513.         print "string comparison"
  3514. }
  3515. .fi
  3516. .P
  3517. .RE
  3518. .P
  3519. would perform a numeric comparison (and output numeric comparison) for
  3520. each odd-numbered line, but perform a string comparison (and output
  3521. string comparison) for each even-numbered line. POSIX.1\(hy2008 ensures that
  3522. comparisons will be numeric if necessary. With historical
  3523. implementations, the following program:
  3524. .sp
  3525. .RS 4
  3526. .nf
  3528. BEGIN {
  3529.     OFMT = "%e"
  3530.     print 3.14
  3531.     OFMT = "%f"
  3532.     print 3.14
  3533. }
  3534. .fi
  3535. .P
  3536. .RE
  3537. .P
  3538. would output
  3539. .BR \(dq3.140000e+00\(dq 
  3540. twice, because in the second
  3541. .BR print
  3542. statement the constant
  3543. .BR \(dq3.14\(dq 
  3544. would have a string value from the previous conversion. POSIX.1\(hy2008 requires
  3545. that the output of the second
  3546. .BR print
  3547. statement be
  3548. .BR \(dq3.140000\(dq .
  3549. The behavior of historical implementations was seen as too unintuitive
  3550. and unpredictable.
  3551. .P
  3552. It was pointed out that with the rules contained in early drafts, the
  3553. following script would print nothing:
  3554. .sp
  3555. .RS 4
  3556. .nf
  3558. BEGIN {
  3559.     y[1.5] = 1
  3560.     OFMT = "%e"
  3561.     print y[1.5]
  3562. }
  3563. .fi
  3564. .P
  3565. .RE
  3566. .P
  3567. Therefore, a new variable,
  3568. .BR CONVFMT ,
  3569. was introduced. The
  3570. .BR OFMT
  3571. variable is now restricted to affecting output conversions of numbers
  3572. to strings and
  3573. .BR CONVFMT
  3574. is used for internal conversions, such as comparisons or array
  3575. indexing. The default value is the same as that for
  3576. .BR OFMT ,
  3577. so unless a program changes
  3578. .BR CONVFMT
  3579. (which no historical program would do), it will receive the historical
  3580. behavior associated with internal string conversions.
  3581. .P
  3582. The POSIX
  3583. .IR awk
  3584. lexical and syntactic conventions are specified more formally than in
  3585. other sources. Again the intent has been to specify historical
  3586. practice. One convention that may not be obvious from the formal
  3587. grammar as in other verbal descriptions is where
  3588. <newline>
  3589. characters are acceptable. There are several obvious placements such as
  3590. terminating a statement, and a
  3591. <backslash>
  3592. can be used to escape
  3593. <newline>
  3594. characters between any lexical tokens. In addition,
  3595. <newline>
  3596. characters without
  3597. <backslash>
  3598. characters can follow a comma, an open brace, a logical AND operator (\c
  3599. .BR \(dq&&\(dq ),
  3600. a logical OR operator (\c
  3601. .BR \(dq||\(dq ),
  3602. the
  3603. .BR do
  3604. keyword, the
  3605. .BR else
  3606. keyword, and the closing parenthesis of an
  3607. .BR if ,
  3608. .BR for ,
  3609. or
  3610. .BR while
  3611. statement. For example:
  3612. .sp
  3613. .RS 4
  3614. .nf
  3616. { print $1,
  3617.         $2 }
  3618. .fi
  3619. .P
  3620. .RE
  3621. .P
  3622. The requirement that
  3623. .IR awk
  3624. add a trailing
  3625. <newline>
  3626. to the program argument text is to simplify the grammar, making it
  3627. match a text file in form. There is no way for an application or test
  3628. suite to determine whether a literal
  3629. <newline>
  3630. is added or whether
  3631. .IR awk
  3632. simply acts as if it did.
  3633. .P
  3634. POSIX.1\(hy2008 requires several changes from historical implementations in order
  3635. to support internationalization. Probably the most subtle of these is
  3636. the use of the decimal-point character, defined by the
  3637. .IR LC_NUMERIC
  3638. category of the locale, in representations of floating-point numbers.
  3639. This locale-specific character is used in recognizing numeric input, in
  3640. converting between strings and numeric values, and in formatting
  3641. output. However, regardless of locale, the
  3642. <period>
  3643. character (the decimal-point character of the POSIX locale) is the
  3644. decimal-point character recognized in processing
  3645. .IR awk
  3646. programs (including assignments in command line arguments). This is
  3647. essentially the same convention as the one used in the ISO\ C standard. The
  3648. difference is that the C language includes the
  3649. \fIsetlocale\fR()
  3650. function, which permits an application to modify its locale. Because of
  3651. this capability, a C application begins executing with its locale set
  3652. to the C locale, and only executes in the environment-specified locale
  3653. after an explicit call to
  3654. \fIsetlocale\fR().
  3655. However, adding such an elaborate new feature to the
  3656. .IR awk
  3657. language was seen as inappropriate for POSIX.1\(hy2008. It is possible to execute
  3658. an
  3659. .IR awk
  3660. program explicitly in any desired locale by setting the environment in
  3661. the shell.
  3662. .P
  3663. The undefined behavior resulting from NULs in extended regular
  3664. expressions allows future extensions for the GNU
  3665. .IR gawk
  3666. program to process binary data.
  3667. .P
  3668. The behavior in the case of invalid
  3669. .IR awk
  3670. programs (including lexical, syntactic, and semantic errors) is
  3671. undefined because it was considered overly limiting on implementations
  3672. to specify. In most cases such errors can be expected to produce a
  3673. diagnostic and a non-zero exit status. However, some implementations
  3674. may choose to extend the language in ways that make use of certain
  3675. invalid constructs. Other invalid constructs might be deemed worthy of
  3676. a warning, but otherwise cause some reasonable behavior. Still other
  3677. constructs may be very difficult to detect in some implementations.
  3678. Also, different implementations might detect a given error during an
  3679. initial parsing of the program (before reading any input files) while
  3680. others might detect it when executing the program after reading some
  3681. input. Implementors should be aware that diagnosing errors as early as
  3682. possible and producing useful diagnostics can ease debugging of
  3683. applications, and thus make an implementation more usable.
  3684. .P
  3685. The unspecified behavior from using multi-character
  3686. .BR RS
  3687. values is to allow possible future extensions based on extended regular
  3688. expressions used for record separators. Historical implementations take
  3689. the first character of the string and ignore the others.
  3690. .P
  3691. Unspecified behavior when
  3692. .IR split (\c
  3693. .IR string ,\c
  3694. .IR array ,\c
  3695. <null>)
  3696. is used is to allow a proposed future extension that would split up a
  3697. string into an array of individual characters.
  3698. .P
  3699. In the context of the
  3700. .BR getline
  3701. function, equally good arguments for different precedences of the
  3702. .BR |
  3703. and
  3704. .BR <
  3705. operators can be made. Historical practice has been that:
  3706. .sp
  3707. .RS 4
  3708. .nf
  3710. getline < "a" "b"
  3711. .fi
  3712. .P
  3713. .RE
  3714. .P
  3715. is parsed as:
  3716. .sp
  3717. .RS 4
  3718. .nf
  3720. ( getline < "a" ) "b"
  3721. .fi
  3722. .P
  3723. .RE
  3724. .P
  3725. although many would argue that the intent was that the file
  3726. .BR ab
  3727. should be read. However:
  3728. .sp
  3729. .RS 4
  3730. .nf
  3732. getline < "x" + 1
  3733. .fi
  3734. .P
  3735. .RE
  3736. .P
  3737. parses as:
  3738. .sp
  3739. .RS 4
  3740. .nf
  3742. getline < ( "x" + 1 )
  3743. .fi
  3744. .P
  3745. .RE
  3746. .P
  3747. Similar problems occur with the
  3748. .BR |
  3749. version of
  3750. .BR getline ,
  3751. particularly in combination with
  3752. .BR $ .
  3753. For example:
  3754. .sp
  3755. .RS 4
  3756. .nf
  3758. $"echo hi" | getline
  3759. .fi
  3760. .P
  3761. .RE
  3762. .P
  3763. (This situation is particularly problematic when used in a
  3764. .BR print
  3765. statement, where the
  3766. .BR |getline
  3767. part might be a redirection of the
  3768. .BR print .)
  3769. .P
  3770. Since in most cases such constructs are not (or at least should not) be
  3771. used (because they have a natural ambiguity for which there is no
  3772. conventional parsing), the meaning of these constructs has been made
  3773. explicitly unspecified. (The effect is that a conforming application that
  3774. runs into the problem must parenthesize to resolve the ambiguity.)
  3775. There appeared to be few if any actual uses of such constructs.
  3776. .P
  3777. Grammars can be written that would cause an error under these
  3778. circumstances. Where backwards-compatibility is not a large
  3779. consideration, implementors may wish to use such grammars.
  3780. .P
  3781. Some historical implementations have allowed some built-in functions to
  3782. be called without an argument list, the result being a default argument
  3783. list chosen in some ``reasonable'' way. Use of
  3784. .BR length
  3785. as a synonym for
  3786. .BR "length($0)"
  3787. is the only one of these forms that is thought to be widely known or
  3788. widely used; this particular form is documented in various places (for
  3789. example, most historical
  3790. .IR awk
  3791. reference pages, although not in the referenced \fIThe AWK Programming Language\fP) as legitimate practice.
  3792. With this exception, default argument lists have always been
  3793. undocumented and vaguely defined, and it is not at all clear how (or
  3794. if) they should be generalized to user-defined functions. They add no
  3795. useful functionality and preclude possible future extensions that might
  3796. need to name functions without calling them. Not standardizing them
  3797. seems the simplest course. The standard developers considered that
  3798. .BR length
  3799. merited special treatment, however, since it has been documented in the
  3800. past and sees possibly substantial use in historical programs.
  3801. Accordingly, this usage has been made legitimate, but Issue\ 5
  3802. removed the obsolescent marking for XSI-conforming implementations
  3803. and many otherwise conforming applications depend on this feature.
  3804. .P
  3805. In
  3806. .BR sub
  3807. and
  3808. .BR gsub ,
  3809. if
  3810. .IR repl
  3811. is a string literal (the lexical token
  3812. .BR STRING ),
  3813. then two consecutive
  3814. <backslash>
  3815. characters should be used in the string to ensure a single
  3816. <backslash>
  3817. will precede the
  3818. <ampersand>
  3819. when the resultant string is passed to the function. (For example,
  3820. to specify one literal
  3821. <ampersand>
  3822. in the replacement string, use
  3823. .BR gsub (\c
  3824. .BR ERE ,
  3825. .BR \(dq\e\e&\(dq ).)
  3826. .P
  3827. Historically, the only special character in the
  3828. .IR repl
  3829. argument of
  3830. .BR sub
  3831. and
  3832. .BR gsub
  3833. string functions was the
  3834. <ampersand>
  3835. (\c
  3836. .BR '&' )
  3837. character and preceding it with the
  3838. <backslash>
  3839. character was used to turn off its special meaning.
  3840. .P
  3841. The description in the ISO\ POSIX\(hy2:\|1993 standard introduced behavior such that the
  3842. <backslash>
  3843. character was another special character and it was unspecified whether
  3844. there were any other special characters. This description introduced
  3845. several portability problems, some of which are described below, and so
  3846. it has been replaced with the more historical description. Some of the
  3847. problems include:
  3848. .IP " *" 4
  3849. Historically, to create the replacement string, a script could use
  3850. .BR gsub (\c
  3851. .BR ERE ,
  3852. .BR \(dq\e\e&\(dq ),
  3853. but with the ISO\ POSIX\(hy2:\|1993 standard wording, it was necessary to use
  3854. .BR gsub (\c
  3855. .BR ERE ,
  3856. .BR \(dq\e\e\e\e&\(dq ).
  3857. The
  3858. <backslash>
  3859. characters are doubled here because all string literals are subject to
  3860. lexical analysis, which would reduce each pair of
  3861. <backslash>
  3862. characters to a single
  3863. <backslash>
  3864. before being passed to
  3865. .BR gsub .
  3866. .IP " *" 4
  3867. Since it was unspecified what the special characters were, for portable
  3868. scripts to guarantee that characters are printed literally, each
  3869. character had to be preceded with a
  3870. <backslash>.
  3871. (For example, a portable script had to use
  3872. .BR gsub (\c
  3873. .BR ERE ,
  3874. .BR \(dq\e\eh\e\ei\(dq )
  3875. to produce a replacement string of
  3876. .BR \(dqhi\(dq .)
  3877. .P
  3878. The description for comparisons in the ISO\ POSIX\(hy2:\|1993 standard did not properly describe
  3879. historical practice because of the way numeric strings are compared as
  3880. numbers. The current rules cause the following code:
  3881. .sp
  3882. .RS 4
  3883. .nf
  3885. if (0 == "000")
  3886.     print "strange, but true"
  3887. else
  3888.     print "not true"
  3889. .fi
  3890. .P
  3891. .RE
  3892. .P
  3893. to do a numeric comparison, causing the
  3894. .BR if
  3895. to succeed. It should be intuitively obvious that this is incorrect
  3896. behavior, and indeed, no historical implementation of
  3897. .IR awk
  3898. actually behaves this way.
  3899. .P
  3900. To fix this problem, the definition of
  3901. .IR "numeric string"
  3902. was enhanced to include only those values obtained from specific
  3903. circumstances (mostly external sources) where it is not possible to
  3904. determine unambiguously whether the value is intended to be a string or
  3905. a numeric.
  3906. .P
  3907. Variables that are assigned to a numeric string shall also be treated
  3908. as a numeric string. (For example, the notion of a numeric string can
  3909. be propagated across assignments.) In comparisons, all variables having
  3910. the uninitialized value are to be treated as a numeric operand
  3911. evaluating to the numeric value zero.
  3912. .P
  3913. Uninitialized variables include all types of variables including
  3914. scalars, array elements, and fields. The definition of an uninitialized
  3915. value in
  3916. .IR "Variables and Special Variables"
  3917. is necessary to describe the value placed on uninitialized variables
  3918. and on fields that are valid (for example,
  3919. .BR <
  3920. .BR $NF )
  3921. but have no characters in them and to describe how these variables are
  3922. to be used in comparisons. A valid field, such as
  3923. .BR $1 ,
  3924. that has no characters in it can be obtained from an input line of
  3925. .BR \(dq\et\et\(dq 
  3926. when
  3927. .BR FS= \c
  3928. .BR '\et' .
  3929. Historically, the comparison (\c
  3930. .BR $1< 10)
  3931. was done numerically after evaluating
  3932. .BR $1
  3933. to the value zero.
  3934. .P
  3935. The phrase ``.\|.\|. also shall have the numeric value of the numeric
  3936. string'' was removed from several sections of the ISO\ POSIX\(hy2:\|1993 standard because is
  3937. specifies an unnecessary implementation detail. It is not necessary for
  3938. POSIX.1\(hy2008 to specify that these objects be assigned two different values.
  3939. It is only necessary to specify that these objects may evaluate to two
  3940. different values depending on context.
  3941. .P
  3942. Historical implementations of
  3943. .IR awk
  3944. did not parse hexadecimal integer or floating constants like
  3945. .BR \(dq0xa\(dq 
  3946. and
  3947. .BR \(dq0xap0\(dq .
  3948. Due to an oversight, the 2001 through 2004 editions of this standard
  3949. required support for hexadecimal floating constants. This was due to
  3950. the reference to
  3951. \fIatof\fR().
  3952. This version of the standard allows but does not require implementations
  3953. to use
  3954. \fIatof\fR()
  3955. and includes a description of how floating-point numbers are recognized
  3956. as an alternative to match historic behavior. The intent of this change
  3957. is to allow implementations to recognize floating-point constants
  3958. according to either the ISO/IEC\ 9899:\|1990 standard or ISO/IEC\ 9899:\|1999 standard, and to allow (but not require)
  3959. implementations to recognize hexadecimal integer constants.
  3960. .P
  3961. Historical implementations of
  3962. .IR awk
  3963. did not support floating-point infinities and NaNs in
  3964. .IR "numeric strings" ;
  3965. e.g.,
  3966. .BR \(dq-INF\(dq 
  3967. and
  3968. .BR \(dqNaN\(dq .
  3969. However, implementations that use the
  3970. \fIatof\fR()
  3971. or
  3972. \fIstrtod\fR()
  3973. functions to do the conversion picked up support for these values if they
  3974. used a ISO/IEC\ 9899:\|1999 standard version of the function instead of a ISO/IEC\ 9899:\|1990 standard version. Due to
  3975. an oversight, the 2001 through 2004 editions of this standard did not
  3976. allow support for infinities and NaNs, but in this revision support is
  3977. allowed (but not required). This is a silent change to the behavior of
  3978. .IR awk
  3979. programs; for example, in the POSIX locale the expression:
  3980. .sp
  3981. .RS 4
  3982. .nf
  3984. ("-INF" + 0 < 0)
  3985. .fi
  3986. .P
  3987. .RE
  3988. .P
  3989. formerly had the value 0 because
  3990. .BR \(dq-INF\(dq 
  3991. converted to 0, but now it may have the value 0 or 1.
  3992. .SH "FUTURE DIRECTIONS"
  3993. A future version of this standard may require the
  3994. .BR \(dq!=\(dq 
  3995. and
  3996. .BR \(dq==\(dq 
  3997. operators to perform string comparisons by checking if the strings are
  3998. identical (and not by checking if they collate equally).
  3999. .SH "SEE ALSO"
  4000. .IR "Section 1.3" ", " "Grammar Conventions",
  4001. .IR "\fIgrep\fR\^",
  4002. .IR "\fIlex\fR\^",
  4003. .IR "\fIsed\fR\^"
  4004. .P
  4005. The Base Definitions volume of POSIX.1\(hy2017,
  4006. .IR "Chapter 5" ", " "File Format Notation",
  4007. .IR "Section 6.1" ", " "Portable Character Set",
  4008. .IR "Chapter 8" ", " "Environment Variables",
  4009. .IR "Chapter 9" ", " "Regular Expressions",
  4010. .IR "Section 12.2" ", " "Utility Syntax Guidelines"
  4011. .P
  4012. The System Interfaces volume of POSIX.1\(hy2017,
  4013. .IR "\fIatof\fR\^(\|)",
  4014. .IR "\fIexec\fR\^",
  4015. .IR "\fIisspace\fR\^(\|)",
  4016. .IR "\fIpopen\fR\^(\|)",
  4017. .IR "\fIsetlocale\fR\^(\|)",
  4018. .IR "\fIstrtod\fR\^(\|)"
  4019. .\"
  4020. .SH COPYRIGHT
  4021. Portions of this text are reprinted and reproduced in electronic form
  4022. from IEEE Std 1003.1-2017, Standard for Information Technology
  4023. -- Portable Operating System Interface (POSIX), The Open Group Base
  4024. Specifications Issue 7, 2018 Edition,
  4025. Copyright (C) 2018 by the Institute of
  4026. Electrical and Electronics Engineers, Inc and The Open Group.
  4027. In the event of any discrepancy between this version and the original IEEE and
  4028. The Open Group Standard, the original IEEE and The Open Group Standard
  4029. is the referee document. The original Standard can be obtained online at
  4030. http://www.opengroup.org/unix/online.html .
  4031. .PP
  4032. Any typographical or formatting errors that appear
  4033. in this page are most likely
  4034. to have been introduced during the conversion of the source files to
  4035. man page format. To report such errors, see
  4036. https://www.kernel.org/doc/man-pages/reporting_bugs.html .