Document about using closed end of two-way pipes.

6 files changed, 236 insertions, 211 deletions

diff --git a/ChangeLog b/ChangeLog
index fe98ed8e..7ba50e8c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -7,6 +7,7 @@
 	(do_print_rec): Ditto.
 	* io.c (do_getline_redir): Same thing for reading from a closed
 	read end of a two-way pipe. Fatal error.
+	* NEWS: Updated.
 
 2016-03-14         Arnold D. Robbins     <arnold@skeeve.com>
 
diff --git a/NEWS b/NEWS
index 31c8471c..472b05e3 100644
--- a/NEWS
+++ b/NEWS
@@ -30,6 +30,10 @@ Changes from 4.1.3 to 4.1.x
 8. The return value of system() has been enhanced to convey more information.
    See the doc.
 
+9. Attempting to write to the "to" end of a two-way pipe that has been
+   closed is now a fatal error. Similarly, so is reading from the "from"
+   end that has been closed.
+
 Changes from 4.1.2 to 4.1.3
 ---------------------------
 
diff --git a/doc/ChangeLog b/doc/ChangeLog
index 9380d248..0da0e7c7 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -3,6 +3,11 @@
 	* gawktexi.in, gawkinet.texi: Enable use of braces in
 	indexes. Requires Texinfo 6.0 or later.
 
+2016-04-02         Arnold D. Robbins     <arnold@skeeve.com>
+
+	* gawktexi.in (Two-way I/O): Document that closing the "to"
+	end waits for the process to exit, so it's not such a great idea.
+
 2016-03-21         Arnold D. Robbins     <arnold@skeeve.com>
 
 	* gawkinet.texi: Update UDP client and discussion, update
diff --git a/doc/gawk.info b/doc/gawk.info
index c0b58599..c3cb0896 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -19668,6 +19668,11 @@ the coprocess and exits.
 ensures traditional Unix (ASCII) sorting from 'sort'.  This is not
 strictly necessary here, but it's good to know how to do this.
 
+   Be careful when closing the '"from"' end of a two-way pipe; in this
+case 'gawk' waits for the child process to exit, which may cause your
+program to hang.  (Thus, this particular feature is of much less use in
+practice than being able to close the '"to"' end.)
+
    You may also use pseudo-ttys (ptys) for two-way communication instead
 of pipes, if your system supports them.  This is done on a per-command
 basis, by setting a special element in the 'PROCINFO' array (*note
@@ -33170,7 +33175,7 @@ Index
 * gawk, predefined variables and:        Built-in Variables.  (line  14)
 * gawk, PROCINFO array in:               Auto-set.            (line 129)
 * gawk, PROCINFO array in <1>:           Time Functions.      (line  47)
-* gawk, PROCINFO array in <2>:           Two-way I/O.         (line  99)
+* gawk, PROCINFO array in <2>:           Two-way I/O.         (line 104)
 * gawk, regexp constants and:            Using Constant Regexps.
                                                               (line  28)
 * gawk, regular expressions, case sensitivity: Case-sensitivity.
@@ -33944,7 +33949,7 @@ Index
 * PROCINFO array:                        Auto-set.            (line 129)
 * PROCINFO array <1>:                    Time Functions.      (line  47)
 * PROCINFO array <2>:                    Passwd Functions.    (line   6)
-* PROCINFO array, and communications via ptys: Two-way I/O.   (line  99)
+* PROCINFO array, and communications via ptys: Two-way I/O.   (line 104)
 * PROCINFO array, and group membership:  Group Functions.     (line   6)
 * PROCINFO array, and user and group ID numbers: Id Program.  (line  15)
 * PROCINFO array, testing the field splitting: Passwd Functions.
@@ -35009,214 +35014,214 @@ Ref: Controlling Array Traversal-Footnote-1790219
 Node: Array Sorting Functions790337
 Ref: Array Sorting Functions-Footnote-1795428
 Node: Two-way I/O795624
-Ref: Two-way I/O-Footnote-1801444
-Ref: Two-way I/O-Footnote-2801631
-Node: TCP/IP Networking801713
-Node: Profiling804831
-Node: Advanced Features Summary812370
-Node: Internationalization814306
-Node: I18N and L10N815786
-Node: Explaining gettext816473
-Ref: Explaining gettext-Footnote-1821496
-Ref: Explaining gettext-Footnote-2821681
-Node: Programmer i18n821846
-Ref: Programmer i18n-Footnote-1826701
-Node: Translator i18n826750
-Node: String Extraction827544
-Ref: String Extraction-Footnote-1828676
-Node: Printf Ordering828762
-Ref: Printf Ordering-Footnote-1831548
-Node: I18N Portability831612
-Ref: I18N Portability-Footnote-1834068
-Node: I18N Example834131
-Ref: I18N Example-Footnote-1836937
-Node: Gawk I18N837010
-Node: I18N Summary837655
-Node: Debugger838996
-Node: Debugging840018
-Node: Debugging Concepts840459
-Node: Debugging Terms842268
-Node: Awk Debugging844843
-Node: Sample Debugging Session845749
-Node: Debugger Invocation846283
-Node: Finding The Bug847669
-Node: List of Debugger Commands854147
-Node: Breakpoint Control855480
-Node: Debugger Execution Control859174
-Node: Viewing And Changing Data862536
-Node: Execution Stack865910
-Node: Debugger Info867547
-Node: Miscellaneous Debugger Commands871618
-Node: Readline Support876706
-Node: Limitations877602
-Node: Debugging Summary879711
-Node: Arbitrary Precision Arithmetic880884
-Node: Computer Arithmetic882300
-Ref: table-numeric-ranges885891
-Ref: Computer Arithmetic-Footnote-1886613
-Node: Math Definitions886670
-Ref: table-ieee-formats889984
-Ref: Math Definitions-Footnote-1890587
-Node: MPFR features890692
-Node: FP Math Caution892409
-Ref: FP Math Caution-Footnote-1893481
-Node: Inexactness of computations893850
-Node: Inexact representation894810
-Node: Comparing FP Values896170
-Node: Errors accumulate897252
-Node: Getting Accuracy898685
-Node: Try To Round901395
-Node: Setting precision902294
-Ref: table-predefined-precision-strings902991
-Node: Setting the rounding mode904821
-Ref: table-gawk-rounding-modes905195
-Ref: Setting the rounding mode-Footnote-1908603
-Node: Arbitrary Precision Integers908782
-Ref: Arbitrary Precision Integers-Footnote-1911766
-Node: POSIX Floating Point Problems911915
-Ref: POSIX Floating Point Problems-Footnote-1915797
-Node: Floating point summary915835
-Node: Dynamic Extensions918025
-Node: Extension Intro919578
-Node: Plugin License920844
-Node: Extension Mechanism Outline921641
-Ref: figure-load-extension922080
-Ref: figure-register-new-function923645
-Ref: figure-call-new-function924737
-Node: Extension API Description926799
-Node: Extension API Functions Introduction928247
-Node: General Data Types933059
-Ref: General Data Types-Footnote-1939014
-Node: Memory Allocation Functions939313
-Ref: Memory Allocation Functions-Footnote-1942158
-Node: Constructor Functions942257
-Node: Registration Functions944002
-Node: Extension Functions944687
-Node: Exit Callback Functions946986
-Node: Extension Version String948236
-Node: Input Parsers948899
-Node: Output Wrappers958784
-Node: Two-way processors963296
-Node: Printing Messages965560
-Ref: Printing Messages-Footnote-1966634
-Node: Updating ERRNO966787
-Node: Requesting Values967526
-Ref: table-value-types-returned968263
-Node: Accessing Parameters969146
-Node: Symbol Table Access970381
-Node: Symbol table by name970893
-Node: Symbol table by cookie972914
-Ref: Symbol table by cookie-Footnote-1977063
-Node: Cached values977127
-Ref: Cached values-Footnote-1980628
-Node: Array Manipulation980719
-Ref: Array Manipulation-Footnote-1981818
-Node: Array Data Types981855
-Ref: Array Data Types-Footnote-1984513
-Node: Array Functions984605
-Node: Flattening Arrays988463
-Node: Creating Arrays995371
-Node: Extension API Variables1000142
-Node: Extension Versioning1000778
-Node: Extension API Informational Variables1002669
-Node: Extension API Boilerplate1003733
-Node: Finding Extensions1007547
-Node: Extension Example1008106
-Node: Internal File Description1008904
-Node: Internal File Ops1012984
-Ref: Internal File Ops-Footnote-11024746
-Node: Using Internal File Ops1024886
-Ref: Using Internal File Ops-Footnote-11027269
-Node: Extension Samples1027543
-Node: Extension Sample File Functions1029072
-Node: Extension Sample Fnmatch1036721
-Node: Extension Sample Fork1038208
-Node: Extension Sample Inplace1039426
-Node: Extension Sample Ord1042636
-Node: Extension Sample Readdir1043472
-Ref: table-readdir-file-types1044361
-Node: Extension Sample Revout1045166
-Node: Extension Sample Rev2way1045755
-Node: Extension Sample Read write array1046495
-Node: Extension Sample Readfile1048437
-Node: Extension Sample Time1049532
-Node: Extension Sample API Tests1050880
-Node: gawkextlib1051372
-Node: Extension summary1053796
-Node: Extension Exercises1057488
-Node: Language History1058985
-Node: V7/SVR3.11060641
-Node: SVR41062793
-Node: POSIX1064227
-Node: BTL1065606
-Node: POSIX/GNU1066335
-Node: Feature History1071856
-Node: Common Extensions1085185
-Node: Ranges and Locales1086468
-Ref: Ranges and Locales-Footnote-11091084
-Ref: Ranges and Locales-Footnote-21091111
-Ref: Ranges and Locales-Footnote-31091346
-Node: Contributors1091567
-Node: History summary1097136
-Node: Installation1098516
-Node: Gawk Distribution1099460
-Node: Getting1099944
-Node: Extracting1100905
-Node: Distribution contents1102543
-Node: Unix Installation1108294
-Node: Quick Installation1108910
-Node: Additional Configuration Options1111337
-Node: Configuration Philosophy1113141
-Node: Non-Unix Installation1115510
-Node: PC Installation1115968
-Node: PC Binary Installation1117288
-Node: PC Compiling1119140
-Ref: PC Compiling-Footnote-11122164
-Node: PC Testing1122273
-Node: PC Using1123453
-Node: Cygwin1127567
-Node: MSYS1128337
-Node: VMS Installation1128838
-Node: VMS Compilation1129629
-Ref: VMS Compilation-Footnote-11130858
-Node: VMS Dynamic Extensions1130916
-Node: VMS Installation Details1132601
-Node: VMS Running1134854
-Node: VMS GNV1139133
-Node: VMS Old Gawk1139868
-Node: Bugs1140339
-Node: Other Versions1144536
-Node: Installation summary1151120
-Node: Notes1152178
-Node: Compatibility Mode1153043
-Node: Additions1153825
-Node: Accessing The Source1154750
-Node: Adding Code1156185
-Node: New Ports1162404
-Node: Derived Files1166892
-Ref: Derived Files-Footnote-11172377
-Ref: Derived Files-Footnote-21172412
-Ref: Derived Files-Footnote-31173010
-Node: Future Extensions1173124
-Node: Implementation Limitations1173782
-Node: Extension Design1174965
-Node: Old Extension Problems1176119
-Ref: Old Extension Problems-Footnote-11177637
-Node: Extension New Mechanism Goals1177694
-Ref: Extension New Mechanism Goals-Footnote-11181058
-Node: Extension Other Design Decisions1181247
-Node: Extension Future Growth1183360
-Node: Old Extension Mechanism1184196
-Node: Notes summary1185959
-Node: Basic Concepts1187141
-Node: Basic High Level1187822
-Ref: figure-general-flow1188104
-Ref: figure-process-flow1188789
-Ref: Basic High Level-Footnote-11192090
-Node: Basic Data Typing1192275
-Node: Glossary1195603
-Node: Copying1227549
-Node: GNU Free Documentation License1265088
-Node: Index1290206
+Ref: Two-way I/O-Footnote-1801709
+Ref: Two-way I/O-Footnote-2801896
+Node: TCP/IP Networking801978
+Node: Profiling805096
+Node: Advanced Features Summary812635
+Node: Internationalization814571
+Node: I18N and L10N816051
+Node: Explaining gettext816738
+Ref: Explaining gettext-Footnote-1821761
+Ref: Explaining gettext-Footnote-2821946
+Node: Programmer i18n822111
+Ref: Programmer i18n-Footnote-1826966
+Node: Translator i18n827015
+Node: String Extraction827809
+Ref: String Extraction-Footnote-1828941
+Node: Printf Ordering829027
+Ref: Printf Ordering-Footnote-1831813
+Node: I18N Portability831877
+Ref: I18N Portability-Footnote-1834333
+Node: I18N Example834396
+Ref: I18N Example-Footnote-1837202
+Node: Gawk I18N837275
+Node: I18N Summary837920
+Node: Debugger839261
+Node: Debugging840283
+Node: Debugging Concepts840724
+Node: Debugging Terms842533
+Node: Awk Debugging845108
+Node: Sample Debugging Session846014
+Node: Debugger Invocation846548
+Node: Finding The Bug847934
+Node: List of Debugger Commands854412
+Node: Breakpoint Control855745
+Node: Debugger Execution Control859439
+Node: Viewing And Changing Data862801
+Node: Execution Stack866175
+Node: Debugger Info867812
+Node: Miscellaneous Debugger Commands871883
+Node: Readline Support876971
+Node: Limitations877867
+Node: Debugging Summary879976
+Node: Arbitrary Precision Arithmetic881149
+Node: Computer Arithmetic882565
+Ref: table-numeric-ranges886156
+Ref: Computer Arithmetic-Footnote-1886878
+Node: Math Definitions886935
+Ref: table-ieee-formats890249
+Ref: Math Definitions-Footnote-1890852
+Node: MPFR features890957
+Node: FP Math Caution892674
+Ref: FP Math Caution-Footnote-1893746
+Node: Inexactness of computations894115
+Node: Inexact representation895075
+Node: Comparing FP Values896435
+Node: Errors accumulate897517
+Node: Getting Accuracy898950
+Node: Try To Round901660
+Node: Setting precision902559
+Ref: table-predefined-precision-strings903256
+Node: Setting the rounding mode905086
+Ref: table-gawk-rounding-modes905460
+Ref: Setting the rounding mode-Footnote-1908868
+Node: Arbitrary Precision Integers909047
+Ref: Arbitrary Precision Integers-Footnote-1912031
+Node: POSIX Floating Point Problems912180
+Ref: POSIX Floating Point Problems-Footnote-1916062
+Node: Floating point summary916100
+Node: Dynamic Extensions918290
+Node: Extension Intro919843
+Node: Plugin License921109
+Node: Extension Mechanism Outline921906
+Ref: figure-load-extension922345
+Ref: figure-register-new-function923910
+Ref: figure-call-new-function925002
+Node: Extension API Description927064
+Node: Extension API Functions Introduction928512
+Node: General Data Types933324
+Ref: General Data Types-Footnote-1939279
+Node: Memory Allocation Functions939578
+Ref: Memory Allocation Functions-Footnote-1942423
+Node: Constructor Functions942522
+Node: Registration Functions944267
+Node: Extension Functions944952
+Node: Exit Callback Functions947251
+Node: Extension Version String948501
+Node: Input Parsers949164
+Node: Output Wrappers959049
+Node: Two-way processors963561
+Node: Printing Messages965825
+Ref: Printing Messages-Footnote-1966899
+Node: Updating ERRNO967052
+Node: Requesting Values967791
+Ref: table-value-types-returned968528
+Node: Accessing Parameters969411
+Node: Symbol Table Access970646
+Node: Symbol table by name971158
+Node: Symbol table by cookie973179
+Ref: Symbol table by cookie-Footnote-1977328
+Node: Cached values977392
+Ref: Cached values-Footnote-1980893
+Node: Array Manipulation980984
+Ref: Array Manipulation-Footnote-1982083
+Node: Array Data Types982120
+Ref: Array Data Types-Footnote-1984778
+Node: Array Functions984870
+Node: Flattening Arrays988728
+Node: Creating Arrays995636
+Node: Extension API Variables1000407
+Node: Extension Versioning1001043
+Node: Extension API Informational Variables1002934
+Node: Extension API Boilerplate1003998
+Node: Finding Extensions1007812
+Node: Extension Example1008371
+Node: Internal File Description1009169
+Node: Internal File Ops1013249
+Ref: Internal File Ops-Footnote-11025011
+Node: Using Internal File Ops1025151
+Ref: Using Internal File Ops-Footnote-11027534
+Node: Extension Samples1027808
+Node: Extension Sample File Functions1029337
+Node: Extension Sample Fnmatch1036986
+Node: Extension Sample Fork1038473
+Node: Extension Sample Inplace1039691
+Node: Extension Sample Ord1042901
+Node: Extension Sample Readdir1043737
+Ref: table-readdir-file-types1044626
+Node: Extension Sample Revout1045431
+Node: Extension Sample Rev2way1046020
+Node: Extension Sample Read write array1046760
+Node: Extension Sample Readfile1048702
+Node: Extension Sample Time1049797
+Node: Extension Sample API Tests1051145
+Node: gawkextlib1051637
+Node: Extension summary1054061
+Node: Extension Exercises1057753
+Node: Language History1059250
+Node: V7/SVR3.11060906
+Node: SVR41063058
+Node: POSIX1064492
+Node: BTL1065871
+Node: POSIX/GNU1066600
+Node: Feature History1072121
+Node: Common Extensions1085450
+Node: Ranges and Locales1086733
+Ref: Ranges and Locales-Footnote-11091349
+Ref: Ranges and Locales-Footnote-21091376
+Ref: Ranges and Locales-Footnote-31091611
+Node: Contributors1091832
+Node: History summary1097401
+Node: Installation1098781
+Node: Gawk Distribution1099725
+Node: Getting1100209
+Node: Extracting1101170
+Node: Distribution contents1102808
+Node: Unix Installation1108559
+Node: Quick Installation1109175
+Node: Additional Configuration Options1111602
+Node: Configuration Philosophy1113406
+Node: Non-Unix Installation1115775
+Node: PC Installation1116233
+Node: PC Binary Installation1117553
+Node: PC Compiling1119405
+Ref: PC Compiling-Footnote-11122429
+Node: PC Testing1122538
+Node: PC Using1123718
+Node: Cygwin1127832
+Node: MSYS1128602
+Node: VMS Installation1129103
+Node: VMS Compilation1129894
+Ref: VMS Compilation-Footnote-11131123
+Node: VMS Dynamic Extensions1131181
+Node: VMS Installation Details1132866
+Node: VMS Running1135119
+Node: VMS GNV1139398
+Node: VMS Old Gawk1140133
+Node: Bugs1140604
+Node: Other Versions1144801
+Node: Installation summary1151385
+Node: Notes1152443
+Node: Compatibility Mode1153308
+Node: Additions1154090
+Node: Accessing The Source1155015
+Node: Adding Code1156450
+Node: New Ports1162669
+Node: Derived Files1167157
+Ref: Derived Files-Footnote-11172642
+Ref: Derived Files-Footnote-21172677
+Ref: Derived Files-Footnote-31173275
+Node: Future Extensions1173389
+Node: Implementation Limitations1174047
+Node: Extension Design1175230
+Node: Old Extension Problems1176384
+Ref: Old Extension Problems-Footnote-11177902
+Node: Extension New Mechanism Goals1177959
+Ref: Extension New Mechanism Goals-Footnote-11181323
+Node: Extension Other Design Decisions1181512
+Node: Extension Future Growth1183625
+Node: Old Extension Mechanism1184461
+Node: Notes summary1186224
+Node: Basic Concepts1187406
+Node: Basic High Level1188087
+Ref: figure-general-flow1188369
+Ref: figure-process-flow1189054
+Ref: Basic High Level-Footnote-11192355
+Node: Basic Data Typing1192540
+Node: Glossary1195868
+Node: Copying1227814
+Node: GNU Free Documentation License1265353
+Node: Index1290471
 
 End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 59e06a08..4b0ea40c 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -27507,6 +27507,11 @@ As a side note, the assignment @samp{LC_ALL=C} in the @command{sort}
 command ensures traditional Unix (ASCII) sorting from @command{sort}.
 This is not strictly necessary here, but it's good to know how to do this.
 
+Be careful when closing the @code{"from"} end of a two-way pipe; in this
+case @command{gawk} waits for the child process to exit, which may cause
+your program to hang.  (Thus, this particular feature is of much less
+use in practice than being able to close the @code{"to"} end.)
+
 @cindex @command{gawk}, @code{PROCINFO} array in
 @cindex @code{PROCINFO} array, and communications via ptys
 You may also use pseudo-ttys (ptys) for
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index cd240a43..4d2a76f3 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -26598,6 +26598,11 @@ As a side note, the assignment @samp{LC_ALL=C} in the @command{sort}
 command ensures traditional Unix (ASCII) sorting from @command{sort}.
 This is not strictly necessary here, but it's good to know how to do this.
 
+Be careful when closing the @code{"from"} end of a two-way pipe; in this
+case @command{gawk} waits for the child process to exit, which may cause
+your program to hang.  (Thus, this particular feature is of much less
+use in practice than being able to close the @code{"to"} end.)
+
 @cindex @command{gawk}, @code{PROCINFO} array in
 @cindex @code{PROCINFO} array, and communications via ptys
 You may also use pseudo-ttys (ptys) for