diff options
Diffstat (limited to 'doc/gawk.1')
| -rw-r--r-- | doc/gawk.1 | 184 |
1 files changed, 109 insertions, 75 deletions
@@ -13,7 +13,7 @@ . if \w'\(rq' .ds rq "\(rq . \} .\} -.TH GAWK 1 "Jan 27 2019" "Free Software Foundation" "Utility Commands" +.TH GAWK 1 "Feb 03 2019" "Free Software Foundation" "Utility Commands" .SH NAME gawk \- pattern scanning and processing language .SH SYNOPSIS @@ -51,7 +51,7 @@ The command line consists of options to itself, the \*(AK program text (if not supplied via the .B \-f or -.B \-i +.B \-\^\-include options), and values to be made available in the .B ARGC @@ -85,7 +85,9 @@ AWK source code and then prompts for debugging commands. .I Gawk can only debug AWK program source provided with the .B \-f -option. +and +.B \-\^\-include +options. The debugger is documented in \*(EP. .SH OPTION FORMAT .PP @@ -134,7 +136,7 @@ Multiple options may be used. Files read with .B \-f -are treated as if they begin with an implict \fB@namespace "awk"\fR statement. +are treated as if they begin with an implicit \fB@namespace "awk"\fR statement. .TP .PD 0 .BI \-F " fs" @@ -252,13 +254,13 @@ as \*(AK program source code. This option allows the easy intermixing of library functions (used via the .B \-f and -.B \-i +.B \-\^\-include options) with source code entered on the command line. It is intended primarily for medium to large \*(AK programs used in shell scripts. Each argument supplied via .B \-e -is treated as if it begins with an implict \fB@namespace "awk"\fR statement. +is treated as if it begins with an implicit \fB@namespace "awk"\fR statement. .TP .PD 0 .BI "\-E " file @@ -317,8 +319,8 @@ suffix. The file will be loaded only once (i.e., duplicates are eliminated), and the code does not constitute the main program source. Files read with -.B \-i -are treated as if they begin with an implict \fB@namespace "awk"\fR statement. +.B \-\^\-include +are treated as if they begin with an implicit \fB@namespace "awk"\fR statement. .TP .PD 0 .BI "\-l " lib @@ -361,7 +363,7 @@ actually invalid are issued. (This is not fully implemented yet.) Force arbitrary precision arithmetic on numbers. This option has no effect if .I gawk -is not compiled to use the GNU MPFR and MP libraries. +is not compiled to use the GNU MPFR and GMP libraries. (In such a case, .I gawk issues a warning.) @@ -419,7 +421,7 @@ is provided, uses a file named .B awkprof.out in the current directory. -Implies +This option implies .BR \-\^\-no\-optimize . .TP .PD 0 @@ -444,7 +446,7 @@ The default is .BR awkprof.out . The profile contains execution counts of each statement in the program in the left margin and function call counts for each user-defined function. -Implies +This option implies .BR \-\^\-no\-optimize . .TP .PD 0 @@ -502,7 +504,7 @@ Interval expressions were not traditionally available in the and .I egrep consistent with each other. -They are enabled by default, but this option remains for use with +They are enabled by default, but this option remains for use together with .BR \-\^\-traditional . .TP .PD 0 @@ -623,14 +625,14 @@ In addition, lines beginning with may be used to include other source files into your program, making library use even easier. This is equivalent to using the -.B \-i +.B \-\^\-include option. .PP Lines beginning with .B @load may be used to load extension functions into your program. This is equivalent to using the -.B \-l +.B \-\^\-load option. .PP The environment variable @@ -639,7 +641,7 @@ specifies a search path to use when finding source files named with the .B \-f and -.B \-i +.B \-\^\-include options. If this variable does not exist, the default path is \fB".:/usr/local/share/awk"\fR. (The actual directory may vary, depending upon how @@ -653,7 +655,7 @@ The environment variable .B AWKLIBPATH specifies a search path to use when finding source files named with the -.B \-l +.B \-\^\-load option. If this variable does not exist, the default path is \fB"/usr/local/lib/gawk"\fR. (The actual directory may vary, depending upon how @@ -862,7 +864,8 @@ Each field in the input record may be referenced by its position: .BR $2 , and so on. .B $0 -is the whole record. +is the whole record, +including leading and trailing whitespace. Fields need not be referenced by constants: .RS .PP @@ -881,7 +884,7 @@ is set to the total number of fields in the input record. .PP References to non-existent fields (i.e., fields after .BR $NF ) -produce the null-string. However, assigning to a non-existent field +produce the null string. However, assigning to a non-existent field (e.g., .BR "$(NF+2) = 5" ) increases the value of @@ -1020,9 +1023,9 @@ When set, .I gawk parses the input into fields, where the fields match the regular expression, instead of using the -value of the +value of .B FS -variable as the field separator. +as the field separator. See .BR Fields , above. @@ -1199,7 +1202,7 @@ The identifier is a built-in function. The identifier is an extension function loaded via .B @load or -.BR \-l . +.BR \-\^\-load . .TP \fB"scalar"\fR The identifier is a scalar. @@ -1213,40 +1216,49 @@ doesn't know yet). The identifier is a user-defined function. .RE .TP +\fBPROCINFO["pgrpid"]\fP +The value of the +.IR getpgrp (2) +system call. +.TP +\fBPROCINFO["pid"]\fP +The value of the +.IR getpid (2) +system call. +.TP \fBPROCINFO["platform"]\fP A string indicating the platform for which .I gawk was compiled. It is one of: .RS .TP -\fB"vms"\fR -OpenVMS or Vax/VMS. +\fB"cygwin"\fR, \fB"djgpp"\fR, \fB"mingw"\fR +Microsoft Windows, using either Cygwin, DJGPP, or MinGW, respectively. .TP \fB"macosx"\fR Mac OS X. .TP -\fB"cygwin"\fR, \fB"djgpp"\fR, \fB"mingw"\fR -Microsoft Windows, using either Cygwin, DJGPP, or MinGW, respectively. -.TP \fB"os2"\fR OS/2. .TP \fB"posix"\fR GNU/Linux and legacy Unix systems. -.RE -.TP -\fBPROCINFO["pgrpid"]\fP -The process group ID of the current process. .TP -\fBPROCINFO["pid"]\fP -The process ID of the current process. +\fB"vms"\fR +OpenVMS or Vax/VMS. +.RE .TP \fBPROCINFO["ppid"]\fP -The parent process ID of the current process. +The value of the +.IR getppid (2) +system call. .TP \fBPROCINFO["strftime"]\fP The default time format string for .BR strftime() . +Changing its value affects how +.B strftime() +formats time values when called with no arguments. .TP \fBPROCINFO["uid"]\fP The value of the @@ -1254,7 +1266,7 @@ The value of the system call. .TP \fBPROCINFO["version"]\fP -the version of +The version of .IR gawk . .PP The following elements are present if loading dynamic @@ -1271,7 +1283,7 @@ compiled into .IR gawk\^ : .TP \fBPROCINFO["gmp_version"]\fP -The version of the GNU MP library used for arbitrary precision +The version of the GNU GMP library used for arbitrary precision number support in .IR gawk . .TP @@ -1328,7 +1340,7 @@ An I/O error that may be retried is one where has the value EAGAIN, EWOULDBLOCK, EINTR, or ETIMEDOUT. This may be useful in conjunction with \fBPROCINFO["\fIinput\^\fB", "READ_TIMEOUT"]\fR -or situations where a file descriptor has been configured to behave in a +or in situations where a file descriptor has been configured to behave in a non-blocking fashion. .TP \fBPROCINFO["sorted_in"]\fP @@ -1377,13 +1389,26 @@ depending on how the elements of the array are to be ordered. .B ROUNDMODE The rounding mode to use for arbitrary precision arithmetic on numbers, by default \fB"N"\fR (IEEE-754 roundTiesToEven mode). -The accepted values are -\fB"N"\fR or \fB"n"\fR for roundTiesToEven, -\fB"U"\fR or \fB"u"\fR for roundTowardPositive, -\fB"D"\fR or \fB"d"\fR for roundTowardNegative, -\fB"Z"\fR or \fB"z"\fR for roundTowardZero, -and if your version of GNU MPFR library supports it, -\fB"A"\fR or \fB"a"\fR for rounding away from zero. +The accepted values are: +.RS +.TP +\fB"A"\fR or \fB"a"\fR +for rounding away from zero. +This one is only available if your version of +the GNU MPFR library supports it. +.TP "\w'\fB\(dqD\(dq\fR or \fB\(dqd\(dq\fR'u+1n" +\fB"D"\fR or \fB"d"\fR +for roundTowardNegative. +.TP +\fB"N"\fR or \fB"n"\fR +for roundTiesToEven. +.TP +\fB"U"\fR or \fB"u"\fR +for roundTowardPositive. +.TP +\fB"Z"\fR or \fB"z"\fR +for roundTowardZero. +.RE .TP .B RS The input record separator, by default a newline. @@ -1409,7 +1434,7 @@ The length of the string matched by \-1 if no match. .TP .B SUBSEP -The character used to separate multiple subscripts in array +The string used to separate multiple subscripts in array elements, by default \fB"\e034"\fR. .TP .B SYMTAB @@ -1547,7 +1572,7 @@ identifier is the variable within it. All simple (non-qualified) names are considered to be in the ``current'' namespace; the default namespace is .BR awk . -However, simple identifiers consisting solely of upper-case +However, simple identifiers consisting solely of uppercase letters are forced into the .B awk namespace, even if the current namespace is different. @@ -1828,8 +1853,8 @@ patterns cannot have missing action parts. .B BEGINFILE and .B ENDFILE -are additional special patterns whose bodies are executed -before reading the first record of each command line input file +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 .B BEGINFILE @@ -1909,6 +1934,7 @@ Matches the end of a string. A character list: matches any of the characters .IR abc.\|.\|. . You may include a range of characters by separating them with a dash. +To include a literal dash in the list, put it first or last. .TP \fB[^\fIabc.\|.\|.\fB]\fR A negated character list: matches any character except @@ -2308,7 +2334,7 @@ It must be a string value, either .B getline Set .B $0 -from next input record; set +from the next input record; set .BR NF , .BR NR , .BR FNR , @@ -2317,7 +2343,7 @@ from next input record; set .BI "getline <" file Set .B $0 -from next record of +from the next record of .IR file ; set .BR NF , @@ -2326,7 +2352,7 @@ set .BI getline " var" Set .I var -from next input record; set +from the next input record; set .BR NR , .BR FNR , .BR RT . @@ -2334,14 +2360,14 @@ from next input record; set .BI getline " var" " <" file Set .I var -from next record of +from the next record of .IR file ; set .BR RT . .TP \fIcommand\fB | getline \fR[\fIvar\fR] Run -.I command +.IR command , piping the output either into .B $0 or @@ -2362,34 +2388,34 @@ as above, and Coprocesses are a .I gawk extension. -.RI ( command +.RI "(The " command can also be a socket. See the subsection .BR "Special File Names" , below.) .TP .B next -Stop processing the current input record. The next input record -is read and processing starts over with the first pattern in the +Stop processing the current input record. +Read the next input record +and start processing over with the first pattern in the \*(AK program. Upon reaching the end of the input data, -.I gawk -executes any +execute any .B END rule(s). .TP .B "nextfile" Stop processing the current input file. The next input record read comes from the next input file. +Update .B FILENAME and -.B ARGIND -are updated, +.BR ARGIND , +reset .B FNR -is reset to 1, and processing starts over with the first pattern in the +to 1, and start processing over with the first pattern in the \*(AK program. Upon reaching the end of the input data, -.I gawk -executes any +execute any .B ENDFILE and .B END @@ -2445,14 +2471,14 @@ and .BR printf . .TP .BI "print .\|.\|. >>" " file" -Appends output to the +Append output to the .IR file . .TP .BI "print .\|.\|. |" " command" -Writes on a pipe. +Write on a pipe. .TP .BI "print .\|.\|. |&" " command" -Sends data to a coprocess or socket. +Send data to a coprocess or socket. (See also the subsection .BR "Special File Names" , below.) @@ -2685,8 +2711,9 @@ of significant digits. For the and .B %X formats, it specifies the minimum number of -digits to print. For -.BR %s , +digits to print. For the +.B %s +format, it specifies the maximum number of characters from the string that should be printed. .PP @@ -2796,6 +2823,9 @@ to force an IPv6 connection. Plain .B /inet uses the system default (most likely IPv4). +Usable only with the +.B |& +two-way I/O operator. .TP .PD 0 .BI /inet/udp/ lport / rhost / rport @@ -3355,15 +3385,15 @@ Return the bitwise XOR of the values provided in the argument list. There must be at least two. .PP .SS Type Functions -The following function is for use with multidimensional arrays. +The following functions provide type related information about +their arguments. .TP \fBisarray(\fIx\fB)\fR Return true if .I x is an array, false otherwise. -.PP -You can tell the type of any variable or array element with the -following function: +This function is mainly for use with the elements of multidimensional arrays +and with function parameters. .TP \fBtypeof(\fIx\fB)\fR Return a string indicating the type of @@ -3676,7 +3706,7 @@ was changed to match its documentation, the .B \-v option for assigning variables before program execution was added to accommodate applications that depended upon the old behavior. -(This feature was agreed upon by both the Bell Laboratories +(This feature was agreed upon by both the Bell Laboratories developers and the \*(GN developers.) .PP When processing arguments, @@ -4008,7 +4038,7 @@ environment variable can be used to provide a list of directories that .I gawk searches when looking for files named via the .BR \-f , -.RB \-\^\-file , +.BR \-\^\-file , .B \-i and .B \-\^\-include @@ -4039,7 +4069,7 @@ For connection to a remote host via socket, .B GAWK_SOCK_RETRIES controls the number of retries, and .B GAWK_MSEC_SLEEP -and the interval between retries. +the interval between retries. The interval is in milliseconds. On systems that do not support .IR usleep (3), the value is rounded up to an integral number of seconds. @@ -4152,7 +4182,11 @@ post a bug report in While the .I gawk developers occasionally read this newsgroup, posting bug reports there -is an unreliable way to report bugs. Instead, please use the electronic mail +is an unreliable way to report bugs. +Similarly, do +.B NOT +use a web forum (such as Stack Overflow) for reporting bugs. +Instead, please use the electronic mail addresses given above. Really. .PP |