Add readfile function.

4 files changed, 741 insertions, 516 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index cddc7e77..dad84a22 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,7 @@
+2013-09-24         Arnold D. Robbins     <arnold@skeeve.com>
+
+	* gawktexi.in (Readfile function): New node.
+
 2013-09-22         Arnold D. Robbins     <arnold@skeeve.com>
 
 	* gawktexi.in (FN, FFN, DF,DDF, PVERSION, CTL): Remove macros.
diff --git a/doc/gawk.info b/doc/gawk.info
index 9072bf06..0bbf9dde 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -401,6 +401,8 @@ texts being (a) (see below), and with the Back-Cover Texts being (b)
 * Join Function::                       A function to join an array into a
                                         string.
 * Getlocaltime Function::               A function to get formatted times.
+* Readfile Function::                   A function to read an entire file at
+                                        once.
 * Data File Management::                Functions for managing command-line
                                         data files.
 * Filetrans Function::                  A function for handling data file
@@ -13663,6 +13665,7 @@ programming use.
                                 vice versa.
 * Join Function::               A function to join an array into a string.
 * Getlocaltime Function::       A function to get formatted times.
+* Readfile Function::           A function to read an entire file at once.
 
 
 File: gawk.info,  Node: Strtonum Function,  Next: Assert Function,  Up: General Functions
@@ -14055,7 +14058,7 @@ concatenation.  The lack of an explicit operator for concatenation
 makes string operations more difficult than they really need to be.
 
 
-File: gawk.info,  Node: Getlocaltime Function,  Prev: Join Function,  Up: General Functions
+File: gawk.info,  Node: Getlocaltime Function,  Next: Readfile Function,  Prev: Join Function,  Up: General Functions
 
 10.2.7 Managing the Time of Day
 -------------------------------
@@ -14137,6 +14140,66 @@ the `getlocaltime()' function would have allowed the user to supply an
 optional timestamp value to use instead of the current time.
 
 
+File: gawk.info,  Node: Readfile Function,  Prev: Getlocaltime Function,  Up: General Functions
+
+10.2.8 Reading A Whole File At Once
+-----------------------------------
+
+Often, it is convenient to have the entire contents of a file available
+in memory as a single string. A straightforward but naive way to do
+that might be as follows:
+
+     function readfile(file,    tmp, contents)
+     {
+         if ((getline tmp < file) < 0)
+             return
+
+         contents = tmp
+         while (getline tmp < file) > 0)
+             contents = contents RT tmp
+
+         close(file)
+         return contents
+     }
+
+   This function reads from `file' one record at a time, building up
+the full contents of the file in the local variable `contents'.  It
+works, but is not necessarily efficient.
+
+   The following function, based on a suggestion by Denis Shirokov,
+reads the entire contents of the named file in one shot:
+
+     # readfile.awk --- read an entire file at once
+
+     function readfile(file,     tmp, save_rs)
+     {
+         save_rs = RS
+         RS = "^$"
+         getline tmp < file
+         close(file)
+         RS = save_rs
+
+         return tmp
+     }
+
+   It works by setting `RS' to `^$', a regular expression that will
+never match if the file has contents.  `gawk' reads data from the file
+into `tmp' attempting to match `RS'.  The match fails after each read,
+but fails quickly, such that `gawk' fills `tmp' with the entire
+contents of the file.  (*Note Records::, for information on `RT' and
+`RS'.)
+
+   In the case that `file' is empty, the return value is the null
+string.  Thus calling code may use something like:
+
+     contents = readfile("/some/path")
+     if (length(contents) == 0)
+         # file was empty ...
+
+   This tests the result to see if it is empty or not. An equivalent
+test would be `contents == ""'.
+
+
 File: gawk.info,  Node: Data File Management,  Next: Getopt Function,  Prev: General Functions,  Up: Library Functions
 
 10.3 Data File Management
@@ -31492,6 +31555,7 @@ Index
                                                               (line   9)
 * readfile extension function:           Extension Sample Readfile.
                                                               (line  11)
+* readfile() user-defined function:      Readfile Function.   (line  30)
 * recipe for a programming language:     History.             (line   6)
 * record separators <1>:                 User-modified.       (line 143)
 * record separators:                     Records.             (line  14)
@@ -32087,520 +32151,521 @@ Index
 
 Tag Table:
 Node: Top1360
-Node: Foreword40338
-Node: Preface44683
-Ref: Preface-Footnote-147736
-Ref: Preface-Footnote-247832
-Node: History48064
-Node: Names50438
-Ref: Names-Footnote-151915
-Node: This Manual51987
-Ref: This Manual-Footnote-157761
-Node: Conventions57861
-Node: Manual History60013
-Ref: Manual History-Footnote-163461
-Ref: Manual History-Footnote-263502
-Node: How To Contribute63576
-Node: Acknowledgments64720
-Node: Getting Started68929
-Node: Running gawk71308
-Node: One-shot72494
-Node: Read Terminal73719
-Ref: Read Terminal-Footnote-175369
-Ref: Read Terminal-Footnote-275645
-Node: Long75816
-Node: Executable Scripts77192
-Ref: Executable Scripts-Footnote-179025
-Ref: Executable Scripts-Footnote-279127
-Node: Comments79674
-Node: Quoting82141
-Node: DOS Quoting86764
-Node: Sample Data Files87439
-Node: Very Simple90471
-Node: Two Rules95070
-Node: More Complex97217
-Ref: More Complex-Footnote-1100147
-Node: Statements/Lines100232
-Ref: Statements/Lines-Footnote-1104694
-Node: Other Features104959
-Node: When105887
-Node: Invoking Gawk108034
-Node: Command Line109495
-Node: Options110278
-Ref: Options-Footnote-1125670
-Node: Other Arguments125695
-Node: Naming Standard Input128353
-Node: Environment Variables129447
-Node: AWKPATH Variable130005
-Ref: AWKPATH Variable-Footnote-1132763
-Node: AWKLIBPATH Variable133023
-Node: Other Environment Variables133741
-Node: Exit Status136236
-Node: Include Files136911
-Node: Loading Shared Libraries140480
-Node: Obsolete141844
-Node: Undocumented142541
-Node: Regexp142784
-Node: Regexp Usage144173
-Node: Escape Sequences146199
-Node: Regexp Operators151868
-Ref: Regexp Operators-Footnote-1159248
-Ref: Regexp Operators-Footnote-2159395
-Node: Bracket Expressions159493
-Ref: table-char-classes161383
-Node: GNU Regexp Operators163906
-Node: Case-sensitivity167629
-Ref: Case-sensitivity-Footnote-1170597
-Ref: Case-sensitivity-Footnote-2170832
-Node: Leftmost Longest170940
-Node: Computed Regexps172141
-Node: Reading Files175478
-Node: Records177481
-Ref: Records-Footnote-1186370
-Node: Fields186407
-Ref: Fields-Footnote-1189440
-Node: Nonconstant Fields189526
-Node: Changing Fields191728
-Node: Field Separators197687
-Node: Default Field Splitting200316
-Node: Regexp Field Splitting201433
-Node: Single Character Fields204775
-Node: Command Line Field Separator205834
-Node: Field Splitting Summary209275
-Ref: Field Splitting Summary-Footnote-1212386
-Node: Constant Size212487
-Node: Splitting By Content217071
-Ref: Splitting By Content-Footnote-1220797
-Node: Multiple Line220837
-Ref: Multiple Line-Footnote-1226684
-Node: Getline226863
-Node: Plain Getline229079
-Node: Getline/Variable231174
-Node: Getline/File232321
-Node: Getline/Variable/File233662
-Ref: Getline/Variable/File-Footnote-1235261
-Node: Getline/Pipe235348
-Node: Getline/Variable/Pipe238048
-Node: Getline/Coprocess239155
-Node: Getline/Variable/Coprocess240407
-Node: Getline Notes241144
-Node: Getline Summary243931
-Ref: table-getline-variants244339
-Node: Read Timeout245251
-Ref: Read Timeout-Footnote-1248992
-Node: Command line directories249049
-Node: Printing249679
-Node: Print251310
-Node: Print Examples252647
-Node: Output Separators255431
-Node: OFMT257191
-Node: Printf258549
-Node: Basic Printf259455
-Node: Control Letters260994
-Node: Format Modifiers264806
-Node: Printf Examples270815
-Node: Redirection273530
-Node: Special Files280495
-Node: Special FD281028
-Ref: Special FD-Footnote-1284653
-Node: Special Network284727
-Node: Special Caveats285577
-Node: Close Files And Pipes286373
-Ref: Close Files And Pipes-Footnote-1293356
-Ref: Close Files And Pipes-Footnote-2293504
-Node: Expressions293654
-Node: Values294786
-Node: Constants295462
-Node: Scalar Constants296142
-Ref: Scalar Constants-Footnote-1297001
-Node: Nondecimal-numbers297183
-Node: Regexp Constants300183
-Node: Using Constant Regexps300658
-Node: Variables303713
-Node: Using Variables304368
-Node: Assignment Options306092
-Node: Conversion307964
-Ref: table-locale-affects313464
-Ref: Conversion-Footnote-1314088
-Node: All Operators314197
-Node: Arithmetic Ops314827
-Node: Concatenation317332
-Ref: Concatenation-Footnote-1320125
-Node: Assignment Ops320245
-Ref: table-assign-ops325233
-Node: Increment Ops326564
-Node: Truth Values and Conditions329999
-Node: Truth Values331082
-Node: Typing and Comparison332131
-Node: Variable Typing332920
-Ref: Variable Typing-Footnote-1336817
-Node: Comparison Operators336939
-Ref: table-relational-ops337349
-Node: POSIX String Comparison340898
-Ref: POSIX String Comparison-Footnote-1341854
-Node: Boolean Ops341992
-Ref: Boolean Ops-Footnote-1346070
-Node: Conditional Exp346161
-Node: Function Calls347893
-Node: Precedence351487
-Node: Locales355156
-Node: Patterns and Actions356245
-Node: Pattern Overview357299
-Node: Regexp Patterns358968
-Node: Expression Patterns359511
-Node: Ranges363196
-Node: BEGIN/END366162
-Node: Using BEGIN/END366924
-Ref: Using BEGIN/END-Footnote-1369655
-Node: I/O And BEGIN/END369761
-Node: BEGINFILE/ENDFILE372043
-Node: Empty374957
-Node: Using Shell Variables375273
-Node: Action Overview377558
-Node: Statements379915
-Node: If Statement381769
-Node: While Statement383268
-Node: Do Statement385312
-Node: For Statement386468
-Node: Switch Statement389620
-Node: Break Statement391717
-Node: Continue Statement393707
-Node: Next Statement395500
-Node: Nextfile Statement397890
-Node: Exit Statement400533
-Node: Built-in Variables402949
-Node: User-modified404044
-Ref: User-modified-Footnote-1412404
-Node: Auto-set412466
-Ref: Auto-set-Footnote-1425544
-Ref: Auto-set-Footnote-2425749
-Node: ARGC and ARGV425805
-Node: Arrays429656
-Node: Array Basics431161
-Node: Array Intro431987
-Node: Reference to Elements436305
-Node: Assigning Elements438575
-Node: Array Example439066
-Node: Scanning an Array440798
-Node: Controlling Scanning443112
-Ref: Controlling Scanning-Footnote-1448035
-Node: Delete448351
-Ref: Delete-Footnote-1451116
-Node: Numeric Array Subscripts451173
-Node: Uninitialized Subscripts453356
-Node: Multi-dimensional454984
-Node: Multi-scanning458078
-Node: Arrays of Arrays459669
-Node: Functions464310
-Node: Built-in465129
-Node: Calling Built-in466207
-Node: Numeric Functions468195
-Ref: Numeric Functions-Footnote-1472027
-Ref: Numeric Functions-Footnote-2472384
-Ref: Numeric Functions-Footnote-3472432
-Node: String Functions472701
-Ref: String Functions-Footnote-1496259
-Ref: String Functions-Footnote-2496388
-Ref: String Functions-Footnote-3496636
-Node: Gory Details496723
-Ref: table-sub-escapes498402
-Ref: table-sub-posix-92499756
-Ref: table-sub-proposed501107
-Ref: table-posix-sub502461
-Ref: table-gensub-escapes504006
-Ref: Gory Details-Footnote-1505182
-Ref: Gory Details-Footnote-2505233
-Node: I/O Functions505384
-Ref: I/O Functions-Footnote-1512369
-Node: Time Functions512516
-Ref: Time Functions-Footnote-1523449
-Ref: Time Functions-Footnote-2523517
-Ref: Time Functions-Footnote-3523675
-Ref: Time Functions-Footnote-4523786
-Ref: Time Functions-Footnote-5523898
-Ref: Time Functions-Footnote-6524125
-Node: Bitwise Functions524391
-Ref: table-bitwise-ops524949
-Ref: Bitwise Functions-Footnote-1529170
-Node: Type Functions529354
-Node: I18N Functions530505
-Node: User-defined532132
-Node: Definition Syntax532936
-Ref: Definition Syntax-Footnote-1537846
-Node: Function Example537915
-Node: Function Caveats540509
-Node: Calling A Function540930
-Node: Variable Scope542045
-Node: Pass By Value/Reference545008
-Node: Return Statement548516
-Node: Dynamic Typing551497
-Node: Indirect Calls552428
-Node: Library Functions562113
-Ref: Library Functions-Footnote-1565626
-Ref: Library Functions-Footnote-2565769
-Node: Library Names565940
-Ref: Library Names-Footnote-1569411
-Ref: Library Names-Footnote-2569631
-Node: General Functions569717
-Node: Strtonum Function570670
-Node: Assert Function573600
-Node: Round Function576926
-Node: Cliff Random Function578469
-Node: Ordinal Functions579485
-Ref: Ordinal Functions-Footnote-1582555
-Ref: Ordinal Functions-Footnote-2582807
-Node: Join Function583016
-Ref: Join Function-Footnote-1584787
-Node: Getlocaltime Function584987
-Node: Data File Management588702
-Node: Filetrans Function589334
-Node: Rewind Function593403
-Node: File Checking594790
-Node: Empty Files595884
-Node: Ignoring Assigns598114
-Node: Getopt Function599667
-Ref: Getopt Function-Footnote-1610971
-Node: Passwd Functions611174
-Ref: Passwd Functions-Footnote-1620149
-Node: Group Functions620237
-Node: Walking Arrays628321
-Node: Sample Programs630458
-Node: Running Examples631132
-Node: Clones631860
-Node: Cut Program633084
-Node: Egrep Program642929
-Ref: Egrep Program-Footnote-1650702
-Node: Id Program650812
-Node: Split Program654428
-Ref: Split Program-Footnote-1657947
-Node: Tee Program658075
-Node: Uniq Program660878
-Node: Wc Program668307
-Ref: Wc Program-Footnote-1672573
-Ref: Wc Program-Footnote-2672773
-Node: Miscellaneous Programs672865
-Node: Dupword Program674053
-Node: Alarm Program676084
-Node: Translate Program680833
-Ref: Translate Program-Footnote-1685220
-Ref: Translate Program-Footnote-2685448
-Node: Labels Program685582
-Ref: Labels Program-Footnote-1688953
-Node: Word Sorting689037
-Node: History Sorting692921
-Node: Extract Program694760
-Ref: Extract Program-Footnote-1702261
-Node: Simple Sed702389
-Node: Igawk Program705451
-Ref: Igawk Program-Footnote-1720608
-Ref: Igawk Program-Footnote-2720809
-Node: Anagram Program720947
-Node: Signature Program724015
-Node: Advanced Features725115
-Node: Nondecimal Data726997
-Node: Array Sorting728580
-Node: Controlling Array Traversal729277
-Node: Array Sorting Functions737515
-Ref: Array Sorting Functions-Footnote-1741189
-Ref: Array Sorting Functions-Footnote-2741282
-Node: Two-way I/O741476
-Ref: Two-way I/O-Footnote-1746908
-Node: TCP/IP Networking746978
-Node: Profiling749822
-Node: Internationalization757319
-Node: I18N and L10N758744
-Node: Explaining gettext759430
-Ref: Explaining gettext-Footnote-1764498
-Ref: Explaining gettext-Footnote-2764682
-Node: Programmer i18n764847
-Node: Translator i18n769049
-Node: String Extraction769842
-Ref: String Extraction-Footnote-1770803
-Node: Printf Ordering770889
-Ref: Printf Ordering-Footnote-1773673
-Node: I18N Portability773737
-Ref: I18N Portability-Footnote-1776186
-Node: I18N Example776249
-Ref: I18N Example-Footnote-1778887
-Node: Gawk I18N778959
-Node: Debugger779580
-Node: Debugging780551
-Node: Debugging Concepts780984
-Node: Debugging Terms782840
-Node: Awk Debugging785437
-Node: Sample Debugging Session786329
-Node: Debugger Invocation786849
-Node: Finding The Bug788181
-Node: List of Debugger Commands794669
-Node: Breakpoint Control796003
-Node: Debugger Execution Control799667
-Node: Viewing And Changing Data803027
-Node: Execution Stack806383
-Node: Debugger Info807850
-Node: Miscellaneous Debugger Commands811832
-Node: Readline Support817008
-Node: Limitations817839
-Node: Arbitrary Precision Arithmetic820091
-Ref: Arbitrary Precision Arithmetic-Footnote-1821742
-Node: General Arithmetic821890
-Node: Floating Point Issues823610
-Node: String Conversion Precision824491
-Ref: String Conversion Precision-Footnote-1826197
-Node: Unexpected Results826306
-Node: POSIX Floating Point Problems828459
-Ref: POSIX Floating Point Problems-Footnote-1832284
-Node: Integer Programming832322
-Node: Floating-point Programming834061
-Ref: Floating-point Programming-Footnote-1840392
-Ref: Floating-point Programming-Footnote-2840662
-Node: Floating-point Representation840926
-Node: Floating-point Context842091
-Ref: table-ieee-formats842930
-Node: Rounding Mode844314
-Ref: table-rounding-modes844793
-Ref: Rounding Mode-Footnote-1847808
-Node: Gawk and MPFR847987
-Node: Arbitrary Precision Floats849242
-Ref: Arbitrary Precision Floats-Footnote-1851685
-Node: Setting Precision852001
-Ref: table-predefined-precision-strings852687
-Node: Setting Rounding Mode854832
-Ref: table-gawk-rounding-modes855236
-Node: Floating-point Constants856423
-Node: Changing Precision857852
-Ref: Changing Precision-Footnote-1859252
-Node: Exact Arithmetic859426
-Node: Arbitrary Precision Integers862564
-Ref: Arbitrary Precision Integers-Footnote-1865582
-Node: Dynamic Extensions865729
-Node: Extension Intro867187
-Node: Plugin License868452
-Node: Extension Mechanism Outline869137
-Ref: load-extension869554
-Ref: load-new-function871032
-Ref: call-new-function872027
-Node: Extension API Description874042
-Node: Extension API Functions Introduction875255
-Node: General Data Types880121
-Ref: General Data Types-Footnote-1885723
-Node: Requesting Values886022
-Ref: table-value-types-returned886753
-Node: Constructor Functions887707
-Node: Registration Functions890727
-Node: Extension Functions891412
-Node: Exit Callback Functions893637
-Node: Extension Version String894886
-Node: Input Parsers895536
-Node: Output Wrappers905293
-Node: Two-way processors909803
-Node: Printing Messages912011
-Ref: Printing Messages-Footnote-1913088
-Node: Updating `ERRNO'913240
-Node: Accessing Parameters913979
-Node: Symbol Table Access915209
-Node: Symbol table by name915721
-Node: Symbol table by cookie917468
-Ref: Symbol table by cookie-Footnote-1921598
-Node: Cached values921661
-Ref: Cached values-Footnote-1925110
-Node: Array Manipulation925201
-Ref: Array Manipulation-Footnote-1926299
-Node: Array Data Types926338
-Ref: Array Data Types-Footnote-1929041
-Node: Array Functions929133
-Node: Flattening Arrays932899
-Node: Creating Arrays939751
-Node: Extension API Variables944476
-Node: Extension Versioning945112
-Node: Extension API Informational Variables947013
-Node: Extension API Boilerplate948099
-Node: Finding Extensions951903
-Node: Extension Example952463
-Node: Internal File Description953194
-Node: Internal File Ops957285
-Ref: Internal File Ops-Footnote-1968793
-Node: Using Internal File Ops968933
-Ref: Using Internal File Ops-Footnote-1971286
-Node: Extension Samples971552
-Node: Extension Sample File Functions973076
-Node: Extension Sample Fnmatch981563
-Node: Extension Sample Fork983289
-Node: Extension Sample Inplace984507
-Node: Extension Sample Ord986285
-Node: Extension Sample Readdir987121
-Node: Extension Sample Revout988653
-Node: Extension Sample Rev2way989246
-Node: Extension Sample Read write array989936
-Node: Extension Sample Readfile991819
-Node: Extension Sample API Tests992637
-Node: Extension Sample Time993162
-Node: gawkextlib994526
-Node: Language History997286
-Node: V7/SVR3.1998808
-Node: SVR41001129
-Node: POSIX1002571
-Node: BTL1003957
-Node: POSIX/GNU1004691
-Node: Common Extensions1010226
-Node: Ranges and Locales1011532
-Ref: Ranges and Locales-Footnote-11016150
-Ref: Ranges and Locales-Footnote-21016177
-Ref: Ranges and Locales-Footnote-31016437
-Node: Contributors1016658
-Node: Installation1021537
-Node: Gawk Distribution1022431
-Node: Getting1022915
-Node: Extracting1023741
-Node: Distribution contents1025433
-Node: Unix Installation1030694
-Node: Quick Installation1031311
-Node: Additional Configuration Options1033755
-Node: Configuration Philosophy1035232
-Node: Non-Unix Installation1037586
-Node: PC Installation1038044
-Node: PC Binary Installation1039343
-Node: PC Compiling1041191
-Node: PC Testing1044135
-Node: PC Using1045311
-Node: Cygwin1049496
-Node: MSYS1050496
-Node: VMS Installation1051010
-Node: VMS Compilation1051613
-Ref: VMS Compilation-Footnote-11052620
-Node: VMS Installation Details1052678
-Node: VMS Running1054313
-Node: VMS Old Gawk1055920
-Node: Bugs1056394
-Node: Other Versions1060246
-Node: Notes1065847
-Node: Compatibility Mode1066647
-Node: Additions1067430
-Node: Accessing The Source1068357
-Node: Adding Code1069797
-Node: New Ports1075842
-Node: Derived Files1079977
-Ref: Derived Files-Footnote-11085298
-Ref: Derived Files-Footnote-21085332
-Ref: Derived Files-Footnote-31085932
-Node: Future Extensions1086030
-Node: Implementation Limitations1086611
-Node: Extension Design1087863
-Node: Old Extension Problems1089017
-Ref: Old Extension Problems-Footnote-11090525
-Node: Extension New Mechanism Goals1090582
-Ref: Extension New Mechanism Goals-Footnote-11093948
-Node: Extension Other Design Decisions1094134
-Node: Extension Future Growth1096240
-Node: Old Extension Mechanism1097076
-Node: Basic Concepts1098816
-Node: Basic High Level1099497
-Ref: figure-general-flow1099768
-Ref: figure-process-flow1100367
-Ref: Basic High Level-Footnote-11103596
-Node: Basic Data Typing1103781
-Node: Glossary1107136
-Node: Copying1132598
-Node: GNU Free Documentation License1170155
-Node: Index1195292
+Node: Foreword40461
+Node: Preface44806
+Ref: Preface-Footnote-147859
+Ref: Preface-Footnote-247955
+Node: History48187
+Node: Names50561
+Ref: Names-Footnote-152038
+Node: This Manual52110
+Ref: This Manual-Footnote-157884
+Node: Conventions57984
+Node: Manual History60136
+Ref: Manual History-Footnote-163584
+Ref: Manual History-Footnote-263625
+Node: How To Contribute63699
+Node: Acknowledgments64843
+Node: Getting Started69052
+Node: Running gawk71431
+Node: One-shot72617
+Node: Read Terminal73842
+Ref: Read Terminal-Footnote-175492
+Ref: Read Terminal-Footnote-275768
+Node: Long75939
+Node: Executable Scripts77315
+Ref: Executable Scripts-Footnote-179148
+Ref: Executable Scripts-Footnote-279250
+Node: Comments79797
+Node: Quoting82264
+Node: DOS Quoting86887
+Node: Sample Data Files87562
+Node: Very Simple90594
+Node: Two Rules95193
+Node: More Complex97340
+Ref: More Complex-Footnote-1100270
+Node: Statements/Lines100355
+Ref: Statements/Lines-Footnote-1104817
+Node: Other Features105082
+Node: When106010
+Node: Invoking Gawk108157
+Node: Command Line109618
+Node: Options110401
+Ref: Options-Footnote-1125793
+Node: Other Arguments125818
+Node: Naming Standard Input128476
+Node: Environment Variables129570
+Node: AWKPATH Variable130128
+Ref: AWKPATH Variable-Footnote-1132886
+Node: AWKLIBPATH Variable133146
+Node: Other Environment Variables133864
+Node: Exit Status136359
+Node: Include Files137034
+Node: Loading Shared Libraries140603
+Node: Obsolete141967
+Node: Undocumented142664
+Node: Regexp142907
+Node: Regexp Usage144296
+Node: Escape Sequences146322
+Node: Regexp Operators151991
+Ref: Regexp Operators-Footnote-1159371
+Ref: Regexp Operators-Footnote-2159518
+Node: Bracket Expressions159616
+Ref: table-char-classes161506
+Node: GNU Regexp Operators164029
+Node: Case-sensitivity167752
+Ref: Case-sensitivity-Footnote-1170720
+Ref: Case-sensitivity-Footnote-2170955
+Node: Leftmost Longest171063
+Node: Computed Regexps172264
+Node: Reading Files175601
+Node: Records177604
+Ref: Records-Footnote-1186493
+Node: Fields186530
+Ref: Fields-Footnote-1189563
+Node: Nonconstant Fields189649
+Node: Changing Fields191851
+Node: Field Separators197810
+Node: Default Field Splitting200439
+Node: Regexp Field Splitting201556
+Node: Single Character Fields204898
+Node: Command Line Field Separator205957
+Node: Field Splitting Summary209398
+Ref: Field Splitting Summary-Footnote-1212509
+Node: Constant Size212610
+Node: Splitting By Content217194
+Ref: Splitting By Content-Footnote-1220920
+Node: Multiple Line220960
+Ref: Multiple Line-Footnote-1226807
+Node: Getline226986
+Node: Plain Getline229202
+Node: Getline/Variable231297
+Node: Getline/File232444
+Node: Getline/Variable/File233785
+Ref: Getline/Variable/File-Footnote-1235384
+Node: Getline/Pipe235471
+Node: Getline/Variable/Pipe238171
+Node: Getline/Coprocess239278
+Node: Getline/Variable/Coprocess240530
+Node: Getline Notes241267
+Node: Getline Summary244054
+Ref: table-getline-variants244462
+Node: Read Timeout245374
+Ref: Read Timeout-Footnote-1249115
+Node: Command line directories249172
+Node: Printing249802
+Node: Print251433
+Node: Print Examples252770
+Node: Output Separators255554
+Node: OFMT257314
+Node: Printf258672
+Node: Basic Printf259578
+Node: Control Letters261117
+Node: Format Modifiers264929
+Node: Printf Examples270938
+Node: Redirection273653
+Node: Special Files280618
+Node: Special FD281151
+Ref: Special FD-Footnote-1284776
+Node: Special Network284850
+Node: Special Caveats285700
+Node: Close Files And Pipes286496
+Ref: Close Files And Pipes-Footnote-1293479
+Ref: Close Files And Pipes-Footnote-2293627
+Node: Expressions293777
+Node: Values294909
+Node: Constants295585
+Node: Scalar Constants296265
+Ref: Scalar Constants-Footnote-1297124
+Node: Nondecimal-numbers297306
+Node: Regexp Constants300306
+Node: Using Constant Regexps300781
+Node: Variables303836
+Node: Using Variables304491
+Node: Assignment Options306215
+Node: Conversion308087
+Ref: table-locale-affects313587
+Ref: Conversion-Footnote-1314211
+Node: All Operators314320
+Node: Arithmetic Ops314950
+Node: Concatenation317455
+Ref: Concatenation-Footnote-1320248
+Node: Assignment Ops320368
+Ref: table-assign-ops325356
+Node: Increment Ops326687
+Node: Truth Values and Conditions330122
+Node: Truth Values331205
+Node: Typing and Comparison332254
+Node: Variable Typing333043
+Ref: Variable Typing-Footnote-1336940
+Node: Comparison Operators337062
+Ref: table-relational-ops337472
+Node: POSIX String Comparison341021
+Ref: POSIX String Comparison-Footnote-1341977
+Node: Boolean Ops342115
+Ref: Boolean Ops-Footnote-1346193
+Node: Conditional Exp346284
+Node: Function Calls348016
+Node: Precedence351610
+Node: Locales355279
+Node: Patterns and Actions356368
+Node: Pattern Overview357422
+Node: Regexp Patterns359091
+Node: Expression Patterns359634
+Node: Ranges363319
+Node: BEGIN/END366285
+Node: Using BEGIN/END367047
+Ref: Using BEGIN/END-Footnote-1369778
+Node: I/O And BEGIN/END369884
+Node: BEGINFILE/ENDFILE372166
+Node: Empty375080
+Node: Using Shell Variables375396
+Node: Action Overview377681
+Node: Statements380038
+Node: If Statement381892
+Node: While Statement383391
+Node: Do Statement385435
+Node: For Statement386591
+Node: Switch Statement389743
+Node: Break Statement391840
+Node: Continue Statement393830
+Node: Next Statement395623
+Node: Nextfile Statement398013
+Node: Exit Statement400656
+Node: Built-in Variables403072
+Node: User-modified404167
+Ref: User-modified-Footnote-1412527
+Node: Auto-set412589
+Ref: Auto-set-Footnote-1425667
+Ref: Auto-set-Footnote-2425872
+Node: ARGC and ARGV425928
+Node: Arrays429779
+Node: Array Basics431284
+Node: Array Intro432110
+Node: Reference to Elements436428
+Node: Assigning Elements438698
+Node: Array Example439189
+Node: Scanning an Array440921
+Node: Controlling Scanning443235
+Ref: Controlling Scanning-Footnote-1448158
+Node: Delete448474
+Ref: Delete-Footnote-1451239
+Node: Numeric Array Subscripts451296
+Node: Uninitialized Subscripts453479
+Node: Multi-dimensional455107
+Node: Multi-scanning458201
+Node: Arrays of Arrays459792
+Node: Functions464433
+Node: Built-in465252
+Node: Calling Built-in466330
+Node: Numeric Functions468318
+Ref: Numeric Functions-Footnote-1472150
+Ref: Numeric Functions-Footnote-2472507
+Ref: Numeric Functions-Footnote-3472555
+Node: String Functions472824
+Ref: String Functions-Footnote-1496382
+Ref: String Functions-Footnote-2496511
+Ref: String Functions-Footnote-3496759
+Node: Gory Details496846
+Ref: table-sub-escapes498525
+Ref: table-sub-posix-92499879
+Ref: table-sub-proposed501230
+Ref: table-posix-sub502584
+Ref: table-gensub-escapes504129
+Ref: Gory Details-Footnote-1505305
+Ref: Gory Details-Footnote-2505356
+Node: I/O Functions505507
+Ref: I/O Functions-Footnote-1512492
+Node: Time Functions512639
+Ref: Time Functions-Footnote-1523572
+Ref: Time Functions-Footnote-2523640
+Ref: Time Functions-Footnote-3523798
+Ref: Time Functions-Footnote-4523909
+Ref: Time Functions-Footnote-5524021
+Ref: Time Functions-Footnote-6524248
+Node: Bitwise Functions524514
+Ref: table-bitwise-ops525072
+Ref: Bitwise Functions-Footnote-1529293
+Node: Type Functions529477
+Node: I18N Functions530628
+Node: User-defined532255
+Node: Definition Syntax533059
+Ref: Definition Syntax-Footnote-1537969
+Node: Function Example538038
+Node: Function Caveats540632
+Node: Calling A Function541053
+Node: Variable Scope542168
+Node: Pass By Value/Reference545131
+Node: Return Statement548639
+Node: Dynamic Typing551620
+Node: Indirect Calls552551
+Node: Library Functions562236
+Ref: Library Functions-Footnote-1565749
+Ref: Library Functions-Footnote-2565892
+Node: Library Names566063
+Ref: Library Names-Footnote-1569534
+Ref: Library Names-Footnote-2569754
+Node: General Functions569840
+Node: Strtonum Function570868
+Node: Assert Function573798
+Node: Round Function577124
+Node: Cliff Random Function578667
+Node: Ordinal Functions579683
+Ref: Ordinal Functions-Footnote-1582753
+Ref: Ordinal Functions-Footnote-2583005
+Node: Join Function583214
+Ref: Join Function-Footnote-1584985
+Node: Getlocaltime Function585185
+Node: Readfile Function588926
+Node: Data File Management590765
+Node: Filetrans Function591397
+Node: Rewind Function595466
+Node: File Checking596853
+Node: Empty Files597947
+Node: Ignoring Assigns600177
+Node: Getopt Function601730
+Ref: Getopt Function-Footnote-1613034
+Node: Passwd Functions613237
+Ref: Passwd Functions-Footnote-1622212
+Node: Group Functions622300
+Node: Walking Arrays630384
+Node: Sample Programs632521
+Node: Running Examples633195
+Node: Clones633923
+Node: Cut Program635147
+Node: Egrep Program644992
+Ref: Egrep Program-Footnote-1652765
+Node: Id Program652875
+Node: Split Program656491
+Ref: Split Program-Footnote-1660010
+Node: Tee Program660138
+Node: Uniq Program662941
+Node: Wc Program670370
+Ref: Wc Program-Footnote-1674636
+Ref: Wc Program-Footnote-2674836
+Node: Miscellaneous Programs674928
+Node: Dupword Program676116
+Node: Alarm Program678147
+Node: Translate Program682896
+Ref: Translate Program-Footnote-1687283
+Ref: Translate Program-Footnote-2687511
+Node: Labels Program687645
+Ref: Labels Program-Footnote-1691016
+Node: Word Sorting691100
+Node: History Sorting694984
+Node: Extract Program696823
+Ref: Extract Program-Footnote-1704324
+Node: Simple Sed704452
+Node: Igawk Program707514
+Ref: Igawk Program-Footnote-1722671
+Ref: Igawk Program-Footnote-2722872
+Node: Anagram Program723010
+Node: Signature Program726078
+Node: Advanced Features727178
+Node: Nondecimal Data729060
+Node: Array Sorting730643
+Node: Controlling Array Traversal731340
+Node: Array Sorting Functions739578
+Ref: Array Sorting Functions-Footnote-1743252
+Ref: Array Sorting Functions-Footnote-2743345
+Node: Two-way I/O743539
+Ref: Two-way I/O-Footnote-1748971
+Node: TCP/IP Networking749041
+Node: Profiling751885
+Node: Internationalization759382
+Node: I18N and L10N760807
+Node: Explaining gettext761493
+Ref: Explaining gettext-Footnote-1766561
+Ref: Explaining gettext-Footnote-2766745
+Node: Programmer i18n766910
+Node: Translator i18n771112
+Node: String Extraction771905
+Ref: String Extraction-Footnote-1772866
+Node: Printf Ordering772952
+Ref: Printf Ordering-Footnote-1775736
+Node: I18N Portability775800
+Ref: I18N Portability-Footnote-1778249
+Node: I18N Example778312
+Ref: I18N Example-Footnote-1780950
+Node: Gawk I18N781022
+Node: Debugger781643
+Node: Debugging782614
+Node: Debugging Concepts783047
+Node: Debugging Terms784903
+Node: Awk Debugging787500
+Node: Sample Debugging Session788392
+Node: Debugger Invocation788912
+Node: Finding The Bug790244
+Node: List of Debugger Commands796732
+Node: Breakpoint Control798066
+Node: Debugger Execution Control801730
+Node: Viewing And Changing Data805090
+Node: Execution Stack808446
+Node: Debugger Info809913
+Node: Miscellaneous Debugger Commands813895
+Node: Readline Support819071
+Node: Limitations819902
+Node: Arbitrary Precision Arithmetic822154
+Ref: Arbitrary Precision Arithmetic-Footnote-1823805
+Node: General Arithmetic823953
+Node: Floating Point Issues825673
+Node: String Conversion Precision826554
+Ref: String Conversion Precision-Footnote-1828260
+Node: Unexpected Results828369
+Node: POSIX Floating Point Problems830522
+Ref: POSIX Floating Point Problems-Footnote-1834347
+Node: Integer Programming834385
+Node: Floating-point Programming836124
+Ref: Floating-point Programming-Footnote-1842455
+Ref: Floating-point Programming-Footnote-2842725
+Node: Floating-point Representation842989
+Node: Floating-point Context844154
+Ref: table-ieee-formats844993
+Node: Rounding Mode846377
+Ref: table-rounding-modes846856
+Ref: Rounding Mode-Footnote-1849871
+Node: Gawk and MPFR850050
+Node: Arbitrary Precision Floats851305
+Ref: Arbitrary Precision Floats-Footnote-1853748
+Node: Setting Precision854064
+Ref: table-predefined-precision-strings854750
+Node: Setting Rounding Mode856895
+Ref: table-gawk-rounding-modes857299
+Node: Floating-point Constants858486
+Node: Changing Precision859915
+Ref: Changing Precision-Footnote-1861315
+Node: Exact Arithmetic861489
+Node: Arbitrary Precision Integers864627
+Ref: Arbitrary Precision Integers-Footnote-1867645
+Node: Dynamic Extensions867792
+Node: Extension Intro869250
+Node: Plugin License870515
+Node: Extension Mechanism Outline871200
+Ref: load-extension871617
+Ref: load-new-function873095
+Ref: call-new-function874090
+Node: Extension API Description876105
+Node: Extension API Functions Introduction877318
+Node: General Data Types882184
+Ref: General Data Types-Footnote-1887786
+Node: Requesting Values888085
+Ref: table-value-types-returned888816
+Node: Constructor Functions889770
+Node: Registration Functions892790
+Node: Extension Functions893475
+Node: Exit Callback Functions895700
+Node: Extension Version String896949
+Node: Input Parsers897599
+Node: Output Wrappers907356
+Node: Two-way processors911866
+Node: Printing Messages914074
+Ref: Printing Messages-Footnote-1915151
+Node: Updating `ERRNO'915303
+Node: Accessing Parameters916042
+Node: Symbol Table Access917272
+Node: Symbol table by name917784
+Node: Symbol table by cookie919531
+Ref: Symbol table by cookie-Footnote-1923661
+Node: Cached values923724
+Ref: Cached values-Footnote-1927173
+Node: Array Manipulation927264
+Ref: Array Manipulation-Footnote-1928362
+Node: Array Data Types928401
+Ref: Array Data Types-Footnote-1931104
+Node: Array Functions931196
+Node: Flattening Arrays934962
+Node: Creating Arrays941814
+Node: Extension API Variables946539
+Node: Extension Versioning947175
+Node: Extension API Informational Variables949076
+Node: Extension API Boilerplate950162
+Node: Finding Extensions953966
+Node: Extension Example954526
+Node: Internal File Description955257
+Node: Internal File Ops959348
+Ref: Internal File Ops-Footnote-1970856
+Node: Using Internal File Ops970996
+Ref: Using Internal File Ops-Footnote-1973349
+Node: Extension Samples973615
+Node: Extension Sample File Functions975139
+Node: Extension Sample Fnmatch983626
+Node: Extension Sample Fork985352
+Node: Extension Sample Inplace986570
+Node: Extension Sample Ord988348
+Node: Extension Sample Readdir989184
+Node: Extension Sample Revout990716
+Node: Extension Sample Rev2way991309
+Node: Extension Sample Read write array991999
+Node: Extension Sample Readfile993882
+Node: Extension Sample API Tests994700
+Node: Extension Sample Time995225
+Node: gawkextlib996589
+Node: Language History999349
+Node: V7/SVR3.11000871
+Node: SVR41003192
+Node: POSIX1004634
+Node: BTL1006020
+Node: POSIX/GNU1006754
+Node: Common Extensions1012289
+Node: Ranges and Locales1013595
+Ref: Ranges and Locales-Footnote-11018213
+Ref: Ranges and Locales-Footnote-21018240
+Ref: Ranges and Locales-Footnote-31018500
+Node: Contributors1018721
+Node: Installation1023600
+Node: Gawk Distribution1024494
+Node: Getting1024978
+Node: Extracting1025804
+Node: Distribution contents1027496
+Node: Unix Installation1032757
+Node: Quick Installation1033374
+Node: Additional Configuration Options1035818
+Node: Configuration Philosophy1037295
+Node: Non-Unix Installation1039649
+Node: PC Installation1040107
+Node: PC Binary Installation1041406
+Node: PC Compiling1043254
+Node: PC Testing1046198
+Node: PC Using1047374
+Node: Cygwin1051559
+Node: MSYS1052559
+Node: VMS Installation1053073
+Node: VMS Compilation1053676
+Ref: VMS Compilation-Footnote-11054683
+Node: VMS Installation Details1054741
+Node: VMS Running1056376
+Node: VMS Old Gawk1057983
+Node: Bugs1058457
+Node: Other Versions1062309
+Node: Notes1067910
+Node: Compatibility Mode1068710
+Node: Additions1069493
+Node: Accessing The Source1070420
+Node: Adding Code1071860
+Node: New Ports1077905
+Node: Derived Files1082040
+Ref: Derived Files-Footnote-11087361
+Ref: Derived Files-Footnote-21087395
+Ref: Derived Files-Footnote-31087995
+Node: Future Extensions1088093
+Node: Implementation Limitations1088674
+Node: Extension Design1089926
+Node: Old Extension Problems1091080
+Ref: Old Extension Problems-Footnote-11092588
+Node: Extension New Mechanism Goals1092645
+Ref: Extension New Mechanism Goals-Footnote-11096011
+Node: Extension Other Design Decisions1096197
+Node: Extension Future Growth1098303
+Node: Old Extension Mechanism1099139
+Node: Basic Concepts1100879
+Node: Basic High Level1101560
+Ref: figure-general-flow1101831
+Ref: figure-process-flow1102430
+Ref: Basic High Level-Footnote-11105659
+Node: Basic Data Typing1105844
+Node: Glossary1109199
+Node: Copying1134661
+Node: GNU Free Documentation License1172218
+Node: Index1197355
 
 End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 2d23581c..bbf2fc7e 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -608,6 +608,8 @@ particular records in a file and perform operations upon them.
 * Join Function::                       A function to join an array into a
                                         string.
 * Getlocaltime Function::               A function to get formatted times.
+* Readfile Function::                   A function to read an entire file at
+                                        once.
 * Data File Management::                Functions for managing command-line
                                         data files.
 * Filetrans Function::                  A function for handling data file
@@ -19074,6 +19076,7 @@ programming use.
                                 vice versa.
 * Join Function::               A function to join an array into a string.
 * Getlocaltime Function::       A function to get formatted times.
+* Readfile Function::           A function to read an entire file at once.
 @end menu
 
 @node Strtonum Function
@@ -19698,6 +19701,81 @@ A more general design for the @code{getlocaltime()} function would have
 allowed the user to supply an optional timestamp value to use instead
 of the current time.
 
+@node Readfile Function
+@subsection Reading A Whole File At Once
+
+Often, it is convenient to have the entire contents of a file available
+in memory as a single string. A straightforward but naive way to
+do that might be as follows:
+
+@example
+function readfile(file,    tmp, contents)
+@{
+    if ((getline tmp < file) < 0)
+        return
+
+    contents = tmp
+    while (getline tmp < file) > 0)
+        contents = contents RT tmp
+
+    close(file)
+    return contents
+@}
+@end example
+
+This function reads from @code{file} one record at a time, building
+up the full contents of the file in the local variable @code{contents}.
+It works, but is not necessarily efficient.
+
+The following function, based on a suggestion by Denis Shirokov,
+reads the entire contents of the named file in one shot:
+
+@cindex @code{readfile()} user-defined function
+@example
+@c file eg/lib/readfile.awk
+# readfile.awk --- read an entire file at once
+@c endfile
+@ignore
+@c file eg/lib/readfile.awk
+#
+# Original idea by Denis Shirokov, cosmogen@@gmail.com, April 2013
+#
+@c endfile
+@end ignore
+@c file eg/lib/readfile.awk
+
+function readfile(file,     tmp, save_rs)
+@{
+    save_rs = RS
+    RS = "^$"
+    getline tmp < file
+    close(file)
+    RS = save_rs
+
+    return tmp
+@}
+@c endfile
+@end example
+
+It works by setting @code{RS} to @samp{^$}, a regular expression that
+will never match if the file has contents.  @command{gawk} reads data from
+the file into @code{tmp} attempting to match @code{RS}.  The match fails
+after each read, but fails quickly, such that @command{gawk} fills
+@code{tmp} with the entire contents of the file.
+(@xref{Records}, for information on @code{RT} and @code{RS}.)
+
+In the case that @code{file} is empty, the return value is the null
+string.  Thus calling code may use something like:
+
+@example
+contents = readfile("/some/path")
+if (length(contents) == 0)
+    # file was empty @dots{}
+@end example
+
+This tests the result to see if it is empty or not. An equivalent
+test would be @samp{contents == ""}.
+
 @node Data File Management
 @section Data File Management
 
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index 04b8ed56..60e25a2d 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -603,6 +603,8 @@ particular records in a file and perform operations upon them.
 * Join Function::                       A function to join an array into a
                                         string.
 * Getlocaltime Function::               A function to get formatted times.
+* Readfile Function::                   A function to read an entire file at
+                                        once.
 * Data File Management::                Functions for managing command-line
                                         data files.
 * Filetrans Function::                  A function for handling data file
@@ -18252,6 +18254,7 @@ programming use.
                                 vice versa.
 * Join Function::               A function to join an array into a string.
 * Getlocaltime Function::       A function to get formatted times.
+* Readfile Function::           A function to read an entire file at once.
 @end menu
 
 @node Strtonum Function
@@ -18876,6 +18879,81 @@ A more general design for the @code{getlocaltime()} function would have
 allowed the user to supply an optional timestamp value to use instead
 of the current time.
 
+@node Readfile Function
+@subsection Reading A Whole File At Once
+
+Often, it is convenient to have the entire contents of a file available
+in memory as a single string. A straightforward but naive way to
+do that might be as follows:
+
+@example
+function readfile(file,    tmp, contents)
+@{
+    if ((getline tmp < file) < 0)
+        return
+
+    contents = tmp
+    while (getline tmp < file) > 0)
+        contents = contents RT tmp
+
+    close(file)
+    return contents
+@}
+@end example
+
+This function reads from @code{file} one record at a time, building
+up the full contents of the file in the local variable @code{contents}.
+It works, but is not necessarily efficient.
+
+The following function, based on a suggestion by Denis Shirokov,
+reads the entire contents of the named file in one shot:
+
+@cindex @code{readfile()} user-defined function
+@example
+@c file eg/lib/readfile.awk
+# readfile.awk --- read an entire file at once
+@c endfile
+@ignore
+@c file eg/lib/readfile.awk
+#
+# Original idea by Denis Shirokov, cosmogen@@gmail.com, April 2013
+#
+@c endfile
+@end ignore
+@c file eg/lib/readfile.awk
+
+function readfile(file,     tmp, save_rs)
+@{
+    save_rs = RS
+    RS = "^$"
+    getline tmp < file
+    close(file)
+    RS = save_rs
+
+    return tmp
+@}
+@c endfile
+@end example
+
+It works by setting @code{RS} to @samp{^$}, a regular expression that
+will never match if the file has contents.  @command{gawk} reads data from
+the file into @code{tmp} attempting to match @code{RS}.  The match fails
+after each read, but fails quickly, such that @command{gawk} fills
+@code{tmp} with the entire contents of the file.
+(@xref{Records}, for information on @code{RT} and @code{RS}.)
+
+In the case that @code{file} is empty, the return value is the null
+string.  Thus calling code may use something like:
+
+@example
+contents = readfile("/some/path")
+if (length(contents) == 0)
+    # file was empty @dots{}
+@end example
+
+This tests the result to see if it is empty or not. An equivalent
+test would be @samp{contents == ""}.
+
 @node Data File Management
 @section Data File Management