diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ChangeLog | 5 | ||||
| -rw-r--r-- | doc/gawk.1 | 3 | ||||
| -rw-r--r-- | doc/gawk.info | 657 | ||||
| -rw-r--r-- | doc/gawk.texi | 25 | ||||
| -rw-r--r-- | doc/gawktexi.in | 25 |
5 files changed, 395 insertions, 320 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index 87a1bc97..afe5841a 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,8 @@ +2016-03-07 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Document system() return values. + * gawk.1: Add a pointer to the manual about same. + 2016-02-23 Arnold D. Robbins <arnold@skeeve.com> * sidebar.awk: Globally replace [[:space:]] with [ \t] so that @@ -13,7 +13,7 @@ . if \w'\(rq' .ds rq "\(rq . \} .\} -.TH GAWK 1 "Dec 17 2015" "Free Software Foundation" "Utility Commands" +.TH GAWK 1 "Mar 7 2016" "Free Software Foundation" "Utility Commands" .SH NAME gawk \- pattern scanning and processing language .SH SYNOPSIS @@ -2259,6 +2259,7 @@ Execute the command .IR cmd-line , and return the exit status. (This may not be available on non-\*(PX systems.) +See the manual for the full details on the exit status. .TP \&\fBfflush(\fR[\fIfile\^\fR]\fB)\fR Flush any buffers associated with the open output file or pipe diff --git a/doc/gawk.info b/doc/gawk.info index b5b45471..3820a05a 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -12773,7 +12773,7 @@ parameters are enclosed in square brackets ([ ]): 'system(COMMAND)' Execute the operating system command COMMAND and then return to the - 'awk' program. Return COMMAND's exit status. + 'awk' program. Return COMMAND's exit status (see further on). For example, if the following fragment of code is put in your 'awk' program: @@ -12802,6 +12802,29 @@ parameters are enclosed in square brackets ([ ]): NOTE: When '--sandbox' is specified, the 'system()' function is disabled (*note Options::). + On POSIX systems, a command's exit status is a 16-bit number. The + exit value passed to the C 'exit()' function is held in the + high-order eight bits. The low-order bits indicate if the process + was killed by a signal (bit 7) and if so, the signal number (bits + 0-6). + + Traditionally, 'awk''s 'system()' function has simply returned the + exit status value and ignored death-by-signal. POSIX states that + 'awk''s 'system()' should return the full 16-bit value. + + 'gawk' steers a middle ground. With '--posix', it returns the full + 16-bit value. By default, it returns just the exit status. The + '--traditional' option forces 'gawk' to ignore death-by-signal, in + which case 'system()' returns zero. + + If the process was killed by a signal, 'gawk''s 'system()' returns + 256 + SIG, where SIG is the number of the signal that killed the + process. Since exit values are eight bits, where the values range + from 0-255, using 256 + SIG lets you clearly distinguish normal + exit from death-by-signal. + + If some kind of error occurred, 'system()' returns -1. + Controlling Output Buffering with 'system()' The 'fflush()' function provides explicit control over output @@ -32195,11 +32218,11 @@ Index * Buening, Andreas: Acknowledgments. (line 60) * Buening, Andreas <1>: Contributors. (line 93) * Buening, Andreas <2>: Bugs. (line 73) -* buffering, input/output: I/O Functions. (line 139) +* buffering, input/output: I/O Functions. (line 162) * buffering, input/output <1>: Two-way I/O. (line 53) * buffering, interactive vs. noninteractive: I/O Functions. (line 76) * buffers, flushing: I/O Functions. (line 32) -* buffers, flushing <1>: I/O Functions. (line 139) +* buffers, flushing <1>: I/O Functions. (line 162) * buffers, operators for: GNU Regexp Operators. (line 51) * bug reports, email address, bug-gawk@gnu.org: Bugs. (line 30) @@ -33723,7 +33746,7 @@ Index * output redirection: Redirection. (line 6) * output wrapper: Output Wrappers. (line 6) * output, buffering: I/O Functions. (line 32) -* output, buffering <1>: I/O Functions. (line 139) +* output, buffering <1>: I/O Functions. (line 162) * output, duplicating into files: Tee Program. (line 6) * output, files, closing: Close Files And Pipes. (line 6) @@ -34219,7 +34242,7 @@ Index (line 14) * sidebar, Changing NR and FNR: Auto-set. (line 311) * sidebar, Controlling Output Buffering with system(): I/O Functions. - (line 137) + (line 160) * sidebar, Escape Sequences for Metacharacters: Escape Sequences. (line 135) * sidebar, FS and IGNORECASE: Field Splitting Summary. @@ -34874,317 +34897,317 @@ Ref: table-posix-sub537317 Ref: table-gensub-escapes538858 Ref: Gory Details-Footnote-1539681 Node: I/O Functions539832 -Ref: I/O Functions-Footnote-1547052 -Node: Time Functions547200 -Ref: Time Functions-Footnote-1557705 -Ref: Time Functions-Footnote-2557773 -Ref: Time Functions-Footnote-3557931 -Ref: Time Functions-Footnote-4558042 -Ref: Time Functions-Footnote-5558154 -Ref: Time Functions-Footnote-6558381 -Node: Bitwise Functions558647 -Ref: table-bitwise-ops559241 -Ref: Bitwise Functions-Footnote-1563579 -Node: Type Functions563752 -Node: I18N Functions564908 -Node: User-defined566559 -Node: Definition Syntax567364 -Ref: Definition Syntax-Footnote-1573051 -Node: Function Example573122 -Ref: Function Example-Footnote-1576044 -Node: Function Caveats576066 -Node: Calling A Function576584 -Node: Variable Scope577542 -Node: Pass By Value/Reference580536 -Node: Return Statement584035 -Node: Dynamic Typing587014 -Node: Indirect Calls587944 -Ref: Indirect Calls-Footnote-1598195 -Node: Functions Summary598323 -Node: Library Functions601028 -Ref: Library Functions-Footnote-1604635 -Ref: Library Functions-Footnote-2604778 -Node: Library Names604949 -Ref: Library Names-Footnote-1608409 -Ref: Library Names-Footnote-2608632 -Node: General Functions608718 -Node: Strtonum Function609821 -Node: Assert Function612843 -Node: Round Function616169 -Node: Cliff Random Function617710 -Node: Ordinal Functions618726 -Ref: Ordinal Functions-Footnote-1621789 -Ref: Ordinal Functions-Footnote-2622041 -Node: Join Function622251 -Ref: Join Function-Footnote-1624021 -Node: Getlocaltime Function624221 -Node: Readfile Function627963 -Node: Shell Quoting629935 -Node: Data File Management631336 -Node: Filetrans Function631968 -Node: Rewind Function636064 -Node: File Checking637969 -Ref: File Checking-Footnote-1639303 -Node: Empty Files639504 -Node: Ignoring Assigns641483 -Node: Getopt Function643033 -Ref: Getopt Function-Footnote-1654502 -Node: Passwd Functions654702 -Ref: Passwd Functions-Footnote-1663541 -Node: Group Functions663629 -Ref: Group Functions-Footnote-1671526 -Node: Walking Arrays671733 -Node: Library Functions Summary674741 -Node: Library Exercises676147 -Node: Sample Programs676612 -Node: Running Examples677382 -Node: Clones678110 -Node: Cut Program679334 -Node: Egrep Program689263 -Ref: Egrep Program-Footnote-1696775 -Node: Id Program696885 -Node: Split Program700565 -Ref: Split Program-Footnote-1704024 -Node: Tee Program704153 -Node: Uniq Program706943 -Node: Wc Program714369 -Ref: Wc Program-Footnote-1718624 -Node: Miscellaneous Programs718718 -Node: Dupword Program719931 -Node: Alarm Program721961 -Node: Translate Program726816 -Ref: Translate Program-Footnote-1731381 -Node: Labels Program731651 -Ref: Labels Program-Footnote-1735002 -Node: Word Sorting735086 -Node: History Sorting739158 -Node: Extract Program740993 -Node: Simple Sed748522 -Node: Igawk Program751596 -Ref: Igawk Program-Footnote-1765927 -Ref: Igawk Program-Footnote-2766129 -Ref: Igawk Program-Footnote-3766251 -Node: Anagram Program766366 -Node: Signature Program769428 -Node: Programs Summary770675 -Node: Programs Exercises771889 -Ref: Programs Exercises-Footnote-1776018 -Node: Advanced Features776109 -Node: Nondecimal Data778099 -Node: Array Sorting779690 -Node: Controlling Array Traversal780390 -Ref: Controlling Array Traversal-Footnote-1788757 -Node: Array Sorting Functions788875 -Ref: Array Sorting Functions-Footnote-1793966 -Node: Two-way I/O794162 -Ref: Two-way I/O-Footnote-1799982 -Ref: Two-way I/O-Footnote-2800169 -Node: TCP/IP Networking800251 -Node: Profiling803369 -Node: Advanced Features Summary810908 -Node: Internationalization812844 -Node: I18N and L10N814324 -Node: Explaining gettext815011 -Ref: Explaining gettext-Footnote-1820034 -Ref: Explaining gettext-Footnote-2820219 -Node: Programmer i18n820384 -Ref: Programmer i18n-Footnote-1825239 -Node: Translator i18n825288 -Node: String Extraction826082 -Ref: String Extraction-Footnote-1827214 -Node: Printf Ordering827300 -Ref: Printf Ordering-Footnote-1830086 -Node: I18N Portability830150 -Ref: I18N Portability-Footnote-1832606 -Node: I18N Example832669 -Ref: I18N Example-Footnote-1835475 -Node: Gawk I18N835548 -Node: I18N Summary836193 -Node: Debugger837534 -Node: Debugging838556 -Node: Debugging Concepts838997 -Node: Debugging Terms840806 -Node: Awk Debugging843381 -Node: Sample Debugging Session844287 -Node: Debugger Invocation844821 -Node: Finding The Bug846207 -Node: List of Debugger Commands852685 -Node: Breakpoint Control854018 -Node: Debugger Execution Control857712 -Node: Viewing And Changing Data861074 -Node: Execution Stack864448 -Node: Debugger Info866085 -Node: Miscellaneous Debugger Commands870156 -Node: Readline Support875244 -Node: Limitations876140 -Node: Debugging Summary878249 -Node: Arbitrary Precision Arithmetic879422 -Node: Computer Arithmetic880838 -Ref: table-numeric-ranges884429 -Ref: Computer Arithmetic-Footnote-1885151 -Node: Math Definitions885208 -Ref: table-ieee-formats888522 -Ref: Math Definitions-Footnote-1889125 -Node: MPFR features889230 -Node: FP Math Caution890947 -Ref: FP Math Caution-Footnote-1892019 -Node: Inexactness of computations892388 -Node: Inexact representation893348 -Node: Comparing FP Values894708 -Node: Errors accumulate895790 -Node: Getting Accuracy897223 -Node: Try To Round899933 -Node: Setting precision900832 -Ref: table-predefined-precision-strings901529 -Node: Setting the rounding mode903359 -Ref: table-gawk-rounding-modes903733 -Ref: Setting the rounding mode-Footnote-1907141 -Node: Arbitrary Precision Integers907320 -Ref: Arbitrary Precision Integers-Footnote-1910304 -Node: POSIX Floating Point Problems910453 -Ref: POSIX Floating Point Problems-Footnote-1914335 -Node: Floating point summary914373 -Node: Dynamic Extensions916563 -Node: Extension Intro918116 -Node: Plugin License919382 -Node: Extension Mechanism Outline920179 -Ref: figure-load-extension920618 -Ref: figure-register-new-function922183 -Ref: figure-call-new-function923275 -Node: Extension API Description925337 -Node: Extension API Functions Introduction926785 -Node: General Data Types931597 -Ref: General Data Types-Footnote-1937552 -Node: Memory Allocation Functions937851 -Ref: Memory Allocation Functions-Footnote-1940696 -Node: Constructor Functions940795 -Node: Registration Functions942540 -Node: Extension Functions943225 -Node: Exit Callback Functions945524 -Node: Extension Version String946774 -Node: Input Parsers947437 -Node: Output Wrappers957322 -Node: Two-way processors961834 -Node: Printing Messages964098 -Ref: Printing Messages-Footnote-1965172 -Node: Updating ERRNO965325 -Node: Requesting Values966064 -Ref: table-value-types-returned966801 -Node: Accessing Parameters967684 -Node: Symbol Table Access968919 -Node: Symbol table by name969431 -Node: Symbol table by cookie971452 -Ref: Symbol table by cookie-Footnote-1975601 -Node: Cached values975665 -Ref: Cached values-Footnote-1979166 -Node: Array Manipulation979257 -Ref: Array Manipulation-Footnote-1980356 -Node: Array Data Types980393 -Ref: Array Data Types-Footnote-1983051 -Node: Array Functions983143 -Node: Flattening Arrays987001 -Node: Creating Arrays993909 -Node: Extension API Variables998680 -Node: Extension Versioning999316 -Node: Extension API Informational Variables1001207 -Node: Extension API Boilerplate1002271 -Node: Finding Extensions1006085 -Node: Extension Example1006644 -Node: Internal File Description1007442 -Node: Internal File Ops1011522 -Ref: Internal File Ops-Footnote-11023284 -Node: Using Internal File Ops1023424 -Ref: Using Internal File Ops-Footnote-11025807 -Node: Extension Samples1026081 -Node: Extension Sample File Functions1027610 -Node: Extension Sample Fnmatch1035259 -Node: Extension Sample Fork1036746 -Node: Extension Sample Inplace1037964 -Node: Extension Sample Ord1041174 -Node: Extension Sample Readdir1042010 -Ref: table-readdir-file-types1042899 -Node: Extension Sample Revout1043704 -Node: Extension Sample Rev2way1044293 -Node: Extension Sample Read write array1045033 -Node: Extension Sample Readfile1046975 -Node: Extension Sample Time1048070 -Node: Extension Sample API Tests1049418 -Node: gawkextlib1049910 -Node: Extension summary1052334 -Node: Extension Exercises1056026 -Node: Language History1057523 -Node: V7/SVR3.11059179 -Node: SVR41061331 -Node: POSIX1062765 -Node: BTL1064144 -Node: POSIX/GNU1064873 -Node: Feature History1070394 -Node: Common Extensions1083723 -Node: Ranges and Locales1085006 -Ref: Ranges and Locales-Footnote-11089622 -Ref: Ranges and Locales-Footnote-21089649 -Ref: Ranges and Locales-Footnote-31089884 -Node: Contributors1090105 -Node: History summary1095674 -Node: Installation1097054 -Node: Gawk Distribution1097998 -Node: Getting1098482 -Node: Extracting1099443 -Node: Distribution contents1101081 -Node: Unix Installation1106832 -Node: Quick Installation1107448 -Node: Additional Configuration Options1109875 -Node: Configuration Philosophy1111679 -Node: Non-Unix Installation1114048 -Node: PC Installation1114506 -Node: PC Binary Installation1115826 -Node: PC Compiling1117678 -Ref: PC Compiling-Footnote-11120702 -Node: PC Testing1120811 -Node: PC Using1121991 -Node: Cygwin1126105 -Node: MSYS1126875 -Node: VMS Installation1127376 -Node: VMS Compilation1128167 -Ref: VMS Compilation-Footnote-11129396 -Node: VMS Dynamic Extensions1129454 -Node: VMS Installation Details1131139 -Node: VMS Running1133392 -Node: VMS GNV1137671 -Node: VMS Old Gawk1138406 -Node: Bugs1138877 -Node: Other Versions1143074 -Node: Installation summary1149658 -Node: Notes1150716 -Node: Compatibility Mode1151581 -Node: Additions1152363 -Node: Accessing The Source1153288 -Node: Adding Code1154723 -Node: New Ports1160942 -Node: Derived Files1165430 -Ref: Derived Files-Footnote-11170915 -Ref: Derived Files-Footnote-21170950 -Ref: Derived Files-Footnote-31171548 -Node: Future Extensions1171662 -Node: Implementation Limitations1172320 -Node: Extension Design1173503 -Node: Old Extension Problems1174657 -Ref: Old Extension Problems-Footnote-11176175 -Node: Extension New Mechanism Goals1176232 -Ref: Extension New Mechanism Goals-Footnote-11179596 -Node: Extension Other Design Decisions1179785 -Node: Extension Future Growth1181898 -Node: Old Extension Mechanism1182734 -Node: Notes summary1184497 -Node: Basic Concepts1185679 -Node: Basic High Level1186360 -Ref: figure-general-flow1186642 -Ref: figure-process-flow1187327 -Ref: Basic High Level-Footnote-11190628 -Node: Basic Data Typing1190813 -Node: Glossary1194141 -Node: Copying1226087 -Node: GNU Free Documentation License1263626 -Node: Index1288744 +Ref: I/O Functions-Footnote-1548200 +Node: Time Functions548348 +Ref: Time Functions-Footnote-1558853 +Ref: Time Functions-Footnote-2558921 +Ref: Time Functions-Footnote-3559079 +Ref: Time Functions-Footnote-4559190 +Ref: Time Functions-Footnote-5559302 +Ref: Time Functions-Footnote-6559529 +Node: Bitwise Functions559795 +Ref: table-bitwise-ops560389 +Ref: Bitwise Functions-Footnote-1564727 +Node: Type Functions564900 +Node: I18N Functions566056 +Node: User-defined567707 +Node: Definition Syntax568512 +Ref: Definition Syntax-Footnote-1574199 +Node: Function Example574270 +Ref: Function Example-Footnote-1577192 +Node: Function Caveats577214 +Node: Calling A Function577732 +Node: Variable Scope578690 +Node: Pass By Value/Reference581684 +Node: Return Statement585183 +Node: Dynamic Typing588162 +Node: Indirect Calls589092 +Ref: Indirect Calls-Footnote-1599343 +Node: Functions Summary599471 +Node: Library Functions602176 +Ref: Library Functions-Footnote-1605783 +Ref: Library Functions-Footnote-2605926 +Node: Library Names606097 +Ref: Library Names-Footnote-1609557 +Ref: Library Names-Footnote-2609780 +Node: General Functions609866 +Node: Strtonum Function610969 +Node: Assert Function613991 +Node: Round Function617317 +Node: Cliff Random Function618858 +Node: Ordinal Functions619874 +Ref: Ordinal Functions-Footnote-1622937 +Ref: Ordinal Functions-Footnote-2623189 +Node: Join Function623399 +Ref: Join Function-Footnote-1625169 +Node: Getlocaltime Function625369 +Node: Readfile Function629111 +Node: Shell Quoting631083 +Node: Data File Management632484 +Node: Filetrans Function633116 +Node: Rewind Function637212 +Node: File Checking639117 +Ref: File Checking-Footnote-1640451 +Node: Empty Files640652 +Node: Ignoring Assigns642631 +Node: Getopt Function644181 +Ref: Getopt Function-Footnote-1655650 +Node: Passwd Functions655850 +Ref: Passwd Functions-Footnote-1664689 +Node: Group Functions664777 +Ref: Group Functions-Footnote-1672674 +Node: Walking Arrays672881 +Node: Library Functions Summary675889 +Node: Library Exercises677295 +Node: Sample Programs677760 +Node: Running Examples678530 +Node: Clones679258 +Node: Cut Program680482 +Node: Egrep Program690411 +Ref: Egrep Program-Footnote-1697923 +Node: Id Program698033 +Node: Split Program701713 +Ref: Split Program-Footnote-1705172 +Node: Tee Program705301 +Node: Uniq Program708091 +Node: Wc Program715517 +Ref: Wc Program-Footnote-1719772 +Node: Miscellaneous Programs719866 +Node: Dupword Program721079 +Node: Alarm Program723109 +Node: Translate Program727964 +Ref: Translate Program-Footnote-1732529 +Node: Labels Program732799 +Ref: Labels Program-Footnote-1736150 +Node: Word Sorting736234 +Node: History Sorting740306 +Node: Extract Program742141 +Node: Simple Sed749670 +Node: Igawk Program752744 +Ref: Igawk Program-Footnote-1767075 +Ref: Igawk Program-Footnote-2767277 +Ref: Igawk Program-Footnote-3767399 +Node: Anagram Program767514 +Node: Signature Program770576 +Node: Programs Summary771823 +Node: Programs Exercises773037 +Ref: Programs Exercises-Footnote-1777166 +Node: Advanced Features777257 +Node: Nondecimal Data779247 +Node: Array Sorting780838 +Node: Controlling Array Traversal781538 +Ref: Controlling Array Traversal-Footnote-1789905 +Node: Array Sorting Functions790023 +Ref: Array Sorting Functions-Footnote-1795114 +Node: Two-way I/O795310 +Ref: Two-way I/O-Footnote-1801130 +Ref: Two-way I/O-Footnote-2801317 +Node: TCP/IP Networking801399 +Node: Profiling804517 +Node: Advanced Features Summary812056 +Node: Internationalization813992 +Node: I18N and L10N815472 +Node: Explaining gettext816159 +Ref: Explaining gettext-Footnote-1821182 +Ref: Explaining gettext-Footnote-2821367 +Node: Programmer i18n821532 +Ref: Programmer i18n-Footnote-1826387 +Node: Translator i18n826436 +Node: String Extraction827230 +Ref: String Extraction-Footnote-1828362 +Node: Printf Ordering828448 +Ref: Printf Ordering-Footnote-1831234 +Node: I18N Portability831298 +Ref: I18N Portability-Footnote-1833754 +Node: I18N Example833817 +Ref: I18N Example-Footnote-1836623 +Node: Gawk I18N836696 +Node: I18N Summary837341 +Node: Debugger838682 +Node: Debugging839704 +Node: Debugging Concepts840145 +Node: Debugging Terms841954 +Node: Awk Debugging844529 +Node: Sample Debugging Session845435 +Node: Debugger Invocation845969 +Node: Finding The Bug847355 +Node: List of Debugger Commands853833 +Node: Breakpoint Control855166 +Node: Debugger Execution Control858860 +Node: Viewing And Changing Data862222 +Node: Execution Stack865596 +Node: Debugger Info867233 +Node: Miscellaneous Debugger Commands871304 +Node: Readline Support876392 +Node: Limitations877288 +Node: Debugging Summary879397 +Node: Arbitrary Precision Arithmetic880570 +Node: Computer Arithmetic881986 +Ref: table-numeric-ranges885577 +Ref: Computer Arithmetic-Footnote-1886299 +Node: Math Definitions886356 +Ref: table-ieee-formats889670 +Ref: Math Definitions-Footnote-1890273 +Node: MPFR features890378 +Node: FP Math Caution892095 +Ref: FP Math Caution-Footnote-1893167 +Node: Inexactness of computations893536 +Node: Inexact representation894496 +Node: Comparing FP Values895856 +Node: Errors accumulate896938 +Node: Getting Accuracy898371 +Node: Try To Round901081 +Node: Setting precision901980 +Ref: table-predefined-precision-strings902677 +Node: Setting the rounding mode904507 +Ref: table-gawk-rounding-modes904881 +Ref: Setting the rounding mode-Footnote-1908289 +Node: Arbitrary Precision Integers908468 +Ref: Arbitrary Precision Integers-Footnote-1911452 +Node: POSIX Floating Point Problems911601 +Ref: POSIX Floating Point Problems-Footnote-1915483 +Node: Floating point summary915521 +Node: Dynamic Extensions917711 +Node: Extension Intro919264 +Node: Plugin License920530 +Node: Extension Mechanism Outline921327 +Ref: figure-load-extension921766 +Ref: figure-register-new-function923331 +Ref: figure-call-new-function924423 +Node: Extension API Description926485 +Node: Extension API Functions Introduction927933 +Node: General Data Types932745 +Ref: General Data Types-Footnote-1938700 +Node: Memory Allocation Functions938999 +Ref: Memory Allocation Functions-Footnote-1941844 +Node: Constructor Functions941943 +Node: Registration Functions943688 +Node: Extension Functions944373 +Node: Exit Callback Functions946672 +Node: Extension Version String947922 +Node: Input Parsers948585 +Node: Output Wrappers958470 +Node: Two-way processors962982 +Node: Printing Messages965246 +Ref: Printing Messages-Footnote-1966320 +Node: Updating ERRNO966473 +Node: Requesting Values967212 +Ref: table-value-types-returned967949 +Node: Accessing Parameters968832 +Node: Symbol Table Access970067 +Node: Symbol table by name970579 +Node: Symbol table by cookie972600 +Ref: Symbol table by cookie-Footnote-1976749 +Node: Cached values976813 +Ref: Cached values-Footnote-1980314 +Node: Array Manipulation980405 +Ref: Array Manipulation-Footnote-1981504 +Node: Array Data Types981541 +Ref: Array Data Types-Footnote-1984199 +Node: Array Functions984291 +Node: Flattening Arrays988149 +Node: Creating Arrays995057 +Node: Extension API Variables999828 +Node: Extension Versioning1000464 +Node: Extension API Informational Variables1002355 +Node: Extension API Boilerplate1003419 +Node: Finding Extensions1007233 +Node: Extension Example1007792 +Node: Internal File Description1008590 +Node: Internal File Ops1012670 +Ref: Internal File Ops-Footnote-11024432 +Node: Using Internal File Ops1024572 +Ref: Using Internal File Ops-Footnote-11026955 +Node: Extension Samples1027229 +Node: Extension Sample File Functions1028758 +Node: Extension Sample Fnmatch1036407 +Node: Extension Sample Fork1037894 +Node: Extension Sample Inplace1039112 +Node: Extension Sample Ord1042322 +Node: Extension Sample Readdir1043158 +Ref: table-readdir-file-types1044047 +Node: Extension Sample Revout1044852 +Node: Extension Sample Rev2way1045441 +Node: Extension Sample Read write array1046181 +Node: Extension Sample Readfile1048123 +Node: Extension Sample Time1049218 +Node: Extension Sample API Tests1050566 +Node: gawkextlib1051058 +Node: Extension summary1053482 +Node: Extension Exercises1057174 +Node: Language History1058671 +Node: V7/SVR3.11060327 +Node: SVR41062479 +Node: POSIX1063913 +Node: BTL1065292 +Node: POSIX/GNU1066021 +Node: Feature History1071542 +Node: Common Extensions1084871 +Node: Ranges and Locales1086154 +Ref: Ranges and Locales-Footnote-11090770 +Ref: Ranges and Locales-Footnote-21090797 +Ref: Ranges and Locales-Footnote-31091032 +Node: Contributors1091253 +Node: History summary1096822 +Node: Installation1098202 +Node: Gawk Distribution1099146 +Node: Getting1099630 +Node: Extracting1100591 +Node: Distribution contents1102229 +Node: Unix Installation1107980 +Node: Quick Installation1108596 +Node: Additional Configuration Options1111023 +Node: Configuration Philosophy1112827 +Node: Non-Unix Installation1115196 +Node: PC Installation1115654 +Node: PC Binary Installation1116974 +Node: PC Compiling1118826 +Ref: PC Compiling-Footnote-11121850 +Node: PC Testing1121959 +Node: PC Using1123139 +Node: Cygwin1127253 +Node: MSYS1128023 +Node: VMS Installation1128524 +Node: VMS Compilation1129315 +Ref: VMS Compilation-Footnote-11130544 +Node: VMS Dynamic Extensions1130602 +Node: VMS Installation Details1132287 +Node: VMS Running1134540 +Node: VMS GNV1138819 +Node: VMS Old Gawk1139554 +Node: Bugs1140025 +Node: Other Versions1144222 +Node: Installation summary1150806 +Node: Notes1151864 +Node: Compatibility Mode1152729 +Node: Additions1153511 +Node: Accessing The Source1154436 +Node: Adding Code1155871 +Node: New Ports1162090 +Node: Derived Files1166578 +Ref: Derived Files-Footnote-11172063 +Ref: Derived Files-Footnote-21172098 +Ref: Derived Files-Footnote-31172696 +Node: Future Extensions1172810 +Node: Implementation Limitations1173468 +Node: Extension Design1174651 +Node: Old Extension Problems1175805 +Ref: Old Extension Problems-Footnote-11177323 +Node: Extension New Mechanism Goals1177380 +Ref: Extension New Mechanism Goals-Footnote-11180744 +Node: Extension Other Design Decisions1180933 +Node: Extension Future Growth1183046 +Node: Old Extension Mechanism1183882 +Node: Notes summary1185645 +Node: Basic Concepts1186827 +Node: Basic High Level1187508 +Ref: figure-general-flow1187790 +Ref: figure-process-flow1188475 +Ref: Basic High Level-Footnote-11191776 +Node: Basic Data Typing1191961 +Node: Glossary1195289 +Node: Copying1227235 +Node: GNU Free Documentation License1264774 +Node: Index1289892 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index dcd49e6e..cfb40b6a 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -18338,7 +18338,7 @@ it is all buffered and sent down the pipe to @command{cat} in one shot. @cindex interacting with other programs Execute the operating system command @var{command} and then return to the @command{awk} program. -Return @var{command}'s exit status. +Return @var{command}'s exit status (see further on). For example, if the following fragment of code is put in your @command{awk} program: @@ -18377,6 +18377,29 @@ When @option{--sandbox} is specified, the @code{system()} function is disabled (@pxref{Options}). @end quotation +On POSIX systems, a command's exit status is a 16-bit number. The exit +value passed to the C @code{exit()} function is held in the high-order +eight bits. The low-order bits indicate if the process was killed by a +signal (bit 7) and if so, the signal number (bits 0--6). + +Traditionally, @command{awk}'s @code{system()} function has simply +returned the exit status value and ignored death-by-signal. POSIX +states that @command{awk}'s @code{system()} should return the full +16-bit value. + +@command{gawk} steers a middle ground. With @option{--posix}, it returns +the full 16-bit value. By default, it returns just the exit status. The +@option{--traditional} option forces @command{gawk} to ignore +death-by-signal, in which case @code{system()} returns zero. + +If the process was killed by a signal, @command{gawk}'s @code{system()} +returns 256 + @var{sig}, where @var{sig} is the number of the signal +that killed the process. Since exit values are eight bits, where the +values range from 0--255, using 256 + @var{sig} lets you clearly distinguish +normal exit from death-by-signal. + +If some kind of error occurred, @code{system()} returns @minus{}1. + @end table @cindex sidebar, Controlling Output Buffering with @code{system()} diff --git a/doc/gawktexi.in b/doc/gawktexi.in index ff5672a5..4b0af55b 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -17530,7 +17530,7 @@ it is all buffered and sent down the pipe to @command{cat} in one shot. @cindex interacting with other programs Execute the operating system command @var{command} and then return to the @command{awk} program. -Return @var{command}'s exit status. +Return @var{command}'s exit status (see further on). For example, if the following fragment of code is put in your @command{awk} program: @@ -17569,6 +17569,29 @@ When @option{--sandbox} is specified, the @code{system()} function is disabled (@pxref{Options}). @end quotation +On POSIX systems, a command's exit status is a 16-bit number. The exit +value passed to the C @code{exit()} function is held in the high-order +eight bits. The low-order bits indicate if the process was killed by a +signal (bit 7) and if so, the signal number (bits 0--6). + +Traditionally, @command{awk}'s @code{system()} function has simply +returned the exit status value and ignored death-by-signal. POSIX +states that @command{awk}'s @code{system()} should return the full +16-bit value. + +@command{gawk} steers a middle ground. With @option{--posix}, it returns +the full 16-bit value. By default, it returns just the exit status. The +@option{--traditional} option forces @command{gawk} to ignore +death-by-signal, in which case @code{system()} returns zero. + +If the process was killed by a signal, @command{gawk}'s @code{system()} +returns 256 + @var{sig}, where @var{sig} is the number of the signal +that killed the process. Since exit values are eight bits, where the +values range from 0--255, using 256 + @var{sig} lets you clearly distinguish +normal exit from death-by-signal. + +If some kind of error occurred, @code{system()} returns @minus{}1. + @end table @sidebar Controlling Output Buffering with @code{system()} |