diff options
Diffstat (limited to 'doc/gawk.1')
| -rw-r--r-- | doc/gawk.1 | 347 |
1 files changed, 250 insertions, 97 deletions
@@ -33,30 +33,6 @@ gawk \- pattern scanning and processing language ] .I program-text file .\|.\|. -.sp -.B pgawk -[ \*(PX or \*(GN style options ] -.B \-f -.I program-file -[ -.B \-\^\- -] file .\|.\|. -.br -.B pgawk -[ \*(PX or \*(GN style options ] -[ -.B \-\^\- -] -.I program-text -file .\|.\|. -.sp -.B dgawk -[ \*(PX or \*(GN style options ] -.B \-f -.I program-file -[ -.B \-\^\- -] file .\|.\|. .SH DESCRIPTION .I Gawk is the \*(GN Project's implementation of the \*(AK programming language. @@ -84,27 +60,31 @@ and .B ARGV pre-defined \*(AK variables. .PP -.I Pgawk -is the profiling version of -.IR gawk . -It is identical in every way to -.IR gawk , -except that programs run more slowly, -and it automatically produces an execution profile in the file +When +.I gawk +is invoked with the +.B \-\^\-profile +option, it starts gathering profiling statistics +from the execution of the program. +.I Gawk +runs more slowly in this mode, and automatically produces an execution +profile in the file .B awkprof.out when done. See the .B \-\^\-profile option, below. .PP -.I Dgawk -is an -.I awk -debugger. Instead of running the program directly, it loads the +.I Gawk +also has an integrated debugger. An interactive debugging session can +be started by supplying the +.B \-\^\-debug +option to the command line. In this mode of execution, +.I gawk +loads the AWK source code and then prompts for debugging commands. -Unlike -.IR gawk " and " pgawk ", " dgawk -only processes AWK program source provided with the +.I Gawk +can only debug AWK program source provided with the .B \-f option. The debugger is documented in \*(EP. @@ -117,8 +97,8 @@ while long options start with \*(lq\-\^\-\*(rq. Long options are provided for both \*(GN-specific features and for \*(PX-mandated features. .PP -.IR Gawk - -specific options are typically used in long-option form. +.IR Gawk -specific +options are typically used in long-option form. Arguments to long options are either joined with the option by an .B = @@ -273,6 +253,18 @@ names like and so on.) .TP .PD 0 +\fB\-D\fR[\fIfile\fR] +.TP +.PD +\fB\-\^\-debug\fR[\fB=\fIfile\fR] +Enable debugging of \*(AK programs. +By default, the debugger reads commands interactively from the terminal. +The optional +.IR file +argument can be used to specify a file with a list +of commands for the debugger to execute non-interactively. +.TP +.PD 0 .BI "\-e " program-text .TP .PD @@ -331,6 +323,33 @@ the standard output. these options cause an immediate, successful exit.) .TP .PD 0 +.BI "\-i " include-file +.TP +.PD +.BI \-\^\-include " include-file" +Load an awk source library. +This searches for the library using the +.B 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 eliminated), and the code does not constitute +the main program source. +.TP +.PD 0 +.BI "\-l " lib +.TP +.PD +.BI \-\^\-load " lib" +Load a shared library +.IR lib . +This searches for the library using the +.B AWKLIBPATH +environment variable. If the initial search fails, another attempt will +be made after appending the default shared library suffix for the platform. +The library initialization routine is expected to be named +.BR dl_load() . +.TP +.PD 0 .BR "\-L " [ \fIvalue\fR ] .TP .PD @@ -348,6 +367,16 @@ only warnings about things that are actually invalid are issued. (This is not fully implemented yet.) .TP .PD 0 +.B \-M +.TP +.PD +.B \-\^\-bignum +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. +.TP +.PD 0 .B \-n .TP .PD @@ -387,12 +416,28 @@ users. .. .TP .PD 0 +\fB\-o\fR[\fIfile\fR] +.TP +.PD +\fB\-\^\-pretty-print\fR[\fB=\fIfile\fR] +Output a pretty printed version of the program to +.IR file . +If no +.I file +is provided, +.I gawk +uses a file named +.B awkprof.out +in the current directory. +.TP +.PD 0 .B \-O .TP .PD .B \-\^\-optimize Enable optimizations upon the internal representation of the program. -Currently, this includes just simple constant-folding. The +Currently, this includes simple constant-folding, and tail call +elimination for recursive functions. The .I gawk maintainer hopes to add additional optimizations over time. .TP @@ -401,16 +446,11 @@ maintainer hopes to add additional optimizations over time. .TP .PD \fB\-\^\-profile\fR[\fB=\fIprof_file\fR] -Send profiling data to +Start a profiling session, and send the profiling data to .IR prof_file . The default is .BR awkprof.out . -When run with -.IR gawk , -the profile is just a \*(lqpretty printed\*(rq version of the program. -When run with -.IR pgawk , -the profile contains execution counts of each statement in the program +The profile contains execution counts of each statement in the program in the left margin and function call counts for each user-defined function. .TP .PD 0 @@ -477,15 +517,6 @@ They are enabled by default, but this option remains for use with .BR \-\^-traditional . .TP .PD 0 -.B \-R -.TP -.PD -.BI \-\^\-command " file" -.I Dgawk -only. Read stored debugger commands from -.IR file . -.TP -.PD 0 .BI \-S .TP .PD @@ -550,6 +581,9 @@ and optional function definitions. .RS .PP \fB@include "\fIfilename\fB" +.br +\fB@load "\fIfilename\fB" +.br \fIpattern\fB { \fIaction statements\fB }\fR .br \fBfunction \fIname\fB(\fIparameter list\fB) { \fIstatements\fB }\fR @@ -581,12 +615,21 @@ In addition, lines beginning with may be used to include other source files into your program, making library use even easier. .PP +Lines beginning with +.B @load +may be used to load shared libraries into your program. This is equivalent +to using the +.B \-l +option. +.PP The environment variable .B AWKPATH specifies a search path to use when finding source files named with the .B \-f -option. If this variable does not exist, the default path is +and +.B \-i +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 .I gawk @@ -941,6 +984,17 @@ The input field separator, a space by default. See .BR Fields , above. .TP +.B FUNCTAB +An array whose indices are the names of all the user-defined +or extension functions in the program. +.BR NOTE : +The array values cannot currently be used. +Also, you may not use the +.B delete +statment with the +.B FUNCTAB +array. +.TP .B IGNORECASE Controls the case-sensitivity of all regular expression and string operations. If @@ -1017,6 +1071,10 @@ The output field separator, a space by default. .B ORS The output record separator, by default a newline. .TP +.B PREC +The working precision of arbitrary precision floating-point +numbers, 53 by default. +.TP .B PROCINFO The elements of this array provide access to information about the running \*(AK program. @@ -1056,6 +1114,35 @@ or \fB"FIELDWIDTHS"\fP if field splitting with .B FIELDWIDTHS is in effect. .TP +\fBPROCINFO["identifiers"]\fP +A subarray, indexed by the names of all identifiers used in the +text of the AWK program. For each identifier, the value of the element is one of the following: +.RS +.TP +\fB"array"\fR +The identifier is an array. +.TP +\fB"extension"\fR +The identifier is an extension function loaded via +.BR @load . +.TP +\fB"scalar"\fR +The identifier is a scalar. +.TP +\fB"untyped"\fR +The identifier is untyped (could be used as a scalar or array, +.I gawk +doesn't know yet). +.TP +\fB"user"\fR +The identifier is a user-defined function. +.RE +The values indicate what +.I gawk +knows about the identifiers after it has finished parsing the program; they are +.I not +updated while the program runs. +.TP \fBPROCINFO["gid"]\fP the value of the .IR getgid (2) @@ -1115,11 +1202,48 @@ 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. .TP +\fBPROCINFO["input", "READ_TIMEOUT"]\fP +specifies the timeout in milliseconds for reading data from +.IR input , +where +.I input +is a redirection string or a filename. A value of zero or +less than zero means no timeout. +.TP +\fBPROCINFO["mpfr_version"]\fP +the version of the GNU MPFR library used for arbitrary precision +number support in +.IR gawk . +.TP +\fBPROCINFO["gmp_version"]\fP +the version of the GNU MP library used for arbitrary precision +number support in +.IR gawk . +.TP +\fBPROCINFO["prec_max"]\fP +the maximum precision supported by the GNU MPFR library for +arbitrary precision floating-point numbers. +.TP +\fBPROCINFO["prec_min"]\fP +the minimum precision allowed by the GNU MPFR library for +arbitrary precision floating-point numbers. +.TP \fBPROCINFO["version"]\fP the version of .IR gawk . .RE .TP +.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 roundTiesToAway. +.TP .B RS The input record separator, by default a newline. .TP @@ -1147,6 +1271,30 @@ The length of the string matched by The character used to separate multiple subscripts in array elements, by default \fB"\e034"\fR. .TP +.B 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: +.PP +.RS +.ft B +foo = 5 +SYMTAB["foo"] = 4 +print foo # prints 4 +.ft R +.RE +.PP +The +.B isarray() +function may be used to test if an element in +.B SYMTAB +is an array. +You may not use the +.B delete +statment with the +.B SYMTAB +array. +.TP .B TEXTDOMAIN The text domain of the \*(AK program; used to find the localized translations for the program's strings. @@ -2886,11 +3034,9 @@ integers, doing the operation, and then converting the result back to floating point. The functions are: .TP "\w'\fBrshift(\fIval\fB, \fIcount\fB)\fR'u+2n" -\fBand(\fIv1\fB, \fIv2\fB)\fR -Return the bitwise AND of the values provided by -.I v1 -and -.IR v2 . +\fBand(\fIv1\fB, \fIv2 \fR[, ...]\fB)\fR +Return the bitwise AND of the values provided in the argument list. +There must be at least two. .TP \fBcompl(\fIval\fB)\fR Return the bitwise complement of @@ -2903,11 +3049,9 @@ shifted left by .I count bits. .TP -\fBor(\fIv1\fB, \fIv2\fB)\fR -Return the bitwise OR of the values provided by -.I v1 -and -.IR v2 . +\fBor(\fIv1\fB, \fIv2 \fR[, ...]\fB)\fR +Return the bitwise OR of the values provided in the argument list. +There must be at least two. .TP \fBrshift(\fIval\fB, \fIcount\fB)\fR Return the value of @@ -2916,11 +3060,9 @@ shifted right by .I count bits. .TP -\fBxor(\fIv1\fB, \fIv2\fB)\fR -Return the bitwise XOR of the values provided by -.I v1 -and -.IR v2 . +\fBxor(\fIv1\fB, \fIv2 \fR[, ...]\fB)\fR +Return the bitwise XOR of the values provided in the argument list. +There must be at least two. .PP .SS Type Function The following function is for use with multidimensional arrays. @@ -3096,27 +3238,15 @@ may be used in place of .SH DYNAMICALLY LOADING NEW FUNCTIONS You can dynamically add new built-in functions to the running .I gawk -interpreter. +interpreter with the +.B @load +statement. The full details are beyond the scope of this manual page; -see \*(EP for the details. -.PP -.TP 8 -\fBextension(\fIobject\fB, \fIfunction\fB)\fR -Dynamically link the shared object file named by -.IR object , -and invoke -.I function -in that object, to perform initialization. -These should both be provided as strings. -Return the value returned by -.IR function . -.PP -Using this feature at the C level is not pretty, but -it is unlikely to go away. Additional mechanisms may -be added at some point. +see \*(EP. .SH SIGNALS -.I pgawk -accepts two signals. +The +.I gawk +profiler accepts two signals. .B SIGUSR1 causes it to dump a profile and function call stack to the profile file, which is either @@ -3126,7 +3256,7 @@ or whatever file was named with the option. It then continues to run. .B SIGHUP causes -.I pgawk +.I gawk to dump the profile and function call stack and then exit. .SH INTERNATIONALIZATION .PP @@ -3559,10 +3689,31 @@ environment variable can be used to provide a list of directories that .I gawk searches when looking for files named via the .B \-f -and +, .B \-\^\-file +, +.B \-i +and +.B \-\^\-include +options. If the initial search fails, the path is searched again after +appending ".awk" to the filename. +.PP +The +.B AWKLIBPATH +environment variable can be used to provide a list of directories that +.I gawk +searches when looking for files named via the +.B \-l +and +.B \-\^\-load options. .PP +The +.B GAWK_READ_TIMEOUT +environment variable can be used to specify a timeout +in milliseconds for reading input from a terminal, pipe +or two-way communication including sockets. +.PP For socket communication, two special environment variables can be used to control the number of retries .RB ( GAWK_SOCK_RETRIES ), and the interval between retries @@ -3613,7 +3764,7 @@ status is 2. On non-POSIX systems, this value may be mapped to .SH VERSION INFORMATION This man page documents .IR gawk , -version 4.0. +version 4.1. .SH AUTHORS The original version of \*(UX .I awk @@ -3691,6 +3842,7 @@ While the developers occasionally read this newsgroup, posting bug reports there is an unreliable way to report bugs. Instead, please use the electronic mail addresses given above. +Really. .PP If you're using a GNU/Linux or BSD-based system, you may wish to submit a bug report to the vendor of your distribution. @@ -3710,6 +3862,7 @@ are surprisingly difficult to diagnose in the completely general case, and the effort to do so really is not worth it. .SH SEE ALSO .IR egrep (1), +.IR sed (1), .IR getpid (2), .IR getppid (2), .IR getpgrp (2), @@ -3725,7 +3878,7 @@ Alfred V. Aho, Brian W. Kernighan, Peter J. Weinberger, Addison-Wesley, 1988. ISBN 0-201-07981-X. .PP \*(EP, -Edition 4.0, shipped with the +Edition 4.1, shipped with the .I gawk source. The current version of this document is available online at @@ -3772,7 +3925,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 +2010, 2011, 2012 Free Software Foundation, Inc. .PP Permission is granted to make and distribute verbatim copies of |