Doc update.

4 files changed, 275 insertions, 239 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 37a28ac0..4aaad6c5 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,8 @@
+2022-02-27         Arnold D. Robbins     <arnold@skeeve.com>
+
+	* gawktexi.in (Array Sorting Functions): Add a note to be careful
+	to use local variables in comparison functions.
+
 2022-02-07         Arnold D. Robbins     <arnold@skeeve.com>
 
 	* gawktexi.in (Indirect Calls): Expand discussion of calling
diff --git a/doc/gawk.info b/doc/gawk.info
index 0f00b0c3..77bdc99f 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -21484,6 +21484,15 @@ both values to lowercase in order to compare them ignoring case.
      -| A a B b c C D d e E F f g G H h i I J j k K l L M m
      -| n N O o p P Q q r R S s t T u U V v w W X x y Y z Z
 
+     NOTE: 'Under the hood," 'gawk' uses the C library 'qsort()'
+     function to manage the sorting.  'qsort()' can call itself
+     recursively.  This means that when you write a comparison function,
+     you should be careful to avoid the use of global variables and
+     arrays; use only local variables and arrays that you declare as
+     additional parameters to the comparison function.  Otherwise, you
+     are likely to cause unintentional memory corruption in your global
+     arrays and possibly cause 'gawk' itself to fail.
+
    ---------- Footnotes ----------
 
    (1) This is true because locale-based comparison occurs only when in
@@ -38977,245 +38986,245 @@ Node: Array Sorting856936
 Node: Controlling Array Traversal857636
 Ref: Controlling Array Traversal-Footnote-1866004
 Node: Array Sorting Functions866122
-Ref: Array Sorting Functions-Footnote-1871496
-Node: Two-way I/O871692
-Ref: Two-way I/O-Footnote-1879418
-Ref: Two-way I/O-Footnote-2879605
-Node: TCP/IP Networking879687
-Node: Profiling882763
-Node: Extension Philosophy892072
-Node: Advanced Features Summary893551
-Node: Internationalization895566
-Node: I18N and L10N897240
-Node: Explaining gettext897927
-Ref: Explaining gettext-Footnote-1903819
-Ref: Explaining gettext-Footnote-2904004
-Node: Programmer i18n904169
-Ref: Programmer i18n-Footnote-1909118
-Node: Translator i18n909167
-Node: String Extraction909961
-Ref: String Extraction-Footnote-1911093
-Node: Printf Ordering911179
-Ref: Printf Ordering-Footnote-1913965
-Node: I18N Portability914029
-Ref: I18N Portability-Footnote-1916485
-Node: I18N Example916548
-Ref: I18N Example-Footnote-1919823
-Ref: I18N Example-Footnote-2919896
-Node: Gawk I18N920005
-Node: I18N Summary920627
-Node: Debugger921968
-Node: Debugging922968
-Node: Debugging Concepts923409
-Node: Debugging Terms925218
-Node: Awk Debugging927793
-Ref: Awk Debugging-Footnote-1928738
-Node: Sample Debugging Session928870
-Node: Debugger Invocation929404
-Node: Finding The Bug930790
-Node: List of Debugger Commands937264
-Node: Breakpoint Control938597
-Node: Debugger Execution Control942291
-Node: Viewing And Changing Data945653
-Node: Execution Stack949194
-Node: Debugger Info950831
-Node: Miscellaneous Debugger Commands954902
-Node: Readline Support959964
-Node: Limitations960860
-Node: Debugging Summary963414
-Node: Namespaces964693
-Node: Global Namespace965804
-Node: Qualified Names967202
-Node: Default Namespace968201
-Node: Changing The Namespace968942
-Node: Naming Rules970556
-Node: Internal Name Management972404
-Node: Namespace Example973446
-Node: Namespace And Features976008
-Node: Namespace Summary977443
-Node: Arbitrary Precision Arithmetic978920
-Node: Computer Arithmetic980407
-Ref: table-numeric-ranges984173
-Ref: table-floating-point-ranges984667
-Ref: Computer Arithmetic-Footnote-1985326
-Node: Math Definitions985383
-Ref: table-ieee-formats988699
-Ref: Math Definitions-Footnote-1989303
-Node: MPFR features989408
-Node: FP Math Caution991126
-Ref: FP Math Caution-Footnote-1992198
-Node: Inexactness of computations992567
-Node: Inexact representation993527
-Node: Comparing FP Values994887
-Node: Errors accumulate996128
-Node: Getting Accuracy997561
-Node: Try To Round1000271
-Node: Setting precision1001170
-Ref: table-predefined-precision-strings1001867
-Node: Setting the rounding mode1003698
-Ref: table-gawk-rounding-modes1004072
-Ref: Setting the rounding mode-Footnote-11008004
-Node: Arbitrary Precision Integers1008183
-Ref: Arbitrary Precision Integers-Footnote-11011358
-Node: Checking for MPFR1011507
-Node: POSIX Floating Point Problems1012981
-Ref: POSIX Floating Point Problems-Footnote-11017634
-Node: Floating point summary1017672
-Node: Dynamic Extensions1019862
-Node: Extension Intro1021415
-Node: Plugin License1022681
-Node: Extension Mechanism Outline1023478
-Ref: figure-load-extension1023917
-Ref: figure-register-new-function1025483
-Ref: figure-call-new-function1026576
-Node: Extension API Description1028639
-Node: Extension API Functions Introduction1030352
-Ref: table-api-std-headers1032188
-Node: General Data Types1036438
-Ref: General Data Types-Footnote-11045068
-Node: Memory Allocation Functions1045367
-Ref: Memory Allocation Functions-Footnote-11049868
-Node: Constructor Functions1049967
-Node: API Ownership of MPFR and GMP Values1053433
-Node: Registration Functions1054746
-Node: Extension Functions1055446
-Node: Exit Callback Functions1060768
-Node: Extension Version String1062018
-Node: Input Parsers1062681
-Node: Output Wrappers1075402
-Node: Two-way processors1079914
-Node: Printing Messages1082179
-Ref: Printing Messages-Footnote-11083350
-Node: Updating ERRNO1083503
-Node: Requesting Values1084242
-Ref: table-value-types-returned1084979
-Node: Accessing Parameters1085916
-Node: Symbol Table Access1087153
-Node: Symbol table by name1087665
-Ref: Symbol table by name-Footnote-11090690
-Node: Symbol table by cookie1090818
-Ref: Symbol table by cookie-Footnote-11095003
-Node: Cached values1095067
-Ref: Cached values-Footnote-11098603
-Node: Array Manipulation1098756
-Ref: Array Manipulation-Footnote-11099847
-Node: Array Data Types1099884
-Ref: Array Data Types-Footnote-11102542
-Node: Array Functions1102634
-Node: Flattening Arrays1107132
-Node: Creating Arrays1114108
-Node: Redirection API1118875
-Node: Extension API Variables1121708
-Node: Extension Versioning1122419
-Ref: gawk-api-version1122848
-Node: Extension GMP/MPFR Versioning1124580
-Node: Extension API Informational Variables1126208
-Node: Extension API Boilerplate1127281
-Node: Changes from API V11131255
-Node: Finding Extensions1132827
-Node: Extension Example1133386
-Node: Internal File Description1134184
-Node: Internal File Ops1138264
-Ref: Internal File Ops-Footnote-11149614
-Node: Using Internal File Ops1149754
-Ref: Using Internal File Ops-Footnote-11152137
-Node: Extension Samples1152411
-Node: Extension Sample File Functions1153940
-Node: Extension Sample Fnmatch1161589
-Node: Extension Sample Fork1163076
-Node: Extension Sample Inplace1164294
-Node: Extension Sample Ord1167920
-Node: Extension Sample Readdir1168756
-Ref: table-readdir-file-types1169645
-Node: Extension Sample Revout1170713
-Node: Extension Sample Rev2way1171302
-Node: Extension Sample Read write array1172042
-Node: Extension Sample Readfile1173984
-Node: Extension Sample Time1175079
-Node: Extension Sample API Tests1176831
-Node: gawkextlib1177323
-Node: Extension summary1180241
-Node: Extension Exercises1183943
-Node: Language History1185185
-Node: V7/SVR3.11186841
-Node: SVR41188993
-Node: POSIX1190427
-Node: BTL1191808
-Node: POSIX/GNU1192537
-Node: Feature History1198315
-Node: Common Extensions1215490
-Node: Ranges and Locales1216773
-Ref: Ranges and Locales-Footnote-11221389
-Ref: Ranges and Locales-Footnote-21221416
-Ref: Ranges and Locales-Footnote-31221651
-Node: Contributors1221874
-Node: History summary1227871
-Node: Installation1229251
-Node: Gawk Distribution1230195
-Node: Getting1230679
-Node: Extracting1231642
-Node: Distribution contents1233280
-Node: Unix Installation1240341
-Node: Quick Installation1241145
-Node: Compiling with MPFR1243565
-Node: Shell Startup Files1244255
-Node: Additional Configuration Options1245344
-Node: Configuration Philosophy1247659
-Node: Compiling from Git1250055
-Node: Building the Documentation1250610
-Node: Non-Unix Installation1251994
-Node: PC Installation1252454
-Node: PC Binary Installation1253292
-Node: PC Compiling1254165
-Node: PC Using1255282
-Node: Cygwin1258835
-Node: MSYS1260059
-Node: VMS Installation1260661
-Node: VMS Compilation1261380
-Ref: VMS Compilation-Footnote-11262609
-Node: VMS Dynamic Extensions1262667
-Node: VMS Installation Details1264352
-Node: VMS Running1266614
-Node: VMS GNV1270893
-Node: Bugs1271607
-Node: Bug definition1272519
-Node: Bug address1275455
-Node: Usenet1278843
-Node: Performance bugs1280032
-Node: Asking for help1282953
-Node: Maintainers1284920
-Node: Other Versions1286114
-Node: Installation summary1294278
-Node: Notes1295642
-Node: Compatibility Mode1296436
-Node: Additions1297218
-Node: Accessing The Source1298143
-Node: Adding Code1299580
-Node: New Ports1305772
-Node: Derived Files1310147
-Ref: Derived Files-Footnote-11315807
-Ref: Derived Files-Footnote-21315842
-Ref: Derived Files-Footnote-31316440
-Node: Future Extensions1316554
-Node: Implementation Limitations1317212
-Node: Extension Design1318422
-Node: Old Extension Problems1319566
-Ref: Old Extension Problems-Footnote-11321084
-Node: Extension New Mechanism Goals1321141
-Ref: Extension New Mechanism Goals-Footnote-11324505
-Node: Extension Other Design Decisions1324694
-Node: Extension Future Growth1326807
-Node: Notes summary1327413
-Node: Basic Concepts1328571
-Node: Basic High Level1329252
-Ref: figure-general-flow1329534
-Ref: figure-process-flow1330220
-Ref: Basic High Level-Footnote-11333522
-Node: Basic Data Typing1333707
-Node: Glossary1337035
-Node: Copying1368920
-Node: GNU Free Documentation License1406463
-Node: Index1431583
+Ref: Array Sorting Functions-Footnote-1872033
+Node: Two-way I/O872229
+Ref: Two-way I/O-Footnote-1879955
+Ref: Two-way I/O-Footnote-2880142
+Node: TCP/IP Networking880224
+Node: Profiling883300
+Node: Extension Philosophy892609
+Node: Advanced Features Summary894088
+Node: Internationalization896103
+Node: I18N and L10N897777
+Node: Explaining gettext898464
+Ref: Explaining gettext-Footnote-1904356
+Ref: Explaining gettext-Footnote-2904541
+Node: Programmer i18n904706
+Ref: Programmer i18n-Footnote-1909655
+Node: Translator i18n909704
+Node: String Extraction910498
+Ref: String Extraction-Footnote-1911630
+Node: Printf Ordering911716
+Ref: Printf Ordering-Footnote-1914502
+Node: I18N Portability914566
+Ref: I18N Portability-Footnote-1917022
+Node: I18N Example917085
+Ref: I18N Example-Footnote-1920360
+Ref: I18N Example-Footnote-2920433
+Node: Gawk I18N920542
+Node: I18N Summary921164
+Node: Debugger922505
+Node: Debugging923505
+Node: Debugging Concepts923946
+Node: Debugging Terms925755
+Node: Awk Debugging928330
+Ref: Awk Debugging-Footnote-1929275
+Node: Sample Debugging Session929407
+Node: Debugger Invocation929941
+Node: Finding The Bug931327
+Node: List of Debugger Commands937801
+Node: Breakpoint Control939134
+Node: Debugger Execution Control942828
+Node: Viewing And Changing Data946190
+Node: Execution Stack949731
+Node: Debugger Info951368
+Node: Miscellaneous Debugger Commands955439
+Node: Readline Support960501
+Node: Limitations961397
+Node: Debugging Summary963951
+Node: Namespaces965230
+Node: Global Namespace966341
+Node: Qualified Names967739
+Node: Default Namespace968738
+Node: Changing The Namespace969479
+Node: Naming Rules971093
+Node: Internal Name Management972941
+Node: Namespace Example973983
+Node: Namespace And Features976545
+Node: Namespace Summary977980
+Node: Arbitrary Precision Arithmetic979457
+Node: Computer Arithmetic980944
+Ref: table-numeric-ranges984710
+Ref: table-floating-point-ranges985204
+Ref: Computer Arithmetic-Footnote-1985863
+Node: Math Definitions985920
+Ref: table-ieee-formats989236
+Ref: Math Definitions-Footnote-1989840
+Node: MPFR features989945
+Node: FP Math Caution991663
+Ref: FP Math Caution-Footnote-1992735
+Node: Inexactness of computations993104
+Node: Inexact representation994064
+Node: Comparing FP Values995424
+Node: Errors accumulate996665
+Node: Getting Accuracy998098
+Node: Try To Round1000808
+Node: Setting precision1001707
+Ref: table-predefined-precision-strings1002404
+Node: Setting the rounding mode1004235
+Ref: table-gawk-rounding-modes1004609
+Ref: Setting the rounding mode-Footnote-11008541
+Node: Arbitrary Precision Integers1008720
+Ref: Arbitrary Precision Integers-Footnote-11011895
+Node: Checking for MPFR1012044
+Node: POSIX Floating Point Problems1013518
+Ref: POSIX Floating Point Problems-Footnote-11018171
+Node: Floating point summary1018209
+Node: Dynamic Extensions1020399
+Node: Extension Intro1021952
+Node: Plugin License1023218
+Node: Extension Mechanism Outline1024015
+Ref: figure-load-extension1024454
+Ref: figure-register-new-function1026020
+Ref: figure-call-new-function1027113
+Node: Extension API Description1029176
+Node: Extension API Functions Introduction1030889
+Ref: table-api-std-headers1032725
+Node: General Data Types1036975
+Ref: General Data Types-Footnote-11045605
+Node: Memory Allocation Functions1045904
+Ref: Memory Allocation Functions-Footnote-11050405
+Node: Constructor Functions1050504
+Node: API Ownership of MPFR and GMP Values1053970
+Node: Registration Functions1055283
+Node: Extension Functions1055983
+Node: Exit Callback Functions1061305
+Node: Extension Version String1062555
+Node: Input Parsers1063218
+Node: Output Wrappers1075939
+Node: Two-way processors1080451
+Node: Printing Messages1082716
+Ref: Printing Messages-Footnote-11083887
+Node: Updating ERRNO1084040
+Node: Requesting Values1084779
+Ref: table-value-types-returned1085516
+Node: Accessing Parameters1086453
+Node: Symbol Table Access1087690
+Node: Symbol table by name1088202
+Ref: Symbol table by name-Footnote-11091227
+Node: Symbol table by cookie1091355
+Ref: Symbol table by cookie-Footnote-11095540
+Node: Cached values1095604
+Ref: Cached values-Footnote-11099140
+Node: Array Manipulation1099293
+Ref: Array Manipulation-Footnote-11100384
+Node: Array Data Types1100421
+Ref: Array Data Types-Footnote-11103079
+Node: Array Functions1103171
+Node: Flattening Arrays1107669
+Node: Creating Arrays1114645
+Node: Redirection API1119412
+Node: Extension API Variables1122245
+Node: Extension Versioning1122956
+Ref: gawk-api-version1123385
+Node: Extension GMP/MPFR Versioning1125117
+Node: Extension API Informational Variables1126745
+Node: Extension API Boilerplate1127818
+Node: Changes from API V11131792
+Node: Finding Extensions1133364
+Node: Extension Example1133923
+Node: Internal File Description1134721
+Node: Internal File Ops1138801
+Ref: Internal File Ops-Footnote-11150151
+Node: Using Internal File Ops1150291
+Ref: Using Internal File Ops-Footnote-11152674
+Node: Extension Samples1152948
+Node: Extension Sample File Functions1154477
+Node: Extension Sample Fnmatch1162126
+Node: Extension Sample Fork1163613
+Node: Extension Sample Inplace1164831
+Node: Extension Sample Ord1168457
+Node: Extension Sample Readdir1169293
+Ref: table-readdir-file-types1170182
+Node: Extension Sample Revout1171250
+Node: Extension Sample Rev2way1171839
+Node: Extension Sample Read write array1172579
+Node: Extension Sample Readfile1174521
+Node: Extension Sample Time1175616
+Node: Extension Sample API Tests1177368
+Node: gawkextlib1177860
+Node: Extension summary1180778
+Node: Extension Exercises1184480
+Node: Language History1185722
+Node: V7/SVR3.11187378
+Node: SVR41189530
+Node: POSIX1190964
+Node: BTL1192345
+Node: POSIX/GNU1193074
+Node: Feature History1198852
+Node: Common Extensions1216027
+Node: Ranges and Locales1217310
+Ref: Ranges and Locales-Footnote-11221926
+Ref: Ranges and Locales-Footnote-21221953
+Ref: Ranges and Locales-Footnote-31222188
+Node: Contributors1222411
+Node: History summary1228408
+Node: Installation1229788
+Node: Gawk Distribution1230732
+Node: Getting1231216
+Node: Extracting1232179
+Node: Distribution contents1233817
+Node: Unix Installation1240878
+Node: Quick Installation1241682
+Node: Compiling with MPFR1244102
+Node: Shell Startup Files1244792
+Node: Additional Configuration Options1245881
+Node: Configuration Philosophy1248196
+Node: Compiling from Git1250592
+Node: Building the Documentation1251147
+Node: Non-Unix Installation1252531
+Node: PC Installation1252991
+Node: PC Binary Installation1253829
+Node: PC Compiling1254702
+Node: PC Using1255819
+Node: Cygwin1259372
+Node: MSYS1260596
+Node: VMS Installation1261198
+Node: VMS Compilation1261917
+Ref: VMS Compilation-Footnote-11263146
+Node: VMS Dynamic Extensions1263204
+Node: VMS Installation Details1264889
+Node: VMS Running1267151
+Node: VMS GNV1271430
+Node: Bugs1272144
+Node: Bug definition1273056
+Node: Bug address1275992
+Node: Usenet1279380
+Node: Performance bugs1280569
+Node: Asking for help1283490
+Node: Maintainers1285457
+Node: Other Versions1286651
+Node: Installation summary1294815
+Node: Notes1296179
+Node: Compatibility Mode1296973
+Node: Additions1297755
+Node: Accessing The Source1298680
+Node: Adding Code1300117
+Node: New Ports1306309
+Node: Derived Files1310684
+Ref: Derived Files-Footnote-11316344
+Ref: Derived Files-Footnote-21316379
+Ref: Derived Files-Footnote-31316977
+Node: Future Extensions1317091
+Node: Implementation Limitations1317749
+Node: Extension Design1318959
+Node: Old Extension Problems1320103
+Ref: Old Extension Problems-Footnote-11321621
+Node: Extension New Mechanism Goals1321678
+Ref: Extension New Mechanism Goals-Footnote-11325042
+Node: Extension Other Design Decisions1325231
+Node: Extension Future Growth1327344
+Node: Notes summary1327950
+Node: Basic Concepts1329108
+Node: Basic High Level1329789
+Ref: figure-general-flow1330071
+Ref: figure-process-flow1330757
+Ref: Basic High Level-Footnote-11334059
+Node: Basic Data Typing1334244
+Node: Glossary1337572
+Node: Copying1369457
+Node: GNU Free Documentation License1407000
+Node: Index1432120
 
 End Tag Table
 
diff --git a/doc/gawk.texi b/doc/gawk.texi
index bc12119a..bc2768c2 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -30093,6 +30093,17 @@ $ @kbd{gawk -f case_fold_compare.awk}
 @print{} n N O o p P Q q r R S s t T u U V v w W X x y Y z Z
 @end example
 
+@quotation NOTE
+`Under the hood,'' @command{gawk} uses the C library @code{qsort()}
+function to manage the sorting. @code{qsort()} can call itself
+recursively.  This means that when you write a comparison function,
+you should be careful to avoid the use of global variables and arrays;
+use only local variables and arrays that you declare as additional
+parameters to the comparison function.  Otherwise, you are likely to
+cause unintentional memory corruption in your global arrays and possibly
+cause @command{gawk} itself to fail.
+@end quotation
+
 @node Two-way I/O
 @section Two-Way Communications with Another Process
 
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index 72945757..93308f52 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -28975,6 +28975,17 @@ $ @kbd{gawk -f case_fold_compare.awk}
 @print{} n N O o p P Q q r R S s t T u U V v w W X x y Y z Z
 @end example
 
+@quotation NOTE
+`Under the hood,'' @command{gawk} uses the C library @code{qsort()}
+function to manage the sorting. @code{qsort()} can call itself
+recursively.  This means that when you write a comparison function,
+you should be careful to avoid the use of global variables and arrays;
+use only local variables and arrays that you declare as additional
+parameters to the comparison function.  Otherwise, you are likely to
+cause unintentional memory corruption in your global arrays and possibly
+cause @command{gawk} itself to fail.
+@end quotation
+
 @node Two-way I/O
 @section Two-Way Communications with Another Process