Document the new get_file API function in gawktexi.in.

6 files changed, 741 insertions, 564 deletions

diff --git a/ChangeLog b/ChangeLog
index c93bd631..eb7555f2 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,9 @@
 2015-01-04         Andrew J. Schorr     <aschorr@telemetry-investments.com>
 
+	* gawkapi.h: Fix another comment typo.
+
+2015-01-04         Andrew J. Schorr     <aschorr@telemetry-investments.com>
+
 	* gawkapi.h: Fix typo in comment.
 
 2015-01-02         Andrew J. Schorr     <aschorr@telemetry-investments.com>
diff --git a/doc/ChangeLog b/doc/ChangeLog
index 31bcecce..de948bda 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,5 +1,9 @@
 2015-01-04         Andrew J. Schorr     <aschorr@telemetry-investments.com>
 
+	* gawktexi.in: Document the get_file API function.
+
+2015-01-04         Andrew J. Schorr     <aschorr@telemetry-investments.com>
+
 	* gawk.1: Document new features PROCINFO["errno"] and
 	PROCINFO["input", "RETRY"], and new getline return value of -2.
 	* gawktexi.in: Ditto.
diff --git a/doc/gawk.info b/doc/gawk.info
index 02b59b92..9513e5d6 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -558,6 +558,7 @@ entitled "GNU Free Documentation License".
 * Array Functions::                     Functions for working with arrays.
 * Flattening Arrays::                   How to flatten arrays.
 * Creating Arrays::                     How to create and populate arrays.
+* Redirection API::                     How to access and manipulate redirections.
 * Extension API Variables::             Variables provided by the API.
 * Extension Versioning::                API Version information.
 * Extension API Informational Variables:: Variables providing information about
@@ -22922,6 +22923,7 @@ describes the API in detail.
 * Symbol Table Access::                  Functions for accessing global
                                          variables.
 * Array Manipulation::                   Functions for working with arrays.
+* Redirection API::                      How to access and manipulate redirections.
 * Extension API Variables::              Variables provided by the API.
 * Extension API Boilerplate::            Boilerplate code for using the API.
 
@@ -22982,6 +22984,9 @@ operations:
         - Flattening an array for easy C style looping over all its
           indices and elements
 
+   * Accessing and manipulating redirections.
+
+
    Some points about using the API:
 
    * The following types, macros, and/or functions are referenced in
@@ -24188,7 +24193,7 @@ using `release_value()'.
 `double' to store.
 
 
-File: gawk.info,  Node: Array Manipulation,  Next: Extension API Variables,  Prev: Symbol Table Access,  Up: Extension API Description
+File: gawk.info,  Node: Array Manipulation,  Next: Redirection API,  Prev: Symbol Table Access,  Up: Extension API Description
 
 16.4.11 Array Manipulation
 --------------------------
@@ -24673,9 +24678,64 @@ array:
 environment variable.)
 
 
-File: gawk.info,  Node: Extension API Variables,  Next: Extension API Boilerplate,  Prev: Array Manipulation,  Up: Extension API Description
-
-16.4.12 API Variables
+File: gawk.info,  Node: Redirection API,  Next: Extension API Variables,  Prev: Array Manipulation,  Up: Extension API Description
+
+16.4.12 Accessing and Manipulating Redirections
+-----------------------------------------------
+
+The following function allows extensions to access and manipulate
+redirections.
+
+`awk_bool_t get_file(const char *name,'
+`                    size_t name_len,'
+`                    const char *filetype,'
+`                    int fd,'
+`                    const awk_input_buf_t **ibufp,'
+`                    const awk_output_buf_t **obufp);'
+     Look up a file in `gawk''s internal redirection table.  If `name'
+     is NULL or `name_len' is 0, it returns data for the currently open
+     input file corresponding to `FILENAME' (and it will not access the
+     `filetype' argument, so that may be undefined).  If the file is
+     not already open, it tries to open it.  The `filetype' argument
+     must be NUL-terminated and should be one of:
+    `>'
+          A file opened for output.
+
+    `>>'
+          A file opened for append.
+
+    `<'
+          A file opened for input.
+
+    `|>'
+          A pipe opened for output.
+
+    `|<'
+          A pipe opened for input.
+
+    `|&'
+          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.
+
+
+File: gawk.info,  Node: Extension API Variables,  Next: Extension API Boilerplate,  Prev: Redirection API,  Up: Extension API Description
+
+16.4.13 API Variables
 ---------------------
 
 The API provides two sets of variables.  The first provides information
@@ -24692,7 +24752,7 @@ information about how `gawk' was invoked.
 
 File: gawk.info,  Node: Extension Versioning,  Next: Extension API Informational Variables,  Up: Extension API Variables
 
-16.4.12.1 API Version Constants and Variables
+16.4.13.1 API Version Constants and Variables
 .............................................
 
 The API provides both a "major" and a "minor" version number.  The API
@@ -24741,7 +24801,7 @@ Boilerplate::).
 
 File: gawk.info,  Node: Extension API Informational Variables,  Prev: Extension Versioning,  Up: Extension API Variables
 
-16.4.12.2 Informational Variables
+16.4.13.2 Informational Variables
 .................................
 
 The API provides access to several variables that describe whether the
@@ -24776,7 +24836,7 @@ not change during execution.
 
 File: gawk.info,  Node: Extension API Boilerplate,  Prev: Extension API Variables,  Up: Extension API Description
 
-16.4.13 Boilerplate Code
+16.4.14 Boilerplate Code
 ------------------------
 
 As mentioned earlier (*note Extension Mechanism Outline::), the function
@@ -34502,561 +34562,562 @@ Index
 
 Tag Table:
 Node: Top1204
-Node: Foreword342300
-Node: Foreword446742
-Node: Preface48264
-Ref: Preface-Footnote-151135
-Ref: Preface-Footnote-251242
-Ref: Preface-Footnote-351475
-Node: History51617
-Node: Names53963
-Ref: Names-Footnote-155057
-Node: This Manual55203
-Ref: This Manual-Footnote-161690
-Node: Conventions61790
-Node: Manual History64128
-Ref: Manual History-Footnote-167110
-Ref: Manual History-Footnote-267151
-Node: How To Contribute67225
-Node: Acknowledgments68354
-Node: Getting Started73159
-Node: Running gawk75592
-Node: One-shot76782
-Node: Read Terminal78030
-Node: Long80057
-Node: Executable Scripts81573
-Ref: Executable Scripts-Footnote-184362
-Node: Comments84465
-Node: Quoting86947
-Node: DOS Quoting92471
-Node: Sample Data Files93146
-Node: Very Simple95741
-Node: Two Rules100639
-Node: More Complex102525
-Node: Statements/Lines105387
-Ref: Statements/Lines-Footnote-1109842
-Node: Other Features110107
-Node: When111038
-Ref: When-Footnote-1112792
-Node: Intro Summary112857
-Node: Invoking Gawk113740
-Node: Command Line115254
-Node: Options116052
-Ref: Options-Footnote-1131856
-Ref: Options-Footnote-2132085
-Node: Other Arguments132110
-Node: Naming Standard Input135058
-Node: Environment Variables136151
-Node: AWKPATH Variable136709
-Ref: AWKPATH Variable-Footnote-1140122
-Ref: AWKPATH Variable-Footnote-2140167
-Node: AWKLIBPATH Variable140427
-Node: Other Environment Variables141683
-Node: Exit Status145171
-Node: Include Files145847
-Node: Loading Shared Libraries149444
-Node: Obsolete150871
-Node: Undocumented151568
-Node: Invoking Summary151835
-Node: Regexp153499
-Node: Regexp Usage154953
-Node: Escape Sequences156990
-Node: Regexp Operators163231
-Ref: Regexp Operators-Footnote-1170657
-Ref: Regexp Operators-Footnote-2170804
-Node: Bracket Expressions170902
-Ref: table-char-classes172917
-Node: Leftmost Longest175841
-Node: Computed Regexps177143
-Node: GNU Regexp Operators180540
-Node: Case-sensitivity184213
-Ref: Case-sensitivity-Footnote-1187098
-Ref: Case-sensitivity-Footnote-2187333
-Node: Regexp Summary187441
-Node: Reading Files188908
-Node: Records191069
-Node: awk split records191802
-Node: gawk split records196717
-Ref: gawk split records-Footnote-1201261
-Node: Fields201298
-Ref: Fields-Footnote-1204074
-Node: Nonconstant Fields204160
-Ref: Nonconstant Fields-Footnote-1206403
-Node: Changing Fields206607
-Node: Field Separators212536
-Node: Default Field Splitting215241
-Node: Regexp Field Splitting216358
-Node: Single Character Fields219708
-Node: Command Line Field Separator220767
-Node: Full Line Fields223979
-Ref: Full Line Fields-Footnote-1225496
-Ref: Full Line Fields-Footnote-2225542
-Node: Field Splitting Summary225643
-Node: Constant Size227717
-Node: Splitting By Content232306
-Ref: Splitting By Content-Footnote-1236300
-Node: Multiple Line236463
-Ref: Multiple Line-Footnote-1242349
-Node: Getline242528
-Node: Plain Getline245010
-Node: Getline/Variable247650
-Node: Getline/File248798
-Node: Getline/Variable/File250182
-Ref: Getline/Variable/File-Footnote-1251785
-Node: Getline/Pipe251872
-Node: Getline/Variable/Pipe254555
-Node: Getline/Coprocess255686
-Node: Getline/Variable/Coprocess256938
-Node: Getline Notes257677
-Node: Getline Summary260469
-Ref: table-getline-variants260881
-Node: Read Timeout261710
-Ref: Read Timeout-Footnote-1265597
-Node: Retrying I/O265655
-Node: Command-line directories266838
-Node: Input Summary267743
-Node: Input Exercises271044
-Node: Printing271772
-Node: Print273549
-Node: Print Examples275006
-Node: Output Separators277785
-Node: OFMT279803
-Node: Printf281157
-Node: Basic Printf281942
-Node: Control Letters283512
-Node: Format Modifiers287495
-Node: Printf Examples293504
-Node: Redirection295990
-Node: Special FD302831
-Ref: Special FD-Footnote-1305991
-Node: Special Files306065
-Node: Other Inherited Files306682
-Node: Special Network307682
-Node: Special Caveats308544
-Node: Close Files And Pipes309495
-Ref: Close Files And Pipes-Footnote-1316677
-Ref: Close Files And Pipes-Footnote-2316825
-Node: Output Summary316975
-Node: Output Exercises317973
-Node: Expressions318653
-Node: Values319838
-Node: Constants320516
-Node: Scalar Constants321207
-Ref: Scalar Constants-Footnote-1322066
-Node: Nondecimal-numbers322316
-Node: Regexp Constants325334
-Node: Using Constant Regexps325859
-Node: Variables329002
-Node: Using Variables329657
-Node: Assignment Options331568
-Node: Conversion333443
-Node: Strings And Numbers333967
-Ref: Strings And Numbers-Footnote-1337032
-Node: Locale influences conversions337141
-Ref: table-locale-affects339888
-Node: All Operators340476
-Node: Arithmetic Ops341106
-Node: Concatenation343611
-Ref: Concatenation-Footnote-1346430
-Node: Assignment Ops346536
-Ref: table-assign-ops351515
-Node: Increment Ops352787
-Node: Truth Values and Conditions356225
-Node: Truth Values357310
-Node: Typing and Comparison358359
-Node: Variable Typing359169
-Node: Comparison Operators362822
-Ref: table-relational-ops363232
-Node: POSIX String Comparison366727
-Ref: POSIX String Comparison-Footnote-1367799
-Node: Boolean Ops367937
-Ref: Boolean Ops-Footnote-1372416
-Node: Conditional Exp372507
-Node: Function Calls374234
-Node: Precedence378114
-Node: Locales381775
-Node: Expressions Summary383407
-Node: Patterns and Actions385967
-Node: Pattern Overview387087
-Node: Regexp Patterns388766
-Node: Expression Patterns389309
-Node: Ranges393019
-Node: BEGIN/END396125
-Node: Using BEGIN/END396886
-Ref: Using BEGIN/END-Footnote-1399620
-Node: I/O And BEGIN/END399726
-Node: BEGINFILE/ENDFILE402040
-Node: Empty404941
-Node: Using Shell Variables405258
-Node: Action Overview407531
-Node: Statements409857
-Node: If Statement411705
-Node: While Statement413200
-Node: Do Statement415229
-Node: For Statement416373
-Node: Switch Statement419530
-Node: Break Statement421912
-Node: Continue Statement423953
-Node: Next Statement425780
-Node: Nextfile Statement428161
-Node: Exit Statement430791
-Node: Built-in Variables433194
-Node: User-modified434327
-Ref: User-modified-Footnote-1442008
-Node: Auto-set442070
-Ref: Auto-set-Footnote-1456282
-Ref: Auto-set-Footnote-2456487
-Node: ARGC and ARGV456543
-Node: Pattern Action Summary460761
-Node: Arrays463188
-Node: Array Basics464517
-Node: Array Intro465361
-Ref: figure-array-elements467325
-Ref: Array Intro-Footnote-1469851
-Node: Reference to Elements469979
-Node: Assigning Elements472431
-Node: Array Example472922
-Node: Scanning an Array474680
-Node: Controlling Scanning477696
-Ref: Controlling Scanning-Footnote-1482892
-Node: Numeric Array Subscripts483208
-Node: Uninitialized Subscripts485393
-Node: Delete487010
-Ref: Delete-Footnote-1489753
-Node: Multidimensional489810
-Node: Multiscanning492907
-Node: Arrays of Arrays494496
-Node: Arrays Summary499255
-Node: Functions501347
-Node: Built-in502246
-Node: Calling Built-in503324
-Node: Numeric Functions505315
-Ref: Numeric Functions-Footnote-1510134
-Ref: Numeric Functions-Footnote-2510491
-Ref: Numeric Functions-Footnote-3510539
-Node: String Functions510811
-Ref: String Functions-Footnote-1534286
-Ref: String Functions-Footnote-2534415
-Ref: String Functions-Footnote-3534663
-Node: Gory Details534750
-Ref: table-sub-escapes536531
-Ref: table-sub-proposed538051
-Ref: table-posix-sub539415
-Ref: table-gensub-escapes540951
-Ref: Gory Details-Footnote-1541783
-Node: I/O Functions541934
-Ref: I/O Functions-Footnote-1549152
-Node: Time Functions549299
-Ref: Time Functions-Footnote-1559787
-Ref: Time Functions-Footnote-2559855
-Ref: Time Functions-Footnote-3560013
-Ref: Time Functions-Footnote-4560124
-Ref: Time Functions-Footnote-5560236
-Ref: Time Functions-Footnote-6560463
-Node: Bitwise Functions560729
-Ref: table-bitwise-ops561291
-Ref: Bitwise Functions-Footnote-1565600
-Node: Type Functions565769
-Node: I18N Functions566920
-Node: User-defined568565
-Node: Definition Syntax569370
-Ref: Definition Syntax-Footnote-1574777
-Node: Function Example574848
-Ref: Function Example-Footnote-1577767
-Node: Function Caveats577789
-Node: Calling A Function578307
-Node: Variable Scope579265
-Node: Pass By Value/Reference582253
-Node: Return Statement585748
-Node: Dynamic Typing588729
-Node: Indirect Calls589658
-Ref: Indirect Calls-Footnote-1600960
-Node: Functions Summary601088
-Node: Library Functions603790
-Ref: Library Functions-Footnote-1607399
-Ref: Library Functions-Footnote-2607542
-Node: Library Names607713
-Ref: Library Names-Footnote-1611167
-Ref: Library Names-Footnote-2611390
-Node: General Functions611476
-Node: Strtonum Function612579
-Node: Assert Function615601
-Node: Round Function618925
-Node: Cliff Random Function620466
-Node: Ordinal Functions621482
-Ref: Ordinal Functions-Footnote-1624545
-Ref: Ordinal Functions-Footnote-2624797
-Node: Join Function625008
-Ref: Join Function-Footnote-1626777
-Node: Getlocaltime Function626977
-Node: Readfile Function630721
-Node: Shell Quoting632691
-Node: Data File Management634092
-Node: Filetrans Function634724
-Node: Rewind Function638780
-Node: File Checking640167
-Ref: File Checking-Footnote-1641499
-Node: Empty Files641700
-Node: Ignoring Assigns643679
-Node: Getopt Function645230
-Ref: Getopt Function-Footnote-1656692
-Node: Passwd Functions656892
-Ref: Passwd Functions-Footnote-1665729
-Node: Group Functions665817
-Ref: Group Functions-Footnote-1673711
-Node: Walking Arrays673924
-Node: Library Functions Summary675527
-Node: Library Exercises676928
-Node: Sample Programs678208
-Node: Running Examples678978
-Node: Clones679706
-Node: Cut Program680930
-Node: Egrep Program690649
-Ref: Egrep Program-Footnote-1698147
-Node: Id Program698257
-Node: Split Program701902
-Ref: Split Program-Footnote-1705350
-Node: Tee Program705478
-Node: Uniq Program708267
-Node: Wc Program715686
-Ref: Wc Program-Footnote-1719936
-Node: Miscellaneous Programs720030
-Node: Dupword Program721243
-Node: Alarm Program723274
-Node: Translate Program728078
-Ref: Translate Program-Footnote-1732643
-Node: Labels Program732913
-Ref: Labels Program-Footnote-1736264
-Node: Word Sorting736348
-Node: History Sorting740419
-Node: Extract Program742255
-Node: Simple Sed749780
-Node: Igawk Program752848
-Ref: Igawk Program-Footnote-1767172
-Ref: Igawk Program-Footnote-2767373
-Ref: Igawk Program-Footnote-3767495
-Node: Anagram Program767610
-Node: Signature Program770667
-Node: Programs Summary771914
-Node: Programs Exercises773107
-Ref: Programs Exercises-Footnote-1777238
-Node: Advanced Features777329
-Node: Nondecimal Data779277
-Node: Array Sorting780867
-Node: Controlling Array Traversal781564
-Ref: Controlling Array Traversal-Footnote-1789897
-Node: Array Sorting Functions790015
-Ref: Array Sorting Functions-Footnote-1793904
-Node: Two-way I/O794100
-Ref: Two-way I/O-Footnote-1799045
-Ref: Two-way I/O-Footnote-2799231
-Node: TCP/IP Networking799313
-Node: Profiling802186
-Node: Advanced Features Summary810463
-Node: Internationalization812396
-Node: I18N and L10N813876
-Node: Explaining gettext814562
-Ref: Explaining gettext-Footnote-1819587
-Ref: Explaining gettext-Footnote-2819771
-Node: Programmer i18n819936
-Ref: Programmer i18n-Footnote-1824802
-Node: Translator i18n824851
-Node: String Extraction825645
-Ref: String Extraction-Footnote-1826776
-Node: Printf Ordering826862
-Ref: Printf Ordering-Footnote-1829648
-Node: I18N Portability829712
-Ref: I18N Portability-Footnote-1832167
-Node: I18N Example832230
-Ref: I18N Example-Footnote-1835033
-Node: Gawk I18N835105
-Node: I18N Summary835743
-Node: Debugger837082
-Node: Debugging838104
-Node: Debugging Concepts838545
-Node: Debugging Terms840398
-Node: Awk Debugging842970
-Node: Sample Debugging Session843864
-Node: Debugger Invocation844384
-Node: Finding The Bug845768
-Node: List of Debugger Commands852243
-Node: Breakpoint Control853576
-Node: Debugger Execution Control857272
-Node: Viewing And Changing Data860636
-Node: Execution Stack864014
-Node: Debugger Info865651
-Node: Miscellaneous Debugger Commands869668
-Node: Readline Support874697
-Node: Limitations875589
-Node: Debugging Summary877703
-Node: Arbitrary Precision Arithmetic878871
-Node: Computer Arithmetic880287
-Ref: table-numeric-ranges883885
-Ref: Computer Arithmetic-Footnote-1884744
-Node: Math Definitions884801
-Ref: table-ieee-formats888089
-Ref: Math Definitions-Footnote-1888693
-Node: MPFR features888798
-Node: FP Math Caution890469
-Ref: FP Math Caution-Footnote-1891519
-Node: Inexactness of computations891888
-Node: Inexact representation892847
-Node: Comparing FP Values894204
-Node: Errors accumulate895286
-Node: Getting Accuracy896719
-Node: Try To Round899381
-Node: Setting precision900280
-Ref: table-predefined-precision-strings900964
-Node: Setting the rounding mode902753
-Ref: table-gawk-rounding-modes903117
-Ref: Setting the rounding mode-Footnote-1906572
-Node: Arbitrary Precision Integers906751
-Ref: Arbitrary Precision Integers-Footnote-1911650
-Node: POSIX Floating Point Problems911799
-Ref: POSIX Floating Point Problems-Footnote-1915672
-Node: Floating point summary915710
-Node: Dynamic Extensions917904
-Node: Extension Intro919456
-Node: Plugin License920722
-Node: Extension Mechanism Outline921519
-Ref: figure-load-extension921947
-Ref: figure-register-new-function923427
-Ref: figure-call-new-function924431
-Node: Extension API Description926417
-Node: Extension API Functions Introduction927867
-Node: General Data Types932691
-Ref: General Data Types-Footnote-1938430
-Node: Memory Allocation Functions938729
-Ref: Memory Allocation Functions-Footnote-1941568
-Node: Constructor Functions941664
-Node: Registration Functions943398
-Node: Extension Functions944083
-Node: Exit Callback Functions946380
-Node: Extension Version String947628
-Node: Input Parsers948293
-Node: Output Wrappers958172
-Node: Two-way processors962687
-Node: Printing Messages964891
-Ref: Printing Messages-Footnote-1965967
-Node: Updating `ERRNO'966119
-Node: Requesting Values966859
-Ref: table-value-types-returned967587
-Node: Accessing Parameters968544
-Node: Symbol Table Access969775
-Node: Symbol table by name970289
-Node: Symbol table by cookie972270
-Ref: Symbol table by cookie-Footnote-1976414
-Node: Cached values976477
-Ref: Cached values-Footnote-1979976
-Node: Array Manipulation980067
-Ref: Array Manipulation-Footnote-1981165
-Node: Array Data Types981202
-Ref: Array Data Types-Footnote-1983857
-Node: Array Functions983949
-Node: Flattening Arrays987803
-Node: Creating Arrays994695
-Node: Extension API Variables999466
-Node: Extension Versioning1000102
-Node: Extension API Informational Variables1002003
-Node: Extension API Boilerplate1003068
-Node: Finding Extensions1006877
-Node: Extension Example1007437
-Node: Internal File Description1008209
-Node: Internal File Ops1012276
-Ref: Internal File Ops-Footnote-11023946
-Node: Using Internal File Ops1024086
-Ref: Using Internal File Ops-Footnote-11026469
-Node: Extension Samples1026742
-Node: Extension Sample File Functions1028268
-Node: Extension Sample Fnmatch1035906
-Node: Extension Sample Fork1037397
-Node: Extension Sample Inplace1038612
-Node: Extension Sample Ord1040287
-Node: Extension Sample Readdir1041123
-Ref: table-readdir-file-types1041999
-Node: Extension Sample Revout1042810
-Node: Extension Sample Rev2way1043400
-Node: Extension Sample Read write array1044140
-Node: Extension Sample Readfile1046080
-Node: Extension Sample Time1047175
-Node: Extension Sample API Tests1048524
-Node: gawkextlib1049015
-Node: Extension summary1051673
-Node: Extension Exercises1055362
-Node: Language History1056084
-Node: V7/SVR3.11057740
-Node: SVR41059921
-Node: POSIX1061366
-Node: BTL1062755
-Node: POSIX/GNU1063489
-Node: Feature History1069113
-Node: Common Extensions1082211
-Node: Ranges and Locales1083535
-Ref: Ranges and Locales-Footnote-11088153
-Ref: Ranges and Locales-Footnote-21088180
-Ref: Ranges and Locales-Footnote-31088414
-Node: Contributors1088635
-Node: History summary1094176
-Node: Installation1095546
-Node: Gawk Distribution1096492
-Node: Getting1096976
-Node: Extracting1097799
-Node: Distribution contents1099434
-Node: Unix Installation1105499
-Node: Quick Installation1106182
-Node: Shell Startup Files1108593
-Node: Additional Configuration Options1109672
-Node: Configuration Philosophy1111411
-Node: Non-Unix Installation1113780
-Node: PC Installation1114238
-Node: PC Binary Installation1115557
-Node: PC Compiling1117405
-Ref: PC Compiling-Footnote-11120426
-Node: PC Testing1120535
-Node: PC Using1121711
-Node: Cygwin1125826
-Node: MSYS1126649
-Node: VMS Installation1127149
-Node: VMS Compilation1127941
-Ref: VMS Compilation-Footnote-11129163
-Node: VMS Dynamic Extensions1129221
-Node: VMS Installation Details1130905
-Node: VMS Running1133157
-Node: VMS GNV1135993
-Node: VMS Old Gawk1136727
-Node: Bugs1137197
-Node: Other Versions1141080
-Node: Installation summary1147508
-Node: Notes1148564
-Node: Compatibility Mode1149429
-Node: Additions1150211
-Node: Accessing The Source1151136
-Node: Adding Code1152572
-Node: New Ports1158737
-Node: Derived Files1163219
-Ref: Derived Files-Footnote-11168694
-Ref: Derived Files-Footnote-21168728
-Ref: Derived Files-Footnote-31169324
-Node: Future Extensions1169438
-Node: Implementation Limitations1170044
-Node: Extension Design1171292
-Node: Old Extension Problems1172446
-Ref: Old Extension Problems-Footnote-11173963
-Node: Extension New Mechanism Goals1174020
-Ref: Extension New Mechanism Goals-Footnote-11177380
-Node: Extension Other Design Decisions1177569
-Node: Extension Future Growth1179677
-Node: Old Extension Mechanism1180513
-Node: Notes summary1182275
-Node: Basic Concepts1183461
-Node: Basic High Level1184142
-Ref: figure-general-flow1184414
-Ref: figure-process-flow1185013
-Ref: Basic High Level-Footnote-11188242
-Node: Basic Data Typing1188427
-Node: Glossary1191755
-Node: Copying1216913
-Node: GNU Free Documentation License1254469
-Node: Index1279605
+Node: Foreword342383
+Node: Foreword446825
+Node: Preface48347
+Ref: Preface-Footnote-151218
+Ref: Preface-Footnote-251325
+Ref: Preface-Footnote-351558
+Node: History51700
+Node: Names54046
+Ref: Names-Footnote-155140
+Node: This Manual55286
+Ref: This Manual-Footnote-161773
+Node: Conventions61873
+Node: Manual History64211
+Ref: Manual History-Footnote-167193
+Ref: Manual History-Footnote-267234
+Node: How To Contribute67308
+Node: Acknowledgments68437
+Node: Getting Started73242
+Node: Running gawk75675
+Node: One-shot76865
+Node: Read Terminal78113
+Node: Long80140
+Node: Executable Scripts81656
+Ref: Executable Scripts-Footnote-184445
+Node: Comments84548
+Node: Quoting87030
+Node: DOS Quoting92554
+Node: Sample Data Files93229
+Node: Very Simple95824
+Node: Two Rules100722
+Node: More Complex102608
+Node: Statements/Lines105470
+Ref: Statements/Lines-Footnote-1109925
+Node: Other Features110190
+Node: When111121
+Ref: When-Footnote-1112875
+Node: Intro Summary112940
+Node: Invoking Gawk113823
+Node: Command Line115337
+Node: Options116135
+Ref: Options-Footnote-1131939
+Ref: Options-Footnote-2132168
+Node: Other Arguments132193
+Node: Naming Standard Input135141
+Node: Environment Variables136234
+Node: AWKPATH Variable136792
+Ref: AWKPATH Variable-Footnote-1140205
+Ref: AWKPATH Variable-Footnote-2140250
+Node: AWKLIBPATH Variable140510
+Node: Other Environment Variables141766
+Node: Exit Status145254
+Node: Include Files145930
+Node: Loading Shared Libraries149527
+Node: Obsolete150954
+Node: Undocumented151651
+Node: Invoking Summary151918
+Node: Regexp153582
+Node: Regexp Usage155036
+Node: Escape Sequences157073
+Node: Regexp Operators163314
+Ref: Regexp Operators-Footnote-1170740
+Ref: Regexp Operators-Footnote-2170887
+Node: Bracket Expressions170985
+Ref: table-char-classes173000
+Node: Leftmost Longest175924
+Node: Computed Regexps177226
+Node: GNU Regexp Operators180623
+Node: Case-sensitivity184296
+Ref: Case-sensitivity-Footnote-1187181
+Ref: Case-sensitivity-Footnote-2187416
+Node: Regexp Summary187524
+Node: Reading Files188991
+Node: Records191152
+Node: awk split records191885
+Node: gawk split records196800
+Ref: gawk split records-Footnote-1201344
+Node: Fields201381
+Ref: Fields-Footnote-1204157
+Node: Nonconstant Fields204243
+Ref: Nonconstant Fields-Footnote-1206486
+Node: Changing Fields206690
+Node: Field Separators212619
+Node: Default Field Splitting215324
+Node: Regexp Field Splitting216441
+Node: Single Character Fields219791
+Node: Command Line Field Separator220850
+Node: Full Line Fields224062
+Ref: Full Line Fields-Footnote-1225579
+Ref: Full Line Fields-Footnote-2225625
+Node: Field Splitting Summary225726
+Node: Constant Size227800
+Node: Splitting By Content232389
+Ref: Splitting By Content-Footnote-1236383
+Node: Multiple Line236546
+Ref: Multiple Line-Footnote-1242432
+Node: Getline242611
+Node: Plain Getline245093
+Node: Getline/Variable247733
+Node: Getline/File248881
+Node: Getline/Variable/File250265
+Ref: Getline/Variable/File-Footnote-1251868
+Node: Getline/Pipe251955
+Node: Getline/Variable/Pipe254638
+Node: Getline/Coprocess255769
+Node: Getline/Variable/Coprocess257021
+Node: Getline Notes257760
+Node: Getline Summary260552
+Ref: table-getline-variants260964
+Node: Read Timeout261793
+Ref: Read Timeout-Footnote-1265680
+Node: Retrying I/O265738
+Node: Command-line directories266921
+Node: Input Summary267826
+Node: Input Exercises271127
+Node: Printing271855
+Node: Print273632
+Node: Print Examples275089
+Node: Output Separators277868
+Node: OFMT279886
+Node: Printf281240
+Node: Basic Printf282025
+Node: Control Letters283595
+Node: Format Modifiers287578
+Node: Printf Examples293587
+Node: Redirection296073
+Node: Special FD302914
+Ref: Special FD-Footnote-1306074
+Node: Special Files306148
+Node: Other Inherited Files306765
+Node: Special Network307765
+Node: Special Caveats308627
+Node: Close Files And Pipes309578
+Ref: Close Files And Pipes-Footnote-1316760
+Ref: Close Files And Pipes-Footnote-2316908
+Node: Output Summary317058
+Node: Output Exercises318056
+Node: Expressions318736
+Node: Values319921
+Node: Constants320599
+Node: Scalar Constants321290
+Ref: Scalar Constants-Footnote-1322149
+Node: Nondecimal-numbers322399
+Node: Regexp Constants325417
+Node: Using Constant Regexps325942
+Node: Variables329085
+Node: Using Variables329740
+Node: Assignment Options331651
+Node: Conversion333526
+Node: Strings And Numbers334050
+Ref: Strings And Numbers-Footnote-1337115
+Node: Locale influences conversions337224
+Ref: table-locale-affects339971
+Node: All Operators340559
+Node: Arithmetic Ops341189
+Node: Concatenation343694
+Ref: Concatenation-Footnote-1346513
+Node: Assignment Ops346619
+Ref: table-assign-ops351598
+Node: Increment Ops352870
+Node: Truth Values and Conditions356308
+Node: Truth Values357393
+Node: Typing and Comparison358442
+Node: Variable Typing359252
+Node: Comparison Operators362905
+Ref: table-relational-ops363315
+Node: POSIX String Comparison366810
+Ref: POSIX String Comparison-Footnote-1367882
+Node: Boolean Ops368020
+Ref: Boolean Ops-Footnote-1372499
+Node: Conditional Exp372590
+Node: Function Calls374317
+Node: Precedence378197
+Node: Locales381858
+Node: Expressions Summary383490
+Node: Patterns and Actions386050
+Node: Pattern Overview387170
+Node: Regexp Patterns388849
+Node: Expression Patterns389392
+Node: Ranges393102
+Node: BEGIN/END396208
+Node: Using BEGIN/END396969
+Ref: Using BEGIN/END-Footnote-1399703
+Node: I/O And BEGIN/END399809
+Node: BEGINFILE/ENDFILE402123
+Node: Empty405024
+Node: Using Shell Variables405341
+Node: Action Overview407614
+Node: Statements409940
+Node: If Statement411788
+Node: While Statement413283
+Node: Do Statement415312
+Node: For Statement416456
+Node: Switch Statement419613
+Node: Break Statement421995
+Node: Continue Statement424036
+Node: Next Statement425863
+Node: Nextfile Statement428244
+Node: Exit Statement430874
+Node: Built-in Variables433277
+Node: User-modified434410
+Ref: User-modified-Footnote-1442091
+Node: Auto-set442153
+Ref: Auto-set-Footnote-1456365
+Ref: Auto-set-Footnote-2456570
+Node: ARGC and ARGV456626
+Node: Pattern Action Summary460844
+Node: Arrays463271
+Node: Array Basics464600
+Node: Array Intro465444
+Ref: figure-array-elements467408
+Ref: Array Intro-Footnote-1469934
+Node: Reference to Elements470062
+Node: Assigning Elements472514
+Node: Array Example473005
+Node: Scanning an Array474763
+Node: Controlling Scanning477779
+Ref: Controlling Scanning-Footnote-1482975
+Node: Numeric Array Subscripts483291
+Node: Uninitialized Subscripts485476
+Node: Delete487093
+Ref: Delete-Footnote-1489836
+Node: Multidimensional489893
+Node: Multiscanning492990
+Node: Arrays of Arrays494579
+Node: Arrays Summary499338
+Node: Functions501430
+Node: Built-in502329
+Node: Calling Built-in503407
+Node: Numeric Functions505398
+Ref: Numeric Functions-Footnote-1510217
+Ref: Numeric Functions-Footnote-2510574
+Ref: Numeric Functions-Footnote-3510622
+Node: String Functions510894
+Ref: String Functions-Footnote-1534369
+Ref: String Functions-Footnote-2534498
+Ref: String Functions-Footnote-3534746
+Node: Gory Details534833
+Ref: table-sub-escapes536614
+Ref: table-sub-proposed538134
+Ref: table-posix-sub539498
+Ref: table-gensub-escapes541034
+Ref: Gory Details-Footnote-1541866
+Node: I/O Functions542017
+Ref: I/O Functions-Footnote-1549235
+Node: Time Functions549382
+Ref: Time Functions-Footnote-1559870
+Ref: Time Functions-Footnote-2559938
+Ref: Time Functions-Footnote-3560096
+Ref: Time Functions-Footnote-4560207
+Ref: Time Functions-Footnote-5560319
+Ref: Time Functions-Footnote-6560546
+Node: Bitwise Functions560812
+Ref: table-bitwise-ops561374
+Ref: Bitwise Functions-Footnote-1565683
+Node: Type Functions565852
+Node: I18N Functions567003
+Node: User-defined568648
+Node: Definition Syntax569453
+Ref: Definition Syntax-Footnote-1574860
+Node: Function Example574931
+Ref: Function Example-Footnote-1577850
+Node: Function Caveats577872
+Node: Calling A Function578390
+Node: Variable Scope579348
+Node: Pass By Value/Reference582336
+Node: Return Statement585831
+Node: Dynamic Typing588812
+Node: Indirect Calls589741
+Ref: Indirect Calls-Footnote-1601043
+Node: Functions Summary601171
+Node: Library Functions603873
+Ref: Library Functions-Footnote-1607482
+Ref: Library Functions-Footnote-2607625
+Node: Library Names607796
+Ref: Library Names-Footnote-1611250
+Ref: Library Names-Footnote-2611473
+Node: General Functions611559
+Node: Strtonum Function612662
+Node: Assert Function615684
+Node: Round Function619008
+Node: Cliff Random Function620549
+Node: Ordinal Functions621565
+Ref: Ordinal Functions-Footnote-1624628
+Ref: Ordinal Functions-Footnote-2624880
+Node: Join Function625091
+Ref: Join Function-Footnote-1626860
+Node: Getlocaltime Function627060
+Node: Readfile Function630804
+Node: Shell Quoting632774
+Node: Data File Management634175
+Node: Filetrans Function634807
+Node: Rewind Function638863
+Node: File Checking640250
+Ref: File Checking-Footnote-1641582
+Node: Empty Files641783
+Node: Ignoring Assigns643762
+Node: Getopt Function645313
+Ref: Getopt Function-Footnote-1656775
+Node: Passwd Functions656975
+Ref: Passwd Functions-Footnote-1665812
+Node: Group Functions665900
+Ref: Group Functions-Footnote-1673794
+Node: Walking Arrays674007
+Node: Library Functions Summary675610
+Node: Library Exercises677011
+Node: Sample Programs678291
+Node: Running Examples679061
+Node: Clones679789
+Node: Cut Program681013
+Node: Egrep Program690732
+Ref: Egrep Program-Footnote-1698230
+Node: Id Program698340
+Node: Split Program701985
+Ref: Split Program-Footnote-1705433
+Node: Tee Program705561
+Node: Uniq Program708350
+Node: Wc Program715769
+Ref: Wc Program-Footnote-1720019
+Node: Miscellaneous Programs720113
+Node: Dupword Program721326
+Node: Alarm Program723357
+Node: Translate Program728161
+Ref: Translate Program-Footnote-1732726
+Node: Labels Program732996
+Ref: Labels Program-Footnote-1736347
+Node: Word Sorting736431
+Node: History Sorting740502
+Node: Extract Program742338
+Node: Simple Sed749863
+Node: Igawk Program752931
+Ref: Igawk Program-Footnote-1767255
+Ref: Igawk Program-Footnote-2767456
+Ref: Igawk Program-Footnote-3767578
+Node: Anagram Program767693
+Node: Signature Program770750
+Node: Programs Summary771997
+Node: Programs Exercises773190
+Ref: Programs Exercises-Footnote-1777321
+Node: Advanced Features777412
+Node: Nondecimal Data779360
+Node: Array Sorting780950
+Node: Controlling Array Traversal781647
+Ref: Controlling Array Traversal-Footnote-1789980
+Node: Array Sorting Functions790098
+Ref: Array Sorting Functions-Footnote-1793987
+Node: Two-way I/O794183
+Ref: Two-way I/O-Footnote-1799128
+Ref: Two-way I/O-Footnote-2799314
+Node: TCP/IP Networking799396
+Node: Profiling802269
+Node: Advanced Features Summary810546
+Node: Internationalization812479
+Node: I18N and L10N813959
+Node: Explaining gettext814645
+Ref: Explaining gettext-Footnote-1819670
+Ref: Explaining gettext-Footnote-2819854
+Node: Programmer i18n820019
+Ref: Programmer i18n-Footnote-1824885
+Node: Translator i18n824934
+Node: String Extraction825728
+Ref: String Extraction-Footnote-1826859
+Node: Printf Ordering826945
+Ref: Printf Ordering-Footnote-1829731
+Node: I18N Portability829795
+Ref: I18N Portability-Footnote-1832250
+Node: I18N Example832313
+Ref: I18N Example-Footnote-1835116
+Node: Gawk I18N835188
+Node: I18N Summary835826
+Node: Debugger837165
+Node: Debugging838187
+Node: Debugging Concepts838628
+Node: Debugging Terms840481
+Node: Awk Debugging843053
+Node: Sample Debugging Session843947
+Node: Debugger Invocation844467
+Node: Finding The Bug845851
+Node: List of Debugger Commands852326
+Node: Breakpoint Control853659
+Node: Debugger Execution Control857355
+Node: Viewing And Changing Data860719
+Node: Execution Stack864097
+Node: Debugger Info865734
+Node: Miscellaneous Debugger Commands869751
+Node: Readline Support874780
+Node: Limitations875672
+Node: Debugging Summary877786
+Node: Arbitrary Precision Arithmetic878954
+Node: Computer Arithmetic880370
+Ref: table-numeric-ranges883968
+Ref: Computer Arithmetic-Footnote-1884827
+Node: Math Definitions884884
+Ref: table-ieee-formats888172
+Ref: Math Definitions-Footnote-1888776
+Node: MPFR features888881
+Node: FP Math Caution890552
+Ref: FP Math Caution-Footnote-1891602
+Node: Inexactness of computations891971
+Node: Inexact representation892930
+Node: Comparing FP Values894287
+Node: Errors accumulate895369
+Node: Getting Accuracy896802
+Node: Try To Round899464
+Node: Setting precision900363
+Ref: table-predefined-precision-strings901047
+Node: Setting the rounding mode902836
+Ref: table-gawk-rounding-modes903200
+Ref: Setting the rounding mode-Footnote-1906655
+Node: Arbitrary Precision Integers906834
+Ref: Arbitrary Precision Integers-Footnote-1911733
+Node: POSIX Floating Point Problems911882
+Ref: POSIX Floating Point Problems-Footnote-1915755
+Node: Floating point summary915793
+Node: Dynamic Extensions917987
+Node: Extension Intro919539
+Node: Plugin License920805
+Node: Extension Mechanism Outline921602
+Ref: figure-load-extension922030
+Ref: figure-register-new-function923510
+Ref: figure-call-new-function924514
+Node: Extension API Description926500
+Node: Extension API Functions Introduction928034
+Node: General Data Types932906
+Ref: General Data Types-Footnote-1938645
+Node: Memory Allocation Functions938944
+Ref: Memory Allocation Functions-Footnote-1941783
+Node: Constructor Functions941879
+Node: Registration Functions943613
+Node: Extension Functions944298
+Node: Exit Callback Functions946595
+Node: Extension Version String947843
+Node: Input Parsers948508
+Node: Output Wrappers958387
+Node: Two-way processors962902
+Node: Printing Messages965106
+Ref: Printing Messages-Footnote-1966182
+Node: Updating `ERRNO'966334
+Node: Requesting Values967074
+Ref: table-value-types-returned967802
+Node: Accessing Parameters968759
+Node: Symbol Table Access969990
+Node: Symbol table by name970504
+Node: Symbol table by cookie972485
+Ref: Symbol table by cookie-Footnote-1976629
+Node: Cached values976692
+Ref: Cached values-Footnote-1980191
+Node: Array Manipulation980282
+Ref: Array Manipulation-Footnote-1981372
+Node: Array Data Types981409
+Ref: Array Data Types-Footnote-1984064
+Node: Array Functions984156
+Node: Flattening Arrays988010
+Node: Creating Arrays994902
+Node: Redirection API999673
+Node: Extension API Variables1001869
+Node: Extension Versioning1002502
+Node: Extension API Informational Variables1004403
+Node: Extension API Boilerplate1005468
+Node: Finding Extensions1009277
+Node: Extension Example1009837
+Node: Internal File Description1010609
+Node: Internal File Ops1014676
+Ref: Internal File Ops-Footnote-11026346
+Node: Using Internal File Ops1026486
+Ref: Using Internal File Ops-Footnote-11028869
+Node: Extension Samples1029142
+Node: Extension Sample File Functions1030668
+Node: Extension Sample Fnmatch1038306
+Node: Extension Sample Fork1039797
+Node: Extension Sample Inplace1041012
+Node: Extension Sample Ord1042687
+Node: Extension Sample Readdir1043523
+Ref: table-readdir-file-types1044399
+Node: Extension Sample Revout1045210
+Node: Extension Sample Rev2way1045800
+Node: Extension Sample Read write array1046540
+Node: Extension Sample Readfile1048480
+Node: Extension Sample Time1049575
+Node: Extension Sample API Tests1050924
+Node: gawkextlib1051415
+Node: Extension summary1054073
+Node: Extension Exercises1057762
+Node: Language History1058484
+Node: V7/SVR3.11060140
+Node: SVR41062321
+Node: POSIX1063766
+Node: BTL1065155
+Node: POSIX/GNU1065889
+Node: Feature History1071513
+Node: Common Extensions1084611
+Node: Ranges and Locales1085935
+Ref: Ranges and Locales-Footnote-11090553
+Ref: Ranges and Locales-Footnote-21090580
+Ref: Ranges and Locales-Footnote-31090814
+Node: Contributors1091035
+Node: History summary1096576
+Node: Installation1097946
+Node: Gawk Distribution1098892
+Node: Getting1099376
+Node: Extracting1100199
+Node: Distribution contents1101834
+Node: Unix Installation1107899
+Node: Quick Installation1108582
+Node: Shell Startup Files1110993
+Node: Additional Configuration Options1112072
+Node: Configuration Philosophy1113811
+Node: Non-Unix Installation1116180
+Node: PC Installation1116638
+Node: PC Binary Installation1117957
+Node: PC Compiling1119805
+Ref: PC Compiling-Footnote-11122826
+Node: PC Testing1122935
+Node: PC Using1124111
+Node: Cygwin1128226
+Node: MSYS1129049
+Node: VMS Installation1129549
+Node: VMS Compilation1130341
+Ref: VMS Compilation-Footnote-11131563
+Node: VMS Dynamic Extensions1131621
+Node: VMS Installation Details1133305
+Node: VMS Running1135557
+Node: VMS GNV1138393
+Node: VMS Old Gawk1139127
+Node: Bugs1139597
+Node: Other Versions1143480
+Node: Installation summary1149908
+Node: Notes1150964
+Node: Compatibility Mode1151829
+Node: Additions1152611
+Node: Accessing The Source1153536
+Node: Adding Code1154972
+Node: New Ports1161137
+Node: Derived Files1165619
+Ref: Derived Files-Footnote-11171094
+Ref: Derived Files-Footnote-21171128
+Ref: Derived Files-Footnote-31171724
+Node: Future Extensions1171838
+Node: Implementation Limitations1172444
+Node: Extension Design1173692
+Node: Old Extension Problems1174846
+Ref: Old Extension Problems-Footnote-11176363
+Node: Extension New Mechanism Goals1176420
+Ref: Extension New Mechanism Goals-Footnote-11179780
+Node: Extension Other Design Decisions1179969
+Node: Extension Future Growth1182077
+Node: Old Extension Mechanism1182913
+Node: Notes summary1184675
+Node: Basic Concepts1185861
+Node: Basic High Level1186542
+Ref: figure-general-flow1186814
+Ref: figure-process-flow1187413
+Ref: Basic High Level-Footnote-11190642
+Node: Basic Data Typing1190827
+Node: Glossary1194155
+Node: Copying1219313
+Node: GNU Free Documentation License1256869
+Node: Index1282005
 
 End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index f0e17602..a222c23e 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -944,6 +944,7 @@ particular records in a file and perform operations upon them.
 * Array Functions::                     Functions for working with arrays.
 * Flattening Arrays::                   How to flatten arrays.
 * Creating Arrays::                     How to create and populate arrays.
+* Redirection API::                     How to access and manipulate redirections.
 * Extension API Variables::             Variables provided by the API.
 * Extension Versioning::                API Version information.
 * Extension API Informational Variables:: Variables providing information about
@@ -31779,6 +31780,7 @@ This (rather large) @value{SECTION} describes the API in detail.
 * Symbol Table Access::                  Functions for accessing global
                                          variables.
 * Array Manipulation::                   Functions for working with arrays.
+* Redirection API::                      How to access and manipulate redirections.
 * Extension API Variables::              Variables provided by the API.
 * Extension API Boilerplate::            Boilerplate code for using the API.
 @end menu
@@ -31854,6 +31856,10 @@ Clearing an array
 @item
 Flattening an array for easy C style looping over all its indices and elements
 @end itemize
+
+@item
+Accessing and manipulating redirections.
+
 @end itemize
 
 Some points about using the API:
@@ -33818,6 +33824,54 @@ $ @kbd{AWKLIBPATH=$PWD ./gawk -f subarray.awk}
 (@DBXREF{Finding Extensions} for more information on the
 @env{AWKLIBPATH} environment variable.)
 
+@node Redirection API
+@subsection Accessing and Manipulating Redirections
+
+The following function allows extensions to access and manipulate redirections.
+
+@table @code
+@item awk_bool_t get_file(const char *name,
+@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ size_t name_len,
+@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ const char *filetype,
+@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ int fd,
+@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ const awk_input_buf_t **ibufp,
+@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ const awk_output_buf_t **obufp);
+Look up a file in @command{gawk}'s internal redirection table.  If @code{name} is NULL or @code{name_len} is 0, it returns
+data for the currently open input file corresponding to @code{FILENAME}
+(and it will not access the @code{filetype} argument, so that may be
+undefined).  
+If the file is not already open, it tries to open it.
+The @code{filetype} argument must be NUL-terminated and should be one of:
+@table @code
+@item >
+A file opened for output.
+@item >>
+A file opened for append.
+@item <
+A file opened for input.
+@item |>
+A pipe opened for output.
+@item |<
+A pipe opened for input.
+@item |&
+A two-way coprocess.
+@end table
+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
+already, @command{gawk} ignores the fd and returns the existing file.  It is
+the caller's responsibility to notice that neither the fd in the returned
+@code{awk_input_buf_t} nor the fd in the returned @code{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 @code{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.
+@end table
+
+For example, this API function can be used to implement I/O multiplexing or a
+socket library.
+
 @node Extension API Variables
 @subsection API Variables
 
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index 638bb909..706512f9 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -939,6 +939,7 @@ particular records in a file and perform operations upon them.
 * Array Functions::                     Functions for working with arrays.
 * Flattening Arrays::                   How to flatten arrays.
 * Creating Arrays::                     How to create and populate arrays.
+* Redirection API::                     How to access and manipulate redirections.
 * Extension API Variables::             Variables provided by the API.
 * Extension Versioning::                API Version information.
 * Extension API Informational Variables:: Variables providing information about
@@ -30872,6 +30873,7 @@ This (rather large) @value{SECTION} describes the API in detail.
 * Symbol Table Access::                  Functions for accessing global
                                          variables.
 * Array Manipulation::                   Functions for working with arrays.
+* Redirection API::                      How to access and manipulate redirections.
 * Extension API Variables::              Variables provided by the API.
 * Extension API Boilerplate::            Boilerplate code for using the API.
 @end menu
@@ -30947,6 +30949,10 @@ Clearing an array
 @item
 Flattening an array for easy C style looping over all its indices and elements
 @end itemize
+
+@item
+Accessing and manipulating redirections.
+
 @end itemize
 
 Some points about using the API:
@@ -32911,6 +32917,54 @@ $ @kbd{AWKLIBPATH=$PWD ./gawk -f subarray.awk}
 (@DBXREF{Finding Extensions} for more information on the
 @env{AWKLIBPATH} environment variable.)
 
+@node Redirection API
+@subsection Accessing and Manipulating Redirections
+
+The following function allows extensions to access and manipulate redirections.
+
+@table @code
+@item awk_bool_t get_file(const char *name,
+@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ size_t name_len,
+@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ const char *filetype,
+@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ int fd,
+@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ const awk_input_buf_t **ibufp,
+@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ const awk_output_buf_t **obufp);
+Look up a file in @command{gawk}'s internal redirection table.  If @code{name} is NULL or @code{name_len} is 0, it returns
+data for the currently open input file corresponding to @code{FILENAME}
+(and it will not access the @code{filetype} argument, so that may be
+undefined).  
+If the file is not already open, it tries to open it.
+The @code{filetype} argument must be NUL-terminated and should be one of:
+@table @code
+@item >
+A file opened for output.
+@item >>
+A file opened for append.
+@item <
+A file opened for input.
+@item |>
+A pipe opened for output.
+@item |<
+A pipe opened for input.
+@item |&
+A two-way coprocess.
+@end table
+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
+already, @command{gawk} ignores the fd and returns the existing file.  It is
+the caller's responsibility to notice that neither the fd in the returned
+@code{awk_input_buf_t} nor the fd in the returned @code{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 @code{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.
+@end table
+
+For example, this API function can be used to implement I/O multiplexing or a
+socket library.
+
 @node Extension API Variables
 @subsection API Variables
 
diff --git a/gawkapi.h b/gawkapi.h
index 6893fda0..cdf81cc8 100644
--- a/gawkapi.h
+++ b/gawkapi.h
@@ -692,7 +692,7 @@ typedef struct gawk_api {
 	 * supplying a file descriptor is currently NOT supported for pipes.
 	 * It should work for input, output, append, and two-way (coprocess)
 	 * sockets.  If the filetype is two-way, we assume that it is a socket!
-	 * Note that in the two-way case, the intput and output file descriptors
+	 * Note that in the two-way case, the input and output file descriptors
 	 * may differ.  To check for success, one must check that either of
 	 * them matches.
 	 */