diff options
Diffstat (limited to 'doc/gawk.info')
| -rw-r--r-- | doc/gawk.info | 370 |
1 files changed, 199 insertions, 171 deletions
diff --git a/doc/gawk.info b/doc/gawk.info index c3c4e8e7..aafd94bf 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -1,11 +1,11 @@ This is gawk.info, produced by makeinfo version 6.1 from gawk.texi. -Copyright (C) 1989, 1991, 1992, 1993, 1996-2005, 2007, 2009-2017 +Copyright (C) 1989, 1991, 1992, 1993, 1996-2005, 2007, 2009-2018 Free Software Foundation, Inc. This is Edition 4.2 of 'GAWK: Effective AWK Programming: A User's -Guide for GNU Awk', for the 4.2.0 (or later) version of the GNU +Guide for GNU Awk', for the 4.2.1 (or later) version of the GNU implementation of AWK. Permission is granted to copy, distribute and/or modify this document @@ -37,12 +37,12 @@ General Introduction This file documents 'awk', a program that you can use to select particular records in a file and perform operations upon them. - Copyright (C) 1989, 1991, 1992, 1993, 1996-2005, 2007, 2009-2017 + Copyright (C) 1989, 1991, 1992, 1993, 1996-2005, 2007, 2009-2018 Free Software Foundation, Inc. This is Edition 4.2 of 'GAWK: Effective AWK Programming: A User's -Guide for GNU Awk', for the 4.2.0 (or later) version of the GNU +Guide for GNU Awk', for the 4.2.1 (or later) version of the GNU implementation of AWK. Permission is granted to copy, distribute and/or modify this document @@ -23137,6 +23137,26 @@ cause any accumulating round-off error to cancel itself out. This is the default rounding mode for IEEE 754 computing functions and operators. + Rounding Modes and Conversion + + It's important to understand that, along with 'CONVFMT' and 'OFMT', +the rounding mode affects how numbers are converted to strings. For +example, consider the following program: + + BEGIN { + pi = 3.1416 + OFMT = "%.f" # Print value as integer + print pi # ROUNDMODE = "N" by default. + ROUNDMODE = "U" # Now change ROUNDMODE + print pi + } + +Running this program produces this output: + + $ gawk -M -f roundmode.awk + -| 3 + -| 4 + The other rounding modes are rarely used. Rounding toward positive infinity ('roundTowardPositive') and toward negative infinity ('roundTowardNegative') are often used to implement interval arithmetic, @@ -23273,10 +23293,14 @@ arbitrary-precision arithmetic is available: if (! adequate_math_precision(fpbits)) { print("Error: insufficient computation precision available.\n" \ "Try again with the -M argument?") > "/dev/stderr" + # Note: you may need to set a flag here to bail out of END rules exit 1 } } + Please be aware that 'exit' will jump to the 'END' rules, if present +(*note Exit Statement::). + File: gawk.info, Node: POSIX Floating Point Problems, Next: Floating point summary, Prev: Checking for MPFR, Up: Arbitrary Precision Arithmetic @@ -28593,7 +28617,7 @@ There are two ways to get GNU software: supported. If you have the 'wget' program, you can use a command like the following: - wget https://ftp.gnu.org/gnu/gawk/gawk-4.2.0.tar.gz + wget https://ftp.gnu.org/gnu/gawk/gawk-4.2.1.tar.gz The GNU software archive is mirrored around the world. The up-to-date list of mirror sites is available from the main FSF website @@ -28615,25 +28639,25 @@ compression programs: 'gzip', 'bzip2', and 'xz'. For simplicity, the rest of these instructions assume you are using the one compressed with the GNU Gzip program ('gzip'). - Once you have the distribution (e.g., 'gawk-4.2.0.tar.gz'), use + Once you have the distribution (e.g., 'gawk-4.2.1.tar.gz'), use 'gzip' to expand the file and then use 'tar' to extract it. You can use the following pipeline to produce the 'gawk' distribution: - gzip -d -c gawk-4.2.0.tar.gz | tar -xvpf - + gzip -d -c gawk-4.2.1.tar.gz | tar -xvpf - On a system with GNU 'tar', you can let 'tar' do the decompression for you: - tar -xvpzf gawk-4.2.0.tar.gz + tar -xvpzf gawk-4.2.1.tar.gz -Extracting the archive creates a directory named 'gawk-4.2.0' in the +Extracting the archive creates a directory named 'gawk-4.2.1' in the current directory. The distribution file name is of the form 'gawk-V.R.P.tar.gz'. The V represents the major version of 'gawk', the R represents the current release of version V, and the P represents a "patch level", meaning that minor bugs have been fixed in the release. The current patch level is -0, but when retrieving distributions, you should get the version with +1, but when retrieving distributions, you should get the version with the highest version, release, and patch level. (Note, however, that patch levels greater than or equal to 70 denote "beta" or nonproduction software; you might not want to retrieve such a version unless you don't @@ -28860,7 +28884,7 @@ Unix-derived systems, GNU/Linux, BSD-based systems, and the Cygwin environment for MS-Windows. After you have extracted the 'gawk' distribution, 'cd' to -'gawk-4.2.0'. As with most GNU software, you configure 'gawk' for your +'gawk-4.2.1'. As with most GNU software, you configure 'gawk' for your system by running the 'configure' program. This program is a Bourne shell script that is generated automatically using GNU Autoconf. (The Autoconf software is described fully starting with *note (Autoconf, @@ -29192,8 +29216,8 @@ environment provides an excellent simulation of GNU/Linux, using Bash, GCC, GNU Make, and other GNU programs. Compilation and installation for Cygwin is the same as for a Unix system: - tar -xvpzf gawk-4.2.0.tar.gz - cd gawk-4.2.0 + tar -xvpzf gawk-4.2.1.tar.gz + cd gawk-4.2.1 ./configure make && make check @@ -29817,9 +29841,9 @@ B.6 Summary * The 'gawk' distribution is available from the GNU Project's main distribution site, 'ftp.gnu.org'. The canonical build recipe is: - wget https://ftp.gnu.org/gnu/gawk/gawk-4.2.0.tar.gz - tar -xvpzf gawk-4.2.0.tar.gz - cd gawk-4.2.0 + wget https://ftp.gnu.org/gnu/gawk/gawk-4.2.1.tar.gz + tar -xvpzf gawk-4.2.1.tar.gz + cd gawk-4.2.1 ./configure && make && make check NOTE: Because of the 'https://' URL, you may have to supply @@ -35415,6 +35439,8 @@ Index * round() user-defined function: Round Function. (line 16) * rounding numbers: Round Function. (line 6) * ROUNDMODE variable: User-modified. (line 131) +* ROUNDMODE variable <1>: Setting the rounding mode. + (line 6) * RS variable: awk split records. (line 12) * RS variable <1>: User-modified. (line 136) * RS variable, multiline records and: Multiple Line. (line 17) @@ -35542,6 +35568,8 @@ Index * sidebar, Pre-POSIX awk Used OFMT for String Conversion: Strings And Numbers. (line 54) * sidebar, Recipe for a Programming Language: History. (line 6) +* sidebar, Rounding Modes and Conversion: Setting the rounding mode. + (line 65) * sidebar, RS = "\0" Is Not Portable: gawk split records. (line 63) * sidebar, So Why Does gawk Have BEGINFILE and ENDFILE?: Filetrans Function. (line 83) @@ -36367,160 +36395,160 @@ Node: Setting precision933040 Ref: table-predefined-precision-strings933737 Node: Setting the rounding mode935567 Ref: table-gawk-rounding-modes935941 -Ref: Setting the rounding mode-Footnote-1939316 -Node: Arbitrary Precision Integers939495 -Ref: Arbitrary Precision Integers-Footnote-1942670 -Node: Checking for MPFR942819 -Node: POSIX Floating Point Problems944116 -Ref: POSIX Floating Point Problems-Footnote-1947987 -Node: Floating point summary948025 -Node: Dynamic Extensions950215 -Node: Extension Intro951768 -Node: Plugin License953034 -Node: Extension Mechanism Outline953831 -Ref: figure-load-extension954270 -Ref: figure-register-new-function955835 -Ref: figure-call-new-function956927 -Node: Extension API Description958989 -Node: Extension API Functions Introduction960631 -Node: General Data Types966171 -Ref: General Data Types-Footnote-1974532 -Node: Memory Allocation Functions974831 -Ref: Memory Allocation Functions-Footnote-1979041 -Node: Constructor Functions979140 -Node: Registration Functions982726 -Node: Extension Functions983411 -Node: Exit Callback Functions988626 -Node: Extension Version String989876 -Node: Input Parsers990539 -Node: Output Wrappers1003260 -Node: Two-way processors1007772 -Node: Printing Messages1010037 -Ref: Printing Messages-Footnote-11011208 -Node: Updating ERRNO1011361 -Node: Requesting Values1012100 -Ref: table-value-types-returned1012837 -Node: Accessing Parameters1013773 -Node: Symbol Table Access1015008 -Node: Symbol table by name1015520 -Node: Symbol table by cookie1017309 -Ref: Symbol table by cookie-Footnote-11021494 -Node: Cached values1021558 -Ref: Cached values-Footnote-11025094 -Node: Array Manipulation1025247 -Ref: Array Manipulation-Footnote-11026338 -Node: Array Data Types1026375 -Ref: Array Data Types-Footnote-11029033 -Node: Array Functions1029125 -Node: Flattening Arrays1033623 -Node: Creating Arrays1040599 -Node: Redirection API1045366 -Node: Extension API Variables1048199 -Node: Extension Versioning1048910 -Ref: gawk-api-version1049339 -Node: Extension GMP/MPFR Versioning1051070 -Node: Extension API Informational Variables1052698 -Node: Extension API Boilerplate1053771 -Node: Changes from API V11057745 -Node: Finding Extensions1059317 -Node: Extension Example1059876 -Node: Internal File Description1060674 -Node: Internal File Ops1064754 -Ref: Internal File Ops-Footnote-11076105 -Node: Using Internal File Ops1076245 -Ref: Using Internal File Ops-Footnote-11078628 -Node: Extension Samples1078902 -Node: Extension Sample File Functions1080431 -Node: Extension Sample Fnmatch1088080 -Node: Extension Sample Fork1089567 -Node: Extension Sample Inplace1090785 -Node: Extension Sample Ord1094002 -Node: Extension Sample Readdir1094838 -Ref: table-readdir-file-types1095727 -Node: Extension Sample Revout1096532 -Node: Extension Sample Rev2way1097121 -Node: Extension Sample Read write array1097861 -Node: Extension Sample Readfile1099803 -Node: Extension Sample Time1100898 -Node: Extension Sample API Tests1102246 -Node: gawkextlib1102738 -Node: Extension summary1105194 -Node: Extension Exercises1108896 -Node: Language History1110394 -Node: V7/SVR3.11112050 -Node: SVR41114202 -Node: POSIX1115636 -Node: BTL1117016 -Node: POSIX/GNU1117745 -Node: Feature History1123523 -Node: Common Extensions1139382 -Node: Ranges and Locales1140665 -Ref: Ranges and Locales-Footnote-11145281 -Ref: Ranges and Locales-Footnote-21145308 -Ref: Ranges and Locales-Footnote-31145543 -Node: Contributors1145764 -Node: History summary1151709 -Node: Installation1153089 -Node: Gawk Distribution1154033 -Node: Getting1154517 -Node: Extracting1155480 -Node: Distribution contents1157118 -Node: Unix Installation1163598 -Node: Quick Installation1164280 -Node: Shell Startup Files1166694 -Node: Additional Configuration Options1167783 -Node: Configuration Philosophy1169948 -Node: Non-Unix Installation1172317 -Node: PC Installation1172777 -Node: PC Binary Installation1173615 -Node: PC Compiling1174050 -Node: PC Using1175167 -Node: Cygwin1178212 -Node: MSYS1178982 -Node: VMS Installation1179483 -Node: VMS Compilation1180274 -Ref: VMS Compilation-Footnote-11181503 -Node: VMS Dynamic Extensions1181561 -Node: VMS Installation Details1183246 -Node: VMS Running1185499 -Node: VMS GNV1189778 -Node: VMS Old Gawk1190513 -Node: Bugs1190984 -Node: Bug address1191647 -Node: Usenet1194439 -Node: Maintainers1195216 -Node: Other Versions1196477 -Node: Installation summary1203239 -Node: Notes1204441 -Node: Compatibility Mode1205306 -Node: Additions1206088 -Node: Accessing The Source1207013 -Node: Adding Code1208450 -Node: New Ports1214669 -Node: Derived Files1219157 -Ref: Derived Files-Footnote-11224803 -Ref: Derived Files-Footnote-21224838 -Ref: Derived Files-Footnote-31225436 -Node: Future Extensions1225550 -Node: Implementation Limitations1226208 -Node: Extension Design1227391 -Node: Old Extension Problems1228545 -Ref: Old Extension Problems-Footnote-11230063 -Node: Extension New Mechanism Goals1230120 -Ref: Extension New Mechanism Goals-Footnote-11233484 -Node: Extension Other Design Decisions1233673 -Node: Extension Future Growth1235786 -Node: Old Extension Mechanism1236622 -Node: Notes summary1238385 -Node: Basic Concepts1239567 -Node: Basic High Level1240248 -Ref: figure-general-flow1240530 -Ref: figure-process-flow1241215 -Ref: Basic High Level-Footnote-11244516 -Node: Basic Data Typing1244701 -Node: Glossary1248029 -Node: Copying1279867 -Node: GNU Free Documentation License1317406 -Node: Index1342524 +Ref: Setting the rounding mode-Footnote-1939872 +Node: Arbitrary Precision Integers940051 +Ref: Arbitrary Precision Integers-Footnote-1943226 +Node: Checking for MPFR943375 +Node: POSIX Floating Point Problems944849 +Ref: POSIX Floating Point Problems-Footnote-1948720 +Node: Floating point summary948758 +Node: Dynamic Extensions950948 +Node: Extension Intro952501 +Node: Plugin License953767 +Node: Extension Mechanism Outline954564 +Ref: figure-load-extension955003 +Ref: figure-register-new-function956568 +Ref: figure-call-new-function957660 +Node: Extension API Description959722 +Node: Extension API Functions Introduction961364 +Node: General Data Types966904 +Ref: General Data Types-Footnote-1975265 +Node: Memory Allocation Functions975564 +Ref: Memory Allocation Functions-Footnote-1979774 +Node: Constructor Functions979873 +Node: Registration Functions983459 +Node: Extension Functions984144 +Node: Exit Callback Functions989359 +Node: Extension Version String990609 +Node: Input Parsers991272 +Node: Output Wrappers1003993 +Node: Two-way processors1008505 +Node: Printing Messages1010770 +Ref: Printing Messages-Footnote-11011941 +Node: Updating ERRNO1012094 +Node: Requesting Values1012833 +Ref: table-value-types-returned1013570 +Node: Accessing Parameters1014506 +Node: Symbol Table Access1015741 +Node: Symbol table by name1016253 +Node: Symbol table by cookie1018042 +Ref: Symbol table by cookie-Footnote-11022227 +Node: Cached values1022291 +Ref: Cached values-Footnote-11025827 +Node: Array Manipulation1025980 +Ref: Array Manipulation-Footnote-11027071 +Node: Array Data Types1027108 +Ref: Array Data Types-Footnote-11029766 +Node: Array Functions1029858 +Node: Flattening Arrays1034356 +Node: Creating Arrays1041332 +Node: Redirection API1046099 +Node: Extension API Variables1048932 +Node: Extension Versioning1049643 +Ref: gawk-api-version1050072 +Node: Extension GMP/MPFR Versioning1051803 +Node: Extension API Informational Variables1053431 +Node: Extension API Boilerplate1054504 +Node: Changes from API V11058478 +Node: Finding Extensions1060050 +Node: Extension Example1060609 +Node: Internal File Description1061407 +Node: Internal File Ops1065487 +Ref: Internal File Ops-Footnote-11076838 +Node: Using Internal File Ops1076978 +Ref: Using Internal File Ops-Footnote-11079361 +Node: Extension Samples1079635 +Node: Extension Sample File Functions1081164 +Node: Extension Sample Fnmatch1088813 +Node: Extension Sample Fork1090300 +Node: Extension Sample Inplace1091518 +Node: Extension Sample Ord1094735 +Node: Extension Sample Readdir1095571 +Ref: table-readdir-file-types1096460 +Node: Extension Sample Revout1097265 +Node: Extension Sample Rev2way1097854 +Node: Extension Sample Read write array1098594 +Node: Extension Sample Readfile1100536 +Node: Extension Sample Time1101631 +Node: Extension Sample API Tests1102979 +Node: gawkextlib1103471 +Node: Extension summary1105927 +Node: Extension Exercises1109629 +Node: Language History1111127 +Node: V7/SVR3.11112783 +Node: SVR41114935 +Node: POSIX1116369 +Node: BTL1117749 +Node: POSIX/GNU1118478 +Node: Feature History1124256 +Node: Common Extensions1140115 +Node: Ranges and Locales1141398 +Ref: Ranges and Locales-Footnote-11146014 +Ref: Ranges and Locales-Footnote-21146041 +Ref: Ranges and Locales-Footnote-31146276 +Node: Contributors1146497 +Node: History summary1152442 +Node: Installation1153822 +Node: Gawk Distribution1154766 +Node: Getting1155250 +Node: Extracting1156213 +Node: Distribution contents1157851 +Node: Unix Installation1164331 +Node: Quick Installation1165013 +Node: Shell Startup Files1167427 +Node: Additional Configuration Options1168516 +Node: Configuration Philosophy1170681 +Node: Non-Unix Installation1173050 +Node: PC Installation1173510 +Node: PC Binary Installation1174348 +Node: PC Compiling1174783 +Node: PC Using1175900 +Node: Cygwin1178945 +Node: MSYS1179715 +Node: VMS Installation1180216 +Node: VMS Compilation1181007 +Ref: VMS Compilation-Footnote-11182236 +Node: VMS Dynamic Extensions1182294 +Node: VMS Installation Details1183979 +Node: VMS Running1186232 +Node: VMS GNV1190511 +Node: VMS Old Gawk1191246 +Node: Bugs1191717 +Node: Bug address1192380 +Node: Usenet1195172 +Node: Maintainers1195949 +Node: Other Versions1197210 +Node: Installation summary1203972 +Node: Notes1205174 +Node: Compatibility Mode1206039 +Node: Additions1206821 +Node: Accessing The Source1207746 +Node: Adding Code1209183 +Node: New Ports1215402 +Node: Derived Files1219890 +Ref: Derived Files-Footnote-11225536 +Ref: Derived Files-Footnote-21225571 +Ref: Derived Files-Footnote-31226169 +Node: Future Extensions1226283 +Node: Implementation Limitations1226941 +Node: Extension Design1228124 +Node: Old Extension Problems1229278 +Ref: Old Extension Problems-Footnote-11230796 +Node: Extension New Mechanism Goals1230853 +Ref: Extension New Mechanism Goals-Footnote-11234217 +Node: Extension Other Design Decisions1234406 +Node: Extension Future Growth1236519 +Node: Old Extension Mechanism1237355 +Node: Notes summary1239118 +Node: Basic Concepts1240300 +Node: Basic High Level1240981 +Ref: figure-general-flow1241263 +Ref: figure-process-flow1241948 +Ref: Basic High Level-Footnote-11245249 +Node: Basic Data Typing1245434 +Node: Glossary1248762 +Node: Copying1280600 +Node: GNU Free Documentation License1318139 +Node: Index1343257 End Tag Table |