diff options
Diffstat (limited to 'doc/gawk.1')
| -rw-r--r-- | doc/gawk.1 | 170 |
1 files changed, 141 insertions, 29 deletions
@@ -13,7 +13,7 @@ . if \w'\(rq' .ds rq "\(rq . \} .\} -.TH GAWK 1 "Mar 7 2016" "Free Software Foundation" "Utility Commands" +.TH GAWK 1 "Jun 30 2016" "Free Software Foundation" "Utility Commands" .SH NAME gawk \- pattern scanning and processing language .SH SYNOPSIS @@ -405,17 +405,20 @@ is provided, uses a file named .B awkprof.out in the current directory. +Implies +.BR \-\^\-no\-optimize . .TP .PD 0 .B \-O .TP .PD .B \-\^\-optimize -Enable optimizations upon the internal representation of the program. +Enable +.IR gawk 's +default optimizations upon the internal representation of the program. Currently, this includes simple constant-folding, and tail call -elimination for recursive functions. The -.I gawk -maintainer hopes to add additional optimizations over time. +elimination for recursive functions. +This option is on by default. .TP .PD 0 \fB\-p\fR[\fIprof-file\fR] @@ -428,6 +431,8 @@ 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 +.BR \-\^\-no\-optimize . .TP .PD 0 .B \-P @@ -444,11 +449,6 @@ mode, with the following additional restrictions: escape sequences are not recognized. .TP \(bu -Only space and tab act as field separators when -.B FS -is set to a single space, newline does not. -.TP -\(bu You cannot continue lines after .B ? and @@ -493,6 +493,15 @@ They are enabled by default, but this option remains for use with .BR \-\^\-traditional . .TP .PD 0 +.B \-s +.TP +.PD +.B \-\^\-no\-optimize +Disable +.IR gawk 's +default optimizations upon the internal representation of the program. +.TP +.PD 0 .BI \-S .TP .PD @@ -785,9 +794,6 @@ In the special case that .B FS is a single space, fields are separated by runs of spaces and/or tabs and/or newlines. -(But see the section -.BR "POSIX COMPATIBILITY" , -below). .BR NOTE : The value of .B IGNORECASE @@ -799,10 +805,13 @@ is a regular expression. .PP If the .B FIELDWIDTHS -variable is set to a space separated list of numbers, each field is +variable is set to a space-separated list of numbers, each field is expected to have fixed width, and .I gawk -splits up the record using the specified widths. The value of +splits up the record using the specified widths. +Each field width may optionally be preceded by a colon-separated +value specifying the number of characters to skip before the field starts. +The value of .B FS is ignored. Assigning a new value to @@ -918,11 +927,17 @@ 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., \fBENVIRON["HOME"]\fP might be \fB"/home/arnold"\fR). -Changing this array does not affect the environment seen by programs which +.sp +In POSIX mode, +changing this array does not affect the environment seen by programs which .I gawk spawns via redirection or the .B system() function. +Otherwise, +.I gawk +updates its real environment so that programs it spawns see +the changes. .TP .B ERRNO If a system error occurs either doing a redirection for @@ -936,14 +951,25 @@ then will contain a string describing the error. The value is subject to translation in non-English locales. +If the string in +.B ERRNO +corresponds to a system error in the +.IR errno (3) +variable, then the numeric value can be found in +.B PROCINFO["errno"]. +For non-system errors, +.B PROCINFO["errno"] +will be zero. .TP .B FIELDWIDTHS -A whitespace separated list of field widths. When set, +A whitespace-separated list of field widths. When set, .I gawk parses the input into fields of fixed width, instead of using the value of the .B 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 .BR Fields , above. @@ -1093,6 +1119,13 @@ The value of the .IR getegid (2) system call. .TP +\fBPROCINFO["errno"]\fP +The value of +.IR errno (3) +when +.BR ERRNO +is set to the associated error message. +.TP \fBPROCINFO["euid"]\fP The value of the .IR geteuid (2) @@ -1105,8 +1138,10 @@ is in effect, \fB"FPAT"\fP if field splitting with .B FPAT is in effect, -or \fB"FIELDWIDTHS"\fP if field splitting with +\fB"FIELDWIDTHS"\fP if field splitting with .B FIELDWIDTHS +is in effect, +or \fB"API"\fP if API input parser field splitting is in effect. .TP \fBPROCINFO["gid"]\fP @@ -1124,7 +1159,7 @@ knows about the identifiers after it has finished parsing the program; they are updated while the program runs. For each identifier, the value of the element is one of the following: .RS -.TP +.TP \w'\fB"extension"\fR'u+1n \fB"array"\fR The identifier is an array. .TP @@ -1207,6 +1242,14 @@ change .IR gawk 's behavior: .TP +\fBPROCINFO["NONFATAL"]\fR +If this exists, then I/O errors for all output redirections become nonfatal. +.TP +\fBPROCINFO["\fIoutput_name\fB", "NONFATAL"]\fR +Make output errors for +.I output_name +be nonfatal. +.TP \fBPROCINFO["\fIcommand\fB", "pty"]\fR Use a pseudo-tty for two-way communication with .I command @@ -1220,6 +1263,23 @@ where is a redirection string or a filename. A value of zero or less than zero means no timeout. .TP +\fBPROCINFO["\fIinput\^\fB", "RETRY"]\fR +If an I/O error that may be retried occurs when reading data from +.IR input , +and this array entry exists, then +.B getline +will return \-2 instead of following the default behavior of returning \-1 +and configuring +.IR input +to return no further data. +An I/O error that may be retried is one where +.IR errno (3) +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 +non-blocking fashion. +.TP \fBPROCINFO["sorted_in"]\fP If this element exists in .BR PROCINFO , @@ -1240,7 +1300,9 @@ Supported values are \fB"@val_num_desc"\fR, and \fB"@unsorted"\fR. -The value can also be the name of any comparison function defined +The value can also be the name (as a +.IR string ) +of any comparison function defined as follows: .sp .in +5m @@ -1544,9 +1606,9 @@ Vertical tab. The character represented by the string of hexadecimal digits following the .BR \ex . -As in ISO C, all following hexadecimal digits are considered part of +Up to two +following hexadecimal digits are considered part of the escape sequence. -(This feature should tell us something about language design by committee.) E.g., \fB"\ex1B"\fR is the \s-1ASCII\s+1 \s-1ESC\s+1 (escape) character. .TP .BI \e ddd @@ -2291,6 +2353,13 @@ below.) The .B getline command returns 1 on success, 0 on end of file, and \-1 on an error. +If the +.IR errno (3) +value indicates that the I/O operation may be retried, +and \fBPROCINFO["\fIinput\^\fP", "RETRY"]\fR +is set, then \-2 will be returned instead of \-1, and further calls to +.B getline +may be attempted. Upon an error, .B ERRNO is set to a string describing the problem. @@ -2643,6 +2712,23 @@ The exponential function. .BI int( expr ) Truncate to integer. .TP +.BI intdiv( num ", " denom ", " result ) +Truncate +.I num +and +.I denom +to integers. Return the quotient of +.I num +divided by +.I denom +in \fIresult\fB["quotient"]\fR +and the remainder in +in \fIresult\fB["remainder"]\fR. +This is a +.I gawk +extension, primarily of value when working with +arbitrarily large integers. +.TP .BI log( expr ) The natural logarithm function. .TP @@ -2891,9 +2977,11 @@ that matched .IR r . The value of .BI seps[ i ] -is the separator that appeared in -front of -.BI a[ i +1]\fR. +is the possibly null separator that appeared after +.BI a[ i ]\fR. +The value of +.B seps[0] +is the possibly null leading separator. \&\fRIf .I r is omitted, @@ -3026,7 +3114,7 @@ provides the following functions for obtaining time stamps and formatting them. .PP .TP "\w'\fBsystime()\fR'u+1n" -\fBmktime(\fIdatespec\fB)\fR +\fBmktime(\fIdatespec\fR [\fB, \fIutc-flag\fR]\fB)\fR Turn .I datespec into a time stamp of the same form as returned by @@ -3048,7 +3136,11 @@ 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. -The time is assumed to be in the local timezone. +If +.I 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 daylight saving flag is positive, the time is assumed to be daylight saving time; if zero, the time is assumed to be standard time; @@ -3102,6 +3194,11 @@ values to .B uintmax_t integers, doing the operation, and then converting the result back to floating point. +.PP +.BR NOTE : +Passing negative operands to any of these functions causes +a fatal error. +.PP The functions are: .TP "\w'\fBrshift(\fIval\fB, \fIcount\fB)\fR'u+2n" \fBand(\fIv1\fB, \fIv2 \fR[, ...]\fB)\fR @@ -3134,13 +3231,28 @@ bits. Return the bitwise XOR of the values provided in the argument list. There must be at least two. .PP -.SS Type Function +.SS Type Functions The following function is for use with multidimensional arrays. .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: +.TP +\fBtypeof(\fIx\fB)\fR +Return a string indicating the type of +.IR x . +The string will be one of +\fB"array"\fP, +\fB"number"\fP, +\fB"regexp"\fP, +\fB"string"\fP, +\fB"strnum"\fP, +or +\fB"undefined"\fP. .SS Internationalization Functions The following functions may be used from within your AWK program for translating strings at run-time. @@ -3987,7 +4099,7 @@ We thank him. .SH COPYING PERMISSIONS Copyright \(co 1989, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002, 2003, 2004, 2005, 2007, 2009, -2010, 2011, 2012, 2013, 2014, 2016 +2010, 2011, 2012, 2013, 2014, 2015, 2016 Free Software Foundation, Inc. .PP Permission is granted to make and distribute verbatim copies of |