Debian Codegraph @

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