Debian Codegraph @

upstream/opensuse-tumbleweed/man1/gawk.1

raw
1 .ds PX \s-1POSIX\s+1
2 .ds UX \s-1UNIX\s+1
3 .ds GN \s-1GNU\s+1
4 .ds AK \s-1AWK\s+1
5 .ds EP \fIGAWK: Effective AWK Programming\fP
6 .if !\w@\*(lq@ \{\
7 .\" The implementation doesn't seem to support the strings `lq` or `rq`.
8 . ie \n(.g \{\
9 . ds lq \(lq\"
10 . ds rq \(rq\"
11 . \}
12 . el \{\
13 . ds lq ``
14 . ds rq ''
15 . \}
16 .\}
17 .TH GAWK 1 "February 10 2026" "Free Software Foundation" "Utility Commands"
18 .SH NAME
19 gawk \- pattern scanning and processing language
20 .SH SYNOPSIS
21 .B gawk
22 [ \*(PX or \*(GN style options ]
23 .B \-f
24 .I program-file
25 [
26 .B \-\^\-
27 ] file .\|.\|.
28 .br
29 .B gawk
30 [ \*(PX or \*(GN style options ]
31 [
32 .B \-\^\-
33 ]
34 .I program-text
35 file .\|.\|.
36 .SH README FIRST
37 This manual page is provided as a
38 .IR courtesy .
39 Please note that the One Source Of Truth for
40 .I gawk
41 is the Texinfo manual, available online in several formats at
42 .IR https://www.gnu.org/software/gawk/manual .
43 It may also be installed in the Info subsystem on your system,
44 and available therefore via the
45 .IR info (1)
46 command.
47 .PP
48 In the case of any contradiction between the Texinfo manual and
49 this manual page, the Texinfo manual should be considered to be authoritative.
50 .PP
51 Note that the Info documentation, HTML web page(s), and PDF version of
52 the manual all have the same content, since they are all generated
53 from the same Texinfo source file.
54 .PP
55 Furthermore, the
56 .I gawk
57 maintainer reserves the right in the future to remove this manual page from
58 the distribution or to severely truncate the content in order to
59 ease his maintenance burden.
60 .SH DESCRIPTION
61 .I Gawk
62 is the \*(GN Project's implementation of the \*(AK programming language.
63 It conforms to the definition of the language in
64 the \*(PX 1003.1 standard.
65 This version in turn is based on the description in
66 .IR "The AWK Programming Language" ,
67 by Aho, Kernighan, and Weinberger.
68 .I Gawk
69 provides the additional features found in the current version
70 of Brian Kernighan's
71 .I awk
72 and numerous \*(GN-specific extensions.
73 .PP
74 The command line consists of options to
75 .I gawk
76 itself, the \*(AK program text (if not supplied via the
77 .B \-f
78 or
79 .B \-\^\-include
80 options), and values to be made
81 available in the
82 .B ARGC
83 and
84 .B ARGV
85 pre-defined \*(AK variables.
86 .SH PREFACE
87 This manual page is intentionally as terse as possible.
88 Full details are provided in \*(EP, and you should look
89 there for the full story on any specific feature.
90 Where possible, links to the online version of the manual
91 are provided.
92 .SH OPTION FORMAT
93 .I Gawk
94 options may be either traditional \*(PX-style one letter options,
95 or \*(GN-style long options. \*(PX options start with a single \*(lq\-\*(rq,
96 while long options start with \*(lq\-\^\-\*(rq.
97 Long options are provided for both \*(GN-specific features and
98 for \*(PX-mandated features.
99 .PP
100 .IR Gawk -specific
101 options are typically used in long-option form.
102 Arguments to long options are either joined with the option
103 by an
104 .B =
105 sign, with no intervening spaces, or they may be provided in the
106 next command line argument.
107 Long options may be abbreviated, as long as the abbreviation
108 remains unique.
109 .PP
110 Additionally, every long option has a corresponding short
111 option, so that the option's functionality may be used from
112 within
113 .B #!\&
114 executable scripts.
115 .SH OPTIONS
116 .I Gawk
117 accepts the following options.
118 Standard options are listed first, followed by options for
119 .I gawk
120 extensions, listed alphabetically by short option.
121 .TP
122 .BI \-f " program-file\fR,\fP " \-\^\-file " program-file"
123 Read the \*(AK program source from the file
124 .IR program-file ,
125 instead of from the first command line argument.
126 Multiple
127 .B \-f
128 options may be used.
129 Files read with
130 .B \-f
131 are treated as if they begin with an implicit \fB@namespace "awk"\fR statement.
132 .TP
133 .BI \-F " fs\fR, \fP" \-\^\-field-separator " fs"
134 Use
135 .I fs
136 for the input field separator (the value of the
137 .B FS
138 predefined
139 variable).
140 .TP
141 \fB\-v\fI var\fB\^=\^\fIval\fR, \fB\-\^\-assign \fIvar\fB\^=\^\fIval\fR
142 Assign the value
143 .I val
144 to the variable
145 .IR var ,
146 before execution of the program begins.
147 Such variable values are available to the
148 .B BEGIN
149 rule of an \*(AK program.
150 .TP
151 .BR \-b ", " \-\^\-characters\-as\-bytes
152 Treat all input data as single-byte characters.
153 The
154 .B \-\^\-posix
155 option overrides this one.
156 .TP
157 .BR \-c ", " \-\^\-traditional
158 Run in
159 .I compatibility
160 mode. In compatibility mode,
161 .I gawk
162 behaves identically to Brian Kernighan's
163 .IR awk ;
164 none of the \*(GN-specific extensions are recognized.
165 .TP
166 .BR \-C ", " \-\^\-copyright
167 Print the short version of the \*(GN copyright information message on
168 the standard output and exit successfully.
169 .TP
170 \fB\-d\fR[\fIfile\fR], \fB\-\^\-dump-variables\fR[\fB=\fIfile\fR]
171 Print a sorted list of global variables, their types and final values to
172 .IR file .
173 The default file is
174 .B awkvars.out
175 in the current directory.
176 .TP
177 \fB\-D\fR[\fIfile\fR], \fB\-\^\-debug\fR[\fB=\fIfile\fR]
178 Enable debugging of \*(AK programs.
179 By default, the debugger reads commands interactively from the keyboard
180 (standard input).
181 The optional
182 .I file
183 argument specifies a file with a list
184 of commands for the debugger to execute non-interactively.
185 .sp .5
186 In this mode of execution,
187 .I gawk
188 loads the
189 AWK source code and then prompts for debugging commands.
190 .I Gawk
191 can only debug AWK program source provided with the
192 .B \-f
193 and
194 .B \-\^\-include
195 options.
196 The debugger is documented in \*(EP; see
197 .IR https://www.gnu.org/software/gawk/manual/html_node/Debugger.html#Debugger .
198 .TP
199 .BI \-e " program-text\fR, \fP" \-\^\-source " program-text"
200 Use
201 .I program-text
202 as \*(AK program source code.
203 Each argument supplied via
204 .B \-e
205 is treated as if it begins with an implicit \fB@namespace "awk"\fR statement.
206 .TP
207 \fB\-E \fIfile\fR, \fB\-\^\-exec \fIfile\fR
208 Similar to
209 .BR \-f ,
210 however, this option is the last one processed.
211 This should be used with
212 .B #!\&
213 scripts, particularly for CGI applications, to avoid
214 passing in options or source code (!\&) on the command line
215 from a URL.
216 This option disables command-line variable assignments.
217 .TP
218 .BR \-g ", " \-\^\-gen\-pot
219 Scan and parse the \*(AK program, and generate a \*(GN
220 .B \&.pot
221 (Portable Object Template)
222 format file on standard output with entries for all localizable
223 strings in the program. The program itself is not executed.
224 .TP
225 .BR \-h ", " \-\^\-help
226 Print a relatively short summary of the available options on
227 the standard output.
228 Per the
229 .IR "GNU Coding Standards" ,
230 these options cause an immediate, successful exit.
231 .TP
232 \fB\-i \fIinclude-file\fR, \fB\-\^\-include \fIinclude-file\fR
233 Load an awk source library.
234 This searches for the library using the
235 .B AWKPATH
236 environment variable. If the initial search fails, another attempt will
237 be made after appending the
238 .B \&.awk
239 suffix. The file will be loaded only
240 once (i.e., duplicates are eliminated), and the code does not constitute
241 the main program source.
242 Files read with
243 .B \-\^\-include
244 are treated as if they begin with an implicit \fB@namespace "awk"\fR statement.
245 .TP
246 .BR \-I ", " \-\^\-trace
247 Print the internal byte code names as they are executed when running
248 the program.
249 The trace is printed to standard error.
250 Each \*(lqop code\*(rq is preceded by a
251 .B +
252 sign in the output.
253 .TP
254 \fB\-k\fR, \fB\-\^\-csv\fR
255 Enable CSV special processing.
256 See
257 .BR "Comma Separated Values" ,
258 below, for more detail.
259 .TP
260 .BI \-l " lib\fR, " \-\^\-load " lib"
261 Load a
262 .I gawk
263 extension from the shared library
264 .IR lib .
265 This searches for the library using the
266 .B AWKLIBPATH
267 environment variable. If the initial search fails, another attempt will
268 be made after appending the default shared library suffix for the platform.
269 The library initialization routine is expected to be named
270 .BR dl_load() .
271 .TP
272 \fB\-L \fR[\fIvalue\fR], \fB\-\^\-lint\fR[\fB=\fIvalue\fR]
273 Provide warnings about constructs that are
274 dubious or non-portable to other \*(AK implementations.
275 See
276 .I https://www.gnu.org/software/gawk/manual/html_node/Options.html#Options
277 for the list of possible values for
278 .IR value .
279 .TP
280 .BR \-M ", " \-\^\-bignum
281 Force arbitrary precision arithmetic on numbers.
282 This option has no effect if
283 .I gawk
284 is not compiled to use the GNU MPFR and GMP libraries.
285 (In such a case,
286 .I gawk
287 issues a warning.)
288 .sp
289 .B NOTE:
290 This feature is
291 .IR "on parole" .
292 The primary
293 .I gawk
294 maintainer is no longer supporting it, although there is
295 a member of the development team who is.
296 If this situation changes,
297 the feature will be removed from
298 .IR gawk .
299 .ig
300 Set
301 .B GAWK_NO_MPFR_WARN
302 in the environment to silence the warning.
303 ..
304 .TP
305 .BR \-n ", " \-\^\-non\-decimal\-data
306 Recognize octal and hexadecimal values in input data.
307 .I "Use this option with great caution!"
308 .TP
309 .BR \-N ", " \-\^\-use\-lc\-numeric
310 Force
311 .I gawk
312 to use the locale's decimal point character when parsing input data.
313 .TP
314 \fB\-o\fR[\fIfile\fR], \fB\-\^\-pretty-print\fR[\fB=\fIfile\fR]
315 Output a pretty printed version of the program to
316 .IR file .
317 The default file is
318 .B awkprof.out
319 in the current directory.
320 This option implies
321 .BR \-\^\-no\-optimize .
322 .TP
323 .BR \-O ", " \-\^\-optimize
324 Enable
325 .IR gawk 's
326 default optimizations upon the internal representation of the program.
327 This option is on by default.
328 .TP
329 \fB\-p\fR[\fIprof-file\fR], \fB\-\^\-profile\fR[\fB=\fIprof-file\fR]
330 Start a profiling session, and send the profiling data to
331 .IR prof-file .
332 The default is
333 .B awkprof.out
334 in the current directory.
335 The profile contains execution counts of each statement in the program
336 in the left margin and function call counts for each user-defined function.
337 .I Gawk
338 runs more slowly in this mode.
339 This option implies
340 .BR \-\^\-no\-optimize .
341 .TP
342 .BR \-P ", " \-\^\-posix
343 This turns on
344 .I compatibility
345 mode, and disables a number of common extensions.
346 .TP
347 .BR \-r ", " \-\^\-re\-interval
348 Enable the use of
349 .I "interval expressions"
350 in regular expression matching.
351 Interval expressions
352 are enabled by default, but this option remains for backwards compatibility.
353 .TP
354 .BR \-s ", " \-\^\-no\-optimize
355 Disable
356 .IR gawk 's
357 default optimizations upon the internal representation of the program.
358 .TP
359 .BR \-S ", " \-\^\-sandbox
360 Run
361 .I gawk
362 in sandbox mode, disabling the
363 .B system()
364 function, input redirection with
365 .BR getline ,
366 output redirection with
367 .BR print " and " printf ,
368 and loading dynamic extensions.
369 Command execution (through pipelines) is also disabled.
370 .TP
371 .BR \-t ", " \-\^\-lint\-old
372 Provide warnings about constructs that are
373 not portable to the original version of \*(UX
374 .IR awk .
375 .TP
376 .BR \-V ", " \-\^\-version
377 Print version information for this particular copy of
378 .I gawk
379 on the standard output.
380 This is useful when reporting bugs.
381 Per the
382 .IR "GNU Coding Standards" ,
383 these options cause an immediate, successful exit.
384 .TP
385 .B \-\^\-
386 Signal the end of options.
387 This is useful to allow further arguments to the
388 \*(AK program itself to start with a \*(lq\-\*(rq.
389 .PP
390 In compatibility mode,
391 any other options are flagged as invalid, but are otherwise ignored.
392 In normal operation, as long as program text has been supplied, unknown
393 options are passed on to the \*(AK program in the
394 .B ARGV
395 array for processing.
396 .PP
397 For \*(PX compatibility, the
398 .B \-W
399 option may be used, followed by the name of a long option.
400 .SH AWK PROGRAM EXECUTION
401 An \*(AK program consists of a sequence of
402 optional directives,
403 pattern-action statements,
404 and optional function definitions.
405 .RS
406 .PP
407 \fB@include "\fIfilename\^\fB"
408 .br
409 \fB@nsinclude "\fIfilename\^\fB"
410 .br
411 \fB@load "\fIfilename\^\fB"
412 .br
413 \fB@namespace "\fIname\^\fB"
414 .br
415 \fIpattern\fB { \fIaction statements\fB }\fR
416 .br
417 \fBfunction \fIname\fB(\fIparameter list\fB) { \fIstatements\fB }\fR
418 .RE
419 .PP
420 .I Gawk
421 first reads the program source from the
422 .IR program-file (s)
423 if specified,
424 from arguments to
425 .BR \-\^\-source ,
426 or from the first non-option argument on the command line.
427 The
428 .B \-f
429 and
430 .B \-\^\-source
431 options may be used multiple times on the command line.
432 .I Gawk
433 reads the program text as if all the
434 .IR program-file s
435 and command line source texts
436 had been concatenated together.
437 .PP
438 In addition, lines beginning with
439 .B @include
440 may be used to include other source files into your program.
441 This is equivalent
442 to using the
443 .B \-\^\-include
444 option.
445 .PP
446 Lines beginning with
447 .B @nsinclude
448 also include files, but with two differences.
449 First, the namespace in the included file is
450 .I not
451 reset to the default of
452 .BR awk ,
453 and such files may be included multiple times.
454 .PP
455 Lines beginning with
456 .B @load
457 may be used to load extension functions into your program. This is equivalent
458 to using the
459 .B \-\^\-load
460 option.
461 .PP
462 The environment variable
463 .B AWKPATH
464 specifies a search path to use when finding source files named with
465 the
466 .B \-f
467 and
468 .B \-\^\-include
469 options. If this variable does not exist, the default path is
470 \fB".:/usr/local/share/awk"\fR.
471 (The actual directory may vary, depending upon how
472 .I gawk
473 was built and installed.)
474 If a file name given to the
475 .B \-f
476 option contains a \*(lq/\*(rq character, no path search is performed.
477 .PP
478 The environment variable
479 .B AWKLIBPATH
480 specifies a search path to use when finding source files named with
481 the
482 .B \-\^\-load
483 option. If this variable does not exist, the default path is
484 \fB"/usr/local/lib/gawk"\fR.
485 (The actual directory may vary, depending upon how
486 .I gawk
487 was built and installed.)
488 .PP
489 .I Gawk
490 executes \*(AK programs in the following order.
491 First,
492 all variable assignments specified via the
493 .B \-v
494 option are performed.
495 Next,
496 .I gawk
497 compiles the program into an internal form.
498 Then,
499 .I gawk
500 executes the code in the
501 .B BEGIN
502 rule(s) (if any),
503 and then proceeds to read
504 each file named in the
505 .B ARGV
506 array (up to
507 .BR ARGV[ARGC\-1] ).
508 If there are no files named on the command line,
509 .I gawk
510 reads the standard input.
511 .PP
512 If a filename on the command line has the form
513 .IB var = val
514 it is treated as a variable assignment. The variable
515 .I var
516 will be assigned the value
517 .IR val .
518 (This happens after any
519 .B BEGIN
520 rule(s) have been run.)
521 .PP
522 If the value of a particular element of
523 .B ARGV
524 is empty (\fB""\fR),
525 .I gawk
526 skips over it.
527 .PP
528 For each input file,
529 if a
530 .B BEGINFILE
531 rule exists,
532 .I gawk
533 executes the associated code
534 before processing the contents of the file.
535 Similarly,
536 .I gawk
537 executes
538 the code associated with
539 .B ENDFILE
540 rules
541 after processing the file.
542 .PP
543 For each record in the input,
544 .I gawk
545 tests to see if it matches any
546 .I pattern
547 in the \*(AK program.
548 For each pattern that the record matches,
549 .I gawk
550 executes the associated
551 .IR action .
552 The patterns are tested in the order they occur in the program.
553 .PP
554 Finally, after all the input is exhausted,
555 .I gawk
556 executes the code in the
557 .B END
558 rule(s) (if any).
559 .SS Command Line Directories
560 According to POSIX, files named on the
561 .I awk
562 command line must be
563 text files. The behavior is \*(lqundefined\*(rq if they are not. Most versions
564 of
565 .I awk
566 treat a directory on the command line as a fatal error.
567 .PP
568 For
569 .IR gawk ,
570 a directory on the command line
571 produces a warning, but is otherwise skipped. If either of the
572 .B \-\^\-posix
573 or
574 .B \-\^\-traditional
575 options is given, then
576 .I gawk
577 reverts to
578 treating directories on the command line as a fatal error.
579 .SH VARIABLES, RECORDS AND FIELDS
580 \*(AK variables are dynamic; they come into existence when they are
581 first used. Their values are either floating-point numbers or strings,
582 or both,
583 depending upon how they are used.
584 Additionally,
585 .I gawk
586 allows variables to have regular-expression type.
587 \*(AK also has one dimensional
588 arrays; arrays with multiple dimensions may be simulated.
589 However,
590 .I gawk
591 provides true arrays of arrays.
592 Several pre-defined variables are set as a program
593 runs; these are described as needed and summarized below.
594 .SS Records
595 Normally, records are separated by newline characters. You can control how
596 records are separated by assigning values to the built-in variable
597 .BR RS .
598 See
599 .I https://www.gnu.org/software/gawk/manual/html_node/Records.html
600 for the details.
601 .SS Fields
602 As each input record is read,
603 .I gawk
604 splits the record into
605 .IR fields ,
606 using the value of the
607 .B FS
608 variable as the field separator.
609 Additionally,
610 .B FIELDWIDTHS
611 and
612 .B FPAT
613 may be used to control input field splitting.
614 See the details, starting at
615 .IR https://www.gnu.org/software/gawk/manual/html_node/Fields.html .
616 .PP
617 Each field in the input record may be referenced by its position:
618 .BR $1 ,
619 .BR $2 ,
620 and so on.
621 .B $0
622 is the whole record,
623 including leading and trailing whitespace.
624 .PP
625 The variable
626 .B NF
627 is set to the total number of fields in the input record.
628 .PP
629 References to non-existent fields (i.e., fields after
630 .BR $NF )
631 produce the null string. However, assigning to a non-existent field
632 (e.g.,
633 .BR "$(NF+2) = 5" )
634 increases the value of
635 .BR NF ,
636 creates any intervening fields with the null string as their values, and
637 causes the value of
638 .B $0
639 to be recomputed, with the fields being separated by the value of
640 .BR OFS .
641 References to negative numbered fields cause a fatal error.
642 Decrementing
643 .B NF
644 causes the values of fields past the new value to be lost, and the value of
645 .B $0
646 to be recomputed, with the fields being separated by the value of
647 .BR OFS .
648 .PP
649 Assigning a value to an existing field
650 causes the whole record to be rebuilt when
651 .B $0
652 is referenced.
653 Similarly, assigning a value to
654 .B $0
655 causes the record to be resplit, creating new
656 values for the fields.
657 .SS Comma Separated Values
658 When invoked with either the
659 .B \-k
660 or the
661 .B \-\^\-csv
662 option,
663 .I gawk
664 does not use regular record determination and field splitting
665 as described above.
666 Instead, records are terminated by unquoted newlines, and
667 fields are separated by commas.
668 Double-quotes may be used to enclose fields containing
669 commas, newlines, or doubled double-quotes.
670 See
671 .I https://www.gnu.org/software/gawk/manual/html_node/Comma-Separated-Fields.html
672 for more details.
673 .SS Built-in Variables
674 .IR Gawk\^ "'s"
675 built-in variables are listed below.
676 This list is purposely terse.
677 For details, see
678 .IR https://www.gnu.org/software/gawk/manual/html_node/Built_002din-Variables .
679 .TP "\w'\fBFIELDWIDTHS\fR'u+1n"
680 .B ARGC
681 The number of command line arguments.
682 .TP
683 .B ARGIND
684 The index in
685 .B ARGV
686 of the current file being processed.
687 .TP
688 .B ARGV
689 Array of command line arguments. The array is indexed from
690 0 to
691 .B ARGC
692 \- 1.
693 .TP
694 .B BINMODE
695 On non-POSIX systems, specifies use of \*(lqbinary\*(rq mode for all file I/O.
696 See
697 .I https://www.gnu.org/software/gawk/manual/html_node/PC-Using.html
698 for the details.
699 .TP
700 .B CONVFMT
701 The conversion format for numbers, \fB"%.6g"\fR, by default.
702 .TP
703 .B ENVIRON
704 An array containing the values of the current environment.
705 The array is indexed by the environment variables, each element being
706 the value of that variable.
707 .TP
708 .B ERRNO
709 If a system error occurs either doing a redirection for
710 .BR getline ,
711 during a read for
712 .BR getline ,
713 or during a
714 .BR close() ,
715 then
716 .B ERRNO
717 is set to
718 a string describing the error.
719 The value is subject to translation in non-English locales.
720 .TP
721 .B FIELDWIDTHS
722 A whitespace-separated list of field widths. When set,
723 .I gawk
724 parses the input into fields of fixed width, instead of using the
725 value of the
726 .B FS
727 variable as the field separator.
728 Each field width may optionally be preceded by a colon-separated
729 value specifying the number of characters to skip before the field starts.
730 .TP
731 .B FILENAME
732 The name of the current input file.
733 If no files are specified on the command line, the value of
734 .B FILENAME
735 is \*(lq\-\*(rq.
736 However,
737 .B FILENAME
738 is undefined inside the
739 .B BEGIN
740 rule
741 (unless set by
742 .BR getline ).
743 .TP
744 .B FNR
745 The input record number in the current input file.
746 .TP
747 .B FPAT
748 A regular expression describing the contents of the
749 fields in a record.
750 When set,
751 .I gawk
752 parses the input into fields, where the fields match the
753 regular expression, instead of using the
754 value of
755 .B FS
756 as the field separator.
757 .TP
758 .B FS
759 The input field separator, a space by default.
760 See
761 .I https://www.gnu.org/software/gawk/manual/html_node/Field-Separators.html
762 for the details.
763 .TP
764 .B FUNCTAB
765 An array whose indices and corresponding values
766 are the names of all the user-defined
767 or extension functions in the program.
768 .BR NOTE :
769 You may not use the
770 .B delete
771 statement with the
772 .B FUNCTAB
773 array.
774 .TP
775 .B IGNORECASE
776 Controls the case-sensitivity of all regular expression
777 and string operations.
778 See
779 .I https://www.gnu.org/software/gawk/manual/html_node/Case_002dsensitivity.html
780 for details.
781 .TP
782 .B LINT
783 Provides dynamic control of the
784 .B \-\^\-lint
785 option from within an \*(AK program.
786 .TP
787 .B NF
788 The number of fields in the current input record.
789 .TP
790 .B NR
791 The total number of input records seen so far.
792 .TP
793 .B OFMT
794 The output format for numbers, \fB"%.6g"\fR, by default.
795 .TP
796 .B OFS
797 The output field separator, a space by default.
798 .TP
799 .B ORS
800 The output record separator, by default a newline.
801 .TP
802 .B PREC
803 The working precision of arbitrary precision floating-point
804 numbers, 53 by default.
805 .TP
806 .B PROCINFO
807 The elements of this array provide access to information about the
808 running \*(AK program.
809 See
810 .I https://www.gnu.org/software/gawk/manual/html_node/Auto_002dset
811 for the details.
812 .TP
813 .B ROUNDMODE
814 The rounding mode to use for arbitrary precision arithmetic on
815 numbers, by default \fB"N"\fR (IEEE-754 roundTiesToEven mode).
816 See
817 .I https://www.gnu.org/software/gawk/manual/html_node/Setting-the-rounding-mode
818 for the details.
819 .TP
820 .B RS
821 The input record separator, by default a newline.
822 .TP
823 .B RT
824 The record terminator.
825 .I Gawk
826 sets
827 .B RT
828 to the input text that matched the character or regular expression
829 specified by
830 .BR RS .
831 .TP
832 .B RSTART
833 The index of the first character matched by
834 .BR match() ;
835 0 if no match.
836 .TP
837 .B RLENGTH
838 The length of the string matched by
839 .BR match() ;
840 \-1 if no match.
841 .TP
842 .B SUBSEP
843 The string used to separate multiple subscripts in array
844 elements, by default \fB"\e034"\fR.
845 .TP
846 .B SYMTAB
847 An array whose indices are the names of all currently defined
848 global variables and arrays in the program.
849 You may not use the
850 .B delete
851 statement with the
852 .B SYMTAB
853 array, nor assign to elements with an index that is
854 not a variable name.
855 .TP
856 .B TEXTDOMAIN
857 The text domain of the \*(AK program; used to find the localized
858 translations for the program's strings.
859 .SS Arrays
860 Arrays are subscripted with an expression between square brackets
861 .RB ( [ " and " ] ).
862 If the expression is an expression list
863 .RI ( expr ", " expr " .\|.\|.)"
864 then the array subscript is a string consisting of the
865 concatenation of the (string) value of each expression,
866 separated by the value of the
867 .B SUBSEP
868 variable.
869 This facility is used to simulate multiply dimensioned
870 arrays. For example:
871 .PP
872 .RS
873 .ft B
874 i = "A";\^ j = "B";\^ k = "C"
875 .br
876 x[i, j, k] = "hello, world\en"
877 .ft R
878 .RE
879 .PP
880 assigns the string \fB"hello,\ world\en"\fR to the element of the array
881 .B x
882 which is indexed by the string \fB"A\e034B\e034C"\fR. All arrays in \*(AK
883 are associative, i.e., indexed by string values.
884 .PP
885 The special operator
886 .B in
887 may be used to test if an array has an index consisting of a particular
888 value:
889 .PP
890 .RS
891 .ft B
892 .nf
893 if (val in array)
894 print array[val]
895 .fi
896 .ft
897 .RE
898 .PP
899 If the array has multiple subscripts, use
900 .BR "(i, j) in array" .
901 .PP
902 The
903 .B in
904 construct may also be used in a
905 .B for
906 loop to iterate over all the elements of an array.
907 However, the
908 .B "(i, j) in array"
909 construct only works in tests, not in
910 .B for
911 loops.
912 .PP
913 An element may be deleted from an array using the
914 .B delete
915 statement.
916 The
917 .B delete
918 statement may also be used to delete the entire contents of an array,
919 just by specifying the array name without a subscript.
920 .PP
921 .I gawk
922 supports true multidimensional arrays.
923 It does not require that such arrays be \*(lqrectangular\*(rq as in C or C++.
924 See
925 .I https://www.gnu.org/software/gawk/manual/html_node/Arrays
926 for details.
927 .SS Namespaces
928 .I Gawk
929 provides a simple
930 .I namespace
931 facility to help work around the fact that all variables in
932 AWK are global.
933 .PP
934 A
935 .I "qualified name"
936 consists of a two simple identifiers joined by a double colon
937 .RB ( :: ).
938 The left-hand identifier represents the namespace and the right-hand
939 identifier is the variable within it.
940 All simple (non-qualified) names are considered to be in the
941 \*(lqcurrent\*(rq namespace; the default namespace is
942 .BR awk .
943 However, simple identifiers consisting solely of uppercase
944 letters are forced into the
945 .B awk
946 namespace, even if the current namespace is different.
947 .PP
948 You change the current namespace with an
949 \fB@namespace "\fIname\^\fB"\fR
950 directive.
951 .PP
952 The standard predefined builtin function names may not be used as
953 namespace names. The names of additional functions provided by
954 .I gawk
955 may be used as namespace names or as simple identifiers in other
956 namespaces.
957 For more details, see
958 .IR https://www.gnu.org/software/gawk/manual/html_node/Namespaces.html#Namespaces .
959 .SS Variable Typing And Conversion
960 Variables and fields
961 may be (floating point) numbers, or strings, or both.
962 They may also be regular expressions.
963 How the value of a variable is interpreted depends upon its context.
964 If used in a numeric expression,
965 it will be treated as a number;
966 if used as a string it will be treated as a string.
967 .PP
968 To force a variable to be treated as a number, add zero to it; to force it
969 to be treated as a string, concatenate it with the null string.
970 .PP
971 Uninitialized variables have the numeric value zero and the string value ""
972 (the null, or empty, string).
973 .PP
974 When a string must be converted to a number, the conversion is accomplished
975 using
976 .IR strtod (3).
977 A number is converted to a string by using the value of
978 .B CONVFMT
979 as a format string for
980 .IR sprintf (3),
981 with the numeric value of the variable as the argument.
982 However, even though all numbers in \*(AK are floating-point,
983 integral values are
984 .I always
985 converted as integers.
986 .PP
987 .I Gawk
988 performs comparisons as follows:
989 If two variables are numeric, they are compared numerically.
990 If one value is numeric and the other has a string value that is a
991 \*(lqnumeric string,\*(rq then comparisons are also done numerically.
992 Otherwise, the numeric value is converted to a string and a string
993 comparison is performed.
994 Two strings are compared, of course, as strings.
995 .PP
996 Note that string constants, such as \fB"57"\fP, are
997 .I not
998 numeric strings, they are string constants.
999 The idea of \*(lqnumeric string\*(rq
1000 only applies to fields,
1001 .B getline
1002 input,
1003 .BR FILENAME ,
1004 .B ARGV
1005 elements,
1006 .B ENVIRON
1007 elements and the elements of an array created by
1008 .B split()
1009 or
1010 .B patsplit()
1011 that are numeric strings.
1012 The basic idea is that
1013 .IR "user input" ,
1014 and only user input, that looks numeric,
1015 should be treated that way.
1016 .SS Octal and Hexadecimal Constants
1017 You may use C-style octal and hexadecimal constants in your AWK
1018 program source code.
1019 For example, the octal value
1020 .B 011
1021 is equal to decimal
1022 .BR 9 ,
1023 and the hexadecimal value
1024 .B 0x11
1025 is equal to decimal 17.
1026 .SS String Constants
1027 String constants in \*(AK are sequences of characters enclosed
1028 between double quotes (like \fB"value"\fR). Within strings, certain
1029 .I "escape sequences"
1030 are recognized, as in C.
1031 See
1032 .I https://www.gnu.org/software/gawk/manual/html_node/Escape-Sequences
1033 for the details.
1034 .SS Regexp Constants
1035 A regular expression constant is a sequence of characters enclosed
1036 between forward slashes (like
1037 .BR /value/ ).
1038 .PP
1039 The escape sequences described in the manual may also be used inside
1040 constant regular expressions
1041 (e.g.,
1042 .B "/[\ \et\ef\en\er\ev]/"
1043 matches whitespace characters).
1044 .PP
1045 .I Gawk
1046 provides
1047 .I "strongly typed"
1048 regular expression constants.
1049 These are written with a leading
1050 .B @
1051 symbol (like so:
1052 .BR @/value/ ).
1053 Such constants may be assigned to scalars (variables, array elements)
1054 and passed to user-defined functions.
1055 Variables that have been so assigned have regular expression type.
1056 .SH PATTERNS AND ACTIONS
1057 \*(AK is a line-oriented language. The pattern comes first, and then the
1058 action. Action statements are enclosed in
1059 .B {
1060 and
1061 .BR } .
1062 Either the pattern may be missing, or the action may be missing, but,
1063 of course, not both. If the pattern is missing, the action
1064 executes for every single record of input.
1065 A missing action is equivalent to
1066 .RS
1067 .PP
1068 .B "{ print }"
1069 .RE
1070 .PP
1071 which prints the entire record.
1072 .PP
1073 Comments begin with the
1074 .B #
1075 character, and continue until the
1076 end of the line.
1077 Empty lines may be used to separate statements.
1078 Normally, a statement ends with a newline, however, this is not the
1079 case for lines ending in
1080 a comma,
1081 .BR { ,
1082 .BR ? ,
1083 .BR : ,
1084 .BR && ,
1085 or
1086 .BR || .
1087 Lines ending in
1088 .B do
1089 or
1090 .B else
1091 also have their statements automatically continued on the following line.
1092 In other cases, a line can be continued by ending it with a \*(lq\e\*(rq,
1093 in which case the newline is ignored. However, a \*(lq\e\*(rq after a
1094 .B #
1095 is not special.
1096 .PP
1097 Multiple statements may
1098 be put on one line by separating them with a \*(lq;\*(rq.
1099 This applies to both the statements within the action part of a
1100 pattern-action pair (the usual case),
1101 and to the pattern-action statements themselves.
1102 .SS Patterns
1103 \*(AK patterns may be one of the following:
1104 .PP
1105 .RS
1106 .nf
1107 .B BEGIN
1108 .B END
1109 .B BEGINFILE
1110 .B ENDFILE
1111 .BI / "regular expression" /
1112 .I "relational expression"
1113 .IB pattern " && " pattern
1114 .IB pattern " || " pattern
1115 .IB pattern " ?\& " pattern " : " pattern
1116 .BI ( pattern )
1117 .BI !\& " pattern"
1118 .IB pattern1 ", " pattern2
1119 .fi
1120 .RE
1121 .PP
1122 .B BEGIN
1123 and
1124 .B END
1125 are two special kinds of patterns which are not tested against
1126 the input.
1127 The action parts of all
1128 .B BEGIN
1129 patterns are merged as if all the statements had
1130 been written in a single
1131 .B BEGIN
1132 rule. They are executed before any
1133 of the input is read. Similarly, all the
1134 .B END
1135 rules are merged,
1136 and executed when all the input is exhausted (or when an
1137 .B exit
1138 statement is executed).
1139 .B BEGIN
1140 and
1141 .B END
1142 patterns cannot be combined with other patterns in pattern expressions.
1143 .B BEGIN
1144 and
1145 .B END
1146 patterns cannot have missing action parts.
1147 .PP
1148 .B BEGINFILE
1149 and
1150 .B ENDFILE
1151 are additional special patterns whose actions are executed
1152 before reading the first record of each command-line input file
1153 and after reading the last record of each file.
1154 Inside the
1155 .B BEGINFILE
1156 rule, the value of
1157 .B ERRNO
1158 is the empty string if the file was opened successfully.
1159 Otherwise, there is some problem with the file and the code should
1160 use
1161 .B nextfile
1162 to skip it.
1163 If that is not done,
1164 .I gawk
1165 produces its usual fatal error for files that cannot be opened.
1166 .PP
1167 For
1168 .BI / "regular expression" /
1169 patterns,
1170 the associated statement is executed for each input record
1171 that matches the regular expression.
1172 Regular expressions are essentially the same as those in
1173 .IR egrep (1).
1174 See
1175 .I https://www.gnu.org/software/gawk/manual/html_node/Regexp.html
1176 for the details on regular expressions.
1177 .PP
1178 A
1179 .I "relational expression"
1180 may use any of the operators defined below in the section on actions.
1181 These generally test whether certain fields match certain regular expressions.
1182 .PP
1183 The
1184 .BR && ,
1185 .BR || ,
1186 and
1187 .B !
1188 operators are logical AND, logical OR, and logical NOT, respectively, as in C.
1189 They do short-circuit evaluation, also as in C, and are used for combining
1190 more primitive pattern expressions. As in most languages, parentheses
1191 may be used to change the order of evaluation.
1192 .PP
1193 The
1194 .B ?\^:
1195 operator is like the same operator in C. If the first pattern is true
1196 then the pattern used for testing is the second pattern, otherwise it is
1197 the third. Only one of the second and third patterns is evaluated.
1198 .PP
1199 The
1200 .IB pattern1 ", " pattern2
1201 form of an expression is called a
1202 .IR "range pattern" .
1203 It matches all input records starting with a record that matches
1204 .IR pattern1 ,
1205 and continuing until a record that matches
1206 .IR pattern2 ,
1207 inclusive. It does not combine with any other sort of pattern expression.
1208 .SS Actions
1209 Action statements are enclosed in braces,
1210 .B {
1211 and
1212 .BR } .
1213 Action statements consist of the usual assignment, conditional, and looping
1214 statements found in most languages. The operators, control statements,
1215 and input/output statements
1216 available are patterned after those in C.
1217 .SS Operators
1218 The operators in \*(AK, in order of decreasing precedence, are:
1219 .TP "\w'\fB*= /= %= ^=\fR'u+1n"
1220 .BR ( \&.\|.\|. )
1221 Grouping
1222 .TP
1223 .B $
1224 Field reference.
1225 .TP
1226 .B "++ \-\^\-"
1227 Increment and decrement, both prefix and postfix.
1228 .TP
1229 .B ^
1230 Exponentiation.
1231 .TP
1232 .B "+ \- !"
1233 Unary plus, unary minus, and logical negation.
1234 .TP
1235 .B "* / %"
1236 Multiplication, division, and modulus.
1237 .TP
1238 .B "+ \-"
1239 Addition and subtraction.
1240 .TP
1241 .I space
1242 String concatenation.
1243 .TP
1244 .B "| |&"
1245 Piped I/O for
1246 .BR getline ,
1247 .BR print ,
1248 and
1249 .BR printf .
1250 .TP
1251 .B "< > <= >= == !="
1252 The regular relational operators.
1253 .TP
1254 .B "~ !~"
1255 Regular expression match, negated match.
1256 .TP
1257 .B in
1258 Array membership.
1259 .TP
1260 .B &&
1261 Logical AND.
1262 .TP
1263 .B ||
1264 Logical OR.
1265 .TP
1266 .B ?:
1267 The C conditional expression. This has the form
1268 .IB expr1 " ? " expr2 " : " expr3\/\fR.
1269 If
1270 .I expr1
1271 is true, the value of the expression is
1272 .IR expr2 ,
1273 otherwise it is
1274 .IR expr3 .
1275 Only one of
1276 .I expr2
1277 and
1278 .I expr3
1279 is evaluated.
1280 .TP
1281 .B "= += \-= *= /= %= ^="
1282 Assignment. Both absolute assignment
1283 .BI ( var " = " value )
1284 and operator-assignment (the other forms) are supported.
1285 .SS Control Statements
1286 The control statements are
1287 as follows:
1288 .PP
1289 .RS
1290 .nf
1291 \fBif (\fIcondition\fB) \fIstatement\fR [ \fBelse\fI statement \fR]
1292 \fBwhile (\fIcondition\fB) \fIstatement\fR
1293 \fBdo \fIstatement \fBwhile (\fIcondition\fB)\fR
1294 \fBfor (\fIexpr1\fB; \fIexpr2\fB; \fIexpr3\fB) \fIstatement\fR
1295 \fBfor (\fIvar \fBin\fI array\fB) \fIstatement\fR
1296 \fBbreak\fR
1297 \fBcontinue\fR
1298 \fBdelete \fIarray\^\fB[\^\fIindex\^\fB]\fR
1299 \fBdelete \fIarray\^\fR
1300 \fBexit\fR [ \fIexpression\fR ]
1301 \fB{ \fIstatements \fB}\fR
1302 \fBswitch (\fIexpression\fB) {
1303 \fBcase \fIvalue\fB|\fIregex\fB : \fIstatement
1304 \&.\^.\^.
1305 \fR[ \fBdefault: \fIstatement \fR]
1306 \fB}\fR
1307 .fi
1308 .RE
1309 .SS I/O Statements
1310 The input/output statements are as follows:
1311 .TP "\w'\fBprintf \fIfmt, expr-list\fR'u+1n"
1312 \fBclose(\fIfile \fR[\fB, \fIhow\fR]\fB)\fR
1313 Close an open file, pipe or coprocess.
1314 The optional
1315 .I how
1316 should only be used when closing one end of a
1317 two-way pipe to a coprocess.
1318 It must be a string value, either
1319 \fB"to"\fR or \fB"from"\fR.
1320 .TP
1321 .B getline
1322 Set
1323 .B $0
1324 from the next input record; set
1325 .BR NF ,
1326 .BR NR ,
1327 .BR FNR ,
1328 .BR RT .
1329 .TP
1330 .BI "getline <" file
1331 Set
1332 .B $0
1333 from the next record of
1334 .IR file ;
1335 set
1336 .BR NF ,
1337 .BR RT .
1338 .TP
1339 .BI getline " var"
1340 Set
1341 .I var
1342 from the next input record; set
1343 .BR NR ,
1344 .BR FNR ,
1345 .BR RT .
1346 .TP
1347 .BI getline " var" " <" file
1348 Set
1349 .I var
1350 from the next record of
1351 .IR file ;
1352 set
1353 .BR RT .
1354 .TP
1355 \fIcommand\fB | getline \fR[\fIvar\fR]
1356 Run
1357 .IR command ,
1358 piping the output either into
1359 .B $0
1360 or
1361 .IR var ,
1362 as above, and
1363 .BR RT .
1364 .TP
1365 \fIcommand\fB |& getline \fR[\fIvar\fR]
1366 Run
1367 .I command
1368 as a coprocess
1369 piping the output either into
1370 .B $0
1371 or
1372 .IR var ,
1373 as above, and
1374 .BR RT .
1375 .RI "(The " command
1376 can also be a socket. See the subsection
1377 .BR "Special File Names" ,
1378 below.)
1379 .TP
1380 \&\fBfflush(\fR[\fIfile\^\fR]\fB)\fR
1381 Flush any buffers associated with the open output file or pipe
1382 .IR file .
1383 If
1384 .I file
1385 is missing or if it
1386 is the null string,
1387 then flush all open output files and pipes.
1388 .TP
1389 .B next
1390 Stop processing the current input record.
1391 Read the next input record
1392 and start processing over with the first pattern in the
1393 \*(AK program.
1394 Upon reaching the end of the input data,
1395 execute any
1396 .B END
1397 rule(s).
1398 .TP
1399 .B nextfile
1400 Stop processing the current input file. The next input record read
1401 comes from the next input file.
1402 Update
1403 .B FILENAME
1404 and
1405 .BR ARGIND ,
1406 reset
1407 .B FNR
1408 to 1, and start processing over with the first pattern in the
1409 \*(AK program.
1410 Upon reaching the end of the input data,
1411 execute any
1412 .B ENDFILE
1413 and
1414 .B END
1415 rule(s).
1416 .TP
1417 .B print
1418 Print the current record.
1419 The output record is terminated with the value of
1420 .BR ORS .
1421 .TP
1422 .BI print " expr-list"
1423 Print expressions.
1424 Each expression is separated by the value of
1425 .BR OFS .
1426 The output record is terminated with the value of
1427 .BR ORS .
1428 .TP
1429 .BI print " expr-list" " >" file
1430 Print expressions on
1431 .IR file .
1432 Each expression is separated by the value of
1433 .BR OFS .
1434 The output record is terminated with the value of
1435 .BR ORS .
1436 .TP
1437 .BI printf " fmt, expr-list"
1438 Format and print.
1439 .TP
1440 .BI printf " fmt, expr-list" " >" file
1441 Format and print on
1442 .IR file .
1443 .TP
1444 .BI system( cmd-line )
1445 Execute the command
1446 .IR cmd-line ,
1447 and return the exit status.
1448 (This may not be available on non-\*(PX systems.)
1449 See
1450 .I https://www.gnu.org/software/gawk/manual/html_node/I_002fO-Functions.html#I_002fO-Functions
1451 for the full details on the exit status.
1452 .PP
1453 Additional output redirections are allowed for
1454 .B print
1455 and
1456 .BR printf .
1457 .TP
1458 .BI "print .\|.\|.\& >>" " file"
1459 Append output to the
1460 .IR file .
1461 .TP
1462 .BI "print .\|.\|.\& |" " command"
1463 Write on a pipe.
1464 .TP
1465 .BI "print .\|.\|.\& |&" " command"
1466 Send data to a coprocess or socket.
1467 (See also the subsection
1468 .BR "Special File Names" ,
1469 below.)
1470 .PP
1471 The
1472 .B getline
1473 function returns 1 on success, zero on end of file, and \-1 on an error.
1474 If the
1475 .IR errno (3)
1476 value indicates that the I/O operation may be retried,
1477 and \fBPROCINFO["\fIinput\^\fP", "RETRY"]\fR
1478 is set, then \-2 is returned instead of \-1, and further calls to
1479 .B getline
1480 may be attempted.
1481 Upon an error,
1482 .B ERRNO
1483 is set to a string describing the problem.
1484 .PP
1485 .BR NOTE :
1486 Failure in opening a two-way socket results in a non-fatal error being
1487 returned to the calling function.
1488 If using a pipe, coprocess, or socket to
1489 .BR getline ,
1490 or from
1491 .B print
1492 or
1493 .B printf
1494 within a loop, you
1495 .I must
1496 use
1497 .B close()
1498 to create new instances of the command or socket.
1499 \*(AK does not automatically close pipes, sockets, or coprocesses when
1500 they return EOF.
1501 .PP
1502 The \*(AK versions of the
1503 .B printf
1504 statement and
1505 .B sprintf()
1506 function
1507 are similar to those of C.
1508 For details, see
1509 .IR https://www.gnu.org/software/gawk/manual/html_node/Printf.html .
1510 .SS Special File Names
1511 When doing I/O redirection from either
1512 .B print
1513 or
1514 .B printf
1515 into a file,
1516 or via
1517 .B getline
1518 from a file,
1519 .I gawk
1520 recognizes certain special filenames internally. These filenames
1521 allow access to open file descriptors inherited from
1522 .IR gawk\^ "'s"
1523 parent process (usually the shell).
1524 These file names may also be used on the command line to name data files.
1525 The filenames are:
1526 .TP "\w'\fB/dev/stdout\fR'u+1n"
1527 .B \-
1528 The standard input.
1529 .TP
1530 .B /dev/stdin
1531 The standard input.
1532 .TP
1533 .B /dev/stdout
1534 The standard output.
1535 .TP
1536 .B /dev/stderr
1537 The standard error output.
1538 .TP
1539 .BI /dev/fd/\^ n
1540 The file associated with the open file descriptor
1541 .IR n .
1542 .PP
1543 The following special filenames may be used with the
1544 .B |&
1545 coprocess operator for creating TCP/IP network connections:
1546 .TP
1547 .PD 0
1548 .BI /inet/tcp/ lport / rhost / rport
1549 .TP
1550 .PD 0
1551 .BI /inet4/tcp/ lport / rhost / rport
1552 .TP
1553 .PD
1554 .BI /inet6/tcp/ lport / rhost / rport
1555 Files for a TCP/IP connection on local port
1556 .I lport
1557 to
1558 remote host
1559 .I rhost
1560 on remote port
1561 .IR rport .
1562 Use a port of
1563 .B 0
1564 to have the system pick a port.
1565 Use
1566 .B /inet4
1567 to force an IPv4 connection,
1568 and
1569 .B /inet6
1570 to force an IPv6 connection.
1571 Plain
1572 .B /inet
1573 uses the system default (most likely IPv4).
1574 Usable only with the
1575 .B |&
1576 two-way I/O operator.
1577 .TP
1578 .PD 0
1579 .BI /inet/udp/ lport / rhost / rport
1580 .TP
1581 .PD 0
1582 .BI /inet4/udp/ lport / rhost / rport
1583 .TP
1584 .PD
1585 .BI /inet6/udp/ lport / rhost / rport
1586 Similar, but use UDP/IP instead of TCP/IP.
1587 .B "UDP support is obsolete and will be removed in the future."
1588 .SS Numeric Functions
1589 \*(AK has the following built-in arithmetic functions:
1590 .TP "\w'\fBsrand(\fR[\fIexpr\^\fR]\fB)\fR'u+1n"
1591 .BI atan2( y , " x" )
1592 Return the arctangent of
1593 .I y/x
1594 in radians.
1595 .TP
1596 .BI cos( expr )
1597 Return the cosine of
1598 .IR expr ,
1599 which is in radians.
1600 .TP
1601 .BI exp( expr )
1602 The exponential function.
1603 .TP
1604 .BI int( expr )
1605 Truncate to integer.
1606 .ig
1607 .TP
1608 .BI intdiv( num ", " denom ", " result )
1609 Truncate
1610 .I num
1611 and
1612 .I denom
1613 to integers.
1614 Return the quotient of
1615 .I num
1616 divided by
1617 .I denom
1618 in \fIresult\fB["quotient"]\fR
1619 and the remainder in
1620 \fIresult\fB["remainder"]\fR.
1621 This is a
1622 .I gawk
1623 extension, primarily of value when working with
1624 arbitrarily large integers.
1625 ..
1626 .TP
1627 .BI log( expr )
1628 The natural logarithm function.
1629 .TP
1630 .B rand()
1631 Return a random number
1632 .IR N ,
1633 between zero and one,
1634 such that 0 \(<= \fIN\fP < 1.
1635 .TP
1636 .BI sin( expr )
1637 Return the sine of
1638 .IR expr ,
1639 which is in radians.
1640 .TP
1641 .BI sqrt( expr )
1642 Return the square root of
1643 .IR expr .
1644 .TP
1645 \&\fBsrand(\fR[\fIexpr\^\fR]\fB)\fR
1646 Use
1647 .I expr
1648 as the new seed for the random number generator. If no
1649 .I expr
1650 is provided, use the time of day.
1651 Return the previous seed for the random
1652 number generator.
1653 .SS String Functions
1654 .I Gawk
1655 has the following built-in string functions; details are provided in
1656 .IR https://www.gnu.org/software/gawk/manual/html_node/String-Functions .
1657 .TP "\w'\fBsprintf(\fIfmt\^\fB, \fIexpr-list\^\fB)\fR'u+1n"
1658 \fBasort(\fIs \fR[\fB, \fId\fR [\fB, \fIhow\fR] ]\fB)\fR
1659 Return the number of elements in the source
1660 array
1661 .IR s .
1662 Sort
1663 the contents of
1664 .I s
1665 using
1666 .IR gawk\^ "'s"
1667 normal rules for
1668 comparing values, and replace the indices of the
1669 sorted values
1670 .I s
1671 with sequential
1672 integers starting with 1.
1673 If the optional destination array
1674 .I d
1675 is specified,
1676 first duplicate
1677 .I s
1678 into
1679 .IR d ,
1680 and then sort
1681 .IR d ,
1682 leaving the indices of the
1683 source array
1684 .I s
1685 unchanged.
1686 The optional string
1687 .I how
1688 controls the direction and the comparison mode.
1689 Valid values for
1690 .I how
1691 are
1692 described in
1693 .IR https://www.gnu.org/software/gawk/manual/html_node/String-Functions.html#String-Functions .
1694 .IR s " and " d
1695 are allowed to be the same array; this only makes sense when
1696 supplying the third argument as well.
1697 .TP
1698 \fBasorti(\fIs \fR[\fB, \fId\fR [\fB, \fIhow\fR] ]\fB)\fR
1699 Return the number of elements in the source
1700 array
1701 .IR s .
1702 The behavior is the same as that of
1703 .BR asort() ,
1704 except that the array
1705 .I indices
1706 are used for sorting, not the array values.
1707 When done, the array is indexed numerically, and
1708 the values are those of the original indices.
1709 The original values are lost; thus provide
1710 a second array if you wish to preserve the original.
1711 The purpose of the optional string
1712 .I how
1713 is the same as for
1714 .BR asort() .
1715 Here too,
1716 .IR s " and " d
1717 are allowed to be the same array; this only makes sense when
1718 supplying the third argument as well.
1719 .TP
1720 \fBgensub(\fIr\fB, \fIs\fB, \fIh \fR[\fB, \fIt\fR]\fB)\fR
1721 Search the target string
1722 .I t
1723 for matches of the regular expression
1724 .IR r .
1725 If
1726 .I h
1727 is a string beginning with
1728 .B g
1729 or
1730 .BR G ,
1731 then replace all matches of
1732 .I r
1733 with
1734 .IR s .
1735 Otherwise,
1736 .I h
1737 is a number indicating which match of
1738 .I r
1739 to replace.
1740 If
1741 .I t
1742 is not supplied, use
1743 .B $0
1744 instead.
1745 Within the replacement text
1746 .IR s ,
1747 the sequence
1748 .BI \e n\fR,
1749 where
1750 .I n
1751 is a digit from 1 to 9, may be used to indicate just the text that
1752 matched the
1753 .IR n 'th
1754 parenthesized subexpression. The sequence
1755 .B \e0
1756 represents the entire matched text, as does the character
1757 .BR & .
1758 Unlike
1759 .B sub()
1760 and
1761 .BR gsub() ,
1762 the modified string is returned as the result of the function,
1763 and the original target string is
1764 .I not
1765 changed.
1766 .TP
1767 \fBgsub(\fIr\fB, \fIs \fR[\fB, \fIt\fR]\fB)\fR
1768 For each substring matching the regular expression
1769 .I r
1770 in the string
1771 .IR t ,
1772 substitute the string
1773 .IR s ,
1774 and return the number of substitutions.
1775 If
1776 .I t
1777 is not supplied, use
1778 .BR $0 .
1779 An
1780 .B &
1781 in the replacement text is replaced with the text that was actually matched.
1782 Use
1783 .B \e&
1784 to get a literal
1785 .BR & .
1786 (This must be typed as \fB"\e\e&"\fP; see
1787 .I https://www.gnu.org/software/gawk/manual/html_node/Gory-Details.html#Gory-Details
1788 for a fuller discussion of the rules for ampersands
1789 and backslashes in the replacement text of
1790 .BR sub() ,
1791 .BR gsub() ,
1792 and
1793 .BR gensub() .)
1794 .TP
1795 .BI index( s , " t" )
1796 Return the index of the string
1797 .I t
1798 in the string
1799 .IR s ,
1800 or zero if
1801 .I t
1802 is not present.
1803 (This implies that character indices start at one.)
1804 .TP
1805 \fBlength(\fR[\fIs\fR]\fB)
1806 Return the length of the string
1807 .IR s ,
1808 or the length of
1809 .B $0
1810 if
1811 .I s
1812 is not supplied.
1813 With an array argument,
1814 .B length()
1815 returns the number of elements in the array.
1816 .TP
1817 \fBmatch(\fIs\fB, \fIr \fR[\fB, \fIa\fR]\fB)\fR
1818 Return the position in
1819 .I s
1820 where the regular expression
1821 .I r
1822 occurs, or zero if
1823 .I r
1824 is not present, and set the values of
1825 .B RSTART
1826 and
1827 .BR RLENGTH .
1828 Note that the argument order is the same as for the
1829 .B ~
1830 operator:
1831 .IB str " ~"
1832 .IR re .
1833 .ft R
1834 See
1835 .I https://www.gnu.org/software/gawk/manual/html_node/String-Functions.html#String-Functions
1836 for a description of how the array
1837 .I a
1838 is filled if it is provided.
1839 .TP
1840 \fBpatsplit(\fIs\fB, \fIa \fR[\fB, \fIr\fR [\fB, \fIseps\fR] ]\fB)\fR
1841 Split the string
1842 .I s
1843 into the array
1844 .I a
1845 and the separators array
1846 .I seps
1847 on the regular expression
1848 .IR r ,
1849 and return the number of fields.
1850 Element values are the portions of
1851 .I s
1852 that matched
1853 .IR r .
1854 The value of
1855 .BI seps[ i ]
1856 is the possibly null separator that appeared after
1857 .BI a[ i ]\fR.
1858 The value of
1859 .B seps[0]
1860 is the possibly null leading separator.
1861 If
1862 .I r
1863 is omitted,
1864 .B FPAT
1865 is used instead.
1866 The arrays
1867 .I a
1868 and
1869 .I seps
1870 are cleared first.
1871 Splitting behaves identically to field splitting with
1872 .BR FPAT .
1873 .TP
1874 \fBsplit(\fIs\fB, \fIa \fR[\fB, \fIr\fR [\fB, \fIseps\fR] ]\fB)\fR
1875 Split the string
1876 .I s
1877 into the array
1878 .I a
1879 and the separators array
1880 .I seps
1881 on the regular expression
1882 .IR r ,
1883 and return the number of fields. If
1884 .I r
1885 is omitted,
1886 .B FS
1887 is used instead.
1888 The arrays
1889 .I a
1890 and
1891 .I seps
1892 are cleared first.
1893 .BI seps[ i ]
1894 is the field separator matched by
1895 .I r
1896 between
1897 .BI a[ i ]
1898 and
1899 .BI a[ i +1]\fR.
1900 Splitting behaves identically to field splitting.
1901 .TP
1902 .BI sprintf( fmt\^ , " expr-list\^" )
1903 Print
1904 .I expr-list
1905 according to
1906 .IR fmt ,
1907 and return the resulting string.
1908 .TP
1909 .BI strtonum( str )
1910 Examine
1911 .IR str ,
1912 and return its numeric value.
1913 If
1914 .I str
1915 begins
1916 with a leading
1917 .BR 0 ,
1918 treat it
1919 as an octal number.
1920 If
1921 .I str
1922 begins
1923 with a leading
1924 .B 0x
1925 or
1926 .BR 0X ,
1927 treat it
1928 as a hexadecimal number.
1929 Otherwise, assume it is a decimal number.
1930 .TP
1931 \fBsub(\fIr\fB, \fIs \fR[\fB, \fIt\fR]\fB)\fR
1932 Just like
1933 .BR gsub() ,
1934 but replace only the first matching substring.
1935 Return either zero or one.
1936 .TP
1937 \fBsubstr(\fIs\fB, \fIi \fR[\fB, \fIn\fR]\fB)\fR
1938 Return the at most
1939 .IR n -character
1940 substring of
1941 .I s
1942 starting at
1943 .IR i .
1944 If
1945 .I n
1946 is omitted, use the rest of
1947 .IR s .
1948 .TP
1949 .BI tolower( str )
1950 Return a copy of the string
1951 .IR str ,
1952 with all the uppercase characters in
1953 .I str
1954 translated to their corresponding lowercase counterparts.
1955 Non-alphabetic characters are left unchanged.
1956 .TP
1957 .BI toupper( str )
1958 Return a copy of the string
1959 .IR str ,
1960 with all the lowercase characters in
1961 .I str
1962 translated to their corresponding uppercase counterparts.
1963 Non-alphabetic characters are left unchanged.
1964 .PP
1965 .I Gawk
1966 is multibyte aware. This means that
1967 .BR index() ,
1968 .BR length() ,
1969 .B substr()
1970 and
1971 .B match()
1972 all work in terms of characters, not bytes.
1973 .SS Time Functions
1974 .I Gawk
1975 provides the following functions for obtaining time stamps and
1976 formatting them.
1977 Details are provided in
1978 .IR https://www.gnu.org/software/gawk/manual/html_node/Time-Functions .
1979 .TP "\w'\fBsystime()\fR'u+1n"
1980 \fBmktime(\fIdatespec\fR [\fB, \fIutc-flag\fR]\fB)\fR
1981 Turn
1982 .I datespec
1983 into a time stamp of the same form as returned by
1984 .BR systime() ,
1985 and return the result.
1986 If
1987 .I utc-flag
1988 is present and is non-zero or non-null, the time is assumed to be in
1989 the UTC time zone; otherwise, the
1990 time is assumed to be in the local time zone.
1991 If
1992 .I datespec
1993 does not contain enough elements or if the resulting time
1994 is out of range,
1995 .B mktime()
1996 returns \-1.
1997 See
1998 .I https://www.gnu.org/software/gawk/manual/html_node/Time-Functions.html#Time-Functions
1999 for the details of
2000 .IR datespec .
2001 .TP
2002 \fBstrftime(\fR[\fIformat \fR[\fB, \fItimestamp\fR[\fB, \fIutc-flag\fR]]]\fB)\fR
2003 Format
2004 .I timestamp
2005 according to the specification in
2006 .IR format .
2007 If
2008 .I utc-flag
2009 is present and is non-zero or non-null, the result
2010 is in UTC, otherwise the result is in local time.
2011 The
2012 .I timestamp
2013 should be of the same form as returned by
2014 .BR systime() .
2015 If
2016 .I timestamp
2017 is missing, the current time of day is used.
2018 If
2019 .I format
2020 is missing, a default format equivalent to the output of
2021 .IR date (1)
2022 is used.
2023 The default format is available in
2024 .BR PROCINFO["strftime"] .
2025 See the specification for the
2026 .B strftime()
2027 function in ISO C for the format conversions that are
2028 guaranteed to be available.
2029 .TP
2030 .B systime()
2031 Return the current time of day as the number of seconds since the Epoch
2032 (1970-01-01 00:00:00 UTC on \*(PX systems).
2033 .SS Bit Manipulations Functions
2034 .I Gawk
2035 supplies the following bit manipulation functions.
2036 They work by converting double-precision floating point
2037 values to
2038 .B uintmax_t
2039 integers, doing the operation, and then converting the
2040 result back to floating point.
2041 Passing negative operands to any of these functions causes
2042 a fatal error.
2043 .PP
2044 The functions are:
2045 .TP "\w'\fBrshift(\fIval\fB, \fIcount\fB)\fR'u+2n"
2046 \fBand(\fIv1\fB, \fIv2 \fR[, ...]\fB)\fR
2047 Return the bitwise AND of the values provided in the argument list.
2048 There must be at least two.
2049 .TP
2050 \fBcompl(\fIval\fB)\fR
2051 Return the bitwise complement of
2052 .IR val .
2053 .TP
2054 \fBlshift(\fIval\fB, \fIcount\fB)\fR
2055 Return the value of
2056 .IR val ,
2057 shifted left by
2058 .I count
2059 bits.
2060 .TP
2061 \fBor(\fIv1\fB, \fIv2 \fR[, ...]\fB)\fR
2062 Return the bitwise OR of the values provided in the argument list.
2063 There must be at least two.
2064 .TP
2065 \fBrshift(\fIval\fB, \fIcount\fB)\fR
2066 Return the value of
2067 .IR val ,
2068 shifted right by
2069 .I count
2070 bits.
2071 .TP
2072 \fBxor(\fIv1\fB, \fIv2 \fR[, ...]\fB)\fR
2073 Return the bitwise XOR of the values provided in the argument list.
2074 There must be at least two.
2075 .SS Type Functions
2076 The following functions provide type related information about
2077 their arguments.
2078 .TP \w'\fBisarray(\fIx\fB)\fR'u+1n
2079 \fBisarray(\fIx\fB)\fR
2080 Return true if
2081 .I x
2082 is an array, false otherwise.
2083 .TP
2084 \fBtypeof(\fIx\fB)\fR
2085 Return a string indicating the type of
2086 .IR x .
2087 The string will be one of
2088 \fB"array"\fP,
2089 \fB"number"\fP,
2090 \fB"regexp"\fP,
2091 \fB"string"\fP,
2092 \fB"strnum"\fP,
2093 \fB"unassigned"\fP,
2094 or
2095 \fB"untyped"\fP.
2096 .SS Internationalization Functions
2097 The following functions may be used from within your AWK program for
2098 translating strings at run-time.
2099 For full details, see
2100 .IR https://www.gnu.org/software/gawk/manual/html_node/I18N-Functions.html#I18N-Functions .
2101 .TP
2102 \fBbindtextdomain(\fIdirectory \fR[\fB, \fIdomain\fR]\fB)\fR
2103 Specify the directory where
2104 .I gawk
2105 looks for the
2106 .B \&.gmo
2107 files, in case they
2108 will not or cannot be placed in the \*(lqstandard\*(rq locations.
2109 It returns the directory where
2110 .I domain
2111 is \*(lqbound.\*(rq
2112 .sp 0.5
2113 The default
2114 .I domain
2115 is the value of
2116 .BR TEXTDOMAIN .
2117 If
2118 .I directory
2119 is the null string (\fB""\fR), then
2120 .B bindtextdomain()
2121 returns the current binding for the
2122 given
2123 .IR domain .
2124 .TP
2125 \fBdcgettext(\fIstring \fR[\fB, \fIdomain \fR[\fB, \fIcategory\fR]]\fB)\fR
2126 Return the translation of
2127 .I string
2128 in text domain
2129 .I domain
2130 for locale category
2131 .IR category .
2132 The default value for
2133 .I domain
2134 is the current value of
2135 .BR TEXTDOMAIN .
2136 The default value for
2137 .I category
2138 is \fB"LC_MESSAGES"\fR.
2139 .TP
2140 \fBdcngettext(\fIstring1\fB, \fIstring2\fB, \fInumber \fR[\fB, \fIdomain \fR[\fB, \fIcategory\fR]]\fB)\fR
2141 Return the plural form used for
2142 .I number
2143 of the translation of
2144 .I string1
2145 and
2146 .I string2
2147 in
2148 text domain
2149 .I domain
2150 for locale category
2151 .IR category .
2152 The default value for
2153 .I domain
2154 is the current value of
2155 .BR TEXTDOMAIN .
2156 The default value for
2157 .I category
2158 is \fB"LC_MESSAGES"\fR.
2159 .SS Boolean Valued Functions
2160 You can create special Boolean-typed values; see the manual for how
2161 they work and why they exist.
2162 .TP
2163 .BI mkbool( expression\^ )
2164 Based on the boolean value of
2165 .I expression
2166 return either a true value or a false value.
2167 True values have numeric value one.
2168 False values have numeric value zero.
2169 .SH USER-DEFINED FUNCTIONS
2170 Functions in \*(AK are defined as follows:
2171 .PP
2172 .RS
2173 \fBfunction \fIname\fB(\fIparameter list\fB) { \fIstatements \fB}\fR
2174 .RE
2175 .PP
2176 Functions execute when they are called from within expressions
2177 in either patterns or actions. Actual parameters supplied in the function
2178 call are used to instantiate the formal parameters declared in the function.
2179 Arrays are passed by reference, other variables are passed by value.
2180 .PP
2181 Local variables are declared as extra parameters
2182 in the parameter list. The convention is to separate local variables from
2183 real parameters by extra spaces in the parameter list. For example:
2184 .PP
2185 .RS
2186 .ft B
2187 .nf
2188 function f(p, q, a, b) # a and b are local
2189 {
2190 \&.\|.\|.
2191 }
2192
2193 /abc/ { .\|.\|.\& ; f(1, 2) ; .\|.\|.\& }
2194 .fi
2195 .ft R
2196 .RE
2197 .PP
2198 The left parenthesis in a function call is required
2199 to immediately follow the function name,
2200 without any intervening whitespace.
2201 This restriction does not apply to the built-in functions listed above.
2202 .PP
2203 Functions may call each other and may be recursive.
2204 Function parameters used as local variables are initialized
2205 to the null string and the number zero upon function invocation.
2206 .PP
2207 Use
2208 .BI return " expr"
2209 to return a value from a function. The return value is undefined if no
2210 value is provided, or if the function returns by \*(lqfalling off\*(rq the
2211 end.
2212 .PP
2213 Functions may be called indirectly.
2214 To do this, assign
2215 the name of the function to be called, as a string, to a variable.
2216 Then use the variable as if it were the name of a function, prefixed with an
2217 .B @
2218 sign, like so:
2219 .RS
2220 .ft B
2221 .nf
2222 function myfunc()
2223 {
2224 print "myfunc called"
2225 \&.\|.\|.
2226 }
2227
2228 { .\|.\|.
2229 the_func = "myfunc"
2230 @the_func() # call through the_func to myfunc
2231 .\|.\|.
2232 }
2233 .fi
2234 .ft R
2235 .RE
2236 .PP
2237 If
2238 .B \-\^\-lint
2239 has been provided,
2240 .I gawk
2241 warns about calls to undefined functions at parse time,
2242 instead of at run time.
2243 Calling an undefined function at run time is a fatal error.
2244 .SH DYNAMICALLY LOADING NEW FUNCTIONS
2245 You can dynamically add new functions written in C or C++ to the running
2246 .I gawk
2247 interpreter with the
2248 .B @load
2249 statement.
2250 The full details are beyond the scope of this manual page;
2251 see
2252 .IR https://www.gnu.org/software/gawk/manual/html_node/Dynamic-Extensions.html#Dynamic-Extensions .
2253 .SH SIGNALS
2254 The
2255 .I gawk
2256 profiler accepts two signals.
2257 .B SIGUSR1
2258 causes it to dump a profile and function call stack to the
2259 profile file, which is either
2260 .BR awkprof.out ,
2261 or whatever file was named with the
2262 .B \-\^\-profile
2263 option. It then continues to run.
2264 .B SIGHUP
2265 causes
2266 .I gawk
2267 to dump the profile and function call stack and then exit.
2268 .SH INTERNATIONALIZATION
2269 String constants are sequences of characters enclosed in double
2270 quotes. In non-English speaking environments, it is possible to mark
2271 strings in the \*(AK program as
2272 requiring translation to the local natural language.
2273 Such strings are marked in the \*(AK program with
2274 a leading underscore (\*(lq_\*(rq). For example,
2275 .sp
2276 .RS
2277 .ft B
2278 gawk 'BEGIN { print "hello, world" }'
2279 .RE
2280 .sp
2281 .ft R
2282 always prints
2283 .BR "hello, world" .
2284 But,
2285 .sp
2286 .RS
2287 .ft B
2288 gawk 'BEGIN { print _"hello, world" }'
2289 .RE
2290 .sp
2291 .ft R
2292 might print
2293 .B "bonjour, monde"
2294 in France.
2295 See
2296 .I https://www.gnu.org/software/gawk/manual/html_node/Internationalization.html#Internationalization
2297 for the steps involved in producing and running a localizable
2298 \*(AK program.
2299 .SH GNU EXTENSIONS
2300 .I Gawk
2301 has a too-large number of extensions to \*(PX
2302 .IR awk .
2303 They are described in
2304 .IR https://www.gnu.org/software/gawk/manual/html_node/POSIX_002fGNU.html .
2305 All the extensions
2306 can be disabled by
2307 invoking
2308 .I gawk
2309 with the
2310 .B \-\^\-traditional
2311 or
2312 .B \-\^\-posix
2313 options.
2314 .SH ENVIRONMENT VARIABLES
2315 The
2316 .B AWKPATH
2317 environment variable can be used to provide a list of directories that
2318 .I gawk
2319 searches when looking for files named via the
2320 .BR \-f ,
2321 .BR \-\^\-file ,
2322 .B \-i
2323 and
2324 .B \-\^\-include
2325 options, and the
2326 .B @include
2327 and
2328 .B @nsinclude
2329 directives. If the initial search fails, the path is searched again after
2330 appending
2331 .B \&.awk
2332 to the filename.
2333 .PP
2334 The
2335 .B AWKLIBPATH
2336 environment variable can be used to provide a list of directories that
2337 .I gawk
2338 searches when looking for files named via the
2339 .B \-l
2340 and
2341 .B \-\^\-load
2342 options.
2343 .PP
2344 The
2345 .B GAWK_PERSIST_FILE
2346 environment variable, if present, specifies a file to use as
2347 the backing store for persistent memory.
2348 See \*(EP for the details.
2349 .PP
2350 The
2351 .B GAWK_READ_TIMEOUT
2352 environment variable can be used to specify a timeout
2353 in milliseconds for reading input from a terminal, pipe
2354 or two-way communication including sockets.
2355 .PP
2356 For connection to a remote host via socket,
2357 .B GAWK_SOCK_RETRIES
2358 controls the number of retries, and
2359 .B GAWK_MSEC_SLEEP
2360 the interval between retries.
2361 The interval is in milliseconds.
2362 On systems that do not support
2363 .IR usleep (3),
2364 the value is rounded up to an integral number of seconds.
2365 .PP
2366 If
2367 .B POSIXLY_CORRECT
2368 exists in the environment, then
2369 .I gawk
2370 behaves exactly as if
2371 .B \-\^\-posix
2372 had been specified on the command line.
2373 If
2374 .B \-\^\-lint
2375 has been specified,
2376 .I gawk
2377 issues a warning message to this effect.
2378 .ig
2379 .PP
2380 Set
2381 .B GAWK_NO_MPFR_WARN
2382 in the environment to silence the warning about MPFR mode
2383 being deprecated.
2384 ..
2385 .SH EXIT STATUS
2386 If the
2387 .B exit
2388 statement is used with a value,
2389 then
2390 .I gawk
2391 exits with
2392 the numeric value given to it.
2393 .PP
2394 Otherwise, if there were no problems during execution,
2395 .I gawk
2396 exits with the value of the C constant
2397 .BR EXIT_SUCCESS .
2398 This is usually zero.
2399 .PP
2400 If an error occurs,
2401 .I gawk
2402 exits with the value of
2403 the C constant
2404 .BR EXIT_FAILURE .
2405 This is usually one.
2406 .PP
2407 If
2408 .I gawk
2409 exits because of a fatal error, the exit
2410 status is 2. On non-POSIX systems, this value may be mapped to
2411 .BR EXIT_FAILURE .
2412 .SH VERSION INFORMATION
2413 This man page documents
2414 .IR gawk ,
2415 version 5.4.
2416 .SH AUTHORS
2417 The original version of \*(UX
2418 .I awk
2419 was designed and implemented by Alfred Aho,
2420 Peter Weinberger, and Brian Kernighan of Bell Laboratories.
2421 Ozan Yigit is the current maintainer.
2422 Brian Kernighan occasionally dabbles in its development.
2423 .PP
2424 Paul Rubin and Jay Fenlason,
2425 of the Free Software Foundation, wrote
2426 .IR gawk ,
2427 to be compatible with the original version of
2428 .I awk
2429 distributed in Seventh Edition \*(UX.
2430 John Woods contributed a number of bug fixes.
2431 David Trueman, with contributions
2432 from Arnold Robbins, made
2433 .I gawk
2434 compatible with the new version of \*(UX
2435 .IR awk .
2436 Arnold Robbins is the current maintainer.
2437 .PP
2438 See \*(EP for a full list of the contributors to
2439 .I gawk
2440 and its documentation.
2441 .PP
2442 See the
2443 .B README
2444 file in the
2445 .I gawk
2446 distribution for up-to-date information about maintainers
2447 and which ports are currently supported.
2448 .SH BUG REPORTS AND QUESTIONS
2449 If you find a bug in
2450 .IR gawk ,
2451 please use the
2452 .IR gawkbug (1)
2453 program to report it.
2454 .PP
2455 Full instructions for reporting a bug are provided in
2456 .IR https://www.gnu.org/software/gawk/manual/html_node/Bugs.html .
2457 .I Please
2458 carefully read and follow the instructions given there.
2459 This will make bug reporting and resolution much easier for everyone involved.
2460 Really.
2461 .PP
2462 On the other hand, if you have a question as to how to accomplish
2463 a particular task using
2464 .I awk
2465 or
2466 .IR gawk ,
2467 send an email to
2468 .B [email protected]
2469 with your request for help.
2470 .SH BUGS
2471 The
2472 .B \-F
2473 option is not necessary given the command line variable assignment feature;
2474 it remains only for backwards compatibility.
2475 .PP
2476 This manual page is too long;
2477 .I gawk
2478 has too many features.
2479 .SH SEE ALSO
2480 .IR egrep (1),
2481 .IR sed (1),
2482 .IR gawkbug (1),
2483 .IR printf (3),
2484 and
2485 .IR strftime (3).
2486 .PP
2487 .IR "The AWK Programming Language" ,
2488 second edition,
2489 Alfred V.\& Aho, Brian W.\& Kernighan, Peter J.\& Weinberger,
2490 Addison-Wesley, 2023.
2491 ISBN 9-780138-269722.
2492 .PP
2493 \*(EP,
2494 Edition 5.3, shipped with the
2495 .I gawk
2496 source.
2497 The current version of this document is available online at
2498 .IR https://www.gnu.org/software/gawk/manual .
2499 .PP
2500 The GNU
2501 .B gettext
2502 documentation, available online at
2503 .IR https://www.gnu.org/software/gettext .
2504 .SH EXAMPLES
2505 .nf
2506 Print and sort the login names of all users:
2507
2508 .ft B
2509 BEGIN { FS = ":" }
2510 { print $1 | "sort" }
2511
2512 .ft R
2513 Count lines in a file:
2514
2515 .ft B
2516 { nlines++ }
2517 END { print nlines }
2518
2519 .ft R
2520 Precede each line by its number in the file:
2521
2522 .ft B
2523 { print FNR, $0 }
2524
2525 .ft R
2526 Concatenate and line number (a variation on a theme):
2527
2528 .ft B
2529 { print NR, $0 }
2530
2531 .ft R
2532 Run an external command for particular lines of data:
2533
2534 .ft B
2535 tail \-f access_log |
2536 awk '/myhome.html/ { system("nmap " $1 ">> logdir/myhome.html") }'
2537 .ft R
2538 .fi
2539 .ig
2540 .SH ACKNOWLEDGEMENTS
2541 Brian Kernighan
2542 provided valuable assistance during testing and debugging.
2543 We thank him.
2544 ..
2545 .SH COPYING PERMISSIONS
2546 Copyright \(co 1989, 1991, 1992, 1993, 1994, 1995, 1996,
2547 1997, 1998, 1999, 2001, 2002, 2003, 2004, 2005, 2007, 2009,
2548 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019,
2549 2020, 2021, 2022, 2023, 2024, 2025, 2026
2550 Free Software Foundation, Inc.
2551 .PP
2552 Permission is granted to make and distribute verbatim copies of
2553 this manual page provided the copyright notice and this permission
2554 notice are preserved on all copies.
2555 .ig
2556 Permission is granted to process this file through troff and print the
2557 results, provided the printed document carries copying permission
2558 notice identical to this one except for the removal of this paragraph
2559 (this paragraph not being relevant to the printed manual page).
2560 ..
2561 .PP
2562 Permission is granted to copy and distribute modified versions of this
2563 manual page under the conditions for verbatim copying, provided that
2564 the entire resulting derived work is distributed under the terms of a
2565 permission notice identical to this one.
2566 .PP
2567 Permission is granted to copy and distribute translations of this
2568 manual page into another language, under the above conditions for
2569 modified versions, except that this permission notice may be stated in
2570 a translation approved by the Foundation.