From 7e8f32c84caa4c2a99e4cea09fa25c5ae9722784 Mon Sep 17 00:00:00 2001 From: "Arnold D. Robbins" Date: Mon, 14 Nov 2011 21:42:42 +0200 Subject: Minor doc fixes in man page. --- doc/gawk.1 | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'doc/gawk.1') diff --git a/doc/gawk.1 b/doc/gawk.1 index 205eb389..e26f9a2e 100644 --- a/doc/gawk.1 +++ b/doc/gawk.1 @@ -14,7 +14,7 @@ . if \w'\(rq' .ds rq "\(rq . \} .\} -.TH GAWK 1 "May 29 2011" "Free Software Foundation" "Utility Commands" +.TH GAWK 1 "Nov 10 2011" "Free Software Foundation" "Utility Commands" .SH NAME gawk \- pattern scanning and processing language .SH SYNOPSIS @@ -782,7 +782,7 @@ each field is made up of text that matches that regular expression. In this case, the regular expression describes the fields themselves, instead of the text that separates the fields. Assigning a new value to -.BR FS +.B FS or .B FIELDWIDTHS overrides the use of @@ -2089,7 +2089,7 @@ Sends data to a co-process or socket. below.) .PP The -.BR getline +.B getline command returns 1 on success, 0 on end of file, and \-1 on an error. Upon an error, .B ERRNO @@ -2234,9 +2234,9 @@ For and .BR %X , supply a leading -.BR 0x +.B 0x or -.BR 0X +.B 0X for a nonzero result. For @@ -2517,7 +2517,7 @@ a second array if you wish to preserve the original. The purpose of the optional string .I how is the same as described in -.BR asort() +.B asort() above. .TP \fBgensub(\fIr\fB, \fIs\fB, \fIh \fR[\fB, \fIt\fR]\fB)\fR @@ -2589,7 +2589,7 @@ to get a literal (This must be typed as \fB"\e\e&"\fP; see \*(EP for a fuller discussion of the rules for -.BR &'s +.BR & 's and backslashes in the replacement text of .BR sub() , .BR gsub() , @@ -3275,7 +3275,7 @@ the array; the .BR \ea , and -.BR \ev +.B \ev escape sequences (done originally in .I gawk and fed back into the Bell Laboratories version); the -- cgit v1.2.3 From 73d24cae0db6cc817db209e5e1ea93b0733d1cca Mon Sep 17 00:00:00 2001 From: "Arnold D. Robbins" Date: Mon, 26 Dec 2011 23:39:48 +0200 Subject: The grand merge: dgawk and pgawk folded into gawk. --- doc/gawk.1 | 126 +++++++++++++++++++++++++++++++++---------------------------- 1 file changed, 68 insertions(+), 58 deletions(-) (limited to 'doc/gawk.1') diff --git a/doc/gawk.1 b/doc/gawk.1 index e26f9a2e..c171acbf 100644 --- a/doc/gawk.1 +++ b/doc/gawk.1 @@ -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. @@ -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,21 @@ the standard output. these options cause an immediate, successful exit.) .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 AWKPATH +environment variable. The suffix +.I .so +in the library name is optional, and +the library initialization routine is expected to be named +.BR dlload() . +.TP +.PD 0 .BR "\-L " [ \fIvalue\fR ] .TP .PD @@ -387,12 +394,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 +424,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 @@ -482,15 +500,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 @@ -3122,8 +3131,9 @@ 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. .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 @@ -3133,7 +3143,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 -- cgit v1.2.3 From 2c8f64a8d56bcede9e1dd08859b3b235fc9bd40f Mon Sep 17 00:00:00 2001 From: "Arnold D. Robbins" Date: Wed, 28 Dec 2011 18:12:52 +0200 Subject: Documentation updates. --- doc/gawk.1 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/gawk.1') diff --git a/doc/gawk.1 b/doc/gawk.1 index c171acbf..662ace35 100644 --- a/doc/gawk.1 +++ b/doc/gawk.1 @@ -97,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 = -- cgit v1.2.3 From 7ae469692932aae4a587f746dbff61c1d8b12eb9 Mon Sep 17 00:00:00 2001 From: john haque Date: Fri, 3 Feb 2012 09:20:53 -0600 Subject: Read timeout documentation and bug fix. --- doc/gawk.1 | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'doc/gawk.1') diff --git a/doc/gawk.1 b/doc/gawk.1 index 662ace35..eab20467 100644 --- a/doc/gawk.1 +++ b/doc/gawk.1 @@ -1129,6 +1129,14 @@ 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 +.I input +, where +.I input +is a redirection string or a filename. A value of zero or +less than zero means no timeout. +.TP \fBPROCINFO["version"]\fP the version of .IR gawk . @@ -3587,6 +3595,10 @@ and .B \-\^\-file options. .PP +The 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 -- cgit v1.2.3 From cd44d957787e162df4348028c22e8b9621000790 Mon Sep 17 00:00:00 2001 From: "Arnold D. Robbins" Date: Mon, 6 Feb 2012 21:40:45 +0200 Subject: Minor edits to John's changes. --- doc/gawk.1 | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'doc/gawk.1') diff --git a/doc/gawk.1 b/doc/gawk.1 index eab20467..07a8d0e3 100644 --- a/doc/gawk.1 +++ b/doc/gawk.1 @@ -1131,8 +1131,8 @@ 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 -.I input -, where +.IR input , +where .I input is a redirection string or a filename. A value of zero or less than zero means no timeout. @@ -3595,7 +3595,9 @@ and .B \-\^\-file options. .PP -The GAWK_READ_TIMEOUT environment variable can be used to specify a timeout +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 -- cgit v1.2.3