[gawk-diffs] [SCM] gawk branch, select, updated. gawk-4.1.0-1064-g4e952ae

[Andrew J. Schorr]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "gawk".

The branch, select has been updated
       via  4e952aea89bbfaecd12614f1249c830aff36c551 (commit)
      from  66c827a4607fa11c5c3d26eb8e3a4d63c2b05bef (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
http://git.sv.gnu.org/cgit/gawk.git/commit/?id=4e952aea89bbfaecd12614f1249c830aff36c551

commit 4e952aea89bbfaecd12614f1249c830aff36c551
Author: Andrew J. Schorr <address@hidden>
Date:   Mon Jan 5 14:37:56 2015 -0500

    Improve texinfo documentation of the get_file API function.

diff --git a/doc/ChangeLog b/doc/ChangeLog
index a995b66..4a6fa08 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,5 +1,9 @@
 2015-01-05         Andrew J. Schorr     <address@hidden>
 
+       * gawktexi.in: Improve get_file documentation.
+
+2015-01-05         Andrew J. Schorr     <address@hidden>
+
        * 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 60e0f6f..f0a9d84 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 dc9087b..7c346a3 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 85a1d83..385874a 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

-----------------------------------------------------------------------

Summary of changes:
 doc/ChangeLog   |    4 +
 doc/gawk.info   |  246 ++++++++++++++++++++++++++++---------------------------
 doc/gawk.texi   |   12 ++-
 doc/gawktexi.in |   12 ++-
 4 files changed, 151 insertions(+), 123 deletions(-)


hooks/post-receive
-- 
gawk