Merge branch 'gawk-4.1-stable'

6 files changed, 759 insertions, 522 deletions

diff --git a/ChangeLog b/ChangeLog
index 15c7b37b..64caea35 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2013-09-24         Arnold D. Robbins     <arnold@skeeve.com>
+
+	* debug.c (find_rule): Handle case where lineno is zero. Can happen
+	if break is given without a line number on a current line. Thanks
+	to Ray Song <i@maskray.me> for the report.
+
 2013-09-19         Arnold D. Robbins     <arnold@skeeve.com>
 
 	* dfa.c (parse_bracket_exp): Use code from grep to keep things within
diff --git a/debug.c b/debug.c
index 949ebb49..357ce725 100644
--- a/debug.c
+++ b/debug.c
@@ -2068,12 +2068,18 @@ find_rule(char *src, long lineno)
 {
 	INSTRUCTION *rp;
 
-	assert(lineno > 0);
-	for (rp = rule_list->nexti; rp != NULL; rp = rp->nexti) {
-		if ((rp - 1)->source_file == src
-				&& lineno >= (rp + 1)->first_line
-				&& lineno <= (rp + 1)->last_line)
-			return (rp - 1);
+	if (lineno == 0) {
+		for (rp = rule_list->nexti; rp != NULL; rp = rp->nexti) {
+			if ((rp - 1)->source_file == src && (rp - 1)->source_line > 0)
+				return (rp - 1);
+		}
+	} else {
+		for (rp = rule_list->nexti; rp != NULL; rp = rp->nexti) {
+			if ((rp - 1)->source_file == src
+					&& lineno >= (rp + 1)->first_line
+					&& lineno <= (rp + 1)->last_line)
+				return (rp - 1);
+		}
 	}
 	return NULL;
 }
diff --git a/doc/ChangeLog b/doc/ChangeLog
index e79a1c6c..1ec72010 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 0fa9bdee..79d5eacc 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
@@ -13672,6 +13674,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
@@ -14064,7 +14067,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
 -------------------------------
@@ -14146,6 +14149,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
@@ -31501,6 +31564,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)
@@ -32096,520 +32160,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-1425954
-Ref: Auto-set-Footnote-2426159
-Node: ARGC and ARGV426215
-Node: Arrays430066
-Node: Array Basics431571
-Node: Array Intro432397
-Node: Reference to Elements436715
-Node: Assigning Elements438985
-Node: Array Example439476
-Node: Scanning an Array441208
-Node: Controlling Scanning443522
-Ref: Controlling Scanning-Footnote-1448445
-Node: Delete448761
-Ref: Delete-Footnote-1451526
-Node: Numeric Array Subscripts451583
-Node: Uninitialized Subscripts453766
-Node: Multi-dimensional455394
-Node: Multi-scanning458488
-Node: Arrays of Arrays460079
-Node: Functions464720
-Node: Built-in465539
-Node: Calling Built-in466617
-Node: Numeric Functions468605
-Ref: Numeric Functions-Footnote-1472437
-Ref: Numeric Functions-Footnote-2472794
-Ref: Numeric Functions-Footnote-3472842
-Node: String Functions473111
-Ref: String Functions-Footnote-1496669
-Ref: String Functions-Footnote-2496798
-Ref: String Functions-Footnote-3497046
-Node: Gory Details497133
-Ref: table-sub-escapes498812
-Ref: table-sub-posix-92500166
-Ref: table-sub-proposed501517
-Ref: table-posix-sub502871
-Ref: table-gensub-escapes504416
-Ref: Gory Details-Footnote-1505592
-Ref: Gory Details-Footnote-2505643
-Node: I/O Functions505794
-Ref: I/O Functions-Footnote-1512779
-Node: Time Functions512926
-Ref: Time Functions-Footnote-1523859
-Ref: Time Functions-Footnote-2523927
-Ref: Time Functions-Footnote-3524085
-Ref: Time Functions-Footnote-4524196
-Ref: Time Functions-Footnote-5524308
-Ref: Time Functions-Footnote-6524535
-Node: Bitwise Functions524801
-Ref: table-bitwise-ops525359
-Ref: Bitwise Functions-Footnote-1529580
-Node: Type Functions529764
-Node: I18N Functions530915
-Node: User-defined532542
-Node: Definition Syntax533346
-Ref: Definition Syntax-Footnote-1538256
-Node: Function Example538325
-Node: Function Caveats540919
-Node: Calling A Function541340
-Node: Variable Scope542455
-Node: Pass By Value/Reference545418
-Node: Return Statement548926
-Node: Dynamic Typing551907
-Node: Indirect Calls552838
-Node: Library Functions562523
-Ref: Library Functions-Footnote-1566036
-Ref: Library Functions-Footnote-2566179
-Node: Library Names566350
-Ref: Library Names-Footnote-1569821
-Ref: Library Names-Footnote-2570041
-Node: General Functions570127
-Node: Strtonum Function571080
-Node: Assert Function574010
-Node: Round Function577336
-Node: Cliff Random Function578879
-Node: Ordinal Functions579895
-Ref: Ordinal Functions-Footnote-1582965
-Ref: Ordinal Functions-Footnote-2583217
-Node: Join Function583426
-Ref: Join Function-Footnote-1585197
-Node: Getlocaltime Function585397
-Node: Data File Management589112
-Node: Filetrans Function589744
-Node: Rewind Function593813
-Node: File Checking595200
-Node: Empty Files596294
-Node: Ignoring Assigns598524
-Node: Getopt Function600077
-Ref: Getopt Function-Footnote-1611381
-Node: Passwd Functions611584
-Ref: Passwd Functions-Footnote-1620559
-Node: Group Functions620647
-Node: Walking Arrays628731
-Node: Sample Programs630868
-Node: Running Examples631542
-Node: Clones632270
-Node: Cut Program633494
-Node: Egrep Program643339
-Ref: Egrep Program-Footnote-1651112
-Node: Id Program651222
-Node: Split Program654838
-Ref: Split Program-Footnote-1658357
-Node: Tee Program658485
-Node: Uniq Program661288
-Node: Wc Program668717
-Ref: Wc Program-Footnote-1672983
-Ref: Wc Program-Footnote-2673183
-Node: Miscellaneous Programs673275
-Node: Dupword Program674463
-Node: Alarm Program676494
-Node: Translate Program681243
-Ref: Translate Program-Footnote-1685630
-Ref: Translate Program-Footnote-2685858
-Node: Labels Program685992
-Ref: Labels Program-Footnote-1689363
-Node: Word Sorting689447
-Node: History Sorting693331
-Node: Extract Program695170
-Ref: Extract Program-Footnote-1702671
-Node: Simple Sed702799
-Node: Igawk Program705861
-Ref: Igawk Program-Footnote-1721018
-Ref: Igawk Program-Footnote-2721219
-Node: Anagram Program721357
-Node: Signature Program724425
-Node: Advanced Features725525
-Node: Nondecimal Data727407
-Node: Array Sorting728990
-Node: Controlling Array Traversal729687
-Node: Array Sorting Functions737925
-Ref: Array Sorting Functions-Footnote-1741599
-Ref: Array Sorting Functions-Footnote-2741692
-Node: Two-way I/O741886
-Ref: Two-way I/O-Footnote-1747318
-Node: TCP/IP Networking747388
-Node: Profiling750232
-Node: Internationalization757729
-Node: I18N and L10N759154
-Node: Explaining gettext759840
-Ref: Explaining gettext-Footnote-1764908
-Ref: Explaining gettext-Footnote-2765092
-Node: Programmer i18n765257
-Node: Translator i18n769459
-Node: String Extraction770252
-Ref: String Extraction-Footnote-1771213
-Node: Printf Ordering771299
-Ref: Printf Ordering-Footnote-1774083
-Node: I18N Portability774147
-Ref: I18N Portability-Footnote-1776596
-Node: I18N Example776659
-Ref: I18N Example-Footnote-1779297
-Node: Gawk I18N779369
-Node: Debugger779990
-Node: Debugging780961
-Node: Debugging Concepts781394
-Node: Debugging Terms783250
-Node: Awk Debugging785847
-Node: Sample Debugging Session786739
-Node: Debugger Invocation787259
-Node: Finding The Bug788591
-Node: List of Debugger Commands795079
-Node: Breakpoint Control796413
-Node: Debugger Execution Control800077
-Node: Viewing And Changing Data803437
-Node: Execution Stack806793
-Node: Debugger Info808260
-Node: Miscellaneous Debugger Commands812242
-Node: Readline Support817418
-Node: Limitations818249
-Node: Arbitrary Precision Arithmetic820501
-Ref: Arbitrary Precision Arithmetic-Footnote-1822152
-Node: General Arithmetic822300
-Node: Floating Point Issues824020
-Node: String Conversion Precision824901
-Ref: String Conversion Precision-Footnote-1826607
-Node: Unexpected Results826716
-Node: POSIX Floating Point Problems828869
-Ref: POSIX Floating Point Problems-Footnote-1832694
-Node: Integer Programming832732
-Node: Floating-point Programming834471
-Ref: Floating-point Programming-Footnote-1840802
-Ref: Floating-point Programming-Footnote-2841072
-Node: Floating-point Representation841336
-Node: Floating-point Context842501
-Ref: table-ieee-formats843340
-Node: Rounding Mode844724
-Ref: table-rounding-modes845203
-Ref: Rounding Mode-Footnote-1848218
-Node: Gawk and MPFR848397
-Node: Arbitrary Precision Floats849652
-Ref: Arbitrary Precision Floats-Footnote-1852095
-Node: Setting Precision852411
-Ref: table-predefined-precision-strings853097
-Node: Setting Rounding Mode855242
-Ref: table-gawk-rounding-modes855646
-Node: Floating-point Constants856833
-Node: Changing Precision858262
-Ref: Changing Precision-Footnote-1859662
-Node: Exact Arithmetic859836
-Node: Arbitrary Precision Integers862974
-Ref: Arbitrary Precision Integers-Footnote-1865992
-Node: Dynamic Extensions866139
-Node: Extension Intro867597
-Node: Plugin License868862
-Node: Extension Mechanism Outline869547
-Ref: load-extension869964
-Ref: load-new-function871442
-Ref: call-new-function872437
-Node: Extension API Description874452
-Node: Extension API Functions Introduction875665
-Node: General Data Types880531
-Ref: General Data Types-Footnote-1886133
-Node: Requesting Values886432
-Ref: table-value-types-returned887163
-Node: Constructor Functions888117
-Node: Registration Functions891137
-Node: Extension Functions891822
-Node: Exit Callback Functions894047
-Node: Extension Version String895296
-Node: Input Parsers895946
-Node: Output Wrappers905703
-Node: Two-way processors910213
-Node: Printing Messages912421
-Ref: Printing Messages-Footnote-1913498
-Node: Updating `ERRNO'913650
-Node: Accessing Parameters914389
-Node: Symbol Table Access915619
-Node: Symbol table by name916131
-Node: Symbol table by cookie917878
-Ref: Symbol table by cookie-Footnote-1922008
-Node: Cached values922071
-Ref: Cached values-Footnote-1925520
-Node: Array Manipulation925611
-Ref: Array Manipulation-Footnote-1926709
-Node: Array Data Types926748
-Ref: Array Data Types-Footnote-1929451
-Node: Array Functions929543
-Node: Flattening Arrays933309
-Node: Creating Arrays940161
-Node: Extension API Variables944886
-Node: Extension Versioning945522
-Node: Extension API Informational Variables947423
-Node: Extension API Boilerplate948509
-Node: Finding Extensions952313
-Node: Extension Example952873
-Node: Internal File Description953604
-Node: Internal File Ops957695
-Ref: Internal File Ops-Footnote-1969203
-Node: Using Internal File Ops969343
-Ref: Using Internal File Ops-Footnote-1971696
-Node: Extension Samples971962
-Node: Extension Sample File Functions973486
-Node: Extension Sample Fnmatch981973
-Node: Extension Sample Fork983699
-Node: Extension Sample Inplace984917
-Node: Extension Sample Ord986695
-Node: Extension Sample Readdir987531
-Node: Extension Sample Revout989063
-Node: Extension Sample Rev2way989656
-Node: Extension Sample Read write array990346
-Node: Extension Sample Readfile992229
-Node: Extension Sample API Tests993047
-Node: Extension Sample Time993572
-Node: gawkextlib994936
-Node: Language History997696
-Node: V7/SVR3.1999218
-Node: SVR41001539
-Node: POSIX1002981
-Node: BTL1004367
-Node: POSIX/GNU1005101
-Node: Common Extensions1010636
-Node: Ranges and Locales1011942
-Ref: Ranges and Locales-Footnote-11016560
-Ref: Ranges and Locales-Footnote-21016587
-Ref: Ranges and Locales-Footnote-31016847
-Node: Contributors1017068
-Node: Installation1021947
-Node: Gawk Distribution1022841
-Node: Getting1023325
-Node: Extracting1024151
-Node: Distribution contents1025843
-Node: Unix Installation1031104
-Node: Quick Installation1031721
-Node: Additional Configuration Options1034165
-Node: Configuration Philosophy1035642
-Node: Non-Unix Installation1037996
-Node: PC Installation1038454
-Node: PC Binary Installation1039753
-Node: PC Compiling1041601
-Node: PC Testing1044545
-Node: PC Using1045721
-Node: Cygwin1049906
-Node: MSYS1050906
-Node: VMS Installation1051420
-Node: VMS Compilation1052023
-Ref: VMS Compilation-Footnote-11053030
-Node: VMS Installation Details1053088
-Node: VMS Running1054723
-Node: VMS Old Gawk1056330
-Node: Bugs1056804
-Node: Other Versions1060656
-Node: Notes1066257
-Node: Compatibility Mode1067057
-Node: Additions1067840
-Node: Accessing The Source1068767
-Node: Adding Code1070207
-Node: New Ports1076252
-Node: Derived Files1080387
-Ref: Derived Files-Footnote-11085708
-Ref: Derived Files-Footnote-21085742
-Ref: Derived Files-Footnote-31086342
-Node: Future Extensions1086440
-Node: Implementation Limitations1087021
-Node: Extension Design1088273
-Node: Old Extension Problems1089427
-Ref: Old Extension Problems-Footnote-11090935
-Node: Extension New Mechanism Goals1090992
-Ref: Extension New Mechanism Goals-Footnote-11094358
-Node: Extension Other Design Decisions1094544
-Node: Extension Future Growth1096650
-Node: Old Extension Mechanism1097486
-Node: Basic Concepts1099226
-Node: Basic High Level1099907
-Ref: figure-general-flow1100178
-Ref: figure-process-flow1100777
-Ref: Basic High Level-Footnote-11104006
-Node: Basic Data Typing1104191
-Node: Glossary1107546
-Node: Copying1133008
-Node: GNU Free Documentation License1170565
-Node: Index1195702
+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-1426077
+Ref: Auto-set-Footnote-2426282
+Node: ARGC and ARGV426338
+Node: Arrays430189
+Node: Array Basics431694
+Node: Array Intro432520
+Node: Reference to Elements436838
+Node: Assigning Elements439108
+Node: Array Example439599
+Node: Scanning an Array441331
+Node: Controlling Scanning443645
+Ref: Controlling Scanning-Footnote-1448568
+Node: Delete448884
+Ref: Delete-Footnote-1451649
+Node: Numeric Array Subscripts451706
+Node: Uninitialized Subscripts453889
+Node: Multi-dimensional455517
+Node: Multi-scanning458611
+Node: Arrays of Arrays460202
+Node: Functions464843
+Node: Built-in465662
+Node: Calling Built-in466740
+Node: Numeric Functions468728
+Ref: Numeric Functions-Footnote-1472560
+Ref: Numeric Functions-Footnote-2472917
+Ref: Numeric Functions-Footnote-3472965
+Node: String Functions473234
+Ref: String Functions-Footnote-1496792
+Ref: String Functions-Footnote-2496921
+Ref: String Functions-Footnote-3497169
+Node: Gory Details497256
+Ref: table-sub-escapes498935
+Ref: table-sub-posix-92500289
+Ref: table-sub-proposed501640
+Ref: table-posix-sub502994
+Ref: table-gensub-escapes504539
+Ref: Gory Details-Footnote-1505715
+Ref: Gory Details-Footnote-2505766
+Node: I/O Functions505917
+Ref: I/O Functions-Footnote-1512902
+Node: Time Functions513049
+Ref: Time Functions-Footnote-1523982
+Ref: Time Functions-Footnote-2524050
+Ref: Time Functions-Footnote-3524208
+Ref: Time Functions-Footnote-4524319
+Ref: Time Functions-Footnote-5524431
+Ref: Time Functions-Footnote-6524658
+Node: Bitwise Functions524924
+Ref: table-bitwise-ops525482
+Ref: Bitwise Functions-Footnote-1529703
+Node: Type Functions529887
+Node: I18N Functions531038
+Node: User-defined532665
+Node: Definition Syntax533469
+Ref: Definition Syntax-Footnote-1538379
+Node: Function Example538448
+Node: Function Caveats541042
+Node: Calling A Function541463
+Node: Variable Scope542578
+Node: Pass By Value/Reference545541
+Node: Return Statement549049
+Node: Dynamic Typing552030
+Node: Indirect Calls552961
+Node: Library Functions562646
+Ref: Library Functions-Footnote-1566159
+Ref: Library Functions-Footnote-2566302
+Node: Library Names566473
+Ref: Library Names-Footnote-1569944
+Ref: Library Names-Footnote-2570164
+Node: General Functions570250
+Node: Strtonum Function571278
+Node: Assert Function574208
+Node: Round Function577534
+Node: Cliff Random Function579077
+Node: Ordinal Functions580093
+Ref: Ordinal Functions-Footnote-1583163
+Ref: Ordinal Functions-Footnote-2583415
+Node: Join Function583624
+Ref: Join Function-Footnote-1585395
+Node: Getlocaltime Function585595
+Node: Readfile Function589336
+Node: Data File Management591175
+Node: Filetrans Function591807
+Node: Rewind Function595876
+Node: File Checking597263
+Node: Empty Files598357
+Node: Ignoring Assigns600587
+Node: Getopt Function602140
+Ref: Getopt Function-Footnote-1613444
+Node: Passwd Functions613647
+Ref: Passwd Functions-Footnote-1622622
+Node: Group Functions622710
+Node: Walking Arrays630794
+Node: Sample Programs632931
+Node: Running Examples633605
+Node: Clones634333
+Node: Cut Program635557
+Node: Egrep Program645402
+Ref: Egrep Program-Footnote-1653175
+Node: Id Program653285
+Node: Split Program656901
+Ref: Split Program-Footnote-1660420
+Node: Tee Program660548
+Node: Uniq Program663351
+Node: Wc Program670780
+Ref: Wc Program-Footnote-1675046
+Ref: Wc Program-Footnote-2675246
+Node: Miscellaneous Programs675338
+Node: Dupword Program676526
+Node: Alarm Program678557
+Node: Translate Program683306
+Ref: Translate Program-Footnote-1687693
+Ref: Translate Program-Footnote-2687921
+Node: Labels Program688055
+Ref: Labels Program-Footnote-1691426
+Node: Word Sorting691510
+Node: History Sorting695394
+Node: Extract Program697233
+Ref: Extract Program-Footnote-1704734
+Node: Simple Sed704862
+Node: Igawk Program707924
+Ref: Igawk Program-Footnote-1723081
+Ref: Igawk Program-Footnote-2723282
+Node: Anagram Program723420
+Node: Signature Program726488
+Node: Advanced Features727588
+Node: Nondecimal Data729470
+Node: Array Sorting731053
+Node: Controlling Array Traversal731750
+Node: Array Sorting Functions739988
+Ref: Array Sorting Functions-Footnote-1743662
+Ref: Array Sorting Functions-Footnote-2743755
+Node: Two-way I/O743949
+Ref: Two-way I/O-Footnote-1749381
+Node: TCP/IP Networking749451
+Node: Profiling752295
+Node: Internationalization759792
+Node: I18N and L10N761217
+Node: Explaining gettext761903
+Ref: Explaining gettext-Footnote-1766971
+Ref: Explaining gettext-Footnote-2767155
+Node: Programmer i18n767320
+Node: Translator i18n771522
+Node: String Extraction772315
+Ref: String Extraction-Footnote-1773276
+Node: Printf Ordering773362
+Ref: Printf Ordering-Footnote-1776146
+Node: I18N Portability776210
+Ref: I18N Portability-Footnote-1778659
+Node: I18N Example778722
+Ref: I18N Example-Footnote-1781360
+Node: Gawk I18N781432
+Node: Debugger782053
+Node: Debugging783024
+Node: Debugging Concepts783457
+Node: Debugging Terms785313
+Node: Awk Debugging787910
+Node: Sample Debugging Session788802
+Node: Debugger Invocation789322
+Node: Finding The Bug790654
+Node: List of Debugger Commands797142
+Node: Breakpoint Control798476
+Node: Debugger Execution Control802140
+Node: Viewing And Changing Data805500
+Node: Execution Stack808856
+Node: Debugger Info810323
+Node: Miscellaneous Debugger Commands814305
+Node: Readline Support819481
+Node: Limitations820312
+Node: Arbitrary Precision Arithmetic822564
+Ref: Arbitrary Precision Arithmetic-Footnote-1824215
+Node: General Arithmetic824363
+Node: Floating Point Issues826083
+Node: String Conversion Precision826964
+Ref: String Conversion Precision-Footnote-1828670
+Node: Unexpected Results828779
+Node: POSIX Floating Point Problems830932
+Ref: POSIX Floating Point Problems-Footnote-1834757
+Node: Integer Programming834795
+Node: Floating-point Programming836534
+Ref: Floating-point Programming-Footnote-1842865
+Ref: Floating-point Programming-Footnote-2843135
+Node: Floating-point Representation843399
+Node: Floating-point Context844564
+Ref: table-ieee-formats845403
+Node: Rounding Mode846787
+Ref: table-rounding-modes847266
+Ref: Rounding Mode-Footnote-1850281
+Node: Gawk and MPFR850460
+Node: Arbitrary Precision Floats851715
+Ref: Arbitrary Precision Floats-Footnote-1854158
+Node: Setting Precision854474
+Ref: table-predefined-precision-strings855160
+Node: Setting Rounding Mode857305
+Ref: table-gawk-rounding-modes857709
+Node: Floating-point Constants858896
+Node: Changing Precision860325
+Ref: Changing Precision-Footnote-1861725
+Node: Exact Arithmetic861899
+Node: Arbitrary Precision Integers865037
+Ref: Arbitrary Precision Integers-Footnote-1868055
+Node: Dynamic Extensions868202
+Node: Extension Intro869660
+Node: Plugin License870925
+Node: Extension Mechanism Outline871610
+Ref: load-extension872027
+Ref: load-new-function873505
+Ref: call-new-function874500
+Node: Extension API Description876515
+Node: Extension API Functions Introduction877728
+Node: General Data Types882594
+Ref: General Data Types-Footnote-1888196
+Node: Requesting Values888495
+Ref: table-value-types-returned889226
+Node: Constructor Functions890180
+Node: Registration Functions893200
+Node: Extension Functions893885
+Node: Exit Callback Functions896110
+Node: Extension Version String897359
+Node: Input Parsers898009
+Node: Output Wrappers907766
+Node: Two-way processors912276
+Node: Printing Messages914484
+Ref: Printing Messages-Footnote-1915561
+Node: Updating `ERRNO'915713
+Node: Accessing Parameters916452
+Node: Symbol Table Access917682
+Node: Symbol table by name918194
+Node: Symbol table by cookie919941
+Ref: Symbol table by cookie-Footnote-1924071
+Node: Cached values924134
+Ref: Cached values-Footnote-1927583
+Node: Array Manipulation927674
+Ref: Array Manipulation-Footnote-1928772
+Node: Array Data Types928811
+Ref: Array Data Types-Footnote-1931514
+Node: Array Functions931606
+Node: Flattening Arrays935372
+Node: Creating Arrays942224
+Node: Extension API Variables946949
+Node: Extension Versioning947585
+Node: Extension API Informational Variables949486
+Node: Extension API Boilerplate950572
+Node: Finding Extensions954376
+Node: Extension Example954936
+Node: Internal File Description955667
+Node: Internal File Ops959758
+Ref: Internal File Ops-Footnote-1971266
+Node: Using Internal File Ops971406
+Ref: Using Internal File Ops-Footnote-1973759
+Node: Extension Samples974025
+Node: Extension Sample File Functions975549
+Node: Extension Sample Fnmatch984036
+Node: Extension Sample Fork985762
+Node: Extension Sample Inplace986980
+Node: Extension Sample Ord988758
+Node: Extension Sample Readdir989594
+Node: Extension Sample Revout991126
+Node: Extension Sample Rev2way991719
+Node: Extension Sample Read write array992409
+Node: Extension Sample Readfile994292
+Node: Extension Sample API Tests995110
+Node: Extension Sample Time995635
+Node: gawkextlib996999
+Node: Language History999759
+Node: V7/SVR3.11001281
+Node: SVR41003602
+Node: POSIX1005044
+Node: BTL1006430
+Node: POSIX/GNU1007164
+Node: Common Extensions1012699
+Node: Ranges and Locales1014005
+Ref: Ranges and Locales-Footnote-11018623
+Ref: Ranges and Locales-Footnote-21018650
+Ref: Ranges and Locales-Footnote-31018910
+Node: Contributors1019131
+Node: Installation1024010
+Node: Gawk Distribution1024904
+Node: Getting1025388
+Node: Extracting1026214
+Node: Distribution contents1027906
+Node: Unix Installation1033167
+Node: Quick Installation1033784
+Node: Additional Configuration Options1036228
+Node: Configuration Philosophy1037705
+Node: Non-Unix Installation1040059
+Node: PC Installation1040517
+Node: PC Binary Installation1041816
+Node: PC Compiling1043664
+Node: PC Testing1046608
+Node: PC Using1047784
+Node: Cygwin1051969
+Node: MSYS1052969
+Node: VMS Installation1053483
+Node: VMS Compilation1054086
+Ref: VMS Compilation-Footnote-11055093
+Node: VMS Installation Details1055151
+Node: VMS Running1056786
+Node: VMS Old Gawk1058393
+Node: Bugs1058867
+Node: Other Versions1062719
+Node: Notes1068320
+Node: Compatibility Mode1069120
+Node: Additions1069903
+Node: Accessing The Source1070830
+Node: Adding Code1072270
+Node: New Ports1078315
+Node: Derived Files1082450
+Ref: Derived Files-Footnote-11087771
+Ref: Derived Files-Footnote-21087805
+Ref: Derived Files-Footnote-31088405
+Node: Future Extensions1088503
+Node: Implementation Limitations1089084
+Node: Extension Design1090336
+Node: Old Extension Problems1091490
+Ref: Old Extension Problems-Footnote-11092998
+Node: Extension New Mechanism Goals1093055
+Ref: Extension New Mechanism Goals-Footnote-11096421
+Node: Extension Other Design Decisions1096607
+Node: Extension Future Growth1098713
+Node: Old Extension Mechanism1099549
+Node: Basic Concepts1101289
+Node: Basic High Level1101970
+Ref: figure-general-flow1102241
+Ref: figure-process-flow1102840
+Ref: Basic High Level-Footnote-11106069
+Node: Basic Data Typing1106254
+Node: Glossary1109609
+Node: Copying1135071
+Node: GNU Free Documentation License1172628
+Node: Index1197765
 
 End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 2b67a6ca..1c642255 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
@@ -19082,6 +19084,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
@@ -19706,6 +19709,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 56c0c3f1..e36a465b 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
@@ -18260,6 +18262,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
@@ -18884,6 +18887,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