docs.json

{"functions":{"gensub(r, s, h [, t])":"Search the target string t for matches of the regular expression r. If h is a string beginning with g or G, then replace all matches of r with s. Otherwise, h is a number indicating which match of r to replace. If t is not supplied, use $0 instead. Within the replacement text s, the sequence \\n, where n is a digit from 1 to 9, may be used to indicate just the text that matched the n'th parenthesized subexpression. The sequence \\0 represents the entire matched text, as does the character &. Unlike sub() and gsub(), the modified string is returned as the result of the function, and the original target string is not changed.","toupper(str)":"Return a copy of the string str, with all the lowercase characters in str translated to their corresponding uppercase counterparts. Non-alphabetic characters are left unchanged.","rshift(val, count)":"Return the value of val, shifted right by count bits.","bindtextdomain(directory [, domain])":"Specify the directory where gawk looks for the .gmo files, in case they will not or cannot be placed in the ``standard'' locations (e.g., during testing). It returns the directory where domain is ``bound.'' The default domain is the value of TEXTDOMAIN. If directory is the null string (\"\"), then bindtextdomain() returns the current binding for the given domain.","log(expr)":"The natural logarithm function.","length([s])":"Return the length of the string s, or the length of $0 if s is not supplied. As a non-standard extension, with an array argument, length() returns the number of elements in the array.","isarray(x)":"Return true if x is an array, false otherwise. This function is mainly for use with the elements of multidimensional arrays and with function parameters.","srand([expr])":"Use expr as the new seed for the random number generator. If no expr is provided, use the time of day. Return the previous seed for the random number generator.","strtonum(str)":"Examine str, and return its numeric value. If str begins with a leading 0, treat it as an octal number. If str begins with a leading 0x or 0X, treat it as a hexadecimal number. Otherwise, assume it is a decimal number.","compl(val)":"Return the bitwise complement of val.","cos(expr)":"Return the cosine of expr, which is in radians.","asort(s [, d [, how] ])":"Return the number of elements in the source array s. Sort the contents of s using gawk's normal rules for comparing values, and replace the indices of the sorted values s with sequential integers starting with 1. If the optional destination array d is specified, first duplicate s into d, and then sort d, leaving the indices of the source array s unchanged. The optional string how controls the direction and the comparison mode. Valid values for how are any of the strings valid for PROCINFO[\"sorted_in\"]. It can also be the name of a user-defined comparison function as described in PROCINFO[\"sorted_in\"].","dcgettext(string [, domain [, category]])":"Return the translation of string in text domain domain for locale category category. The default value for domain is the current value of TEXTDOMAIN. The default value for category is \"LC_MESSAGES\". If you supply a value for category, it must be a string equal to one of the known locale categories described in GAWK: Effective AWK Programming. You must also supply a text domain. Use TEXTDOMAIN if you want to use the current domain.","gsub(r, s [, t])":"For each substring matching the regular expression r in the string t, substitute the string s, and return the number of substitutions. If t is not supplied, use $0. An & in the replacement text is replaced with the text that was actually matched. Use \\& to get a literal &. (This must be typed as \"\\\\&\"; see GAWK: Effective AWK Programming for a fuller discussion of the rules for ampersands and backslashes in the replacement text of sub(), gsub(), and gensub().)","mktime(datespec [, utc-flag])":"Turn datespec into a time stamp of the same form as returned by systime(), and return the result. The datespec is a string of the form YYYY MM DD HH MM SS[ DST]. The contents of the string are six or seven numbers representing respectively the full year including century, the month from 1 to 12, the day of the month from 1 to 31, the hour of the day from 0 to 23, the minute from 0 to 59, the second from 0 to 60, and an optional daylight saving flag. The values of these numbers need not be within the ranges specified; for example, an hour of -1 means 1 hour before midnight. The origin-zero Gregorian calendar is assumed, with year 0 preceding year 1 and year -1 preceding year 0. If utc-flag is present and is non-zero or non-null, the time is assumed to be in the UTC time zone; otherwise, the time is assumed to be in the local time zone. If the DST daylight saving flag is positive, the time is assumed to be daylight saving time; if zero, the time is assumed to be standard time; and if negative (the default), mktime() attempts to determine whether daylight saving time is in effect for the specified time. If datespec does not contain enough elements or if the resulting time is out of range, mktime() returns -1.","typeof(x)":"Return a string indicating the type of x. The string will be one of \"array\", \"number\", \"regexp\", \"string\", \"strnum\", \"unassigned\", or \"undefined\".","sqrt(expr)":"Return the square root of expr.","match(s, r [, a])":"Return the position in s where the regular expression r occurs, or zero if r is not present, and set the values of RSTART and RLENGTH. Note that the argument order is the same as for the ~ operator: str ~ re. If array a is provided, a is cleared and then elements 1 through n are filled with the portions of s that match the corresponding parenthesized subexpression in r. The zero'th element of a contains the portion of s matched by the entire regular expression r. Subscripts a[n, \"start\"], and a[n, \"length\"] provide the starting index in the string and length respectively, of each matching substring.","split(s, a [, r [, seps] ])":"Split the string s into the array a and the separators array seps on the regular expression r, and return the number of fields. If r is omitted, FS is used instead. The arrays a and seps are cleared first. seps[i] is the field separator matched by r between a[i] and a[i+1]. If r is a single space, then leading whitespace in s goes into the extra array element seps[0] and trailing whitespace goes into the extra array element seps[n], where n is the return value of split(s, a, r, seps). Splitting behaves identically to field splitting, described above. In particular, if r is a single-character string, that string acts as the separator, even if it happens to be a regular expression metacharacter.","dcngettext(string1, string2, number [, domain [, category]])":"Return the plural form used for number of the translation of string1 and string2 in text domain domain for locale category category. The default value for domain is the current value of TEXTDOMAIN. The default value for category is \"LC_MESSAGES\". If you supply a value for category, it must be a string equal to one of the known locale categories described in GAWK: Effective AWK Programming. You must also supply a text domain. Use TEXTDOMAIN if you want to use the current domain.","sin(expr)":"Return the sine of expr, which is in radians.","substr(s, i [, n])":"Return the at most n-character substring of s starting at i. If n is omitted, use the rest of s.","systime()":"Return the current time of day as the number of seconds since the Epoch (1970-01-01 00:00:00 UTC on POSIX systems).","or(v1, v2 [, ...])":"Return the bitwise OR of the values provided in the argument list. There must be at least two.","int(expr)":"Truncate to integer.","exp(expr)":"The exponential function.","rand()":"Return a random number N, between zero and one, such that 0 ≤ N < 1.","index(s, t)":"Return the index of the string t in the string s, or zero if t is not present. (This implies that character indices start at one.) It is a fatal error to use a regexp constant for t.","tolower(str)":"Return a copy of the string str, with all the uppercase characters in str translated to their corresponding lowercase counterparts. Non-alphabetic characters are left unchanged.","lshift(val, count)":"Return the value of val, shifted left by count bits.","patsplit(s, a [, r [, seps] ])":"Split the string s into the array a and the separators array seps on the regular expression r, and return the number of fields. Element values are the portions of s that matched r. The value of seps[i] is the possibly null separator that appeared after a[i]. The value of seps[0] is the possibly null leading separator. If r is omitted, FPAT is used instead. The arrays a and seps are cleared first. Splitting behaves identically to field splitting with FPAT, described above.","sprintf(fmt, expr-list)":"Print expr-list according to fmt, and return the resulting string.","strftime([format [, timestamp[, utc-flag]]])":"Format timestamp according to the specification in format. If utc-flag is present and is non-zero or non-null, the result is in UTC, otherwise the result is in local time. The timestamp should be of the same form as returned by systime(). If timestamp is missing, the current time of day is used. If format is missing, a default format equivalent to the output of date(1) is used. The default format is available in PROCINFO[\"strftime\"]. See the specification for the strftime() function in ISO C for the format conversions that are guaranteed to be available.","and(v1, v2 [, ...])":"Return the bitwise AND of the values provided in the argument list. There must be at least two.","asorti(s [, d [, how] ])":"Return the number of elements in the source array s. The behavior is the same as that of asort(), except that the array indices are used for sorting, not the array values. When done, the array is indexed numerically, and the values are those of the original indices. The original values are lost; thus provide a second array if you wish to preserve the original. The purpose of the optional string how is the same as described previously for asort().","sub(r, s [, t])":"Just like gsub(), but replace only the first matching substring. Return either zero or one.","xor(v1, v2 [, ...])":"Return the bitwise XOR of the values provided in the argument list. There must be at least two."},"builtins":{"OFS":"The output field separator, a space by default.","ARGC":"The number of command line arguments (does not include options to gawk, or the program source).","PROCINFO[\"NONFATAL\"]":"If this exists, then I/O errors for all redirections become nonfatal.","PREC":"The working precision of arbitrary precision floating-point numbers, 53 by default.","ARGIND":"The index in ARGV of the current file being processed.","ERRNO":"If a system error occurs either doing a redirection for getline, during a read for getline, or during a close(), then ERRNO is set to a string describing the error. The value is subject to translation in non-English locales. If the string in ERRNO corresponds to a system error in the errno(3) variable, then the numeric value can be found in PROCINFO[\"errno\"]. For nonsystem errors, PROCINFO[\"errno\"] will be zero.","ARGV":"Array of command line arguments. The array is indexed from 0 to ARGC - 1. Dynamically changing the contents of ARGV can control the files used for data.","PROCINFO[\"name\", \"NONFATAL\"]":"Make I/O errors for name be nonfatal.","PROCINFO[\"prec_max\"]":"The maximum precision supported by the GNU MPFR library for arbitrary precision floating-point numbers.","ROUNDMODE":"The rounding mode to use for arbitrary precision arithmetic on numbers, by default \"N\" (IEEE-754 roundTiesToEven mode). The accepted values are:\\n\"A\" or \"a\" for rounding away from zero. These are only available if your version of the GNU MPFR library supports rounding away from zero.\\n\"D\" or \"d\" for roundTowardNegative.\\n\"N\" or \"n\" for roundTiesToEven.\\n\"U\" or \"u\" for roundTowardPositive.\\n\"Z\" or \"z\" for roundTowardZero.","FNR":"The input record number in the current input file.","PROCINFO[\"version\"]":"The version of gawk.\\nThe following elements are present if loading dynamic extensions is available:","PROCINFO[\"mpfr_version\"]":"The version of the GNU MPFR library used for arbitrary precision number support in gawk.","PROCINFO[\"input\", \"RETRY\"]":"If an I/O error that may be retried occurs when reading data from input, and this array entry exists, then getline returns -2 instead of following the default behavior of returning -1 and configuring input to return no further data. An I/O error that may be retried is one where errno(3) has the value EAGAIN, EWOULDBLOCK, EINTR, or ETIMEDOUT. This may be useful in conjunction with PROCINFO[\"input\", \"READ_TIMEOUT\"] or in situations where a file descriptor has been configured to behave in a non-blocking fashion.","PROCINFO[\"platform\"]":"A string indicating the platform for which gawk was compiled. It is one of:\\n\"djgpp\", \"mingw\" Microsoft Windows, using either DJGPP, or MinGW, respectively.\\n\"os2\" OS/2.\\n\"posix\" GNU/Linux, Cygwin, Mac OS X, and legacy Unix systems.\\n\"vms\" OpenVMS or Vax/VMS.","TEXTDOMAIN":"The text domain of the AWK program; used to find the localized translations for the program's strings.","ORS":"The output record separator, by default a newline.","PROCINFO[\"pgrpid\"]":"The value of the getpgrp(2) system call.","RSTART":"The index of the first character matched by match(); 0 if no match. (This implies that character indices start at one.)","PROCINFO[\"gmp_version\"]":"The version of the GNU GMP library used for arbitrary precision number support in gawk.","PROCINFO[\"api_minor\"]":"The minor version of the extension API.\\nThe following elements are available if MPFR support is compiled into gawk:","PROCINFO[\"uid\"]":"The value of the getuid(2) system call.","PROCINFO[\"argv\"]":"The command line arguments as received by gawk at the C-language level. The subscripts start from zero.","LINT":"Provides dynamic control of the --lint option from within an AWK program. When true, gawk prints lint warnings. When false, it does not. The values allowed for the --lint option may also be assigned to LINT, with the same effects. Any other true value just prints warnings.","PROCINFO[\"identifiers\"]":"A subarray, indexed by the names of all identifiers used in the text of the AWK program. The values indicate what gawk knows about the identifiers after it has finished parsing the program; they are not updated while the program runs. For each identifier, the value of the element is one of the following:\\n\"array\" The identifier is an array.\\n\"builtin\" The identifier is a built-in function.\\n\"extension\" The identifier is an extension function loaded via @load or --load.\\n\"scalar\" The identifier is a scalar.\\n\"untyped\" The identifier is untyped (could be used as a scalar or array, gawk doesn't know yet).\\n\"user\" The identifier is a user-defined function.","IGNORECASE":"Controls the case-sensitivity of all regular expression and string operations. If IGNORECASE has a non-zero value, then string comparisons and pattern matching in rules, field splitting with FS and FPAT, record separating with RS, regular expression matching with ~ and !~, and the gensub(), gsub(), index(), match(), patsplit(), split(), and sub() built-in functions all ignore case when doing regular expression operations. NOTE: Array subscripting is not affected. However, the asort() and asorti() functions are affected. Thus, if IGNORECASE is not equal to zero, /aB/ matches all of the strings \"ab\", \"aB\", \"Ab\", and \"AB\". As with all AWK variables, the initial value of IGNORECASE is zero, so all regular expression and string operations are normally case-sensitive.","CONVFMT":"The conversion format for numbers, \"%.6g\", by default.","PROCINFO[\"input\", \"READ_TIMEOUT\"]":"The timeout in milliseconds for reading data from input, where input is a redirection string or a filename. A value of zero or less than zero means no timeout.","FS":"The input field separator, a space by default. See Fields, above.","BINMODE":"On non-POSIX systems, specifies use of “binary” mode for all file I/O. Numeric values of 1, 2, or 3, specify that input files, output files, or all files, respectively, should use binary I/O. String values of \"r\", or \"w\" specify that input files, or output files, respectively, should use binary I/O. String values of \"rw\" or \"wr\" specify that all files should use binary I/O. Any other string value is treated as \"rw\", but generates a warning message.","FIELDWIDTHS":"A whitespace-separated list of field widths. When set, gawk parses the input into fields of fixed width, instead of using the value of the FS variable as the field separator. Each field width may optionally be preceded by a colon-separated value specifying the number of characters to skip before the field starts. See Fields, above.","FILENAME":"The name of the current input file. If no files are specified on the command line, the value of FILENAME is “-”. However, FILENAME is undefined inside the BEGIN rule (unless set by getline).","PROCINFO[\"euid\"]":"The value of the geteuid(2) system call.","FUNCTAB":"An array whose indices and corresponding values are the names of all the user-defined or extension functions in the program. NOTE: You may not use the delete statement with the FUNCTAB array.","NF":"The number of fields in the current input record.","PROCINFO[\"api_major\"]":"The major version of the extension API.","PROCINFO[\"errno\"]":"The value of errno(3) when ERRNO is set to the associated error message.","PROCINFO[\"gid\"]":"The value of the getgid(2) system call.","PROCINFO[\"ppid\"]":"The value of the getppid(2) system call.","NR":"The total number of input records seen so far.","SUBSEP":"The string used to separate multiple subscripts in array elements, by default \"\\034\".","OFMT":"The output format for numbers, \"%.6g\", by default.","RLENGTH":"The length of the string matched by match(); -1 if no match.","PROCINFO[\"command\", \"pty\"]":"Use a pseudo-tty for two-way communication with command instead of setting up two one-way pipes.","PROCINFO[\"strftime\"]":"The default time format string for strftime(). Changing its value affects how strftime() formats time values when called with no arguments.","FPAT":"A regular expression describing the contents of the fields in a record. When set, gawk parses the input into fields, where the fields match the regular expression, instead of using the value of FS as the field separator. See Fields, above.","RS":"The input record separator, by default a newline.","PROCINFO":"The elements of this array provide access to information about the running AWK program. On some systems, there may be elements in the array, \"group1\" through \"groupn\" for some n, which is the number of supplementary groups that the process has. Use the in operator to test for these elements. The following elements are guaranteed to be available:","PROCINFO[\"sorted_in\"]":"If this element exists in PROCINFO, then its value controls the order in which array elements are traversed in for loops. Supported values are \"@ind_str_asc\", \"@ind_num_asc\", \"@val_type_asc\", \"@val_str_asc\", \"@val_num_asc\", \"@ind_str_desc\", \"@ind_num_desc\", \"@val_type_desc\", \"@val_str_desc\", \"@val_num_desc\", and \"@unsorted\". The value can also be the name (as a string) of any comparison function defined as follows:\\nfunction cmp_func(i1, v1, i2, v2)\\nwhere i1 and i2 are the indices, and v1 and v2 are the corresponding values of the two elements being compared. It should return a number less than, equal to, or greater than 0, depending on how the elements of the array are to be ordered.","RT":"The record terminator. Gawk sets RT to the input text that matched the character or regular expression specified by RS.","PROCINFO[\"pid\"]":"The value of the getpid(2) system call.","PROCINFO[\"prec_min\"]":"The minimum precision allowed by the GNU MPFR library for arbitrary precision floating-point numbers.\\nThe following elements may set by a program to change gawk's behavior:","SYMTAB":"An array whose indices are the names of all currently defined global variables and arrays in the program. The array may be used for indirect access to read or write the value of a variable:\\nfoo = 5 SYMTAB[\"foo\"] = 4 print foo # prints 4\\nThe typeof() function may be used to test if an element in SYMTAB is an array. You may not use the delete statement with the SYMTAB array, nor assign to elements with an index that is not a variable name.","PROCINFO[\"FS\"]":"\"FS\" if field splitting with FS is in effect, \"FPAT\" if field splitting with FPAT is in effect, \"FIELDWIDTHS\" if field splitting with FIELDWIDTHS is in effect, or \"API\" if API input parser field splitting is in effect.","PROCINFO[\"egid\"]":"The value of the getegid(2) system call.","ENVIRON":"An array containing the values of the current environment. The array is indexed by the environment variables, each element being the value of that variable (e.g., ENVIRON[\"HOME\"] might be \"/home/arnold\").\\nIn POSIX mode, changing this array does not affect the environment seen by programs which gawk spawns via redirection or the system() function. Otherwise, gawk updates its real environment so that programs it spawns see the changes."},"io_statements":{"getline":"Set $0 from the next input record; set NF, NR, FNR, RT.","getline var <file":"Set var from the next record of file; set RT.","next":"Stop processing the current input record. Read the next input record and start processing over with the first pattern in the AWK program. Upon reaching the end of the input data, execute any END rule(s).","print expr-list >file":"Print expressions on file. Each expression is separated by the value of OFS. The output record is terminated with the value of ORS.","printf fmt, expr-list >file":"Format and print on file.","getline var":"Set var from the next input record; set NR, FNR, RT.","printf fmt, expr-list":"Format and print. See The printf Statement, below.","print ... |& command":"Send data to a coprocess or socket. (See also the subsection Special File Names, below.)","print":"Print the current record. The output record is terminated with the value of ORS.","print ... >> file":"Append output to the file.","getline <file":"Set $0 from the next record of file; set NF, RT.","command |& getline [var]":"Run command as a coprocess piping the output either into $0 or var, as above, and RT. Coprocesses are a gawk extension. (The command can also be a socket. See the subsection Special File Names, below.)","print expr-list":"Print expressions. Each expression is separated by the value of OFS. The output record is terminated with the value of ORS.","system(cmd-line)":"Execute the command cmd-line, and return the exit status. (This may not be available on non-POSIX systems.) See GAWK: Effective AWK Programming for the full details on the exit status.","print ... | command":"Write on a pipe.","fflush([file])":"Flush any buffers associated with the open output file or pipe file. If file is missing or if it is the null string, then flush all open output files and pipes.","command | getline [var]":"Run command, piping the output either into $0 or var, as above, and RT.","nextfile":"Stop processing the current input file. The next input record read comes from the next input file. Update FILENAME and ARGIND, reset FNR to 1, and start processing over with the first pattern in the AWK program. Upon reaching the end of the input data, execute any ENDFILE and END rule(s).","close(file [, how])":"Close file, pipe or coprocess. The optional how should only be used when closing one end of a two-way pipe to a coprocess. It must be a string value, either \"to\" or \"from\"."},"version":"5.1","patterns":{"ENDFILE":"BEGINFILE and ENDFILE are additional special patterns whose actions are executed before reading the first record of each command-line input file and after reading the last record of each file. Inside the BEGINFILE rule, the value of ERRNO is the empty string if the file was opened successfully. Otherwise, there is some problem with the file and the code should use nextfile to skip it. If that is not done, gawk produces its usual fatal error for files that cannot be opened.","BEGIN":"BEGIN and END are two special kinds of patterns which are not tested against the input. The action parts of all BEGIN patterns are merged as if all the statements had been written in a single BEGIN rule. They are executed before any of the input is read. Similarly, all the END rules are merged, and executed when all the input is exhausted (or when an exit statement is executed). BEGIN and END patterns cannot be combined with other patterns in pattern expressions. BEGIN and END patterns cannot have missing action parts.","END":"BEGIN and END are two special kinds of patterns which are not tested against the input. The action parts of all BEGIN patterns are merged as if all the statements had been written in a single BEGIN rule. They are executed before any of the input is read. Similarly, all the END rules are merged, and executed when all the input is exhausted (or when an exit statement is executed). BEGIN and END patterns cannot be combined with other patterns in pattern expressions. BEGIN and END patterns cannot have missing action parts.","BEGINFILE":"BEGINFILE and ENDFILE are additional special patterns whose actions are executed before reading the first record of each command-line input file and after reading the last record of each file. Inside the BEGINFILE rule, the value of ERRNO is the empty string if the file was opened successfully. Otherwise, there is some problem with the file and the code should use nextfile to skip it. If that is not done, gawk produces its usual fatal error for files that cannot be opened."}}