diff options
| -rw-r--r-- | doc/ChangeLog | 6 | ||||
| -rw-r--r-- | doc/gawk.info | 402 | ||||
| -rw-r--r-- | doc/gawk.texi | 63 | ||||
| -rw-r--r-- | doc/gawktexi.in | 63 |
4 files changed, 363 insertions, 171 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index d4e8ad23..713d03b7 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,9 @@ +2015-06-30 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in (Limitations): Document that sometimes the + debugger can affect the program being run. + Thanks to Hermann Peifer for the test case. + 2015-06-26 Arnold D. Robbins <arnold@skeeve.com> * gawktexi.in: Update description of values returned by typeof. diff --git a/doc/gawk.info b/doc/gawk.info index 5b756d9e..9a6b291f 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -21860,6 +21860,62 @@ some limitations. A few that it's worth being aware of are: * The 'gawk' debugger only accepts source code supplied with the '-f' option. + One other point is worth disucssing. Conventional debuggers run in a +separate process (and thus address space) from the programs that they +debug (the "debuggee", if you will). + + The 'gawk' debugger is different; it is an integrated part of 'gawk' +itself. This makes it possible, in rare cases, for 'gawk' to become an +excellent demonstrator of Heisenburg Uncertainty physics, where the mere +act of observing something can change it. Consider the following:(1) + + $ cat test.awk + -| { print typeof($1), typeof($2) } + $ cat test.data + -| abc 123 + $ gawk -f test.awk test.data + -| strnum strnum + + This is all as expected: field data has the STRNUM attribute (*note +Variable Typing::). Now watch what happens when we run this program +under the debugger: + + $ gawk -D -f test.awk test.data + gawk> w $1 Set watchpoint on $1 + -| Watchpoint 1: $1 + gawk> w $2 Set watchpoint on $2 + -| Watchpoint 2: $2 + gawk> r Start the program + -| Starting program: + -| Stopping in Rule ... + -| Watchpoint 1: $1 Watchpoint fires + -| Old value: "" + -| New value: "abc" + -| main() at `test.awk':1 + -| 1 { print typeof($1), typeof($2) } + gawk> n Keep going ... + -| Watchpoint 2: $2 Watchpoint fires + -| Old value: "" + -| New value: "123" + -| main() at `test.awk':1 + -| 1 { print typeof($1), typeof($2) } + gawk> n Get result from typeof() + -| strnum string Result for $2 isn't right + -| Program exited normally with exit value: 0 + gawk> quit + + In this case, the act of comparing the new value of '$2' with the old +one caused 'gawk' to evaluate it and determine that it is indeed a +string, and this is reflected in the result of 'typeof()'. + + Cases like this where the debugger is not transparent to the +program's execution should be rare. If you encounter one, please report +it (*note Bugs::). + + ---------- Footnotes ---------- + + (1) Thanks to Hermann Peifer for this example. + File: gawk.info, Node: Debugging Summary, Prev: Limitations, Up: Debugger @@ -21888,6 +21944,9 @@ File: gawk.info, Node: Debugging Summary, Prev: Limitations, Up: Debugger it is used by the debugger to provide command-line history and editing. + * Usually, the debugger does not not affect the program being + debugged, but occasionally it can. + File: gawk.info, Node: Arbitrary Precision Arithmetic, Next: Dynamic Extensions, Prev: Debugger, Up: Top @@ -35398,176 +35457,177 @@ Node: Debugger Info874246 Node: Miscellaneous Debugger Commands878317 Node: Readline Support883326 Node: Limitations884222 -Node: Debugging Summary886331 -Node: Arbitrary Precision Arithmetic887504 -Node: Computer Arithmetic888920 -Ref: table-numeric-ranges892511 -Ref: Computer Arithmetic-Footnote-1893233 -Node: Math Definitions893290 -Ref: table-ieee-formats896604 -Ref: Math Definitions-Footnote-1897207 -Node: MPFR features897312 -Node: FP Math Caution898985 -Ref: FP Math Caution-Footnote-1900057 -Node: Inexactness of computations900426 -Node: Inexact representation901386 -Node: Comparing FP Values902746 -Node: Errors accumulate903828 -Node: Getting Accuracy905261 -Node: Try To Round907971 -Node: Setting precision908870 -Ref: table-predefined-precision-strings909567 -Node: Setting the rounding mode911397 -Ref: table-gawk-rounding-modes911771 -Ref: Setting the rounding mode-Footnote-1915179 -Node: Arbitrary Precision Integers915358 -Ref: Arbitrary Precision Integers-Footnote-1920275 -Node: POSIX Floating Point Problems920424 -Ref: POSIX Floating Point Problems-Footnote-1924306 -Node: Floating point summary924344 -Node: Dynamic Extensions926534 -Node: Extension Intro928087 -Node: Plugin License929353 -Node: Extension Mechanism Outline930150 -Ref: figure-load-extension930589 -Ref: figure-register-new-function932154 -Ref: figure-call-new-function933246 -Node: Extension API Description935309 -Node: Extension API Functions Introduction936843 -Node: General Data Types941702 -Ref: General Data Types-Footnote-1947657 -Node: Memory Allocation Functions947956 -Ref: Memory Allocation Functions-Footnote-1950801 -Node: Constructor Functions950900 -Node: Registration Functions952645 -Node: Extension Functions953330 -Node: Exit Callback Functions955629 -Node: Extension Version String956879 -Node: Input Parsers957542 -Node: Output Wrappers967427 -Node: Two-way processors971939 -Node: Printing Messages974203 -Ref: Printing Messages-Footnote-1975279 -Node: Updating 'ERRNO'975432 -Node: Requesting Values976173 -Ref: table-value-types-returned976912 -Node: Accessing Parameters977795 -Node: Symbol Table Access979031 -Node: Symbol table by name979543 -Node: Symbol table by cookie981564 -Ref: Symbol table by cookie-Footnote-1985713 -Node: Cached values985777 -Ref: Cached values-Footnote-1989278 -Node: Array Manipulation989369 -Ref: Array Manipulation-Footnote-1990460 -Node: Array Data Types990497 -Ref: Array Data Types-Footnote-1993155 -Node: Array Functions993247 -Node: Flattening Arrays997106 -Node: Creating Arrays1004014 -Node: Redirection API1008786 -Node: Extension API Variables1011617 -Node: Extension Versioning1012250 -Node: Extension API Informational Variables1014141 -Node: Extension API Boilerplate1015205 -Node: Finding Extensions1019019 -Node: Extension Example1019579 -Node: Internal File Description1020377 -Node: Internal File Ops1024457 -Ref: Internal File Ops-Footnote-11036219 -Node: Using Internal File Ops1036359 -Ref: Using Internal File Ops-Footnote-11038742 -Node: Extension Samples1039017 -Node: Extension Sample File Functions1040546 -Node: Extension Sample Fnmatch1048195 -Node: Extension Sample Fork1049682 -Node: Extension Sample Inplace1050900 -Node: Extension Sample Ord1054110 -Node: Extension Sample Readdir1054946 -Ref: table-readdir-file-types1055835 -Node: Extension Sample Revout1056640 -Node: Extension Sample Rev2way1057229 -Node: Extension Sample Read write array1057969 -Node: Extension Sample Readfile1059911 -Node: Extension Sample Time1061006 -Node: Extension Sample API Tests1062354 -Node: gawkextlib1062846 -Node: Extension summary1065293 -Node: Extension Exercises1068985 -Node: Language History1070482 -Node: V7/SVR3.11072138 -Node: SVR41074291 -Node: POSIX1075725 -Node: BTL1077105 -Node: POSIX/GNU1077835 -Node: Feature History1083674 -Node: Common Extensions1097993 -Node: Ranges and Locales1099276 -Ref: Ranges and Locales-Footnote-11103892 -Ref: Ranges and Locales-Footnote-21103919 -Ref: Ranges and Locales-Footnote-31104154 -Node: Contributors1104375 -Node: History summary1109944 -Node: Installation1111324 -Node: Gawk Distribution1112269 -Node: Getting1112753 -Node: Extracting1113576 -Node: Distribution contents1115214 -Node: Unix Installation1121310 -Node: Quick Installation1121992 -Node: Shell Startup Files1124406 -Node: Additional Configuration Options1125484 -Node: Configuration Philosophy1127289 -Node: Non-Unix Installation1129659 -Node: PC Installation1130117 -Node: PC Binary Installation1131437 -Node: PC Compiling1133289 -Ref: PC Compiling-Footnote-11136313 -Node: PC Testing1136422 -Node: PC Using1137602 -Node: Cygwin1141716 -Node: MSYS1142486 -Node: VMS Installation1142987 -Node: VMS Compilation1143778 -Ref: VMS Compilation-Footnote-11145008 -Node: VMS Dynamic Extensions1145066 -Node: VMS Installation Details1146751 -Node: VMS Running1149004 -Node: VMS GNV1151845 -Node: VMS Old Gawk1152580 -Node: Bugs1153051 -Node: Other Versions1157165 -Node: Installation summary1163639 -Node: Notes1164697 -Node: Compatibility Mode1165562 -Node: Additions1166344 -Node: Accessing The Source1167269 -Node: Adding Code1168705 -Node: New Ports1174860 -Node: Derived Files1179348 -Ref: Derived Files-Footnote-11184833 -Ref: Derived Files-Footnote-21184868 -Ref: Derived Files-Footnote-31185466 -Node: Future Extensions1185580 -Node: Implementation Limitations1186238 -Node: Extension Design1187421 -Node: Old Extension Problems1188575 -Ref: Old Extension Problems-Footnote-11190093 -Node: Extension New Mechanism Goals1190150 -Ref: Extension New Mechanism Goals-Footnote-11193514 -Node: Extension Other Design Decisions1193703 -Node: Extension Future Growth1195816 -Node: Old Extension Mechanism1196652 -Node: Notes summary1198415 -Node: Basic Concepts1199597 -Node: Basic High Level1200278 -Ref: figure-general-flow1200560 -Ref: figure-process-flow1201245 -Ref: Basic High Level-Footnote-11204546 -Node: Basic Data Typing1204731 -Node: Glossary1208059 -Node: Copying1240005 -Node: GNU Free Documentation License1277544 -Node: Index1302662 +Ref: Limitations-Footnote-1888453 +Node: Debugging Summary888504 +Node: Arbitrary Precision Arithmetic889783 +Node: Computer Arithmetic891199 +Ref: table-numeric-ranges894790 +Ref: Computer Arithmetic-Footnote-1895512 +Node: Math Definitions895569 +Ref: table-ieee-formats898883 +Ref: Math Definitions-Footnote-1899486 +Node: MPFR features899591 +Node: FP Math Caution901264 +Ref: FP Math Caution-Footnote-1902336 +Node: Inexactness of computations902705 +Node: Inexact representation903665 +Node: Comparing FP Values905025 +Node: Errors accumulate906107 +Node: Getting Accuracy907540 +Node: Try To Round910250 +Node: Setting precision911149 +Ref: table-predefined-precision-strings911846 +Node: Setting the rounding mode913676 +Ref: table-gawk-rounding-modes914050 +Ref: Setting the rounding mode-Footnote-1917458 +Node: Arbitrary Precision Integers917637 +Ref: Arbitrary Precision Integers-Footnote-1922554 +Node: POSIX Floating Point Problems922703 +Ref: POSIX Floating Point Problems-Footnote-1926585 +Node: Floating point summary926623 +Node: Dynamic Extensions928813 +Node: Extension Intro930366 +Node: Plugin License931632 +Node: Extension Mechanism Outline932429 +Ref: figure-load-extension932868 +Ref: figure-register-new-function934433 +Ref: figure-call-new-function935525 +Node: Extension API Description937588 +Node: Extension API Functions Introduction939122 +Node: General Data Types943981 +Ref: General Data Types-Footnote-1949936 +Node: Memory Allocation Functions950235 +Ref: Memory Allocation Functions-Footnote-1953080 +Node: Constructor Functions953179 +Node: Registration Functions954924 +Node: Extension Functions955609 +Node: Exit Callback Functions957908 +Node: Extension Version String959158 +Node: Input Parsers959821 +Node: Output Wrappers969706 +Node: Two-way processors974218 +Node: Printing Messages976482 +Ref: Printing Messages-Footnote-1977558 +Node: Updating 'ERRNO'977711 +Node: Requesting Values978452 +Ref: table-value-types-returned979191 +Node: Accessing Parameters980074 +Node: Symbol Table Access981310 +Node: Symbol table by name981822 +Node: Symbol table by cookie983843 +Ref: Symbol table by cookie-Footnote-1987992 +Node: Cached values988056 +Ref: Cached values-Footnote-1991557 +Node: Array Manipulation991648 +Ref: Array Manipulation-Footnote-1992739 +Node: Array Data Types992776 +Ref: Array Data Types-Footnote-1995434 +Node: Array Functions995526 +Node: Flattening Arrays999385 +Node: Creating Arrays1006293 +Node: Redirection API1011065 +Node: Extension API Variables1013896 +Node: Extension Versioning1014529 +Node: Extension API Informational Variables1016420 +Node: Extension API Boilerplate1017484 +Node: Finding Extensions1021298 +Node: Extension Example1021858 +Node: Internal File Description1022656 +Node: Internal File Ops1026736 +Ref: Internal File Ops-Footnote-11038498 +Node: Using Internal File Ops1038638 +Ref: Using Internal File Ops-Footnote-11041021 +Node: Extension Samples1041296 +Node: Extension Sample File Functions1042825 +Node: Extension Sample Fnmatch1050474 +Node: Extension Sample Fork1051961 +Node: Extension Sample Inplace1053179 +Node: Extension Sample Ord1056389 +Node: Extension Sample Readdir1057225 +Ref: table-readdir-file-types1058114 +Node: Extension Sample Revout1058919 +Node: Extension Sample Rev2way1059508 +Node: Extension Sample Read write array1060248 +Node: Extension Sample Readfile1062190 +Node: Extension Sample Time1063285 +Node: Extension Sample API Tests1064633 +Node: gawkextlib1065125 +Node: Extension summary1067572 +Node: Extension Exercises1071264 +Node: Language History1072761 +Node: V7/SVR3.11074417 +Node: SVR41076570 +Node: POSIX1078004 +Node: BTL1079384 +Node: POSIX/GNU1080114 +Node: Feature History1085953 +Node: Common Extensions1100272 +Node: Ranges and Locales1101555 +Ref: Ranges and Locales-Footnote-11106171 +Ref: Ranges and Locales-Footnote-21106198 +Ref: Ranges and Locales-Footnote-31106433 +Node: Contributors1106654 +Node: History summary1112223 +Node: Installation1113603 +Node: Gawk Distribution1114548 +Node: Getting1115032 +Node: Extracting1115855 +Node: Distribution contents1117493 +Node: Unix Installation1123589 +Node: Quick Installation1124271 +Node: Shell Startup Files1126685 +Node: Additional Configuration Options1127763 +Node: Configuration Philosophy1129568 +Node: Non-Unix Installation1131938 +Node: PC Installation1132396 +Node: PC Binary Installation1133716 +Node: PC Compiling1135568 +Ref: PC Compiling-Footnote-11138592 +Node: PC Testing1138701 +Node: PC Using1139881 +Node: Cygwin1143995 +Node: MSYS1144765 +Node: VMS Installation1145266 +Node: VMS Compilation1146057 +Ref: VMS Compilation-Footnote-11147287 +Node: VMS Dynamic Extensions1147345 +Node: VMS Installation Details1149030 +Node: VMS Running1151283 +Node: VMS GNV1154124 +Node: VMS Old Gawk1154859 +Node: Bugs1155330 +Node: Other Versions1159444 +Node: Installation summary1165918 +Node: Notes1166976 +Node: Compatibility Mode1167841 +Node: Additions1168623 +Node: Accessing The Source1169548 +Node: Adding Code1170984 +Node: New Ports1177139 +Node: Derived Files1181627 +Ref: Derived Files-Footnote-11187112 +Ref: Derived Files-Footnote-21187147 +Ref: Derived Files-Footnote-31187745 +Node: Future Extensions1187859 +Node: Implementation Limitations1188517 +Node: Extension Design1189700 +Node: Old Extension Problems1190854 +Ref: Old Extension Problems-Footnote-11192372 +Node: Extension New Mechanism Goals1192429 +Ref: Extension New Mechanism Goals-Footnote-11195793 +Node: Extension Other Design Decisions1195982 +Node: Extension Future Growth1198095 +Node: Old Extension Mechanism1198931 +Node: Notes summary1200694 +Node: Basic Concepts1201876 +Node: Basic High Level1202557 +Ref: figure-general-flow1202839 +Ref: figure-process-flow1203524 +Ref: Basic High Level-Footnote-11206825 +Node: Basic Data Typing1207010 +Node: Glossary1210338 +Node: Copying1242284 +Node: GNU Free Documentation License1279823 +Node: Index1304941 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 64f494a0..b33ff085 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -30411,6 +30411,65 @@ executing, short programs. The @command{gawk} debugger only accepts source code supplied with the @option{-f} option. @end itemize +One other point is worth disucssing. Conventional debuggers run in a +separate process (and thus address space) from the programs that they +debug (the @dfn{debuggee}, if you will). + +The @command{gawk} debugger is different; it is an integrated part +of @command{gawk} itself. This makes it possible, in rare cases, +for @command{gawk} to become an excellent demonstrator of Heisenburg +Uncertainty physics, where the mere act of observing something can change +it. Consider the following:@footnote{Thanks to Hermann Peifer for +this example.} + +@example +$ @kbd{cat test.awk} +@print{} @{ print typeof($1), typeof($2) @} +$ @kbd{cat test.data} +@print{} abc 123 +$ @kbd{gawk -f test.awk test.data} +@print{} strnum strnum +@end example + +This is all as expected: field data has the STRNUM attribute +(@pxref{Variable Typing}). Now watch what happens when we run +this program under the debugger: + +@example +$ @kbd{gawk -D -f test.awk test.data} +gawk> @kbd{w $1} @ii{Set watchpoint on} $1 +@print{} Watchpoint 1: $1 +gawk> @kbd{w $2} @ii{Set watchpoint on} $2 +@print{} Watchpoint 2: $2 +gawk> @kbd{r} @ii{Start the program} +@print{} Starting program: +@print{} Stopping in Rule ... +@print{} Watchpoint 1: $1 @ii{Watchpoint fires} +@print{} Old value: "" +@print{} New value: "abc" +@print{} main() at `test.awk':1 +@print{} 1 @{ print typeof($1), typeof($2) @} +gawk> @kbd{n} @ii{Keep going @dots{}} +@print{} Watchpoint 2: $2 @ii{Watchpoint fires} +@print{} Old value: "" +@print{} New value: "123" +@print{} main() at `test.awk':1 +@print{} 1 @{ print typeof($1), typeof($2) @} +gawk> @kbd{n} @ii{Get result from} typeof() +@print{} strnum string @ii{Result for} $2 @ii{isn't right} +@print{} Program exited normally with exit value: 0 +gawk> @kbd{quit} +@end example + +In this case, the act of comparing the new value of @code{$2} +with the old one caused @command{gawk} to evaluate it and determine that it +is indeed a string, and this is reflected in the result of +@code{typeof()}. + +Cases like this where the debugger is not transparent to the program's +execution should be rare. If you encounter one, please report it +(@pxref{Bugs}). + @ignore Look forward to a future release when these and other missing features may be added, and of course feel free to try to add them yourself! @@ -30447,6 +30506,10 @@ If the GNU Readline library is available when @command{gawk} is compiled, it is used by the debugger to provide command-line history and editing. +@item +Usually, the debugger does not not affect the +program being debugged, but occasionally it can. + @end itemize @node Arbitrary Precision Arithmetic diff --git a/doc/gawktexi.in b/doc/gawktexi.in index 81ff1aec..0ed2f3f8 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -29502,6 +29502,65 @@ executing, short programs. The @command{gawk} debugger only accepts source code supplied with the @option{-f} option. @end itemize +One other point is worth disucssing. Conventional debuggers run in a +separate process (and thus address space) from the programs that they +debug (the @dfn{debuggee}, if you will). + +The @command{gawk} debugger is different; it is an integrated part +of @command{gawk} itself. This makes it possible, in rare cases, +for @command{gawk} to become an excellent demonstrator of Heisenburg +Uncertainty physics, where the mere act of observing something can change +it. Consider the following:@footnote{Thanks to Hermann Peifer for +this example.} + +@example +$ @kbd{cat test.awk} +@print{} @{ print typeof($1), typeof($2) @} +$ @kbd{cat test.data} +@print{} abc 123 +$ @kbd{gawk -f test.awk test.data} +@print{} strnum strnum +@end example + +This is all as expected: field data has the STRNUM attribute +(@pxref{Variable Typing}). Now watch what happens when we run +this program under the debugger: + +@example +$ @kbd{gawk -D -f test.awk test.data} +gawk> @kbd{w $1} @ii{Set watchpoint on} $1 +@print{} Watchpoint 1: $1 +gawk> @kbd{w $2} @ii{Set watchpoint on} $2 +@print{} Watchpoint 2: $2 +gawk> @kbd{r} @ii{Start the program} +@print{} Starting program: +@print{} Stopping in Rule ... +@print{} Watchpoint 1: $1 @ii{Watchpoint fires} +@print{} Old value: "" +@print{} New value: "abc" +@print{} main() at `test.awk':1 +@print{} 1 @{ print typeof($1), typeof($2) @} +gawk> @kbd{n} @ii{Keep going @dots{}} +@print{} Watchpoint 2: $2 @ii{Watchpoint fires} +@print{} Old value: "" +@print{} New value: "123" +@print{} main() at `test.awk':1 +@print{} 1 @{ print typeof($1), typeof($2) @} +gawk> @kbd{n} @ii{Get result from} typeof() +@print{} strnum string @ii{Result for} $2 @ii{isn't right} +@print{} Program exited normally with exit value: 0 +gawk> @kbd{quit} +@end example + +In this case, the act of comparing the new value of @code{$2} +with the old one caused @command{gawk} to evaluate it and determine that it +is indeed a string, and this is reflected in the result of +@code{typeof()}. + +Cases like this where the debugger is not transparent to the program's +execution should be rare. If you encounter one, please report it +(@pxref{Bugs}). + @ignore Look forward to a future release when these and other missing features may be added, and of course feel free to try to add them yourself! @@ -29538,6 +29597,10 @@ If the GNU Readline library is available when @command{gawk} is compiled, it is used by the debugger to provide command-line history and editing. +@item +Usually, the debugger does not not affect the +program being debugged, but occasionally it can. + @end itemize @node Arbitrary Precision Arithmetic |