{ "mode": "info", "parameter": "awk", "section": "", "url": "https://www.chedong.com/phpMan.php/info/awk/json", "generated": "2026-08-02T23:10:35Z", "synopsis": "gawk [ POSIX or GNU style options ] -f program-file [ -- ] file ...\ngawk [ POSIX or GNU style options ] [ -- ] program-text file ...", "sections": { "NAME": { "content": "gawk - pattern scanning and processing language\n", "subsections": [] }, "SYNOPSIS": { "content": "gawk [ POSIX or GNU style options ] -f program-file [ -- ] file ...\ngawk [ POSIX or GNU style options ] [ -- ] program-text file ...\n", "subsections": [] }, "DESCRIPTION": { "content": "Gawk is the GNU Project's implementation of the AWK programming lan-\nguage. It conforms to the definition of the language in the POSIX\n1003.1 standard. This version in turn is based on the description in\nThe AWK Programming Language, by Aho, Kernighan, and Weinberger. Gawk\nprovides the additional features found in the current version of Brian\nKernighan's awk and numerous GNU-specific extensions.\n\nThe command line consists of options to gawk itself, the AWK program\ntext (if not supplied via the -f or --include options), and values to\nbe made available in the ARGC and ARGV pre-defined AWK variables.\n\nWhen gawk is invoked with the --profile option, it starts gathering\nprofiling statistics from the execution of the program. Gawk runs more\nslowly in this mode, and automatically produces an execution profile in\nthe file awkprof.out when done. See the --profile option, below.\n\nGawk also has an integrated debugger. An interactive debugging session\ncan be started by supplying the --debug option to the command line. In\nthis mode of execution, gawk loads the AWK source code and then prompts\nfor debugging commands. Gawk can only debug AWK program source pro-\nvided with the -f and --include options. The debugger is documented in\nGAWK: Effective AWK Programming.\n", "subsections": [] }, "OPTION FORMAT": { "content": "Gawk options may be either traditional POSIX-style one letter options,\nor GNU-style long options. POSIX options start with a single \"-\",\nwhile long options start with \"--\". Long options are provided for both\nGNU-specific features and for POSIX-mandated features.\n\nGawk-specific options are typically used in long-option form. Argu-\nments to long options are either joined with the option by an = sign,\nwith no intervening spaces, or they may be provided in the next command\nline argument. Long options may be abbreviated, as long as the abbre-\nviation remains unique.\n\nAdditionally, every long option has a corresponding short option, so\nthat the option's functionality may be used from within #! executable\nscripts.\n", "subsections": [] }, "OPTIONS": { "content": "Gawk accepts the following options. Standard options are listed first,\nfollowed by options for gawk extensions, listed alphabetically by short\noption.\n\n-f program-file\n--file program-file\nRead the AWK program source from the file program-file, instead\nof from the first command line argument. Multiple -f (or\n--file) options may be used. Files read with -f are treated as\nif they begin with an implicit @namespace \"awk\" statement.\n\n-F fs\n--field-separator fs\nUse fs for the input field separator (the value of the FS prede-\nfined variable).\n\n-v var=val\n--assign var=val\nAssign the value val to the variable var, before execution of\nthe program begins. Such variable values are available to the\nBEGIN rule of an AWK program.\n", "subsections": [ { "name": "-b", "content": "", "flag": "-b" }, { "name": "--characters-as-bytes", "content": "Treat all input data as single-byte characters. In other words,\ndon't pay any attention to the locale information when attempt-\ning to process strings as multibyte characters. The --posix op-\ntion overrides this one.\n", "long": "--characters-as-bytes" }, { "name": "-c", "content": "", "flag": "-c" }, { "name": "--traditional", "content": "Run in compatibility mode. In compatibility mode, gawk behaves\nidentically to Brian Kernighan's awk; none of the GNU-specific\nextensions are recognized. See GNU EXTENSIONS, below, for more\ninformation.\n", "long": "--traditional" }, { "name": "-C", "content": "", "flag": "-C" }, { "name": "--copyright", "content": "Print the short version of the GNU copyright information message\non the standard output and exit successfully.\n", "long": "--copyright" }, { "name": "-d[file]", "content": "" }, { "name": "--dump-variables[=file]", "content": "Print a sorted list of global variables, their types and final\nvalues to file. If no file is provided, gawk uses a file named\nawkvars.out in the current directory.\nHaving a list of all the global variables is a good way to look\nfor typographical errors in your programs. You would also use\nthis option if you have a large program with a lot of functions,\nand you want to be sure that your functions don't inadvertently\nuse global variables that you meant to be local. (This is a\nparticularly easy mistake to make with simple variable names\nlike i, j, and so on.)\n" }, { "name": "-D[file]", "content": "" }, { "name": "--debug[=file]", "content": "Enable debugging of AWK programs. By default, the debugger\nreads commands interactively from the keyboard (standard input).\nThe optional file argument specifies a file with a list of com-\nmands for the debugger to execute non-interactively.\n\n-e program-text\n--source program-text\nUse program-text as AWK program source code. This option allows\nthe easy intermixing of library functions (used via the -f and\n--include options) with source code entered on the command line.\nIt is intended primarily for medium to large AWK programs used\nin shell scripts. Each argument supplied via -e is treated as\nif it begins with an implicit @namespace \"awk\" statement.\n\n-E file\n--exec file\nSimilar to -f, however, this is option is the last one pro-\ncessed. This should be used with #! scripts, particularly for\nCGI applications, to avoid passing in options or source code (!)\non the command line from a URL. This option disables command-\nline variable assignments.\n" }, { "name": "-g", "content": "", "flag": "-g" }, { "name": "--gen-pot", "content": "Scan and parse the AWK program, and generate a GNU .pot (Porta-\nble Object Template) format file on standard output with entries\nfor all localizable strings in the program. The program itself\nis not executed. See the GNU gettext distribution for more in-\nformation on .pot files.\n", "long": "--gen-pot" }, { "name": "-h", "content": "--help Print a relatively short summary of the available options on the\nstandard output. (Per the GNU Coding Standards, these options\ncause an immediate, successful exit.)\n\n-i include-file\n--include include-file\nLoad an awk source library. This searches for the library using\nthe AWKPATH environment variable. If the initial search fails,\nanother attempt will be made after appending the .awk suffix.\nThe file will be loaded only once (i.e., duplicates are elimi-\nnated), and the code does not constitute the main program\nsource. Files read with --include are treated as if they begin\nwith an implicit @namespace \"awk\" statement.\n\n-l lib\n--load lib\nLoad a gawk extension from the shared library lib. This\nsearches for the library using the AWKLIBPATH environment vari-\nable. If the initial search fails, another attempt will be made\nafter appending the default shared library suffix for the plat-\nform. The library initialization routine is expected to be\nnamed dlload().\n", "flag": "-h" }, { "name": "-L [value]", "content": "", "flag": "-L", "arg": "[value]" }, { "name": "--lint[=value]", "content": "Provide warnings about constructs that are dubious or non-porta-\nble to other AWK implementations. With an optional argument of\nfatal, lint warnings become fatal errors. This may be drastic,\nbut its use will certainly encourage the development of cleaner\nAWK programs. With an optional argument of invalid, only warn-\nings about things that are actually invalid are issued. (This is\nnot fully implemented yet.) With an optional argument of no-\next, warnings about gawk extensions are disabled.\n" }, { "name": "-M", "content": "", "flag": "-M" }, { "name": "--bignum", "content": "Force arbitrary precision arithmetic on numbers. This option has\nno effect if gawk is not compiled to use the GNU MPFR and GMP\nlibraries. (In such a case, gawk issues a warning.)\n", "long": "--bignum" }, { "name": "-n", "content": "", "flag": "-n" }, { "name": "--non-decimal-data", "content": "Recognize octal and hexadecimal values in input data. Use this\noption with great caution!\n", "long": "--non-decimal-data" }, { "name": "-N", "content": "", "flag": "-N" }, { "name": "--use-lc-numeric", "content": "Force gawk to use the locale's decimal point character when\nparsing input data. Although the POSIX standard requires this\nbehavior, and gawk does so when --posix is in effect, the de-\nfault is to follow traditional behavior and use a period as the\ndecimal point, even in locales where the period is not the deci-\nmal point character. This option overrides the default behav-\nior, without the full draconian strictness of the --posix op-\ntion.\n", "long": "--use-lc-numeric" }, { "name": "-o[file]", "content": "" }, { "name": "--pretty-print[=file]", "content": "Output a pretty printed version of the program to file. If no\nfile is provided, gawk uses a file named awkprof.out in the cur-\nrent directory. This option implies --no-optimize.\n" }, { "name": "-O", "content": "", "flag": "-O" }, { "name": "--optimize", "content": "Enable gawk's default optimizations upon the internal represen-\ntation of the program. Currently, this just includes simple\nconstant folding. This option is on by default.\n", "long": "--optimize" }, { "name": "-p[prof-file]", "content": "" }, { "name": "--profile[=prof-file]", "content": "Start a profiling session, and send the profiling data to prof-\nfile. The default is awkprof.out. The profile contains execu-\ntion counts of each statement in the program in the left margin\nand function call counts for each user-defined function. This\noption implies --no-optimize.\n" }, { "name": "-P", "content": "", "flag": "-P" }, { "name": "--posix", "content": "This turns on compatibility mode, with the following additional\nrestrictions:\n\no \\x escape sequences are not recognized.\n\no You cannot continue lines after ? and :.\n\no The synonym func for the keyword function is not recognized.\n\no The operators and = cannot be used in place of ^ and ^=.\n", "long": "--posix" }, { "name": "-r", "content": "", "flag": "-r" }, { "name": "--re-interval", "content": "Enable the use of interval expressions in regular expression\nmatching (see Regular Expressions, below). Interval expressions\nwere not traditionally available in the AWK language. The POSIX\nstandard added them, to make awk and egrep consistent with each\nother. They are enabled by default, but this option remains for\nuse together with --traditional.\n", "long": "--re-interval" }, { "name": "-s", "content": "", "flag": "-s" }, { "name": "--no-optimize", "content": "Disable gawk's default optimizations upon the internal represen-\ntation of the program.\n", "long": "--no-optimize" }, { "name": "-S", "content": "", "flag": "-S" }, { "name": "--sandbox", "content": "Run gawk in sandbox mode, disabling the system() function, input\nredirection with getline, output redirection with print and\nprintf, and loading dynamic extensions. Command execution\n(through pipelines) is also disabled. This effectively blocks a\nscript from accessing local resources, except for the files\nspecified on the command line.\n", "long": "--sandbox" }, { "name": "-t", "content": "", "flag": "-t" }, { "name": "--lint-old", "content": "Provide warnings about constructs that are not portable to the\noriginal version of UNIX awk.\n", "long": "--lint-old" }, { "name": "-V", "content": "", "flag": "-V" }, { "name": "--version", "content": "Print version information for this particular copy of gawk on\nthe standard output. This is useful mainly for knowing if the\ncurrent copy of gawk on your system is up to date with respect\nto whatever the Free Software Foundation is distributing. This\nis also useful when reporting bugs. (Per the GNU Coding Stan-\ndards, these options cause an immediate, successful exit.)\n\n-- Signal the end of options. This is useful to allow further argu-\nments to the AWK program itself to start with a \"-\". This pro-\nvides consistency with the argument parsing convention used by\nmost other POSIX programs.\n\nIn compatibility mode, any other options are flagged as invalid, but\nare otherwise ignored. In normal operation, as long as program text\nhas been supplied, unknown options are passed on to the AWK program in\nthe ARGV array for processing. This is particularly useful for running\nAWK programs via the #! executable interpreter mechanism.\n\nFor POSIX compatibility, the -W option may be used, followed by the\nname of a long option.\n", "long": "--version" } ] }, "AWK PROGRAM EXECUTION": { "content": "An AWK program consists of a sequence of optional directives, pattern-\naction statements, and optional function definitions.\n\n@include \"filename\"\n@load \"filename\"\n@namespace \"name\"\npattern { action statements }\nfunction name(parameter list) { statements }\n\nGawk first reads the program source from the program-file(s) if speci-\nfied, from arguments to --source, or from the first non-option argument\non the command line. The -f and --source options may be used multiple\ntimes on the command line. Gawk reads the program text as if all the\nprogram-files and command line source texts had been concatenated to-\ngether. This is useful for building libraries of AWK functions, with-\nout having to include them in each new AWK program that uses them. It\nalso provides the ability to mix library functions with command line\nprograms.\n\nIn addition, lines beginning with @include may be used to include other\nsource files into your program, making library use even easier. This\nis equivalent to using the --include option.\n\nLines beginning with @load may be used to load extension functions into\nyour program. This is equivalent to using the --load option.\n\nThe environment variable AWKPATH specifies a search path to use when\nfinding source files named with the -f and --include options. If this\nvariable does not exist, the default path is \".:/usr/local/share/awk\".\n(The actual directory may vary, depending upon how gawk was built and\ninstalled.) If a file name given to the -f option contains a \"/\" char-\nacter, no path search is performed.\n\nThe environment variable AWKLIBPATH specifies a search path to use when\nfinding source files named with the --load option. If this variable\ndoes not exist, the default path is \"/usr/local/lib/gawk\". (The actual\ndirectory may vary, depending upon how gawk was built and installed.)\n\nGawk executes AWK programs in the following order. First, all variable\nassignments specified via the -v option are performed. Next, gawk com-\npiles the program into an internal form. Then, gawk executes the code\nin the BEGIN rule(s) (if any), and then proceeds to read each file\nnamed in the ARGV array (up to ARGV[ARGC-1]). If there are no files\nnamed on the command line, gawk reads the standard input.\n\nIf a filename on the command line has the form var=val it is treated as\na variable assignment. The variable var will be assigned the value\nval. (This happens after any BEGIN rule(s) have been run.) Command\nline variable assignment is most useful for dynamically assigning val-\nues to the variables AWK uses to control how input is broken into\nfields and records. It is also useful for controlling state if multi-\nple passes are needed over a single data file.\n\nIf the value of a particular element of ARGV is empty (\"\"), gawk skips\nover it.\n\nFor each input file, if a BEGINFILE rule exists, gawk executes the as-\nsociated code before processing the contents of the file. Similarly,\ngawk executes the code associated with ENDFILE after processing the\nfile.\n\nFor each record in the input, gawk tests to see if it matches any pat-\ntern in the AWK program. For each pattern that the record matches,\ngawk executes the associated action. The patterns are tested in the\norder they occur in the program.\n\nFinally, after all the input is exhausted, gawk executes the code in\nthe END rule(s) (if any).\n\nCommand Line Directories\nAccording to POSIX, files named on the awk command line must be text\nfiles. The behavior is ``undefined'' if they are not. Most versions\nof awk treat a directory on the command line as a fatal error.\n\nStarting with version 4.0 of gawk, a directory on the command line pro-\nduces a warning, but is otherwise skipped. If either of the --posix or\n--traditional options is given, then gawk reverts to treating directo-\nries on the command line as a fatal error.\n\nVARIABLES, RECORDS AND FIELDS\nAWK variables are dynamic; they come into existence when they are first\nused. Their values are either floating-point numbers or strings, or\nboth, depending upon how they are used. Additionally, gawk allows\nvariables to have regular-expression type. AWK also has one dimen-\nsional arrays; arrays with multiple dimensions may be simulated. Gawk\nprovides true arrays of arrays; see Arrays, below. Several pre-defined\nvariables are set as a program runs; these are described as needed and\nsummarized below.\n\nRecords\nNormally, records are separated by newline characters. You can control\nhow records are separated by assigning values to the built-in variable\nRS. If RS is any single character, that character separates records.\nOtherwise, RS is a regular expression. Text in the input that matches\nthis regular expression separates the record. However, in compatibil-\nity mode, only the first character of its string value is used for sep-\narating records. If RS is set to the null string, then records are\nseparated by empty lines. When RS is set to the null string, the new-\nline character always acts as a field separator, in addition to what-\never value FS may have.\n\nFields\nAs each input record is read, gawk splits the record into fields, using\nthe value of the FS variable as the field separator. If FS is a single\ncharacter, fields are separated by that character. If FS is the null\nstring, then each individual character becomes a separate field. Oth-\nerwise, FS is expected to be a full regular expression. In the special\ncase that FS is a single space, fields are separated by runs of spaces\nand/or tabs and/or newlines. NOTE: The value of IGNORECASE (see below)\nalso affects how fields are split when FS is a regular expression, and\nhow records are separated when RS is a regular expression.\n\nIf the FIELDWIDTHS variable is set to a space-separated list of num-\nbers, each field is expected to have fixed width, and gawk splits up\nthe record using the specified widths. Each field width may optionally\nbe preceded by a colon-separated value specifying the number of charac-\nters to skip before the field starts. The value of FS is ignored. As-\nsigning a new value to FS or FPAT overrides the use of FIELDWIDTHS.\n\nSimilarly, if the FPAT variable is set to a string representing a regu-\nlar expression, each field is made up of text that matches that regular\nexpression. In this case, the regular expression describes the fields\nthemselves, instead of the text that separates the fields. Assigning a\nnew value to FS or FIELDWIDTHS overrides the use of FPAT.\n\nEach field in the input record may be referenced by its position: $1,\n$2, and so on. $0 is the whole record, including leading and trailing\nwhitespace. Fields need not be referenced by constants:\n\nn = 5\nprint $n\n\nprints the fifth field in the input record.\n\nThe variable NF is set to the total number of fields in the input\nrecord.\n\nReferences to non-existent fields (i.e., fields after $NF) produce the\nnull string. However, assigning to a non-existent field (e.g., $(NF+2)\n= 5) increases the value of NF, creates any intervening fields with the\nnull string as their values, and causes the value of $0 to be recom-\nputed, with the fields being separated by the value of OFS. References\nto negative numbered fields cause a fatal error. Decrementing NF\ncauses the values of fields past the new value to be lost, and the\nvalue of $0 to be recomputed, with the fields being separated by the\nvalue of OFS.\n\nAssigning a value to an existing field causes the whole record to be\nrebuilt when $0 is referenced. Similarly, assigning a value to $0\ncauses the record to be resplit, creating new values for the fields.\n\nBuilt-in Variables\nGawk's built-in variables are:\n\nARGC The number of command line arguments (does not include op-\ntions to gawk, or the program source).\n\nARGIND The index in ARGV of the current file being processed.\n\nARGV Array of command line arguments. The array is indexed from\n0 to ARGC - 1. Dynamically changing the contents of ARGV\ncan control the files used for data.\n\nBINMODE On non-POSIX systems, specifies use of \"binary\" mode for\nall file I/O. Numeric values of 1, 2, or 3, specify that\ninput files, output files, or all files, respectively,\nshould use binary I/O. String values of \"r\", or \"w\" spec-\nify that input files, or output files, respectively, should\nuse binary I/O. String values of \"rw\" or \"wr\" specify that\nall files should use binary I/O. Any other string value is\ntreated as \"rw\", but generates a warning message.\n\nCONVFMT The conversion format for numbers, \"%.6g\", by default.\n\nENVIRON An array containing the values of the current environment.\nThe array is indexed by the environment variables, each el-\nement being the value of that variable (e.g., ENVI-\nRON[\"HOME\"] might be \"/home/arnold\").\n\nIn POSIX mode, changing this array does not affect the en-\nvironment seen by programs which gawk spawns via redirect-\nion or the system() function. Otherwise, gawk updates its\nreal environment so that programs it spawns see the\nchanges.\n\nERRNO If a system error occurs either doing a redirection for\ngetline, during a read for getline, or during a close(),\nthen ERRNO is set to a string describing the error. The\nvalue is subject to translation in non-English locales. If\nthe string in ERRNO corresponds to a system error in the\nerrno(3) variable, then the numeric value can be found in\nPROCINFO[\"errno\"]. For non-system errors, PROCINFO[\"er-\nrno\"] will be zero.\n\nFIELDWIDTHS A whitespace-separated list of field widths. When set,\ngawk parses the input into fields of fixed width, instead\nof using the value of the FS variable as the field separa-\ntor. Each field width may optionally be preceded by a\ncolon-separated value specifying the number of characters\nto skip before the field starts. See Fields, above.\n\nFILENAME The name of the current input file. If no files are speci-\nfied on the command line, the value of FILENAME is \"-\".\nHowever, FILENAME is undefined inside the BEGIN rule (un-\nless set by getline).\n\nFNR The input record number in the current input file.\n\nFPAT A regular expression describing the contents of the fields\nin a record. When set, gawk parses the input into fields,\nwhere the fields match the regular expression, instead of\nusing the value of FS as the field separator. See Fields,\nabove.\n\nFS The input field separator, a space by default. See Fields,\nabove.\n\nFUNCTAB An array whose indices and corresponding values are the\nnames of all the user-defined or extension functions in the\nprogram. NOTE: You may not use the delete statement with\nthe FUNCTAB array.\n\nIGNORECASE Controls the case-sensitivity of all regular expression and\nstring operations. If IGNORECASE has a non-zero value,\nthen string comparisons and pattern matching in rules,\nfield splitting with FS and FPAT, record separating with\nRS, regular expression matching with ~ and !~, and the gen-\nsub(), gsub(), index(), match(), patsplit(), split(), and\nsub() built-in functions all ignore case when doing regular\nexpression operations. NOTE: Array subscripting is not af-\nfected. However, the asort() and asorti() functions are\naffected.\nThus, if IGNORECASE is not equal to zero, /aB/ matches all\nof the strings \"ab\", \"aB\", \"Ab\", and \"AB\". As with all AWK\nvariables, the initial value of IGNORECASE is zero, so all\nregular expression and string operations are normally case-\nsensitive.\n\nLINT Provides dynamic control of the --lint option from within\nan AWK program. When true, gawk prints lint warnings. When\nfalse, it does not. The values allowed for the --lint op-\ntion may also be assigned to LINT, with the same effects.\nAny other true value just prints warnings.\n\nNF The number of fields in the current input record.\n\nNR The total number of input records seen so far.\n\nOFMT The output format for numbers, \"%.6g\", by default.\n\nOFS The output field separator, a space by default.\n\nORS The output record separator, by default a newline.\n\nPREC The working precision of arbitrary precision floating-point\nnumbers, 53 by default.\n\nPROCINFO The elements of this array provide access to information\nabout the running AWK program. On some systems, there may\nbe elements in the array, \"group1\" through \"groupn\" for\nsome n, which is the number of supplementary groups that\nthe process has. Use the in operator to test for these el-\nements. The following elements are guaranteed to be avail-\nable:\n\nPROCINFO[\"argv\"] The command line arguments as received\nby gawk at the C-language level. The\nsubscripts start from zero.\n\nPROCINFO[\"egid\"] The value of the getegid(2) system\ncall.\n\nPROCINFO[\"errno\"] The value of errno(3) when ERRNO is\nset to the associated error message.\n\nPROCINFO[\"euid\"] The value of the geteuid(2) system\ncall.\n\nPROCINFO[\"FS\"] \"FS\" if field splitting with FS is in\neffect, \"FPAT\" if field splitting with\nFPAT is in effect, \"FIELDWIDTHS\" if\nfield splitting with FIELDWIDTHS is in\neffect, or \"API\" if API input parser\nfield splitting is in effect.\n\nPROCINFO[\"gid\"] The value of the getgid(2) system\ncall.\n\nPROCINFO[\"identifiers\"]\nA subarray, indexed by the names of\nall identifiers used in the text of\nthe AWK program. The values indicate\nwhat gawk knows about the identifiers\nafter it has finished parsing the pro-\ngram; they are not updated while the\nprogram runs. For each identifier,\nthe value of the element is one of the\nfollowing:\n\n\"array\" The identifier is an ar-\nray.\n\n\"builtin\" The identifier is a built-\nin function.\n\n\"extension\" The identifier is an ex-\ntension function loaded\nvia @load or --load.\n\n\"scalar\" The identifier is a\nscalar.\n\n\"untyped\" The identifier is untyped\n(could be used as a scalar\nor array, gawk doesn't\nknow yet).\n\n\"user\" The identifier is a user-\ndefined function.\n\nPROCINFO[\"pgrpid\"] The value of the getpgrp(2) system\ncall.\n\nPROCINFO[\"pid\"] The value of the getpid(2) system\ncall.\n\nPROCINFO[\"platform\"] A string indicating the platform for\nwhich gawk was compiled. It is one\nof:\n\n\"djgpp\", \"mingw\"\nMicrosoft Windows, using either\nDJGPP, or MinGW, respectively.\n\n\"os2\" OS/2.\n\n\"posix\"\nGNU/Linux, Cygwin, Mac OS X,\nand legacy Unix systems.\n\n\"vms\" OpenVMS or Vax/VMS.\n\nPROCINFO[\"ppid\"] The value of the getppid(2) system\ncall.\n\nPROCINFO[\"strftime\"] The default time format string for\nstrftime(). Changing its value af-\nfects how strftime() formats time val-\nues when called with no arguments.\n\nPROCINFO[\"uid\"] The value of the getuid(2) system\ncall.\n\nPROCINFO[\"version\"] The version of gawk.\n\nThe following elements are present if loading dynamic ex-\ntensions is available:\n\nPROCINFO[\"apimajor\"]\nThe major version of the extension API.\n\nPROCINFO[\"apiminor\"]\nThe minor version of the extension API.\n\nThe following elements are available if MPFR support is\ncompiled into gawk:\n\nPROCINFO[\"gmpversion\"]\nThe version of the GNU GMP library used for arbi-\ntrary precision number support in gawk.\n\nPROCINFO[\"mpfrversion\"]\nThe version of the GNU MPFR library used for arbi-\ntrary precision number support in gawk.\n\nPROCINFO[\"precmax\"]\nThe maximum precision supported by the GNU MPFR li-\nbrary for arbitrary precision floating-point num-\nbers.\n\nPROCINFO[\"precmin\"]\nThe minimum precision allowed by the GNU MPFR li-\nbrary for arbitrary precision floating-point num-\nbers.\n\nThe following elements may set by a program to change\ngawk's behavior:\n\nPROCINFO[\"NONFATAL\"]\nIf this exists, then I/O errors for all redirections\nbecome nonfatal.\n\nPROCINFO[\"name\", \"NONFATAL\"]\nMake I/O errors for name be nonfatal.\n\nPROCINFO[\"command\", \"pty\"]\nUse a pseudo-tty for two-way communication with com-\nmand instead of setting up two one-way pipes.\n\nPROCINFO[\"input\", \"READTIMEOUT\"]\nThe timeout in milliseconds for reading data from\ninput, where input is a redirection string or a\nfilename. A value of zero or less than zero means no\ntimeout.\n\nPROCINFO[\"input\", \"RETRY\"]\nIf an I/O error that may be retried occurs when\nreading data from input, and this array entry ex-\nists, then getline returns -2 instead of following\nthe default behavior of returning -1 and configuring\ninput to return no further data. An I/O error that\nmay be retried is one where errno(3) has the value\nEAGAIN, EWOULDBLOCK, EINTR, or ETIMEDOUT. This may\nbe useful in conjunction with PROCINFO[\"input\",\n\"READTIMEOUT\"] or in situations where a file de-\nscriptor has been configured to behave in a non-\nblocking fashion.\n\nPROCINFO[\"sortedin\"]\nIf this element exists in PROCINFO, then its value\ncontrols the order in which array elements are tra-\nversed in for loops. Supported values are\n\"@indstrasc\", \"@indnumasc\", \"@valtypeasc\",\n\"@valstrasc\", \"@valnumasc\", \"@indstrdesc\",\n\"@indnumdesc\", \"@valtypedesc\", \"@valstrdesc\",\n\"@valnumdesc\", and \"@unsorted\". The value can\nalso be the name (as a string) of any comparison\nfunction defined as follows:\n\nfunction cmpfunc(i1, v1, i2, v2)\n\nwhere i1 and i2 are the indices, and v1 and v2 are\nthe corresponding values of the two elements being\ncompared. It should return a number less than,\nequal to, or greater than 0, depending on how the\nelements of the array are to be ordered.\n\nROUNDMODE The rounding mode to use for arbitrary precision arithmetic\non numbers, by default \"N\" (IEEE-754 roundTiesToEven mode).\nThe accepted values are:\n\n\"A\" or \"a\"\nfor rounding away from zero. These are only avail-\nable if your version of the GNU MPFR library sup-\nports rounding away from zero.\n\n\"D\" or \"d\" for roundTowardNegative.\n\n\"N\" or \"n\" for roundTiesToEven.\n\n\"U\" or \"u\" for roundTowardPositive.\n\n\"Z\" or \"z\" for roundTowardZero.\n\nRS The input record separator, by default a newline.\n\nRT The record terminator. Gawk sets RT to the input text that\nmatched the character or regular expression specified by\nRS.\n\nRSTART The index of the first character matched by match(); 0 if\nno match. (This implies that character indices start at\none.)\n\nRLENGTH The length of the string matched by match(); -1 if no\nmatch.\n\nSUBSEP The string used to separate multiple subscripts in array\nelements, by default \"\\034\".\n\nSYMTAB An array whose indices are the names of all currently de-\nfined global variables and arrays in the program. The ar-\nray may be used for indirect access to read or write the\nvalue of a variable:\n\nfoo = 5\nSYMTAB[\"foo\"] = 4\nprint foo # prints 4\n\nThe typeof() function may be used to test if an element in\nSYMTAB is an array. You may not use the delete statement\nwith the SYMTAB array, nor assign to elements with an index\nthat is not a variable name.\n\nTEXTDOMAIN The text domain of the AWK program; used to find the local-\nized translations for the program's strings.\n\nArrays\nArrays are subscripted with an expression between square brackets ([\nand ]). If the expression is an expression list (expr, expr ...) then\nthe array subscript is a string consisting of the concatenation of the\n(string) value of each expression, separated by the value of the SUBSEP\nvariable. This facility is used to simulate multiply dimensioned ar-\nrays. For example:\n\ni = \"A\"; j = \"B\"; k = \"C\"\nx[i, j, k] = \"hello, world\\n\"\n\nassigns the string \"hello, world\\n\" to the element of the array x which\nis indexed by the string \"A\\034B\\034C\". All arrays in AWK are associa-\ntive, i.e., indexed by string values.\n\nThe special operator in may be used to test if an array has an index\nconsisting of a particular value:\n\nif (val in array)\nprint array[val]\n\nIf the array has multiple subscripts, use (i, j) in array.\n\nThe in construct may also be used in a for loop to iterate over all the\nelements of an array. However, the (i, j) in array construct only\nworks in tests, not in for loops.\n\nAn element may be deleted from an array using the delete statement.\nThe delete statement may also be used to delete the entire contents of\nan array, just by specifying the array name without a subscript.\n\ngawk supports true multidimensional arrays. It does not require that\nsuch arrays be ``rectangular'' as in C or C++. For example:\n\na[1] = 5\na[2][1] = 6\na[2][2] = 7\n\nNOTE: You may need to tell gawk that an array element is really a sub-\narray in order to use it where gawk expects an array (such as in the\nsecond argument to split()). You can do this by creating an element in\nthe subarray and then deleting it with the delete statement.\n\nNamespaces\nGawk provides a simple namespace facility to help work around the fact\nthat all variables in AWK are global.\n\nA qualified name consists of a two simple identifiers joined by a dou-\nble colon (::). The left-hand identifier represents the namespace and\nthe right-hand identifier is the variable within it. All simple (non-\nqualified) names are considered to be in the ``current'' namespace; the\ndefault namespace is awk. However, simple identifiers consisting\nsolely of uppercase letters are forced into the awk namespace, even if\nthe current namespace is different.\n\nYou change the current namespace with an @namespace \"name\" directive.\n\nThe standard predefined builtin function names may not be used as name-\nspace names. The names of additional functions provided by gawk may be\nused as namespace names or as simple identifiers in other namespaces.\nFor more details, see GAWK: Effective AWK Programming.\n\nVariable Typing And Conversion\nVariables and fields may be (floating point) numbers, or strings, or\nboth. They may also be regular expressions. How the value of a vari-\nable is interpreted depends upon its context. If used in a numeric ex-\npression, it will be treated as a number; if used as a string it will\nbe treated as a string.\n\nTo force a variable to be treated as a number, add zero to it; to force\nit to be treated as a string, concatenate it with the null string.\n\nUninitialized variables have the numeric value zero and the string\nvalue \"\" (the null, or empty, string).\n\nWhen a string must be converted to a number, the conversion is accom-\nplished using strtod(3). A number is converted to a string by using\nthe value of CONVFMT as a format string for sprintf(3), with the nu-\nmeric value of the variable as the argument. However, even though all\nnumbers in AWK are floating-point, integral values are always converted\nas integers. Thus, given\n\nCONVFMT = \"%2.2f\"\na = 12\nb = a \"\"\n\nthe variable b has a string value of \"12\" and not \"12.00\".\n\nNOTE: When operating in POSIX mode (such as with the --posix option),\nbeware that locale settings may interfere with the way decimal numbers\nare treated: the decimal separator of the numbers you are feeding to\ngawk must conform to what your locale would expect, be it a comma (,)\nor a period (.).\n\nGawk performs comparisons as follows: If two variables are numeric,\nthey are compared numerically. If one value is numeric and the other\nhas a string value that is a \"numeric string,\" then comparisons are\nalso done numerically. Otherwise, the numeric value is converted to a\nstring and a string comparison is performed. Two strings are compared,\nof course, as strings.\n\nNote that string constants, such as \"57\", are not numeric strings, they\nare string constants. The idea of \"numeric string\" only applies to\nfields, getline input, FILENAME, ARGV elements, ENVIRON elements and\nthe elements of an array created by split() or patsplit() that are nu-\nmeric strings. The basic idea is that user input, and only user input,\nthat looks numeric, should be treated that way.\n\nOctal and Hexadecimal Constants\nYou may use C-style octal and hexadecimal constants in your AWK program\nsource code. For example, the octal value 011 is equal to decimal 9,\nand the hexadecimal value 0x11 is equal to decimal 17.\n\nString Constants\nString constants in AWK are sequences of characters enclosed between\ndouble quotes (like \"value\"). Within strings, certain escape sequences\nare recognized, as in C. These are:\n\n\\\\ A literal backslash.\n\n\\a The \"alert\" character; usually the ASCII BEL character.\n\n\\b Backspace.\n\n\\f Form-feed.\n\n\\n Newline.\n\n\\r Carriage return.\n\n\\t Horizontal tab.\n\n\\v Vertical tab.\n\n\\xhex digits\nThe character represented by the string of hexadecimal digits fol-\nlowing the \\x. Up to two following hexadecimal digits are consid-\nered part of the escape sequence. E.g., \"\\x1B\" is the ASCII ESC\n(escape) character.\n\n\\ddd The character represented by the 1-, 2-, or 3-digit sequence of\noctal digits. E.g., \"\\033\" is the ASCII ESC (escape) character.\n\n\\c The literal character c.\n\nIn compatibility mode, the characters represented by octal and hexadec-\nimal escape sequences are treated literally when used in regular ex-\npression constants. Thus, /a\\52b/ is equivalent to /a\\*b/.\n\nRegexp Constants\nA regular expression constant is a sequence of characters enclosed be-\ntween forward slashes (like /value/). Regular expression matching is\ndescribed more fully below; see Regular Expressions.\n\nThe escape sequences described earlier may also be used inside constant\nregular expressions (e.g., /[ \\t\\f\\n\\r\\v]/ matches whitespace charac-\nters).\n\nGawk provides strongly typed regular expression constants. These are\nwritten with a leading @ symbol (like so: @/value/). Such constants\nmay be assigned to scalars (variables, array elements) and passed to\nuser-defined functions. Variables that have been so assigned have regu-\nlar expression type.\n", "subsections": [] }, "PATTERNS AND ACTIONS": { "content": "AWK is a line-oriented language. The pattern comes first, and then the\naction. Action statements are enclosed in { and }. Either the pattern\nmay be missing, or the action may be missing, but, of course, not both.\nIf the pattern is missing, the action executes for every single record\nof input. A missing action is equivalent to\n\n{ print }\n\nwhich prints the entire record.\n\nComments begin with the # character, and continue until the end of the\nline. Empty lines may be used to separate statements. Normally, a\nstatement ends with a newline, however, this is not the case for lines\nending in a comma, {, ?, :, &&, or ||. Lines ending in do or else also\nhave their statements automatically continued on the following line.\nIn other cases, a line can be continued by ending it with a \"\\\", in\nwhich case the newline is ignored. However, a \"\\\" after a # is not\nspecial.\n\nMultiple statements may be put on one line by separating them with a\n\";\". This applies to both the statements within the action part of a\npattern-action pair (the usual case), and to the pattern-action state-\nments themselves.\n\nPatterns\nAWK patterns may be one of the following:\n\nBEGIN\nEND\nBEGINFILE\nENDFILE\n/regular expression/\nrelational expression\npattern && pattern\npattern || pattern\npattern ? pattern : pattern\n(pattern)\n! pattern\npattern1, pattern2\n\nBEGIN and END are two special kinds of patterns which are not tested\nagainst the input. The action parts of all BEGIN patterns are merged\nas if all the statements had been written in a single BEGIN rule. They\nare executed before any of the input is read. Similarly, all the END\nrules are merged, and executed when all the input is exhausted (or when\nan exit statement is executed). BEGIN and END patterns cannot be com-\nbined with other patterns in pattern expressions. BEGIN and END pat-\nterns cannot have missing action parts.\n\nBEGINFILE and ENDFILE are additional special patterns whose actions are\nexecuted before reading the first record of each command-line input\nfile and after reading the last record of each file. Inside the BEGIN-\nFILE rule, the value of ERRNO is the empty string if the file was\nopened successfully. Otherwise, there is some problem with the file\nand the code should use nextfile to skip it. If that is not done, gawk\nproduces its usual fatal error for files that cannot be opened.\n\nFor /regular expression/ patterns, the associated statement is executed\nfor each input record that matches the regular expression. Regular ex-\npressions are the same as those in egrep(1), and are summarized below.\n\nA relational expression may use any of the operators defined below in\nthe section on actions. These generally test whether certain fields\nmatch certain regular expressions.\n\nThe &&, ||, and ! operators are logical AND, logical OR, and logical\nNOT, respectively, as in C. They do short-circuit evaluation, also as\nin C, and are used for combining more primitive pattern expressions.\nAs in most languages, parentheses may be used to change the order of\nevaluation.\n\nThe ?: operator is like the same operator in C. If the first pattern\nis true then the pattern used for testing is the second pattern, other-\nwise it is the third. Only one of the second and third patterns is\nevaluated.\n\nThe pattern1, pattern2 form of an expression is called a range pattern.\nIt matches all input records starting with a record that matches pat-\ntern1, and continuing until a record that matches pattern2, inclusive.\nIt does not combine with any other sort of pattern expression.\n\nRegular Expressions\nRegular expressions are the extended kind found in egrep. They are\ncomposed of characters as follows:\n\nc Matches the non-metacharacter c.\n\n\\c Matches the literal character c.\n\n. Matches any character including newline.\n\n^ Matches the beginning of a string.\n\n$ Matches the end of a string.\n\n[abc...] A character list: matches any of the characters abc.... You\nmay include a range of characters by separating them with a\ndash. To include a literal dash in the list, put it first\nor last.\n\n[^abc...] A negated character list: matches any character except\nabc....\n\nr1|r2 Alternation: matches either r1 or r2.\n\nr1r2 Concatenation: matches r1, and then r2.\n\nr+ Matches one or more r's.\n\nr* Matches zero or more r's.\n\nr? Matches zero or one r's.\n\n(r) Grouping: matches r.\n\nr{n}\nr{n,}\nr{n,m} One or two numbers inside braces denote an interval expres-\nsion. If there is one number in the braces, the preceding\nregular expression r is repeated n times. If there are two\nnumbers separated by a comma, r is repeated n to m times.\nIf there is one number followed by a comma, then r is re-\npeated at least n times.\n\n\\y Matches the empty string at either the beginning or the end\nof a word.\n\n\\B Matches the empty string within a word.\n\n\\< Matches the empty string at the beginning of a word.\n\n\\> Matches the empty string at the end of a word.\n\n\\s Matches any whitespace character.\n\n\\S Matches any nonwhitespace character.\n\n\\w Matches any word-constituent character (letter, digit, or\nunderscore).\n\n\\W Matches any character that is not word-constituent.\n\n\\` Matches the empty string at the beginning of a buffer\n(string).\n\n\\' Matches the empty string at the end of a buffer.\n\nThe escape sequences that are valid in string constants (see String\nConstants) are also valid in regular expressions.\n\nCharacter classes are a feature introduced in the POSIX standard. A\ncharacter class is a special notation for describing lists of charac-\nters that have a specific attribute, but where the actual characters\nthemselves can vary from country to country and/or from character set\nto character set. For example, the notion of what is an alphabetic\ncharacter differs in the USA and in France.\n\nA character class is only valid in a regular expression inside the\nbrackets of a character list. Character classes consist of [:, a key-\nword denoting the class, and :]. The character classes defined by the\nPOSIX standard are:\n\n[:alnum:] Alphanumeric characters.\n\n[:alpha:] Alphabetic characters.\n\n[:blank:] Space or tab characters.\n\n[:cntrl:] Control characters.\n\n[:digit:] Numeric characters.\n\n[:graph:] Characters that are both printable and visible. (A space is\nprintable, but not visible, while an a is both.)\n\n[:lower:] Lowercase alphabetic characters.\n\n[:print:] Printable characters (characters that are not control char-\nacters.)\n\n[:punct:] Punctuation characters (characters that are not letter, dig-\nits, control characters, or space characters).\n\n[:space:] Space characters (such as space, tab, and formfeed, to name\na few).\n\n[:upper:] Uppercase alphabetic characters.\n\n[:xdigit:] Characters that are hexadecimal digits.\n\nFor example, before the POSIX standard, to match alphanumeric charac-\nters, you would have had to write /[A-Za-z0-9]/. If your character set\nhad other alphabetic characters in it, this would not match them, and\nif your character set collated differently from ASCII, this might not\neven match the ASCII alphanumeric characters. With the POSIX character\nclasses, you can write /[[:alnum:]]/, and this matches the alphabetic\nand numeric characters in your character set, no matter what it is.\n\nTwo additional special sequences can appear in character lists. These\napply to non-ASCII character sets, which can have single symbols\n(called collating elements) that are represented with more than one\ncharacter, as well as several characters that are equivalent for col-\nlating, or sorting, purposes. (E.g., in French, a plain \"e\" and a\ngrave-accented \"`\" are equivalent.)\n\nCollating Symbols\nA collating symbol is a multi-character collating element en-\nclosed in [. and .]. For example, if ch is a collating ele-\nment, then [[.ch.]] is a regular expression that matches this\ncollating element, while [ch] is a regular expression that\nmatches either c or h.\n\nEquivalence Classes\nAn equivalence class is a locale-specific name for a list of\ncharacters that are equivalent. The name is enclosed in [= and\n=]. For example, the name e might be used to represent all of\n\"e\", \"'\", and \"`\". In this case, [[=e=]] is a regular expres-\nsion that matches any of e, ', or `.\n\nThese features are very valuable in non-English speaking locales. The\nlibrary functions that gawk uses for regular expression matching cur-\nrently only recognize POSIX character classes; they do not recognize\ncollating symbols or equivalence classes.\n\nThe \\y, \\B, \\<, \\>, \\s, \\S, \\w, \\W, \\`, and \\' operators are specific\nto gawk; they are extensions based on facilities in the GNU regular ex-\npression libraries.\n\nThe various command line options control how gawk interprets characters\nin regular expressions.\n\nNo options\nIn the default case, gawk provides all the facilities of POSIX\nregular expressions and the GNU regular expression operators de-\nscribed above.\n", "subsections": [ { "name": "--posix", "content": "Only POSIX regular expressions are supported, the GNU operators\nare not special. (E.g., \\w matches a literal w).\n", "long": "--posix" }, { "name": "--traditional", "content": "Traditional UNIX awk regular expressions are matched. The GNU\noperators are not special, and interval expressions are not\navailable. Characters described by octal and hexadecimal escape\nsequences are treated literally, even if they represent regular\nexpression metacharacters.\n", "long": "--traditional" }, { "name": "--re-interval", "content": "Allow interval expressions in regular expressions, even if\n--traditional has been provided.\n\nActions\nAction statements are enclosed in braces, { and }. Action statements\nconsist of the usual assignment, conditional, and looping statements\nfound in most languages. The operators, control statements, and in-\nput/output statements available are patterned after those in C.\n\nOperators\nThe operators in AWK, in order of decreasing precedence, are:\n\n(...) Grouping\n\n$ Field reference.\n\n++ -- Increment and decrement, both prefix and postfix.\n\n^ Exponentiation ( may also be used, and = for the as-\nsignment operator).\n\n+ - ! Unary plus, unary minus, and logical negation.\n\n* / % Multiplication, division, and modulus.\n\n+ - Addition and subtraction.\n\nspace String concatenation.\n\n| |& Piped I/O for getline, print, and printf.\n\n< > <= >= == !=\nThe regular relational operators.\n\n~ !~ Regular expression match, negated match. NOTE: Do not use\na constant regular expression (/foo/) on the left-hand side\nof a ~ or !~. Only use one on the right-hand side. The\nexpression /foo/ ~ exp has the same meaning as (($0 ~\n/foo/) ~ exp). This is usually not what you want.\n\nin Array membership.\n\n&& Logical AND.\n\n|| Logical OR.\n\n?: The C conditional expression. This has the form expr1 ?\nexpr2 : expr3. If expr1 is true, the value of the expres-\nsion is expr2, otherwise it is expr3. Only one of expr2\nand expr3 is evaluated.\n\n= += -= *= /= %= ^=\nAssignment. Both absolute assignment (var = value) and op-\nerator-assignment (the other forms) are supported.\n\nControl Statements\nThe control statements are as follows:\n\nif (condition) statement [ else statement ]\nwhile (condition) statement\ndo statement while (condition)\nfor (expr1; expr2; expr3) statement\nfor (var in array) statement\nbreak\ncontinue\ndelete array[index]\ndelete array\nexit [ expression ]\n{ statements }\nswitch (expression) {\ncase value|regex : statement\n...\n[ default: statement ]\n}\n\nI/O Statements\nThe input/output statements are as follows:\n\nclose(file [, how]) Close file, pipe or coprocess. The optional how\nshould only be used when closing one end of a\ntwo-way pipe to a coprocess. It must be a string\nvalue, either \"to\" or \"from\".\n\ngetline Set $0 from the next input record; set NF, NR,\nFNR, RT.\n\ngetline file Print expressions on file. Each expression is\nseparated by the value of OFS. The output record\nis terminated with the value of ORS.\n\nprintf fmt, expr-list Format and print. See The printf Statement, be-\nlow.\n\nprintf fmt, expr-list >file\nFormat and print on file.\n\nsystem(cmd-line) Execute the command cmd-line, and return the exit\nstatus. (This may not be available on non-POSIX\nsystems.) See GAWK: Effective AWK Programming\nfor the full details on the exit status.\n\nfflush([file]) Flush any buffers associated with the open output\nfile or pipe file. If file is missing or if it\nis the null string, then flush all open output\nfiles and pipes.\n\nAdditional output redirections are allowed for print and printf.\n\nprint ... >> file\nAppend output to the file.\n\nprint ... | command\nWrite on a pipe.\n\nprint ... |& command\nSend data to a coprocess or socket. (See also the subsection\nSpecial File Names, below.)\n\nThe getline command returns 1 on success, zero on end of file, and -1\non an error. If the errno(3) value indicates that the I/O operation\nmay be retried, and PROCINFO[\"input\", \"RETRY\"] is set, then -2 is re-\nturned instead of -1, and further calls to getline may be attempted.\nUpon an error, ERRNO is set to a string describing the problem.\n\nNOTE: Failure in opening a two-way socket results in a non-fatal error\nbeing returned to the calling function. If using a pipe, coprocess, or\nsocket to getline, or from print or printf within a loop, you must use\nclose() to create new instances of the command or socket. AWK does not\nautomatically close pipes, sockets, or coprocesses when they return\nEOF.\n\nThe printf Statement\nThe AWK versions of the printf statement and sprintf() function (see\nbelow) accept the following conversion specification formats:\n\n%a, %A A floating point number of the form [-]0xh.hhhhp+-dd (C99 hexa-\ndecimal floating point format). For %A, uppercase letters are\nused instead of lowercase ones.\n\n%c A single character. If the argument used for %c is numeric, it\nis treated as a character and printed. Otherwise, the argument\nis assumed to be a string, and the only first character of that\nstring is printed.\n\n%d, %i A decimal number (the integer part).\n\n%e, %E A floating point number of the form [-]d.dddddde[+-]dd. The %E\nformat uses E instead of e.\n\n%f, %F A floating point number of the form [-]ddd.dddddd. If the sys-\ntem library supports it, %F is available as well. This is like\n%f, but uses capital letters for special \"not a number\" and\n\"infinity\" values. If %F is not available, gawk uses %f.\n\n%g, %G Use %e or %f conversion, whichever is shorter, with nonsignifi-\ncant zeros suppressed. The %G format uses %E instead of %e.\n\n%o An unsigned octal number (also an integer).\n\n%u An unsigned decimal number (again, an integer).\n\n%s A character string.\n\n%x, %X An unsigned hexadecimal number (an integer). The %X format\nuses ABCDEF instead of abcdef.\n\n%% A single % character; no argument is converted.\n\nOptional, additional parameters may lie between the % and the control\nletter:\n\ncount$ Use the count'th argument at this point in the formatting. This\nis called a positional specifier and is intended primarily for\nuse in translated versions of format strings, not in the origi-\nnal text of an AWK program. It is a gawk extension.\n\n- The expression should be left-justified within its field.\n\nspace For numeric conversions, prefix positive values with a space,\nand negative values with a minus sign.\n\n+ The plus sign, used before the width modifier (see below), says\nto always supply a sign for numeric conversions, even if the\ndata to be formatted is positive. The + overrides the space\nmodifier.\n\n# Use an \"alternate form\" for certain control letters. For %o,\nsupply a leading zero. For %x, and %X, supply a leading 0x or\n0X for a nonzero result. For %e, %E, %f and %F, the result al-\nways contains a decimal point. For %g, and %G, trailing zeros\nare not removed from the result.\n\n0 A leading 0 (zero) acts as a flag, indicating that output should\nbe padded with zeroes instead of spaces. This applies only to\nthe numeric output formats. This flag only has an effect when\nthe field width is wider than the value to be printed.\n\n' A single quote character instructs gawk to insert the locale's\nthousands-separator character into decimal numbers, and to also\nuse the locale's decimal point character with floating point\nformats. This requires correct locale support in the C library\nand in the definition of the current locale.\n\nwidth The field should be padded to this width. The field is normally\npadded with spaces. With the 0 flag, it is padded with zeroes.\n\n.prec A number that specifies the precision to use when printing. For\nthe %e, %E, %f and %F, formats, this specifies the number of\ndigits you want printed to the right of the decimal point. For\nthe %g, and %G formats, it specifies the maximum number of sig-\nnificant digits. For the %d, %i, %o, %u, %x, and %X formats, it\nspecifies the minimum number of digits to print. For the %s\nformat, it specifies the maximum number of characters from the\nstring that should be printed.\n\nThe dynamic width and prec capabilities of the ISO C printf() routines\nare supported. A * in place of either the width or prec specifications\ncauses their values to be taken from the argument list to printf or\nsprintf(). To use a positional specifier with a dynamic width or pre-\ncision, supply the count$ after the * in the format string. For exam-\nple, \"%3$*2$.*1$s\".\n\nSpecial File Names\nWhen doing I/O redirection from either print or printf into a file, or\nvia getline from a file, gawk recognizes certain special filenames in-\nternally. These filenames allow access to open file descriptors inher-\nited from gawk's parent process (usually the shell). These file names\nmay also be used on the command line to name data files. The filenames\nare:\n\n- The standard input.\n\n/dev/stdin The standard input.\n\n/dev/stdout The standard output.\n\n/dev/stderr The standard error output.\n\n/dev/fd/n The file associated with the open file descriptor n.\n\nThese are particularly useful for error messages. For example:\n\nprint \"You blew it!\" > \"/dev/stderr\"\n\nwhereas you would otherwise have to use\n\nprint \"You blew it!\" | \"cat 1>&2\"\n\nThe following special filenames may be used with the |& coprocess oper-\nator for creating TCP/IP network connections:\n\n/inet/tcp/lport/rhost/rport\n/inet4/tcp/lport/rhost/rport\n/inet6/tcp/lport/rhost/rport\nFiles for a TCP/IP connection on local port lport to remote host\nrhost on remote port rport. Use a port of 0 to have the system\npick a port. Use /inet4 to force an IPv4 connection, and /inet6\nto force an IPv6 connection. Plain /inet uses the system de-\nfault (most likely IPv4). Usable only with the |& two-way I/O\noperator.\n\n/inet/udp/lport/rhost/rport\n/inet4/udp/lport/rhost/rport\n/inet6/udp/lport/rhost/rport\nSimilar, but use UDP/IP instead of TCP/IP.\n\nNumeric Functions\nAWK has the following built-in arithmetic functions:\n\natan2(y, x) Return the arctangent of y/x in radians.\n\ncos(expr) Return the cosine of expr, which is in radians.\n\nexp(expr) The exponential function.\n\nint(expr) Truncate to integer.\n\nlog(expr) The natural logarithm function.\n\nrand() Return a random number N, between zero and one, such that\n0 <= N < 1.\n\nsin(expr) Return the sine of expr, which is in radians.\n\nsqrt(expr) Return the square root of expr.\n\nsrand([expr]) Use expr as the new seed for the random number generator.\nIf no expr is provided, use the time of day. Return the\nprevious seed for the random number generator.\n\nString Functions\nGawk has the following built-in string functions:\n\nasort(s [, d [, how] ]) Return the number of elements in the source ar-\nray s. Sort the contents of s using gawk's\nnormal rules for comparing values, and replace\nthe indices of the sorted values s with sequen-\ntial integers starting with 1. If the optional\ndestination array d is specified, first dupli-\ncate s into d, and then sort d, leaving the in-\ndices of the source array s unchanged. The op-\ntional string how controls the direction and\nthe comparison mode. Valid values for how are\nany of the strings valid for\nPROCINFO[\"sortedin\"]. It can also be the name\nof a user-defined comparison function as de-\nscribed in PROCINFO[\"sortedin\"].\n\nasorti(s [, d [, how] ])\nReturn the number of elements in the source ar-\nray s. The behavior is the same as that of\nasort(), except that the array indices are used\nfor sorting, not the array values. When done,\nthe array is indexed numerically, and the val-\nues are those of the original indices. The\noriginal values are lost; thus provide a second\narray if you wish to preserve the original.\nThe purpose of the optional string how is the\nsame as described previously for asort().\n\ngensub(r, s, h [, t]) Search the target string t for matches of the\nregular expression r. If h is a string begin-\nning with g or G, then replace all matches of r\nwith s. Otherwise, h is a number indicating\nwhich match of r to replace. If t is not sup-\nplied, use $0 instead. Within the replacement\ntext s, the sequence \\n, where n is a digit\nfrom 1 to 9, may be used to indicate just the\ntext that matched the n'th parenthesized subex-\npression. The sequence \\0 represents the en-\ntire matched text, as does the character &.\nUnlike sub() and gsub(), the modified string is\nreturned as the result of the function, and the\noriginal target string is not changed.\n\ngsub(r, s [, t]) For each substring matching the regular expres-\nsion r in the string t, substitute the string\ns, and return the number of substitutions. If\nt is not supplied, use $0. An & in the re-\nplacement text is replaced with the text that\nwas actually matched. Use \\& to get a literal\n&. (This must be typed as \"\\\\&\"; see GAWK: Ef-\nfective AWK Programming for a fuller discussion\nof the rules for ampersands and backslashes in\nthe replacement text of sub(), gsub(), and gen-\nsub().)\n\nindex(s, t) Return the index of the string t in the string\ns, or zero if t is not present. (This implies\nthat character indices start at one.) It is a\nfatal error to use a regexp constant for t.\n\nlength([s]) Return the length of the string s, or the\nlength of $0 if s is not supplied. As a non-\nstandard extension, with an array argument,\nlength() returns the number of elements in the\narray.\n\nmatch(s, r [, a]) Return the position in s where the regular ex-\npression r occurs, or zero if r is not present,\nand set the values of RSTART and RLENGTH. Note\nthat the argument order is the same as for the\n~ operator: str ~ re. If array a is provided,\na is cleared and then elements 1 through n are\nfilled with the portions of s that match the\ncorresponding parenthesized subexpression in r.\nThe zero'th element of a contains the portion\nof s matched by the entire regular expression\nr. Subscripts a[n, \"start\"], and a[n,\n\"length\"] provide the starting index in the\nstring and length respectively, of each match-\ning substring.\n\npatsplit(s, a [, r [, seps] ])\nSplit the string s into the array a and the\nseparators array seps on the regular expression\nr, and return the number of fields. Element\nvalues are the portions of s that matched r.\nThe value of seps[i] is the possibly null sepa-\nrator that appeared after a[i]. The value of\nseps[0] is the possibly null leading separator.\nIf r is omitted, FPAT is used instead. The ar-\nrays a and seps are cleared first. Splitting\nbehaves identically to field splitting with\nFPAT, described above.\n\nsplit(s, a [, r [, seps] ])\nSplit the string s into the array a and the\nseparators array seps on the regular expression\nr, and return the number of fields. If r is\nomitted, FS is used instead. The arrays a and\nseps are cleared first. seps[i] is the field\nseparator matched by r between a[i] and a[i+1].\nIf r is a single space, then leading whitespace\nin s goes into the extra array element seps[0]\nand trailing whitespace goes into the extra ar-\nray element seps[n], where n is the return\nvalue of split(s, a, r, seps). Splitting be-\nhaves identically to field splitting, described\nabove. In particular, if r is a single-charac-\nter string, that string acts as the separator,\neven if it happens to be a regular expression\nmetacharacter.\n\nsprintf(fmt, expr-list) Print expr-list according to fmt, and return\nthe resulting string.\n\nstrtonum(str) Examine str, and return its numeric value. If\nstr begins with a leading 0, treat it as an oc-\ntal number. If str begins with a leading 0x or\n0X, treat it as a hexadecimal number. Other-\nwise, assume it is a decimal number.\n\nsub(r, s [, t]) Just like gsub(), but replace only the first\nmatching substring. Return either zero or one.\n\nsubstr(s, i [, n]) Return the at most n-character substring of s\nstarting at i. If n is omitted, use the rest\nof s.\n\ntolower(str) Return a copy of the string str, with all the\nuppercase characters in str translated to their\ncorresponding lowercase counterparts. Non-al-\nphabetic characters are left unchanged.\n\ntoupper(str) Return a copy of the string str, with all the\nlowercase characters in str translated to their\ncorresponding uppercase counterparts. Non-al-\nphabetic characters are left unchanged.\n\nGawk is multibyte aware. This means that index(), length(), substr()\nand match() all work in terms of characters, not bytes.\n\nTime Functions\nSince one of the primary uses of AWK programs is processing log files\nthat contain time stamp information, gawk provides the following func-\ntions for obtaining time stamps and formatting them.\n\nmktime(datespec [, utc-flag])\nTurn datespec into a time stamp of the same form as returned\nby systime(), and return the result. The datespec is a\nstring of the form YYYY MM DD HH MM SS[ DST]. The contents\nof the string are six or seven numbers representing respec-\ntively the full year including century, the month from 1 to\n12, the day of the month from 1 to 31, the hour of the day\nfrom 0 to 23, the minute from 0 to 59, the second from 0 to\n60, and an optional daylight saving flag. The values of\nthese numbers need not be within the ranges specified; for\nexample, an hour of -1 means 1 hour before midnight. The\norigin-zero Gregorian calendar is assumed, with year 0 pre-\nceding year 1 and year -1 preceding year 0. If utc-flag is\npresent and is non-zero or non-null, the time is assumed to\nbe in the UTC time zone; otherwise, the time is assumed to be\nin the local time zone. If the DST daylight saving flag is\npositive, the time is assumed to be daylight saving time; if\nzero, the time is assumed to be standard time; and if nega-\ntive (the default), mktime() attempts to determine whether\ndaylight saving time is in effect for the specified time. If\ndatespec does not contain enough elements or if the resulting\ntime is out of range, mktime() returns -1.\n\nstrftime([format [, timestamp[, utc-flag]]])\nFormat timestamp according to the specification in format.\nIf utc-flag is present and is non-zero or non-null, the re-\nsult is in UTC, otherwise the result is in local time. The\ntimestamp should be of the same form as returned by sys-\ntime(). If timestamp is missing, the current time of day is\nused. If format is missing, a default format equivalent to\nthe output of date(1) is used. The default format is avail-\nable in PROCINFO[\"strftime\"]. See the specification for the\nstrftime() function in ISO C for the format conversions that\nare guaranteed to be available.\n\nsystime() Return the current time of day as the number of seconds since\nthe Epoch (1970-01-01 00:00:00 UTC on POSIX systems).\n\nBit Manipulations Functions\nGawk supplies the following bit manipulation functions. They work by\nconverting double-precision floating point values to uintmaxt inte-\ngers, doing the operation, and then converting the result back to\nfloating point.\n\nNOTE: Passing negative operands to any of these functions causes a fa-\ntal error.\n\nThe functions are:\n\nand(v1, v2 [, ...]) Return the bitwise AND of the values provided in\nthe argument list. There must be at least two.\n\ncompl(val) Return the bitwise complement of val.\n\nlshift(val, count) Return the value of val, shifted left by count\nbits.\n\nor(v1, v2 [, ...]) Return the bitwise OR of the values provided in the\nargument list. There must be at least two.\n\nrshift(val, count) Return the value of val, shifted right by count\nbits.\n\nxor(v1, v2 [, ...]) Return the bitwise XOR of the values provided in\nthe argument list. There must be at least two.\n\nType Functions\nThe following functions provide type related information about their\narguments.\n\nisarray(x) Return true if x is an array, false otherwise. This func-\ntion is mainly for use with the elements of multidimensional\narrays and with function parameters.\n\ntypeof(x) Return a string indicating the type of x. The string will\nbe one of \"array\", \"number\", \"regexp\", \"string\", \"strnum\",\n\"unassigned\", or \"undefined\".\n\nInternationalization Functions\nThe following functions may be used from within your AWK program for\ntranslating strings at run-time. For full details, see GAWK: Effective\nAWK Programming.\n\nbindtextdomain(directory [, domain])\nSpecify the directory where gawk looks for the .gmo files, in\ncase they will not or cannot be placed in the ``standard'' loca-\ntions (e.g., during testing). It returns the directory where\ndomain is ``bound.''\nThe default domain is the value of TEXTDOMAIN. If directory is\nthe null string (\"\"), then bindtextdomain() returns the current\nbinding for the given domain.\n\ndcgettext(string [, domain [, category]])\nReturn the translation of string in text domain domain for lo-\ncale category category. The default value for domain is the\ncurrent value of TEXTDOMAIN. The default value for category is\n\"LCMESSAGES\".\nIf you supply a value for category, it must be a string equal to\none of the known locale categories described in GAWK: Effective\nAWK Programming. You must also supply a text domain. Use\nTEXTDOMAIN if you want to use the current domain.\n\ndcngettext(string1, string2, number [, domain [, category]])\nReturn the plural form used for number of the translation of\nstring1 and string2 in text domain domain for locale category\ncategory. The default value for domain is the current value of\nTEXTDOMAIN. The default value for category is \"LCMESSAGES\".\nIf you supply a value for category, it must be a string equal to\none of the known locale categories described in GAWK: Effective\nAWK Programming. You must also supply a text domain. Use\nTEXTDOMAIN if you want to use the current domain.\n", "long": "--re-interval" } ] }, "USER-DEFINED FUNCTIONS": { "content": "Functions in AWK are defined as follows:\n\nfunction name(parameter list) { statements }\n\nFunctions execute when they are called from within expressions in ei-\nther patterns or actions. Actual parameters supplied in the function\ncall are used to instantiate the formal parameters declared in the\nfunction. Arrays are passed by reference, other variables are passed\nby value.\n\nSince functions were not originally part of the AWK language, the pro-\nvision for local variables is rather clumsy: They are declared as extra\nparameters in the parameter list. The convention is to separate local\nvariables from real parameters by extra spaces in the parameter list.\nFor example:\n\nfunction f(p, q, a, b) # a and b are local\n{\n...\n}\n\n/abc/ { ... ; f(1, 2) ; ... }\n\nThe left parenthesis in a function call is required to immediately fol-\nlow the function name, without any intervening whitespace. This avoids\na syntactic ambiguity with the concatenation operator. This restric-\ntion does not apply to the built-in functions listed above.\n\nFunctions may call each other and may be recursive. Function parame-\nters used as local variables are initialized to the null string and the\nnumber zero upon function invocation.\n\nUse return expr to return a value from a function. The return value is\nundefined if no value is provided, or if the function returns by \"fall-\ning off\" the end.\n\nAs a gawk extension, functions may be called indirectly. To do this,\nassign the name of the function to be called, as a string, to a vari-\nable. Then use the variable as if it were the name of a function, pre-\nfixed with an @ sign, like so:\nfunction myfunc()\n{\nprint \"myfunc called\"\n...\n}\n\n{ ...\nthefunc = \"myfunc\"\n@thefunc() # call through thefunc to myfunc\n...\n}\nAs of version 4.1.2, this works with user-defined functions, built-in\nfunctions, and extension functions.\n\nIf --lint has been provided, gawk warns about calls to undefined func-\ntions at parse time, instead of at run time. Calling an undefined\nfunction at run time is a fatal error.\n\nThe word func may be used in place of function, although this is depre-\ncated.\n", "subsections": [] }, "DYNAMICALLY LOADING NEW FUNCTIONS": { "content": "You can dynamically add new functions written in C or C++ to the run-\nning gawk interpreter with the @load statement. The full details are\nbeyond the scope of this manual page; see GAWK: Effective AWK Program-\nming.\n", "subsections": [] }, "SIGNALS": { "content": "The gawk profiler accepts two signals. SIGUSR1 causes it to dump a\nprofile and function call stack to the profile file, which is either\nawkprof.out, or whatever file was named with the --profile option. It\nthen continues to run. SIGHUP causes gawk to dump the profile and\nfunction call stack and then exit.\n", "subsections": [] }, "INTERNATIONALIZATION": { "content": "String constants are sequences of characters enclosed in double quotes.\nIn non-English speaking environments, it is possible to mark strings in\nthe AWK program as requiring translation to the local natural language.\nSuch strings are marked in the AWK program with a leading underscore\n(\"\"). For example,\n\ngawk 'BEGIN { print \"hello, world\" }'\n\nalways prints hello, world. But,\n\ngawk 'BEGIN { print \"hello, world\" }'\n\nmight print bonjour, monde in France.\n\nThere are several steps involved in producing and running a localizable\nAWK program.\n\n1. Add a BEGIN action to assign a value to the TEXTDOMAIN variable to\nset the text domain to a name associated with your program:\n\nBEGIN { TEXTDOMAIN = \"myprog\" }\n\nThis allows gawk to find the .gmo file associated with your pro-\ngram. Without this step, gawk uses the messages text domain, which\nlikely does not contain translations for your program.\n\n2. Mark all strings that should be translated with leading under-\nscores.\n\n3. If necessary, use the dcgettext() and/or bindtextdomain() functions\nin your program, as appropriate.\n\n4. Run gawk --gen-pot -f myprog.awk > myprog.pot to generate a .pot\nfile for your program.\n\n5. Provide appropriate translations, and build and install the corre-\nsponding .gmo files.\n\nThe internationalization features are described in full detail in GAWK:\nEffective AWK Programming.\n", "subsections": [] }, "POSIX COMPATIBILITY": { "content": "A primary goal for gawk is compatibility with the POSIX standard, as\nwell as with the latest version of Brian Kernighan's awk. To this end,\ngawk incorporates the following user visible features which are not de-\nscribed in the AWK book, but are part of the Brian Kernighan's version\nof awk, and are in the POSIX standard.\n\nThe book indicates that command line variable assignment happens when\nawk would otherwise open the argument as a file, which is after the BE-\nGIN rule is executed. However, in earlier implementations, when such\nan assignment appeared before any file names, the assignment would hap-\npen before the BEGIN rule was run. Applications came to depend on this\n\"feature.\" When awk was changed to match its documentation, the -v op-\ntion for assigning variables before program execution was added to ac-\ncommodate applications that depended upon the old behavior. (This fea-\nture was agreed upon by both the Bell Laboratories developers and the\nGNU developers.)\n\nWhen processing arguments, gawk uses the special option \"--\" to signal\nthe end of arguments. In compatibility mode, it warns about but other-\nwise ignores undefined options. In normal operation, such arguments\nare passed on to the AWK program for it to process.\n\nThe AWK book does not define the return value of srand(). The POSIX\nstandard has it return the seed it was using, to allow keeping track of\nrandom number sequences. Therefore srand() in gawk also returns its\ncurrent seed.\n\nOther features are: The use of multiple -f options (from MKS awk); the\nENVIRON array; the \\a, and \\v escape sequences (done originally in gawk\nand fed back into the Bell Laboratories version); the tolower() and\ntoupper() built-in functions (from the Bell Laboratories version); and\nthe ISO C conversion specifications in printf (done first in the Bell\nLaboratories version).\n", "subsections": [] }, "HISTORICAL FEATURES": { "content": "There is one feature of historical AWK implementations that gawk sup-\nports: It is possible to call the length() built-in function not only\nwith no argument, but even without parentheses! Thus,\n\na = length # Holy Algol 60, Batman!\n\nis the same as either of\n\na = length()\na = length($0)\n\nUsing this feature is poor practice, and gawk issues a warning about\nits use if --lint is specified on the command line.\n", "subsections": [] }, "GNU EXTENSIONS": { "content": "Gawk has a too-large number of extensions to POSIX awk. They are de-\nscribed in this section. All the extensions described here can be dis-\nabled by invoking gawk with the --traditional or --posix options.\n\nThe following features of gawk are not available in POSIX awk.\n\no No path search is performed for files named via the -f option.\nTherefore the AWKPATH environment variable is not special.\n\no There is no facility for doing file inclusion (gawk's @include mecha-\nnism).\n\no There is no facility for dynamically adding new functions written in\nC (gawk's @load mechanism).\n\no The \\x escape sequence.\n\no The ability to continue lines after ? and :.\n\no Octal and hexadecimal constants in AWK programs.\n\no The ARGIND, BINMODE, ERRNO, LINT, PREC, ROUNDMODE, RT and TEXTDOMAIN\nvariables are not special.\n\no The IGNORECASE variable and its side-effects are not available.\n\no The FIELDWIDTHS variable and fixed-width field splitting.\n\no The FPAT variable and field splitting based on field values.\n\no The FUNCTAB, SYMTAB, and PROCINFO arrays are not available.\n\no The use of RS as a regular expression.\n\no The special file names available for I/O redirection are not recog-\nnized.\n\no The |& operator for creating coprocesses.\n\no The BEGINFILE and ENDFILE special patterns are not available.\n\no The ability to split out individual characters using the null string\nas the value of FS, and as the third argument to split().\n\no An optional fourth argument to split() to receive the separator\ntexts.\n\no The optional second argument to the close() function.\n\no The optional third argument to the match() function.\n\no The ability to use positional specifiers with printf and sprintf().\n\no The ability to pass an array to length().\n\no The and(), asort(), asorti(), bindtextdomain(), compl(), dcgettext(),\ndcngettext(), gensub(), lshift(), mktime(), or(), patsplit(),\nrshift(), strftime(), strtonum(), systime() and xor() functions.\n\no Localizable strings.\n\no Non-fatal I/O.\n\no Retryable I/O.\n\nThe AWK book does not define the return value of the close() function.\nGawk's close() returns the value from fclose(3), or pclose(3), when\nclosing an output file or pipe, respectively. It returns the process's\nexit status when closing an input pipe. The return value is -1 if the\nnamed file, pipe or coprocess was not opened with a redirection.\n\nWhen gawk is invoked with the --traditional option, if the fs argument\nto the -F option is \"t\", then FS is set to the tab character. Note\nthat typing gawk -F\\t ... simply causes the shell to quote the \"t,\"\nand does not pass \"\\t\" to the -F option. Since this is a rather ugly\nspecial case, it is not the default behavior. This behavior also does\nnot occur if --posix has been specified. To really get a tab character\nas the field separator, it is best to use single quotes: gawk -F'\\t'\n....\n", "subsections": [] }, "ENVIRONMENT VARIABLES": { "content": "The AWKPATH environment variable can be used to provide a list of di-\nrectories that gawk searches when looking for files named via the -f,\n--file, -i and --include options, and the @include directive. If the\ninitial search fails, the path is searched again after appending .awk\nto the filename.\n\nThe AWKLIBPATH environment variable can be used to provide a list of\ndirectories that gawk searches when looking for files named via the -l\nand --load options.\n\nThe GAWKREADTIMEOUT environment variable can be used to specify a\ntimeout in milliseconds for reading input from a terminal, pipe or two-\nway communication including sockets.\n\nFor connection to a remote host via socket, GAWKSOCKRETRIES controls\nthe number of retries, and GAWKMSECSLEEP the interval between re-\ntries. The interval is in milliseconds. On systems that do not support\nusleep(3), the value is rounded up to an integral number of seconds.\n\nIf POSIXLYCORRECT exists in the environment, then gawk behaves exactly\nas if --posix had been specified on the command line. If --lint has\nbeen specified, gawk issues a warning message to this effect.\n", "subsections": [] }, "EXIT STATUS": { "content": "If the exit statement is used with a value, then gawk exits with the\nnumeric value given to it.\n\nOtherwise, if there were no problems during execution, gawk exits with\nthe value of the C constant EXITSUCCESS. This is usually zero.\n\nIf an error occurs, gawk exits with the value of the C constant\nEXITFAILURE. This is usually one.\n\nIf gawk exits because of a fatal error, the exit status is 2. On non-\nPOSIX systems, this value may be mapped to EXITFAILURE.\n", "subsections": [] }, "VERSION INFORMATION": { "content": "This man page documents gawk, version 5.1.\n", "subsections": [] }, "AUTHORS": { "content": "The original version of UNIX awk was designed and implemented by Alfred\nAho, Peter Weinberger, and Brian Kernighan of Bell Laboratories. Brian\nKernighan continues to maintain and enhance it.\n\nPaul Rubin and Jay Fenlason, of the Free Software Foundation, wrote\ngawk, to be compatible with the original version of awk distributed in\nSeventh Edition UNIX. John Woods contributed a number of bug fixes.\nDavid Trueman, with contributions from Arnold Robbins, made gawk com-\npatible with the new version of UNIX awk. Arnold Robbins is the cur-\nrent maintainer.\n\nSee GAWK: Effective AWK Programming for a full list of the contributors\nto gawk and its documentation.\n\nSee the README file in the gawk distribution for up-to-date information\nabout maintainers and which ports are currently supported.\n", "subsections": [] }, "BUG REPORTS": { "content": "If you find a bug in gawk, please send electronic mail to\nbug-gawk@gnu.org. Please include your operating system and its revi-\nsion, the version of gawk (from gawk --version), which C compiler you\nused to compile it, and a test program and data that are as small as\npossible for reproducing the problem.\n\nBefore sending a bug report, please do the following things. First,\nverify that you have the latest version of gawk. Many bugs (usually\nsubtle ones) are fixed at each release, and if yours is out of date,\nthe problem may already have been solved. Second, please see if set-\nting the environment variable LCALL to LCALL=C causes things to be-\nhave as you expect. If so, it's a locale issue, and may or may not re-\nally be a bug. Finally, please read this man page and the reference\nmanual carefully to be sure that what you think is a bug really is, in-\nstead of just a quirk in the language.\n\nWhatever you do, do NOT post a bug report in comp.lang.awk. While the\ngawk developers occasionally read this newsgroup, posting bug reports\nthere is an unreliable way to report bugs. Similarly, do NOT use a web\nforum (such as Stack Overflow) for reporting bugs. Instead, please use\nthe electronic mail addresses given above. Really.\n\nIf you're using a GNU/Linux or BSD-based system, you may wish to submit\na bug report to the vendor of your distribution. That's fine, but\nplease send a copy to the official email address as well, since there's\nno guarantee that the bug report will be forwarded to the gawk main-\ntainer.\n", "subsections": [] }, "BUGS": { "content": "The -F option is not necessary given the command line variable assign-\nment feature; it remains only for backwards compatibility.\n", "subsections": [] }, "SEE ALSO": { "content": "egrep(1), sed(1), getpid(2), getppid(2), getpgrp(2), getuid(2), ge-\nteuid(2), getgid(2), getegid(2), getgroups(2), printf(3), strftime(3),\nusleep(3)\n\nThe AWK Programming Language, Alfred V. Aho, Brian W. Kernighan, Peter\nJ. Weinberger, Addison-Wesley, 1988. ISBN 0-201-07981-X.\n\nGAWK: Effective AWK Programming, Edition 5.1, shipped with the gawk\nsource. The current version of this document is available online at\nhttps://www.gnu.org/software/gawk/manual.\n\nThe GNU gettext documentation, available online at\nhttps://www.gnu.org/software/gettext.\n", "subsections": [] }, "EXAMPLES": { "content": "Print and sort the login names of all users:\n\nBEGIN { FS = \":\" }\n{ print $1 | \"sort\" }\n\nCount lines in a file:\n\n{ nlines++ }\nEND { print nlines }\n\nPrecede each line by its number in the file:\n\n{ print FNR, $0 }\n\nConcatenate and line number (a variation on a theme):\n\n{ print NR, $0 }\n\nRun an external command for particular lines of data:\n\ntail -f accesslog |\nawk '/myhome.html/ { system(\"nmap \" $1 \">> logdir/myhome.html\") }'\n", "subsections": [] }, "ACKNOWLEDGEMENTS": { "content": "Brian Kernighan provided valuable assistance during testing and debug-\nging. We thank him.\n", "subsections": [] }, "COPYING PERMISSIONS": { "content": "Copyright (C) 1989, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998,\n1999, 2001, 2002, 2003, 2004, 2005, 2007, 2009, 2010, 2011, 2012, 2013,\n2014, 2015, 2016, 2017, 2018, 2019, 2020, Free Software Foundation,\nInc.\n\nPermission is granted to make and distribute verbatim copies of this\nmanual page provided the copyright notice and this permission notice\nare preserved on all copies.\n\nPermission is granted to copy and distribute modified versions of this\nmanual page under the conditions for verbatim copying, provided that\nthe entire resulting derived work is distributed under the terms of a\npermission notice identical to this one.\n\nPermission is granted to copy and distribute translations of this man-\nual page into another language, under the above conditions for modified\nversions, except that this permission notice may be stated in a trans-\nlation approved by the Foundation.\n\nFree Software Foundation Mar 23 2020 GAWK(1)", "subsections": [] } }, "summary": "gawk - pattern scanning and processing language", "flags": [ { "flag": "-b", "long": null, "arg": null, "description": "" }, { "flag": "", "long": "--characters-as-bytes", "arg": null, "description": "Treat all input data as single-byte characters. In other words, don't pay any attention to the locale information when attempt- ing to process strings as multibyte characters. The --posix op- tion overrides this one." }, { "flag": "-c", "long": null, "arg": null, "description": "" }, { "flag": "", "long": "--traditional", "arg": null, "description": "Run in compatibility mode. In compatibility mode, gawk behaves identically to Brian Kernighan's awk; none of the GNU-specific extensions are recognized. See GNU EXTENSIONS, below, for more information." }, { "flag": "-C", "long": null, "arg": null, "description": "" }, { "flag": "", "long": "--copyright", "arg": null, "description": "Print the short version of the GNU copyright information message on the standard output and exit successfully." }, { "flag": "", "long": null, "arg": null, "description": "" }, { "flag": "", "long": null, "arg": null, "description": "Print a sorted list of global variables, their types and final values to file. If no file is provided, gawk uses a file named awkvars.out in the current directory. Having a list of all the global variables is a good way to look for typographical errors in your programs. You would also use this option if you have a large program with a lot of functions, and you want to be sure that your functions don't inadvertently use global variables that you meant to be local. (This is a particularly easy mistake to make with simple variable names like i, j, and so on.)" }, { "flag": "", "long": null, "arg": null, "description": "" }, { "flag": "", "long": null, "arg": null, "description": "Enable debugging of AWK programs. By default, the debugger reads commands interactively from the keyboard (standard input). The optional file argument specifies a file with a list of com- mands for the debugger to execute non-interactively. -e program-text --source program-text Use program-text as AWK program source code. This option allows the easy intermixing of library functions (used via the -f and --include options) with source code entered on the command line. It is intended primarily for medium to large AWK programs used in shell scripts. Each argument supplied via -e is treated as if it begins with an implicit @namespace \"awk\" statement. -E file --exec file Similar to -f, however, this is option is the last one pro- cessed. This should be used with #! scripts, particularly for CGI applications, to avoid passing in options or source code (!) on the command line from a URL. This option disables command- line variable assignments." }, { "flag": "-g", "long": null, "arg": null, "description": "" }, { "flag": "", "long": "--gen-pot", "arg": null, "description": "Scan and parse the AWK program, and generate a GNU .pot (Porta- ble Object Template) format file on standard output with entries for all localizable strings in the program. The program itself is not executed. See the GNU gettext distribution for more in- formation on .pot files." }, { "flag": "-h", "long": null, "arg": null, "description": "--help Print a relatively short summary of the available options on the standard output. (Per the GNU Coding Standards, these options cause an immediate, successful exit.) -i include-file --include include-file Load an awk source library. This searches for the library using the AWKPATH environment variable. If the initial search fails, another attempt will be made after appending the .awk suffix. The file will be loaded only once (i.e., duplicates are elimi- nated), and the code does not constitute the main program source. Files read with --include are treated as if they begin with an implicit @namespace \"awk\" statement. -l lib --load lib Load a gawk extension from the shared library lib. This searches for the library using the AWKLIBPATH environment vari- able. If the initial search fails, another attempt will be made after appending the default shared library suffix for the plat- form. The library initialization routine is expected to be named dlload()." }, { "flag": "-L", "long": null, "arg": null, "description": "" }, { "flag": "", "long": null, "arg": null, "description": "Provide warnings about constructs that are dubious or non-porta- ble to other AWK implementations. With an optional argument of fatal, lint warnings become fatal errors. This may be drastic, but its use will certainly encourage the development of cleaner AWK programs. With an optional argument of invalid, only warn- ings about things that are actually invalid are issued. (This is not fully implemented yet.) With an optional argument of no- ext, warnings about gawk extensions are disabled." }, { "flag": "-M", "long": null, "arg": null, "description": "" }, { "flag": "", "long": "--bignum", "arg": null, "description": "Force arbitrary precision arithmetic on numbers. This option has no effect if gawk is not compiled to use the GNU MPFR and GMP libraries. (In such a case, gawk issues a warning.)" }, { "flag": "-n", "long": null, "arg": null, "description": "" }, { "flag": "", "long": "--non-decimal-data", "arg": null, "description": "Recognize octal and hexadecimal values in input data. Use this option with great caution!" }, { "flag": "-N", "long": null, "arg": null, "description": "" }, { "flag": "", "long": "--use-lc-numeric", "arg": null, "description": "Force gawk to use the locale's decimal point character when parsing input data. Although the POSIX standard requires this behavior, and gawk does so when --posix is in effect, the de- fault is to follow traditional behavior and use a period as the decimal point, even in locales where the period is not the deci- mal point character. This option overrides the default behav- ior, without the full draconian strictness of the --posix op- tion." }, { "flag": "", "long": null, "arg": null, "description": "" }, { "flag": "", "long": null, "arg": null, "description": "Output a pretty printed version of the program to file. If no file is provided, gawk uses a file named awkprof.out in the cur- rent directory. This option implies --no-optimize." }, { "flag": "-O", "long": null, "arg": null, "description": "" }, { "flag": "", "long": "--optimize", "arg": null, "description": "Enable gawk's default optimizations upon the internal represen- tation of the program. Currently, this just includes simple constant folding. This option is on by default." }, { "flag": "", "long": null, "arg": null, "description": "" }, { "flag": "", "long": null, "arg": null, "description": "Start a profiling session, and send the profiling data to prof- file. The default is awkprof.out. The profile contains execu- tion counts of each statement in the program in the left margin and function call counts for each user-defined function. This option implies --no-optimize." }, { "flag": "-P", "long": null, "arg": null, "description": "" }, { "flag": "", "long": "--posix", "arg": null, "description": "This turns on compatibility mode, with the following additional restrictions: o \\x escape sequences are not recognized. o You cannot continue lines after ? and :. o The synonym func for the keyword function is not recognized. o The operators and = cannot be used in place of ^ and ^=." }, { "flag": "-r", "long": null, "arg": null, "description": "" }, { "flag": "", "long": "--re-interval", "arg": null, "description": "Enable the use of interval expressions in regular expression matching (see Regular Expressions, below). Interval expressions were not traditionally available in the AWK language. The POSIX standard added them, to make awk and egrep consistent with each other. They are enabled by default, but this option remains for use together with --traditional." }, { "flag": "-s", "long": null, "arg": null, "description": "" }, { "flag": "", "long": "--no-optimize", "arg": null, "description": "Disable gawk's default optimizations upon the internal represen- tation of the program." }, { "flag": "-S", "long": null, "arg": null, "description": "" }, { "flag": "", "long": "--sandbox", "arg": null, "description": "Run gawk in sandbox mode, disabling the system() function, input redirection with getline, output redirection with print and printf, and loading dynamic extensions. Command execution (through pipelines) is also disabled. This effectively blocks a script from accessing local resources, except for the files specified on the command line." }, { "flag": "-t", "long": null, "arg": null, "description": "" }, { "flag": "", "long": "--lint-old", "arg": null, "description": "Provide warnings about constructs that are not portable to the original version of UNIX awk." }, { "flag": "-V", "long": null, "arg": null, "description": "" }, { "flag": "", "long": "--version", "arg": null, "description": "Print version information for this particular copy of gawk on the standard output. This is useful mainly for knowing if the current copy of gawk on your system is up to date with respect to whatever the Free Software Foundation is distributing. This is also useful when reporting bugs. (Per the GNU Coding Stan- dards, these options cause an immediate, successful exit.) -- Signal the end of options. This is useful to allow further argu- ments to the AWK program itself to start with a \"-\". This pro- vides consistency with the argument parsing convention used by most other POSIX programs. In compatibility mode, any other options are flagged as invalid, but are otherwise ignored. In normal operation, as long as program text has been supplied, unknown options are passed on to the AWK program in the ARGV array for processing. This is particularly useful for running AWK programs via the #! executable interpreter mechanism. For POSIX compatibility, the -W option may be used, followed by the name of a long option." } ], "examples": [ "Print and sort the login names of all users:", "BEGIN { FS = \":\" }", "{ print $1 | \"sort\" }", "Count lines in a file:", "{ nlines++ }", "END { print nlines }", "Precede each line by its number in the file:", "{ print FNR, $0 }", "Concatenate and line number (a variation on a theme):", "{ print NR, $0 }", "Run an external command for particular lines of data:", "tail -f accesslog |", "awk '/myhome.html/ { system(\"nmap \" $1 \">> logdir/myhome.html\") }'" ], "see_also": [ { "name": "egrep", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/egrep/1/json" }, { "name": "sed", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/sed/1/json" }, { "name": "getpid", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/getpid/2/json" }, { "name": "getppid", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/getppid/2/json" }, { "name": "getpgrp", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/getpgrp/2/json" }, { "name": "getuid", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/getuid/2/json" }, { "name": "teuid", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/teuid/2/json" }, { "name": "getgid", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/getgid/2/json" }, { "name": "getegid", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/getegid/2/json" }, { "name": "getgroups", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/getgroups/2/json" }, { "name": "printf", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/printf/3/json" }, { "name": "strftime", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/strftime/3/json" }, { "name": "usleep", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/usleep/3/json" } ] }