Debian Codegraph @

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