Improve texinfo documentation of the get_file API function.

4 files changed, 151 insertions, 123 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index a995b66d..4a6fa085 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,5 +1,9 @@
 2015-01-05         Andrew J. Schorr     <aschorr@telemetry-investments.com>
 
+	* gawktexi.in: Improve get_file documentation.
+
+2015-01-05         Andrew J. Schorr     <aschorr@telemetry-investments.com>
+
 	* gawktexi.in: Replace "Retrying I/O" with "Retrying Input", since this
 	feature pertains to input, not output.
 
diff --git a/doc/gawk.info b/doc/gawk.info
index 60e0f6f9..f0a9d84d 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -24715,22 +24715,30 @@ redirections.
 
     `|&'
           A two-way coprocess.
-     If the file is not already open, and the fd argument is
-     non-negative, `gawk' will use that file descriptor instead of
-     opening the file in the usual way.  If the fd is non-negative, but
-     the file exists already, `gawk' ignores the fd and returns the
-     existing file.  It is the caller's responsibility to notice that
-     neither the fd in the returned `awk_input_buf_t' nor the fd in the
-     returned `awk_output_buf_t' matches the requested value.  Note that
-     supplying a file descriptor is currently NOT supported for pipes.
-     It should work for input, output, append, and two-way (coprocess)
-     sockets.  If `filetype' is two-way, we assume that it is a socket!
-     Note that in the two-way case, the input and output file
-     descriptors may differ.  To check for success, one must check
-     whether either matches.
-
-   For example, this API function can be used to implement I/O
-multiplexing or a socket library.
+     On error, a `false' value is returned.  Otherwise, the return
+     status is `true', and additional information about the redirection
+     is returned in the `ibufp' and `obufp' pointers.  For input
+     redirections, the `*ibufp' value should be non-NULL, and `*obufp'
+     should be NULL.  For output redirections, the `*obufp' value
+     should be non-NULL, and `*ibufp' should be NULL.  For two-way
+     coprocesses, both values should be non-NULL.  In the usual case,
+     the extension is interested in `(*ibufp)->fd' and/or
+     `fileno((*obufp)->fp)'.  If the file is not already open, and the
+     fd argument is non-negative, `gawk' will use that file descriptor
+     instead of opening the file in the usual way.  If the fd is
+     non-negative, but the file exists already, `gawk' ignores the fd
+     and returns the existing file.  It is the caller's responsibility
+     to notice that neither the fd in the returned `awk_input_buf_t'
+     nor the fd in the returned `awk_output_buf_t' matches the
+     requested value.  Note that supplying a file descriptor is
+     currently NOT supported for pipes.  It should work for input,
+     output, append, and two-way (coprocess) sockets.  If `filetype' is
+     two-way, we assume that it is a socket!  Note that in the two-way
+     case, the input and output file descriptors may differ.  To check
+     for success, one must check whether either matches.
+
+   It is anticipated that this API function will be used to implement
+I/O multiplexing and a socket library.
 
 
 File: gawk.info,  Node: Extension API Variables,  Next: Extension API Boilerplate,  Prev: Redirection API,  Up: Extension API Description
@@ -35017,108 +35025,108 @@ Node: Array Functions984184
 Node: Flattening Arrays988038
 Node: Creating Arrays994930
 Node: Redirection API999701
-Node: Extension API Variables1001897
-Node: Extension Versioning1002530
-Node: Extension API Informational Variables1004431
-Node: Extension API Boilerplate1005496
-Node: Finding Extensions1009305
-Node: Extension Example1009865
-Node: Internal File Description1010637
-Node: Internal File Ops1014704
-Ref: Internal File Ops-Footnote-11026374
-Node: Using Internal File Ops1026514
-Ref: Using Internal File Ops-Footnote-11028897
-Node: Extension Samples1029170
-Node: Extension Sample File Functions1030696
-Node: Extension Sample Fnmatch1038334
-Node: Extension Sample Fork1039825
-Node: Extension Sample Inplace1041040
-Node: Extension Sample Ord1042715
-Node: Extension Sample Readdir1043551
-Ref: table-readdir-file-types1044427
-Node: Extension Sample Revout1045238
-Node: Extension Sample Rev2way1045828
-Node: Extension Sample Read write array1046568
-Node: Extension Sample Readfile1048508
-Node: Extension Sample Time1049603
-Node: Extension Sample API Tests1050952
-Node: gawkextlib1051443
-Node: Extension summary1054101
-Node: Extension Exercises1057790
-Node: Language History1058512
-Node: V7/SVR3.11060168
-Node: SVR41062349
-Node: POSIX1063794
-Node: BTL1065183
-Node: POSIX/GNU1065917
-Node: Feature History1071541
-Node: Common Extensions1084639
-Node: Ranges and Locales1085963
-Ref: Ranges and Locales-Footnote-11090581
-Ref: Ranges and Locales-Footnote-21090608
-Ref: Ranges and Locales-Footnote-31090842
-Node: Contributors1091063
-Node: History summary1096604
-Node: Installation1097974
-Node: Gawk Distribution1098920
-Node: Getting1099404
-Node: Extracting1100227
-Node: Distribution contents1101862
-Node: Unix Installation1107927
-Node: Quick Installation1108610
-Node: Shell Startup Files1111021
-Node: Additional Configuration Options1112100
-Node: Configuration Philosophy1113839
-Node: Non-Unix Installation1116208
-Node: PC Installation1116666
-Node: PC Binary Installation1117985
-Node: PC Compiling1119833
-Ref: PC Compiling-Footnote-11122854
-Node: PC Testing1122963
-Node: PC Using1124139
-Node: Cygwin1128254
-Node: MSYS1129077
-Node: VMS Installation1129577
-Node: VMS Compilation1130369
-Ref: VMS Compilation-Footnote-11131591
-Node: VMS Dynamic Extensions1131649
-Node: VMS Installation Details1133333
-Node: VMS Running1135585
-Node: VMS GNV1138421
-Node: VMS Old Gawk1139155
-Node: Bugs1139625
-Node: Other Versions1143508
-Node: Installation summary1149936
-Node: Notes1150992
-Node: Compatibility Mode1151857
-Node: Additions1152639
-Node: Accessing The Source1153564
-Node: Adding Code1155000
-Node: New Ports1161165
-Node: Derived Files1165647
-Ref: Derived Files-Footnote-11171122
-Ref: Derived Files-Footnote-21171156
-Ref: Derived Files-Footnote-31171752
-Node: Future Extensions1171866
-Node: Implementation Limitations1172472
-Node: Extension Design1173720
-Node: Old Extension Problems1174874
-Ref: Old Extension Problems-Footnote-11176391
-Node: Extension New Mechanism Goals1176448
-Ref: Extension New Mechanism Goals-Footnote-11179808
-Node: Extension Other Design Decisions1179997
-Node: Extension Future Growth1182105
-Node: Old Extension Mechanism1182941
-Node: Notes summary1184703
-Node: Basic Concepts1185889
-Node: Basic High Level1186570
-Ref: figure-general-flow1186842
-Ref: figure-process-flow1187441
-Ref: Basic High Level-Footnote-11190670
-Node: Basic Data Typing1190855
-Node: Glossary1194183
-Node: Copying1219341
-Node: GNU Free Documentation License1256897
-Node: Index1282033
+Node: Extension API Variables1002472
+Node: Extension Versioning1003105
+Node: Extension API Informational Variables1005006
+Node: Extension API Boilerplate1006071
+Node: Finding Extensions1009880
+Node: Extension Example1010440
+Node: Internal File Description1011212
+Node: Internal File Ops1015279
+Ref: Internal File Ops-Footnote-11026949
+Node: Using Internal File Ops1027089
+Ref: Using Internal File Ops-Footnote-11029472
+Node: Extension Samples1029745
+Node: Extension Sample File Functions1031271
+Node: Extension Sample Fnmatch1038909
+Node: Extension Sample Fork1040400
+Node: Extension Sample Inplace1041615
+Node: Extension Sample Ord1043290
+Node: Extension Sample Readdir1044126
+Ref: table-readdir-file-types1045002
+Node: Extension Sample Revout1045813
+Node: Extension Sample Rev2way1046403
+Node: Extension Sample Read write array1047143
+Node: Extension Sample Readfile1049083
+Node: Extension Sample Time1050178
+Node: Extension Sample API Tests1051527
+Node: gawkextlib1052018
+Node: Extension summary1054676
+Node: Extension Exercises1058365
+Node: Language History1059087
+Node: V7/SVR3.11060743
+Node: SVR41062924
+Node: POSIX1064369
+Node: BTL1065758
+Node: POSIX/GNU1066492
+Node: Feature History1072116
+Node: Common Extensions1085214
+Node: Ranges and Locales1086538
+Ref: Ranges and Locales-Footnote-11091156
+Ref: Ranges and Locales-Footnote-21091183
+Ref: Ranges and Locales-Footnote-31091417
+Node: Contributors1091638
+Node: History summary1097179
+Node: Installation1098549
+Node: Gawk Distribution1099495
+Node: Getting1099979
+Node: Extracting1100802
+Node: Distribution contents1102437
+Node: Unix Installation1108502
+Node: Quick Installation1109185
+Node: Shell Startup Files1111596
+Node: Additional Configuration Options1112675
+Node: Configuration Philosophy1114414
+Node: Non-Unix Installation1116783
+Node: PC Installation1117241
+Node: PC Binary Installation1118560
+Node: PC Compiling1120408
+Ref: PC Compiling-Footnote-11123429
+Node: PC Testing1123538
+Node: PC Using1124714
+Node: Cygwin1128829
+Node: MSYS1129652
+Node: VMS Installation1130152
+Node: VMS Compilation1130944
+Ref: VMS Compilation-Footnote-11132166
+Node: VMS Dynamic Extensions1132224
+Node: VMS Installation Details1133908
+Node: VMS Running1136160
+Node: VMS GNV1138996
+Node: VMS Old Gawk1139730
+Node: Bugs1140200
+Node: Other Versions1144083
+Node: Installation summary1150511
+Node: Notes1151567
+Node: Compatibility Mode1152432
+Node: Additions1153214
+Node: Accessing The Source1154139
+Node: Adding Code1155575
+Node: New Ports1161740
+Node: Derived Files1166222
+Ref: Derived Files-Footnote-11171697
+Ref: Derived Files-Footnote-21171731
+Ref: Derived Files-Footnote-31172327
+Node: Future Extensions1172441
+Node: Implementation Limitations1173047
+Node: Extension Design1174295
+Node: Old Extension Problems1175449
+Ref: Old Extension Problems-Footnote-11176966
+Node: Extension New Mechanism Goals1177023
+Ref: Extension New Mechanism Goals-Footnote-11180383
+Node: Extension Other Design Decisions1180572
+Node: Extension Future Growth1182680
+Node: Old Extension Mechanism1183516
+Node: Notes summary1185278
+Node: Basic Concepts1186464
+Node: Basic High Level1187145
+Ref: figure-general-flow1187417
+Ref: figure-process-flow1188016
+Ref: Basic High Level-Footnote-11191245
+Node: Basic Data Typing1191430
+Node: Glossary1194758
+Node: Copying1219916
+Node: GNU Free Documentation License1257472
+Node: Index1282608
 
 End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index dc9087ba..7c346a3a 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -33856,6 +33856,14 @@ A pipe opened for input.
 @item |&
 A two-way coprocess.
 @end table
+On error, a @code{false} value is returned.  Otherwise, the return status
+is @code{true}, and additional information about the redirection is
+returned in the @code{ibufp} and @code{obufp} pointers.  For input redirections,
+the @code{*ibufp} value should be non-NULL, and @code{*obufp} should be NULL.
+For output redirections,
+the @code{*obufp} value should be non-NULL, and @code{*ibufp} should be NULL.
+For two-way coprocesses, both values should be non-NULL.  In the usual case,
+the extension is interested in @code{(*ibufp)->fd} and/or @code{fileno((*obufp)->fp)}.
 If the file is not already open, and the fd argument is non-negative,
 @command{gawk} will use that file descriptor instead of opening the file
 in the usual way.  If the fd is non-negative, but the file exists
@@ -33869,8 +33877,8 @@ Note that in the two-way case, the input and output file descriptors
 may differ.  To check for success, one must check whether either matches.
 @end table
 
-For example, this API function can be used to implement I/O multiplexing or a
-socket library.
+It is anticipated that this API function will be used to implement I/O
+multiplexing and a socket library.
 
 @node Extension API Variables
 @subsection API Variables
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index 85a1d83c..385874a7 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -32949,6 +32949,14 @@ A pipe opened for input.
 @item |&
 A two-way coprocess.
 @end table
+On error, a @code{false} value is returned.  Otherwise, the return status
+is @code{true}, and additional information about the redirection is
+returned in the @code{ibufp} and @code{obufp} pointers.  For input redirections,
+the @code{*ibufp} value should be non-NULL, and @code{*obufp} should be NULL.
+For output redirections,
+the @code{*obufp} value should be non-NULL, and @code{*ibufp} should be NULL.
+For two-way coprocesses, both values should be non-NULL.  In the usual case,
+the extension is interested in @code{(*ibufp)->fd} and/or @code{fileno((*obufp)->fp)}.
 If the file is not already open, and the fd argument is non-negative,
 @command{gawk} will use that file descriptor instead of opening the file
 in the usual way.  If the fd is non-negative, but the file exists
@@ -32962,8 +32970,8 @@ Note that in the two-way case, the input and output file descriptors
 may differ.  To check for success, one must check whether either matches.
 @end table
 
-For example, this API function can be used to implement I/O multiplexing or a
-socket library.
+It is anticipated that this API function will be used to implement I/O
+multiplexing and a socket library.
 
 @node Extension API Variables
 @subsection API Variables