diff options
| -rw-r--r-- | ChangeLog | 11 | ||||
| -rw-r--r-- | NEWS | 3 | ||||
| -rw-r--r-- | builtin.c | 33 | ||||
| -rw-r--r-- | doc/ChangeLog | 9 | ||||
| -rw-r--r-- | doc/gawk.1 | 3 | ||||
| -rw-r--r-- | doc/gawk.info | 676 | ||||
| -rw-r--r-- | doc/gawk.texi | 30 | ||||
| -rw-r--r-- | doc/gawktexi.in | 30 |
8 files changed, 466 insertions, 329 deletions
@@ -1,3 +1,12 @@ +2016-03-10 Arnold D. Robbins <arnold@skeeve.com> + + * builtin.c (do_system): Further improvements. Catch core dump + flag. + +2016-03-11 Arnold D. Robbins <arnold@skeeve.com> + + * builtin.c (do_system): Improve return values of system(). + 2016-03-08 Arnold D. Robbins <arnold@skeeve.com> * profile.c (print_instruction): Fix duplicate case not caught @@ -7,6 +16,8 @@ * profile.c (print_instruction): Further improvements in instruction dump, especially for when pretty-printing. + * builtin.c (do_system): Augment the logic for the return + value so that death-by-signal info is available too. 2016-03-03 Arnold D. Robbins <arnold@skeeve.com> @@ -100,6 +100,9 @@ Changes from 4.1.3 to 4.1.x 7. The profiler / pretty-printer now chains else-if statements instead of causing cascading elses. +8. The return value of system() has been enhanced to convey more information. + See the doc. + Changes from 4.1.2 to 4.1.3 --------------------------- @@ -2075,9 +2075,10 @@ NODE * do_system(int nargs) { NODE *tmp; - int ret = 0; + AWKNUM ret = 0; /* floating point on purpose, compat Unix awk */ char *cmd; char save; + int status; if (do_sandbox) fatal(_("'system' function not allowed in sandbox mode")); @@ -2094,9 +2095,33 @@ do_system(int nargs) cmd[tmp->stlen] = '\0'; os_restore_mode(fileno(stdin)); - ret = system(cmd); - if (ret != -1) - ret = WEXITSTATUS(ret); + status = system(cmd); + /* + * 3/2016. What to do with ret? It's never simple. + * POSIX says to use the full return value. BWK awk + * divides the result by 256. That normally gives the + * exit status but gives a weird result for death-by-signal. + * So we compromise as follows: + */ + ret = status; + if (status != -1) { + if (do_posix) + ; /* leave it alone, full 16 bits */ + else if (do_traditional) + ret = (status / 256.0); + else if (WIFEXITED(status)) + ret = WEXITSTATUS(status); /* normal exit */ + else if (WIFSIGNALED(status)) { + bool coredumped = false; +#ifdef WCOREDUMP + coredumped = WCOREDUMP(status); +#endif + /* use 256 since exit values are 8 bits */ + ret = WTERMSIG(status) + + (coredumped ? 512 : 256); + } else + ret = 0; /* shouldn't get here */ + } if ((BINMODE & BINMODE_INPUT) != 0) os_setbinmode(fileno(stdin), O_BINARY); diff --git a/doc/ChangeLog b/doc/ChangeLog index 70cf277c..2b8bb720 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,12 @@ +2016-03-11 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Improve system() return values documentation. + +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 "Feb 04 2016" "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 @@ -2314,6 +2314,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 cf6a1356..4e1608df 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -12993,7 +12993,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: @@ -13022,6 +13022,33 @@ 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 guilty signal number + (bits 0-6). + + Traditionally, 'awk''s 'system()' function has simply returned the + exit status value divided by 256. In the normal case this gives + the exit status but in the case of death-by-signal it yields a + fractional floating-point value.(2) POSIX states that 'awk''s + 'system()' should return the full 16-bit value. + + 'gawk' steers a middle ground. The return values are summarized in + *note Table 9.5: table-system-return-values. + + Situation Return value from 'system()' + -------------------------------------------------------------------------- + '--traditional' C 'system()''s value divided by 256 + '--posix' C 'system()''s value + Normal exit of command Command's exit status + Death by signal of command 256 + number of murderous signal + Death by signal of command 512 + number of murderous signal + with core dump + Some kind of error -1 + + Table 9.5: Return values from 'system()' + Controlling Output Buffering with 'system()' The 'fflush()' function provides explicit control over output @@ -13071,6 +13098,9 @@ would see the latter (undesirable) output. terminal device. On modern systems, this means your keyboard and screen. + (2) In private correspondance, Dr. Kernighan has indicated to me that +the way this was done was probably a mistake. + File: gawk.info, Node: Time Functions, Next: Bitwise Functions, Prev: I/O Functions, Up: Built-in @@ -13399,7 +13429,7 @@ File: gawk.info, Node: Bitwise Functions, Next: Type Functions, Prev: Time Fu two integer numbers. In other words, the operation is performed on each successive pair of bits in the operands. Three common operations are bitwise AND, OR, and XOR. The operations are described in *note Table -9.5: table-bitwise-ops. +9.6: table-bitwise-ops. Bit operator | AND | OR | XOR @@ -13409,7 +13439,7 @@ bitwise AND, OR, and XOR. The operations are described in *note Table 0 | 0 0 | 0 1 | 0 1 1 | 0 1 | 1 1 | 1 0 -Table 9.5: Bitwise operations +Table 9.6: Bitwise operations As you can see, the result of an AND operation is 1 only when _both_ bits are 1. The result of an OR operation is 1 if _either_ bit is 1. @@ -32754,11 +32784,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 166) * 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 166) * buffers, operators for: GNU Regexp Operators. (line 51) * bug reports, email address, bug-gawk@gnu.org: Bugs. (line 30) @@ -34289,7 +34319,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 166) * output, duplicating into files: Tee Program. (line 6) * output, files, closing: Close Files And Pipes. (line 6) @@ -34783,7 +34813,7 @@ Index (line 14) * sidebar, Changing NR and FNR: Auto-set. (line 342) * sidebar, Controlling Output Buffering with system(): I/O Functions. - (line 137) + (line 164) * sidebar, Escape Sequences for Metacharacters: Escape Sequences. (line 138) * sidebar, FS and IGNORECASE: Field Splitting Summary. @@ -35442,320 +35472,322 @@ Ref: table-posix-sub547420 Ref: table-gensub-escapes548961 Ref: Gory Details-Footnote-1549784 Node: I/O Functions549935 -Ref: I/O Functions-Footnote-1557155 -Node: Time Functions557303 -Ref: Time Functions-Footnote-1567808 -Ref: Time Functions-Footnote-2567876 -Ref: Time Functions-Footnote-3568034 -Ref: Time Functions-Footnote-4568145 -Ref: Time Functions-Footnote-5568257 -Ref: Time Functions-Footnote-6568484 -Node: Bitwise Functions568750 -Ref: table-bitwise-ops569344 -Ref: Bitwise Functions-Footnote-1573682 -Node: Type Functions573855 -Node: I18N Functions576516 -Node: User-defined578167 -Node: Definition Syntax578972 -Ref: Definition Syntax-Footnote-1584659 -Node: Function Example584730 -Ref: Function Example-Footnote-1587652 -Node: Function Caveats587674 -Node: Calling A Function588192 -Node: Variable Scope589150 -Node: Pass By Value/Reference592144 -Node: Return Statement595643 -Node: Dynamic Typing598622 -Node: Indirect Calls599552 -Ref: Indirect Calls-Footnote-1609803 -Node: Functions Summary609931 -Node: Library Functions612636 -Ref: Library Functions-Footnote-1616243 -Ref: Library Functions-Footnote-2616386 -Node: Library Names616557 -Ref: Library Names-Footnote-1620017 -Ref: Library Names-Footnote-2620240 -Node: General Functions620326 -Node: Strtonum Function621429 -Node: Assert Function624451 -Node: Round Function627777 -Node: Cliff Random Function629318 -Node: Ordinal Functions630334 -Ref: Ordinal Functions-Footnote-1633397 -Ref: Ordinal Functions-Footnote-2633649 -Node: Join Function633859 -Ref: Join Function-Footnote-1635629 -Node: Getlocaltime Function635829 -Node: Readfile Function639571 -Node: Shell Quoting641543 -Node: Data File Management642944 -Node: Filetrans Function643576 -Node: Rewind Function647672 -Node: File Checking649577 -Ref: File Checking-Footnote-1650911 -Node: Empty Files651112 -Node: Ignoring Assigns653091 -Node: Getopt Function654641 -Ref: Getopt Function-Footnote-1666110 -Node: Passwd Functions666310 -Ref: Passwd Functions-Footnote-1675149 -Node: Group Functions675237 -Ref: Group Functions-Footnote-1683134 -Node: Walking Arrays683341 -Node: Library Functions Summary686349 -Node: Library Exercises687755 -Node: Sample Programs688220 -Node: Running Examples688990 -Node: Clones689718 -Node: Cut Program690942 -Node: Egrep Program700871 -Ref: Egrep Program-Footnote-1708383 -Node: Id Program708493 -Node: Split Program712173 -Ref: Split Program-Footnote-1715632 -Node: Tee Program715761 -Node: Uniq Program718551 -Node: Wc Program725977 -Ref: Wc Program-Footnote-1730232 -Node: Miscellaneous Programs730326 -Node: Dupword Program731539 -Node: Alarm Program733569 -Node: Translate Program738424 -Ref: Translate Program-Footnote-1742989 -Node: Labels Program743259 -Ref: Labels Program-Footnote-1746610 -Node: Word Sorting746694 -Node: History Sorting750766 -Node: Extract Program752601 -Node: Simple Sed760130 -Node: Igawk Program763204 -Ref: Igawk Program-Footnote-1777535 -Ref: Igawk Program-Footnote-2777737 -Ref: Igawk Program-Footnote-3777859 -Node: Anagram Program777974 -Node: Signature Program781036 -Node: Programs Summary782283 -Node: Programs Exercises783497 -Ref: Programs Exercises-Footnote-1787626 -Node: Advanced Features787717 -Node: Nondecimal Data789707 -Node: Array Sorting791298 -Node: Controlling Array Traversal791998 -Ref: Controlling Array Traversal-Footnote-1800365 -Node: Array Sorting Functions800483 -Ref: Array Sorting Functions-Footnote-1805574 -Node: Two-way I/O805770 -Ref: Two-way I/O-Footnote-1811590 -Ref: Two-way I/O-Footnote-2811777 -Node: TCP/IP Networking811859 -Node: Profiling814977 -Node: Advanced Features Summary823431 -Node: Internationalization825275 -Node: I18N and L10N826755 -Node: Explaining gettext827442 -Ref: Explaining gettext-Footnote-1832465 -Ref: Explaining gettext-Footnote-2832650 -Node: Programmer i18n832815 -Ref: Programmer i18n-Footnote-1837670 -Node: Translator i18n837719 -Node: String Extraction838513 -Ref: String Extraction-Footnote-1839645 -Node: Printf Ordering839731 -Ref: Printf Ordering-Footnote-1842517 -Node: I18N Portability842581 -Ref: I18N Portability-Footnote-1845037 -Node: I18N Example845100 -Ref: I18N Example-Footnote-1847906 -Node: Gawk I18N847979 -Node: I18N Summary848624 -Node: Debugger849965 -Node: Debugging850987 -Node: Debugging Concepts851428 -Node: Debugging Terms853237 -Node: Awk Debugging855812 -Node: Sample Debugging Session856718 -Node: Debugger Invocation857252 -Node: Finding The Bug858638 -Node: List of Debugger Commands865116 -Node: Breakpoint Control866449 -Node: Debugger Execution Control870143 -Node: Viewing And Changing Data873505 -Node: Execution Stack876879 -Node: Debugger Info878516 -Node: Miscellaneous Debugger Commands882587 -Node: Readline Support887675 -Node: Limitations888571 -Ref: Limitations-Footnote-1892802 -Node: Debugging Summary892853 -Node: Arbitrary Precision Arithmetic894132 -Node: Computer Arithmetic895548 -Ref: table-numeric-ranges899139 -Ref: Computer Arithmetic-Footnote-1899861 -Node: Math Definitions899918 -Ref: table-ieee-formats903232 -Ref: Math Definitions-Footnote-1903835 -Node: MPFR features903940 -Node: FP Math Caution905657 -Ref: FP Math Caution-Footnote-1906729 -Node: Inexactness of computations907098 -Node: Inexact representation908058 -Node: Comparing FP Values909418 -Node: Errors accumulate910500 -Node: Getting Accuracy911933 -Node: Try To Round914643 -Node: Setting precision915542 -Ref: table-predefined-precision-strings916239 -Node: Setting the rounding mode918069 -Ref: table-gawk-rounding-modes918443 -Ref: Setting the rounding mode-Footnote-1921851 -Node: Arbitrary Precision Integers922030 -Ref: Arbitrary Precision Integers-Footnote-1926947 -Node: POSIX Floating Point Problems927096 -Ref: POSIX Floating Point Problems-Footnote-1930978 -Node: Floating point summary931016 -Node: Dynamic Extensions933206 -Node: Extension Intro934759 -Node: Plugin License936025 -Node: Extension Mechanism Outline936822 -Ref: figure-load-extension937261 -Ref: figure-register-new-function938826 -Ref: figure-call-new-function939918 -Node: Extension API Description941980 -Node: Extension API Functions Introduction943512 -Node: General Data Types948371 -Ref: General Data Types-Footnote-1954326 -Node: Memory Allocation Functions954625 -Ref: Memory Allocation Functions-Footnote-1957470 -Node: Constructor Functions957569 -Node: Registration Functions959314 -Node: Extension Functions959999 -Node: Exit Callback Functions962298 -Node: Extension Version String963548 -Node: Input Parsers964211 -Node: Output Wrappers974096 -Node: Two-way processors978608 -Node: Printing Messages980872 -Ref: Printing Messages-Footnote-1981946 -Node: Updating ERRNO982099 -Node: Requesting Values982838 -Ref: table-value-types-returned983575 -Node: Accessing Parameters984458 -Node: Symbol Table Access985693 -Node: Symbol table by name986205 -Node: Symbol table by cookie988226 -Ref: Symbol table by cookie-Footnote-1992375 -Node: Cached values992439 -Ref: Cached values-Footnote-1995940 -Node: Array Manipulation996031 -Ref: Array Manipulation-Footnote-1997122 -Node: Array Data Types997159 -Ref: Array Data Types-Footnote-1999817 -Node: Array Functions999909 -Node: Flattening Arrays1003767 -Node: Creating Arrays1010675 -Node: Redirection API1015446 -Node: Extension API Variables1018277 -Node: Extension Versioning1018910 -Node: Extension API Informational Variables1020801 -Node: Extension API Boilerplate1021865 -Node: Finding Extensions1025679 -Node: Extension Example1026238 -Node: Internal File Description1027036 -Node: Internal File Ops1031116 -Ref: Internal File Ops-Footnote-11042878 -Node: Using Internal File Ops1043018 -Ref: Using Internal File Ops-Footnote-11045401 -Node: Extension Samples1045675 -Node: Extension Sample File Functions1047204 -Node: Extension Sample Fnmatch1054853 -Node: Extension Sample Fork1056340 -Node: Extension Sample Inplace1057558 -Node: Extension Sample Ord1060768 -Node: Extension Sample Readdir1061604 -Ref: table-readdir-file-types1062493 -Node: Extension Sample Revout1063298 -Node: Extension Sample Rev2way1063887 -Node: Extension Sample Read write array1064627 -Node: Extension Sample Readfile1066569 -Node: Extension Sample Time1067664 -Node: Extension Sample API Tests1069012 -Node: gawkextlib1069504 -Node: Extension summary1071951 -Node: Extension Exercises1075643 -Node: Language History1077140 -Node: V7/SVR3.11078796 -Node: SVR41080948 -Node: POSIX1082382 -Node: BTL1083761 -Node: POSIX/GNU1084490 -Node: Feature History1090352 -Node: Common Extensions1104722 -Node: Ranges and Locales1106005 -Ref: Ranges and Locales-Footnote-11110621 -Ref: Ranges and Locales-Footnote-21110648 -Ref: Ranges and Locales-Footnote-31110883 -Node: Contributors1111104 -Node: History summary1116673 -Node: Installation1118053 -Node: Gawk Distribution1118997 -Node: Getting1119481 -Node: Extracting1120442 -Node: Distribution contents1122080 -Node: Unix Installation1128174 -Node: Quick Installation1128856 -Node: Shell Startup Files1131270 -Node: Additional Configuration Options1132348 -Node: Configuration Philosophy1134153 -Node: Non-Unix Installation1136522 -Node: PC Installation1136980 -Node: PC Binary Installation1138300 -Node: PC Compiling1140152 -Ref: PC Compiling-Footnote-11143176 -Node: PC Testing1143285 -Node: PC Using1144465 -Node: Cygwin1148579 -Node: MSYS1149349 -Node: VMS Installation1149850 -Node: VMS Compilation1150641 -Ref: VMS Compilation-Footnote-11151870 -Node: VMS Dynamic Extensions1151928 -Node: VMS Installation Details1153613 -Node: VMS Running1155866 -Node: VMS GNV1160145 -Node: VMS Old Gawk1160880 -Node: Bugs1161351 -Node: Other Versions1165548 -Node: Installation summary1172132 -Node: Notes1173190 -Node: Compatibility Mode1174055 -Node: Additions1174837 -Node: Accessing The Source1175762 -Node: Adding Code1177197 -Node: New Ports1183416 -Node: Derived Files1187904 -Ref: Derived Files-Footnote-11193389 -Ref: Derived Files-Footnote-21193424 -Ref: Derived Files-Footnote-31194022 -Node: Future Extensions1194136 -Node: Implementation Limitations1194794 -Node: Extension Design1195977 -Node: Old Extension Problems1197131 -Ref: Old Extension Problems-Footnote-11198649 -Node: Extension New Mechanism Goals1198706 -Ref: Extension New Mechanism Goals-Footnote-11202070 -Node: Extension Other Design Decisions1202259 -Node: Extension Future Growth1204372 -Node: Old Extension Mechanism1205208 -Node: Notes summary1206971 -Node: Basic Concepts1208153 -Node: Basic High Level1208834 -Ref: figure-general-flow1209116 -Ref: figure-process-flow1209801 -Ref: Basic High Level-Footnote-11213102 -Node: Basic Data Typing1213287 -Node: Glossary1216615 -Node: Copying1248561 -Node: GNU Free Documentation License1286100 -Node: Index1311218 +Ref: table-system-return-values556517 +Ref: I/O Functions-Footnote-1558497 +Ref: I/O Functions-Footnote-2558645 +Node: Time Functions558765 +Ref: Time Functions-Footnote-1569270 +Ref: Time Functions-Footnote-2569338 +Ref: Time Functions-Footnote-3569496 +Ref: Time Functions-Footnote-4569607 +Ref: Time Functions-Footnote-5569719 +Ref: Time Functions-Footnote-6569946 +Node: Bitwise Functions570212 +Ref: table-bitwise-ops570806 +Ref: Bitwise Functions-Footnote-1575144 +Node: Type Functions575317 +Node: I18N Functions577978 +Node: User-defined579629 +Node: Definition Syntax580434 +Ref: Definition Syntax-Footnote-1586121 +Node: Function Example586192 +Ref: Function Example-Footnote-1589114 +Node: Function Caveats589136 +Node: Calling A Function589654 +Node: Variable Scope590612 +Node: Pass By Value/Reference593606 +Node: Return Statement597105 +Node: Dynamic Typing600084 +Node: Indirect Calls601014 +Ref: Indirect Calls-Footnote-1611265 +Node: Functions Summary611393 +Node: Library Functions614098 +Ref: Library Functions-Footnote-1617705 +Ref: Library Functions-Footnote-2617848 +Node: Library Names618019 +Ref: Library Names-Footnote-1621479 +Ref: Library Names-Footnote-2621702 +Node: General Functions621788 +Node: Strtonum Function622891 +Node: Assert Function625913 +Node: Round Function629239 +Node: Cliff Random Function630780 +Node: Ordinal Functions631796 +Ref: Ordinal Functions-Footnote-1634859 +Ref: Ordinal Functions-Footnote-2635111 +Node: Join Function635321 +Ref: Join Function-Footnote-1637091 +Node: Getlocaltime Function637291 +Node: Readfile Function641033 +Node: Shell Quoting643005 +Node: Data File Management644406 +Node: Filetrans Function645038 +Node: Rewind Function649134 +Node: File Checking651039 +Ref: File Checking-Footnote-1652373 +Node: Empty Files652574 +Node: Ignoring Assigns654553 +Node: Getopt Function656103 +Ref: Getopt Function-Footnote-1667572 +Node: Passwd Functions667772 +Ref: Passwd Functions-Footnote-1676611 +Node: Group Functions676699 +Ref: Group Functions-Footnote-1684596 +Node: Walking Arrays684803 +Node: Library Functions Summary687811 +Node: Library Exercises689217 +Node: Sample Programs689682 +Node: Running Examples690452 +Node: Clones691180 +Node: Cut Program692404 +Node: Egrep Program702333 +Ref: Egrep Program-Footnote-1709845 +Node: Id Program709955 +Node: Split Program713635 +Ref: Split Program-Footnote-1717094 +Node: Tee Program717223 +Node: Uniq Program720013 +Node: Wc Program727439 +Ref: Wc Program-Footnote-1731694 +Node: Miscellaneous Programs731788 +Node: Dupword Program733001 +Node: Alarm Program735031 +Node: Translate Program739886 +Ref: Translate Program-Footnote-1744451 +Node: Labels Program744721 +Ref: Labels Program-Footnote-1748072 +Node: Word Sorting748156 +Node: History Sorting752228 +Node: Extract Program754063 +Node: Simple Sed761592 +Node: Igawk Program764666 +Ref: Igawk Program-Footnote-1778997 +Ref: Igawk Program-Footnote-2779199 +Ref: Igawk Program-Footnote-3779321 +Node: Anagram Program779436 +Node: Signature Program782498 +Node: Programs Summary783745 +Node: Programs Exercises784959 +Ref: Programs Exercises-Footnote-1789088 +Node: Advanced Features789179 +Node: Nondecimal Data791169 +Node: Array Sorting792760 +Node: Controlling Array Traversal793460 +Ref: Controlling Array Traversal-Footnote-1801827 +Node: Array Sorting Functions801945 +Ref: Array Sorting Functions-Footnote-1807036 +Node: Two-way I/O807232 +Ref: Two-way I/O-Footnote-1813052 +Ref: Two-way I/O-Footnote-2813239 +Node: TCP/IP Networking813321 +Node: Profiling816439 +Node: Advanced Features Summary824893 +Node: Internationalization826737 +Node: I18N and L10N828217 +Node: Explaining gettext828904 +Ref: Explaining gettext-Footnote-1833927 +Ref: Explaining gettext-Footnote-2834112 +Node: Programmer i18n834277 +Ref: Programmer i18n-Footnote-1839132 +Node: Translator i18n839181 +Node: String Extraction839975 +Ref: String Extraction-Footnote-1841107 +Node: Printf Ordering841193 +Ref: Printf Ordering-Footnote-1843979 +Node: I18N Portability844043 +Ref: I18N Portability-Footnote-1846499 +Node: I18N Example846562 +Ref: I18N Example-Footnote-1849368 +Node: Gawk I18N849441 +Node: I18N Summary850086 +Node: Debugger851427 +Node: Debugging852449 +Node: Debugging Concepts852890 +Node: Debugging Terms854699 +Node: Awk Debugging857274 +Node: Sample Debugging Session858180 +Node: Debugger Invocation858714 +Node: Finding The Bug860100 +Node: List of Debugger Commands866578 +Node: Breakpoint Control867911 +Node: Debugger Execution Control871605 +Node: Viewing And Changing Data874967 +Node: Execution Stack878341 +Node: Debugger Info879978 +Node: Miscellaneous Debugger Commands884049 +Node: Readline Support889137 +Node: Limitations890033 +Ref: Limitations-Footnote-1894264 +Node: Debugging Summary894315 +Node: Arbitrary Precision Arithmetic895594 +Node: Computer Arithmetic897010 +Ref: table-numeric-ranges900601 +Ref: Computer Arithmetic-Footnote-1901323 +Node: Math Definitions901380 +Ref: table-ieee-formats904694 +Ref: Math Definitions-Footnote-1905297 +Node: MPFR features905402 +Node: FP Math Caution907119 +Ref: FP Math Caution-Footnote-1908191 +Node: Inexactness of computations908560 +Node: Inexact representation909520 +Node: Comparing FP Values910880 +Node: Errors accumulate911962 +Node: Getting Accuracy913395 +Node: Try To Round916105 +Node: Setting precision917004 +Ref: table-predefined-precision-strings917701 +Node: Setting the rounding mode919531 +Ref: table-gawk-rounding-modes919905 +Ref: Setting the rounding mode-Footnote-1923313 +Node: Arbitrary Precision Integers923492 +Ref: Arbitrary Precision Integers-Footnote-1928409 +Node: POSIX Floating Point Problems928558 +Ref: POSIX Floating Point Problems-Footnote-1932440 +Node: Floating point summary932478 +Node: Dynamic Extensions934668 +Node: Extension Intro936221 +Node: Plugin License937487 +Node: Extension Mechanism Outline938284 +Ref: figure-load-extension938723 +Ref: figure-register-new-function940288 +Ref: figure-call-new-function941380 +Node: Extension API Description943442 +Node: Extension API Functions Introduction944974 +Node: General Data Types949833 +Ref: General Data Types-Footnote-1955788 +Node: Memory Allocation Functions956087 +Ref: Memory Allocation Functions-Footnote-1958932 +Node: Constructor Functions959031 +Node: Registration Functions960776 +Node: Extension Functions961461 +Node: Exit Callback Functions963760 +Node: Extension Version String965010 +Node: Input Parsers965673 +Node: Output Wrappers975558 +Node: Two-way processors980070 +Node: Printing Messages982334 +Ref: Printing Messages-Footnote-1983408 +Node: Updating ERRNO983561 +Node: Requesting Values984300 +Ref: table-value-types-returned985037 +Node: Accessing Parameters985920 +Node: Symbol Table Access987155 +Node: Symbol table by name987667 +Node: Symbol table by cookie989688 +Ref: Symbol table by cookie-Footnote-1993837 +Node: Cached values993901 +Ref: Cached values-Footnote-1997402 +Node: Array Manipulation997493 +Ref: Array Manipulation-Footnote-1998584 +Node: Array Data Types998621 +Ref: Array Data Types-Footnote-11001279 +Node: Array Functions1001371 +Node: Flattening Arrays1005229 +Node: Creating Arrays1012137 +Node: Redirection API1016908 +Node: Extension API Variables1019739 +Node: Extension Versioning1020372 +Node: Extension API Informational Variables1022263 +Node: Extension API Boilerplate1023327 +Node: Finding Extensions1027141 +Node: Extension Example1027700 +Node: Internal File Description1028498 +Node: Internal File Ops1032578 +Ref: Internal File Ops-Footnote-11044340 +Node: Using Internal File Ops1044480 +Ref: Using Internal File Ops-Footnote-11046863 +Node: Extension Samples1047137 +Node: Extension Sample File Functions1048666 +Node: Extension Sample Fnmatch1056315 +Node: Extension Sample Fork1057802 +Node: Extension Sample Inplace1059020 +Node: Extension Sample Ord1062230 +Node: Extension Sample Readdir1063066 +Ref: table-readdir-file-types1063955 +Node: Extension Sample Revout1064760 +Node: Extension Sample Rev2way1065349 +Node: Extension Sample Read write array1066089 +Node: Extension Sample Readfile1068031 +Node: Extension Sample Time1069126 +Node: Extension Sample API Tests1070474 +Node: gawkextlib1070966 +Node: Extension summary1073413 +Node: Extension Exercises1077105 +Node: Language History1078602 +Node: V7/SVR3.11080258 +Node: SVR41082410 +Node: POSIX1083844 +Node: BTL1085223 +Node: POSIX/GNU1085952 +Node: Feature History1091814 +Node: Common Extensions1106184 +Node: Ranges and Locales1107467 +Ref: Ranges and Locales-Footnote-11112083 +Ref: Ranges and Locales-Footnote-21112110 +Ref: Ranges and Locales-Footnote-31112345 +Node: Contributors1112566 +Node: History summary1118135 +Node: Installation1119515 +Node: Gawk Distribution1120459 +Node: Getting1120943 +Node: Extracting1121904 +Node: Distribution contents1123542 +Node: Unix Installation1129636 +Node: Quick Installation1130318 +Node: Shell Startup Files1132732 +Node: Additional Configuration Options1133810 +Node: Configuration Philosophy1135615 +Node: Non-Unix Installation1137984 +Node: PC Installation1138442 +Node: PC Binary Installation1139762 +Node: PC Compiling1141614 +Ref: PC Compiling-Footnote-11144638 +Node: PC Testing1144747 +Node: PC Using1145927 +Node: Cygwin1150041 +Node: MSYS1150811 +Node: VMS Installation1151312 +Node: VMS Compilation1152103 +Ref: VMS Compilation-Footnote-11153332 +Node: VMS Dynamic Extensions1153390 +Node: VMS Installation Details1155075 +Node: VMS Running1157328 +Node: VMS GNV1161607 +Node: VMS Old Gawk1162342 +Node: Bugs1162813 +Node: Other Versions1167010 +Node: Installation summary1173594 +Node: Notes1174652 +Node: Compatibility Mode1175517 +Node: Additions1176299 +Node: Accessing The Source1177224 +Node: Adding Code1178659 +Node: New Ports1184878 +Node: Derived Files1189366 +Ref: Derived Files-Footnote-11194851 +Ref: Derived Files-Footnote-21194886 +Ref: Derived Files-Footnote-31195484 +Node: Future Extensions1195598 +Node: Implementation Limitations1196256 +Node: Extension Design1197439 +Node: Old Extension Problems1198593 +Ref: Old Extension Problems-Footnote-11200111 +Node: Extension New Mechanism Goals1200168 +Ref: Extension New Mechanism Goals-Footnote-11203532 +Node: Extension Other Design Decisions1203721 +Node: Extension Future Growth1205834 +Node: Old Extension Mechanism1206670 +Node: Notes summary1208433 +Node: Basic Concepts1209615 +Node: Basic High Level1210296 +Ref: figure-general-flow1210578 +Ref: figure-process-flow1211263 +Ref: Basic High Level-Footnote-11214564 +Node: Basic Data Typing1214749 +Node: Glossary1218077 +Node: Copying1250023 +Node: GNU Free Documentation License1287562 +Node: Index1312680 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 002953eb..fb05d522 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -18622,7 +18622,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: @@ -18661,6 +18661,34 @@ 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 guilty signal number (bits 0--6). + +Traditionally, @command{awk}'s @code{system()} function has simply +returned the exit status value divided by 256. In the normal case this +gives the exit status but in the case of death-by-signal it yields +a fractional floating-point value.@footnote{In private correspondance, +Dr.@: Kernighan has indicated to me that the way this was done +was probably a mistake.} POSIX states that @command{awk}'s +@code{system()} should return the full 16-bit value. + +@command{gawk} steers a middle ground. +The return values are summarized in @ref{table-system-return-values}. + +@float Table,table-system-return-values +@caption{Return values from @code{system()}} +@multitable @columnfractions .40 .60 +@headitem Situation @tab Return value from @code{system()} +@item @option{--traditional} @tab C @code{system()}'s value divided by 256 +@item @option{--posix} @tab C @code{system()}'s value +@item Normal exit of command @tab Command's exit status +@item Death by signal of command @tab 256 + number of murderous signal +@item Death by signal of command with core dump @tab 512 + number of murderous signal +@item Some kind of error @tab @minus{}1 +@end multitable +@end float @end table @cindex sidebar, Controlling Output Buffering with @code{system()} diff --git a/doc/gawktexi.in b/doc/gawktexi.in index 37bffc32..d420ad68 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -17814,7 +17814,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: @@ -17853,6 +17853,34 @@ 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 guilty signal number (bits 0--6). + +Traditionally, @command{awk}'s @code{system()} function has simply +returned the exit status value divided by 256. In the normal case this +gives the exit status but in the case of death-by-signal it yields +a fractional floating-point value.@footnote{In private correspondance, +Dr.@: Kernighan has indicated to me that the way this was done +was probably a mistake.} POSIX states that @command{awk}'s +@code{system()} should return the full 16-bit value. + +@command{gawk} steers a middle ground. +The return values are summarized in @ref{table-system-return-values}. + +@float Table,table-system-return-values +@caption{Return values from @code{system()}} +@multitable @columnfractions .40 .60 +@headitem Situation @tab Return value from @code{system()} +@item @option{--traditional} @tab C @code{system()}'s value divided by 256 +@item @option{--posix} @tab C @code{system()}'s value +@item Normal exit of command @tab Command's exit status +@item Death by signal of command @tab 256 + number of murderous signal +@item Death by signal of command with core dump @tab 512 + number of murderous signal +@item Some kind of error @tab @minus{}1 +@end multitable +@end float @end table @sidebar Controlling Output Buffering with @code{system()} |