From 6522e5b623e083565229dc742336219a0dda1344 Mon Sep 17 00:00:00 2001 From: "Arnold D. Robbins" Date: Tue, 24 Mar 2015 22:58:20 +0200 Subject: General cleanups prepatory to merging. --- ChangeLog | 5 + awk.h | 4 +- doc/ChangeLog | 3 + doc/gawk.1 | 6 +- doc/gawk.info | 1024 ++++++++++++++++++++++++++++--------------------------- doc/gawk.texi | 99 +++--- doc/gawktexi.in | 99 +++--- gawkapi.c | 53 +-- io.c | 13 +- 9 files changed, 680 insertions(+), 626 deletions(-) diff --git a/ChangeLog b/ChangeLog index d52c86f0..468875fb 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2015-03-24 Arnold D. Robbins + + * awk.h, gawkapi.c, io.c: Minor code reformatting. + 2015-03-18 Arnold D. Robbins * config.guess, config.sub: Updated, from libtool 2.4.6. @@ -1672,6 +1676,7 @@ * eval.c (update_ERRNO_int, unset_ERRNO): Update PROCINFO["errno"]. 2013-06-30 Andrew J. Schorr + * awk.h (redirect_string): Declare new function that provides API access to the redirection mechanism. * gawkapi.h (GAWK_API_MINOR_VERSION): Bump from 0 to 1 since 2 new diff --git a/awk.h b/awk.h index 101e5866..6b9ac10b 100644 --- a/awk.h +++ b/awk.h @@ -1483,7 +1483,9 @@ extern void set_FNR(void); extern void set_NR(void); extern struct redirect *redirect(NODE *redir_exp, int redirtype, int *errflg, bool failure_fatal); -extern struct redirect *redirect_string(const char *redir_exp_str, size_t redir_exp_len, bool not_string_flag, int redirtype, int *errflg, int extfd, bool failure_fatal); +extern struct redirect *redirect_string(const char *redir_exp_str, + size_t redir_exp_len, bool not_string_flag, int redirtype, + int *errflg, int extfd, bool failure_fatal); extern NODE *do_close(int nargs); extern int flush_io(void); extern int close_io(bool *stdio_problem); diff --git a/doc/ChangeLog b/doc/ChangeLog index f0c7523b..679e1bea 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -2,6 +2,9 @@ * gawktexi.in: Minor fixes from Antonio Colombo and new exercise in chapter 16. + * gawk.1: Minor edits. + * gawktexi.in: Edits in material on errno and retryable and get_file + API. 2015-03-17 Andrew J. Schorr diff --git a/doc/gawk.1 b/doc/gawk.1 index b425c24c..45a4c9f2 100644 --- a/doc/gawk.1 +++ b/doc/gawk.1 @@ -13,7 +13,7 @@ . if \w'\(rq' .ds rq "\(rq . \} .\} -.TH GAWK 1 "Aug 03 2014" "Free Software Foundation" "Utility Commands" +.TH GAWK 1 "Mar 24 2015" "Free Software Foundation" "Utility Commands" .SH NAME gawk \- pattern scanning and processing language .SH SYNOPSIS @@ -1241,8 +1241,8 @@ less than zero means no timeout. If an I/O error that may be retried occurs when reading data from .IR input , and this array entry exists, then -.BR getline -will return -2 instead of following the default behavior of returning -1 +.B getline +will return \-2 instead of following the default behavior of returning \-1 and configuring .IR input to return no further data. diff --git a/doc/gawk.info b/doc/gawk.info index f0318e20..6b107344 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -5451,11 +5451,11 @@ how `awk' works. encounters the end of the file. If there is some error in getting a record, such as a file that cannot be opened, then `getline' returns -1. In this case, `gawk' sets the variable `ERRNO' to a string -describing the error that occurred. If the `errno' variable indicates -that the I/O operation may be retried, and `PROCINFO["input", "RETRY"]' -is set, then -2 will be returned instead of -1, and further calls to -`getline' may be attemped. *Note Retrying Input::, for further -information about this feature. +describing the error that occurred. If `ERRNO' indicates that the I/O +operation may be retried, and `PROCINFO["input", "RETRY"]' is set, then +-2 will be returned instead of -1, and further calls to `getline' may +be attemped. *Note Retrying Input::, for further information about +this feature. In the following examples, COMMAND stands for a string value that represents a shell command. @@ -5995,22 +5995,22 @@ File: gawk.info, Node: Retrying Input, Next: Command-line directories, Prev: This minor node describes a feature that is specific to `gawk'. - When `gawk' encounters an error while reading input, it will by -default return -1 from getline, and subsequent attempts to read from -that file will result in an end-of-file indication. However, you may -optionally instruct `gawk' to allow I/O to be retried when certain -errors are encountered by setting setting a special element in the -`PROCINFO' array (*note Auto-set::): + When `gawk' encounters an error while reading input, by default +`getline' returns -1, and subsequent attempts to read from that file +result in an end-of-file indication. However, you may optionally +instruct `gawk' to allow I/O to be retried when certain errors are +encountered by setting setting a special element in the `PROCINFO' +array (*note Auto-set::): - PROCINFO["input_name", "RETRY"] + PROCINFO["INPUT_NAME", "RETRY"] = 1 - When set, this causes `gawk' to check the value of the system + When this element exists, `gawk' checks the value of the system `errno' variable when an I/O error occurs. If `errno' indicates a -subsequent I/O attempt may succeed, `getline' will instead return -2 and +subsequent I/O attempt may succeed, `getline' instead returns -2 and further calls to `getline' may succeed. This applies to `errno' values -EAGAIN, EWOULDBLOCK, EINTR, or ETIMEDOUT. +`EAGAIN', `EWOULDBLOCK', `EINTR', or `ETIMEDOUT'. - This feature is useful in conjunction with `PROCINFO["input_name", + This feature is useful in conjunction with `PROCINFO["INPUT_NAME", "READ_TIMEOUT"]' or situations where a file descriptor has been configured to behave in a non-blocking fashion. @@ -24796,49 +24796,55 @@ redirections. ` const awk_input_buf_t **ibufp,' ` const awk_output_buf_t **obufp);' Look up a file in `gawk''s internal redirection table. If `name' - is NULL or `name_len' is 0, it returns data for the currently open - input file corresponding to `FILENAME' (and it will not access the - `filetype' argument, so that may be undefined). If the file is - not already open, it tries to open it. The `filetype' argument - must be NUL-terminated and should be one of: - `>' + is `NULL' or `name_len' is zero, return data for the currently + open input file corresponding to `FILENAME'. (This does not + access the `filetype' argument, so that may be undefined). If the + file is not already open, attempt to open it. The `filetype' + argument must be zero-terminated and should be one of: + + `">"' A file opened for output. - `>>' + `">>"' A file opened for append. - `<' + `"<"' A file opened for input. - `|>' + `"|>"' A pipe opened for output. - `|<' + `"|<"' A pipe opened for input. - `|&' + `"|&"' A two-way coprocess. - On error, a `false' value is returned. Otherwise, the return - status is `true', and additional information about the redirection - is returned in the `ibufp' and `obufp' pointers. For input - redirections, the `*ibufp' value should be non-NULL, and `*obufp' - should be NULL. For output redirections, the `*obufp' value - should be non-NULL, and `*ibufp' should be NULL. For two-way - coprocesses, both values should be non-NULL. In the usual case, - the extension is interested in `(*ibufp)->fd' and/or - `fileno((*obufp)->fp)'. If the file is not already open, and the - fd argument is non-negative, `gawk' will use that file descriptor - instead of opening the file in the usual way. If the fd is - non-negative, but the file exists already, `gawk' ignores the fd + + On error, return a `false' value. Otherwise, return `true', and + return additional information about the redirection in the `ibufp' + and `obufp' pointers. For input redirections, the `*ibufp' value + should be non-`NULL', and `*obufp' should be `NULL'. For output + redirections, the `*obufp' value should be non-`NULL', and `*ibufp' + should be `NULL'. For two-way coprocesses, both values should be + non-`NULL'. + + In the usual case, the extension is interested in `(*ibufp)->fd' + and/or `fileno((*obufp)->fp)'. If the file is not already open, + and the `fd' argument is non-negative, `gawk' will use that file + descriptor instead of opening the file in the usual way. If `fd' + is non-negative, but the file exists already, `gawk' ignores `fd' and returns the existing file. It is the caller's responsibility - to notice that neither the fd in the returned `awk_input_buf_t' - nor the fd in the returned `awk_output_buf_t' matches the - requested value. Note that supplying a file descriptor is - currently NOT supported for pipes. It should work for input, - output, append, and two-way (coprocess) sockets. If `filetype' is - two-way, we assume that it is a socket! Note that in the two-way - case, the input and output file descriptors may differ. To check - for success, one must check whether either matches. + to notice that neither the `fd' in the returned `awk_input_buf_t' + nor the `fd' in the returned `awk_output_buf_t' matches the + requested value. + + Note that supplying a file descriptor is currently _not_ supported + for pipes. However, supplying a file descriptor should work for + input, output, append, and two-way (coprocess) sockets. If + `filetype' is two-way, `gawk' assumes that it is a socket! Note + that in the two-way case, the input and output file descriptors + may differ. To check for success, you must check whether either + matches. It is anticipated that this API function will be used to implement I/O multiplexing and a socket library. @@ -34975,467 +34981,467 @@ Ref: Splitting By Content-Footnote-1236687 Node: Multiple Line236850 Ref: Multiple Line-Footnote-1242731 Node: Getline242910 -Node: Plain Getline245389 -Node: Getline/Variable248029 -Node: Getline/File249178 -Node: Getline/Variable/File250563 -Ref: Getline/Variable/File-Footnote-1252166 -Node: Getline/Pipe252253 -Node: Getline/Variable/Pipe254931 -Node: Getline/Coprocess256062 -Node: Getline/Variable/Coprocess257326 -Node: Getline Notes258065 -Node: Getline Summary260859 -Ref: table-getline-variants261271 -Node: Read Timeout262100 -Ref: Read Timeout-Footnote-1266003 -Node: Retrying Input266061 -Node: Command-line directories267256 -Node: Input Summary268163 -Node: Input Exercises271548 -Node: Printing272276 -Node: Print274111 -Node: Print Examples275568 -Node: Output Separators278347 -Node: OFMT280365 -Node: Printf281720 -Node: Basic Printf282505 -Node: Control Letters284077 -Node: Format Modifiers288062 -Node: Printf Examples294068 -Node: Redirection296554 -Node: Special FD303392 -Ref: Special FD-Footnote-1306558 -Node: Special Files306632 -Node: Other Inherited Files307249 -Node: Special Network308249 -Node: Special Caveats309111 -Node: Close Files And Pipes310060 -Ref: Close Files And Pipes-Footnote-1317245 -Ref: Close Files And Pipes-Footnote-2317393 -Node: Nonfatal317543 -Node: Output Summary319868 -Node: Output Exercises321089 -Node: Expressions321769 -Node: Values322958 -Node: Constants323635 -Node: Scalar Constants324326 -Ref: Scalar Constants-Footnote-1325188 -Node: Nondecimal-numbers325438 -Node: Regexp Constants328448 -Node: Using Constant Regexps328974 -Node: Variables332137 -Node: Using Variables332794 -Node: Assignment Options334705 -Node: Conversion336580 -Node: Strings And Numbers337104 -Ref: Strings And Numbers-Footnote-1340169 -Node: Locale influences conversions340278 -Ref: table-locale-affects343024 -Node: All Operators343616 -Node: Arithmetic Ops344245 -Node: Concatenation346750 -Ref: Concatenation-Footnote-1349569 -Node: Assignment Ops349676 -Ref: table-assign-ops354655 -Node: Increment Ops355965 -Node: Truth Values and Conditions359396 -Node: Truth Values360479 -Node: Typing and Comparison361528 -Node: Variable Typing362344 -Node: Comparison Operators366011 -Ref: table-relational-ops366421 -Node: POSIX String Comparison369916 -Ref: POSIX String Comparison-Footnote-1370988 -Node: Boolean Ops371127 -Ref: Boolean Ops-Footnote-1375605 -Node: Conditional Exp375696 -Node: Function Calls377434 -Node: Precedence381314 -Node: Locales384974 -Node: Expressions Summary386606 -Node: Patterns and Actions389177 -Node: Pattern Overview390297 -Node: Regexp Patterns391976 -Node: Expression Patterns392519 -Node: Ranges396299 -Node: BEGIN/END399406 -Node: Using BEGIN/END400167 -Ref: Using BEGIN/END-Footnote-1402903 -Node: I/O And BEGIN/END403009 -Node: BEGINFILE/ENDFILE405324 -Node: Empty408221 -Node: Using Shell Variables408538 -Node: Action Overview410811 -Node: Statements413137 -Node: If Statement414985 -Node: While Statement416480 -Node: Do Statement418508 -Node: For Statement419656 -Node: Switch Statement422814 -Node: Break Statement425196 -Node: Continue Statement427289 -Node: Next Statement429116 -Node: Nextfile Statement431497 -Node: Exit Statement434125 -Node: Built-in Variables436536 -Node: User-modified437669 -Ref: User-modified-Footnote-1445303 -Node: Auto-set445365 -Ref: Auto-set-Footnote-1459598 -Ref: Auto-set-Footnote-2459803 -Node: ARGC and ARGV459859 -Node: Pattern Action Summary464077 -Node: Arrays466510 -Node: Array Basics467839 -Node: Array Intro468683 -Ref: figure-array-elements470620 -Ref: Array Intro-Footnote-1473243 -Node: Reference to Elements473371 -Node: Assigning Elements475833 -Node: Array Example476324 -Node: Scanning an Array478083 -Node: Controlling Scanning481106 -Ref: Controlling Scanning-Footnote-1486500 -Node: Numeric Array Subscripts486816 -Node: Uninitialized Subscripts489001 -Node: Delete490618 -Ref: Delete-Footnote-1493367 -Node: Multidimensional493424 -Node: Multiscanning496521 -Node: Arrays of Arrays498110 -Node: Arrays Summary502864 -Node: Functions504955 -Node: Built-in505994 -Node: Calling Built-in507072 -Node: Numeric Functions509067 -Ref: Numeric Functions-Footnote-1513885 -Ref: Numeric Functions-Footnote-2514242 -Ref: Numeric Functions-Footnote-3514290 -Node: String Functions514562 -Ref: String Functions-Footnote-1538063 -Ref: String Functions-Footnote-2538192 -Ref: String Functions-Footnote-3538440 -Node: Gory Details538527 -Ref: table-sub-escapes540308 -Ref: table-sub-proposed541823 -Ref: table-posix-sub543185 -Ref: table-gensub-escapes544722 -Ref: Gory Details-Footnote-1545555 -Node: I/O Functions545706 -Ref: I/O Functions-Footnote-1552942 -Node: Time Functions553089 -Ref: Time Functions-Footnote-1563598 -Ref: Time Functions-Footnote-2563666 -Ref: Time Functions-Footnote-3563824 -Ref: Time Functions-Footnote-4563935 -Ref: Time Functions-Footnote-5564047 -Ref: Time Functions-Footnote-6564274 -Node: Bitwise Functions564540 -Ref: table-bitwise-ops565102 -Ref: Bitwise Functions-Footnote-1569430 -Node: Type Functions569602 -Node: I18N Functions570754 -Node: User-defined572401 -Node: Definition Syntax573206 -Ref: Definition Syntax-Footnote-1578865 -Node: Function Example578936 -Ref: Function Example-Footnote-1581857 -Node: Function Caveats581879 -Node: Calling A Function582397 -Node: Variable Scope583355 -Node: Pass By Value/Reference586348 -Node: Return Statement589845 -Node: Dynamic Typing592824 -Node: Indirect Calls593753 -Ref: Indirect Calls-Footnote-1603618 -Node: Functions Summary603746 -Node: Library Functions606448 -Ref: Library Functions-Footnote-1610056 -Ref: Library Functions-Footnote-2610199 -Node: Library Names610370 -Ref: Library Names-Footnote-1613828 -Ref: Library Names-Footnote-2614051 -Node: General Functions614137 -Node: Strtonum Function615240 -Node: Assert Function618262 -Node: Round Function621586 -Node: Cliff Random Function623127 -Node: Ordinal Functions624143 -Ref: Ordinal Functions-Footnote-1627206 -Ref: Ordinal Functions-Footnote-2627458 -Node: Join Function627669 -Ref: Join Function-Footnote-1629439 -Node: Getlocaltime Function629639 -Node: Readfile Function633383 -Node: Shell Quoting635355 -Node: Data File Management636756 -Node: Filetrans Function637388 -Node: Rewind Function641484 -Node: File Checking642870 -Ref: File Checking-Footnote-1644203 -Node: Empty Files644404 -Node: Ignoring Assigns646383 -Node: Getopt Function647933 -Ref: Getopt Function-Footnote-1659397 -Node: Passwd Functions659597 -Ref: Passwd Functions-Footnote-1668437 -Node: Group Functions668525 -Ref: Group Functions-Footnote-1676422 -Node: Walking Arrays676627 -Node: Library Functions Summary679633 -Node: Library Exercises681035 -Node: Sample Programs682315 -Node: Running Examples683085 -Node: Clones683813 -Node: Cut Program685037 -Node: Egrep Program694757 -Ref: Egrep Program-Footnote-1702260 -Node: Id Program702370 -Node: Split Program706046 -Ref: Split Program-Footnote-1709500 -Node: Tee Program709628 -Node: Uniq Program712417 -Node: Wc Program719836 -Ref: Wc Program-Footnote-1724086 -Node: Miscellaneous Programs724180 -Node: Dupword Program725393 -Node: Alarm Program727424 -Node: Translate Program732229 -Ref: Translate Program-Footnote-1736792 -Node: Labels Program737062 -Ref: Labels Program-Footnote-1740413 -Node: Word Sorting740497 -Node: History Sorting744567 -Node: Extract Program746402 -Node: Simple Sed753926 -Node: Igawk Program756996 -Ref: Igawk Program-Footnote-1771322 -Ref: Igawk Program-Footnote-2771523 -Ref: Igawk Program-Footnote-3771645 -Node: Anagram Program771760 -Node: Signature Program774821 -Node: Programs Summary776068 -Node: Programs Exercises777289 -Ref: Programs Exercises-Footnote-1781420 -Node: Advanced Features781511 -Node: Nondecimal Data783493 -Node: Array Sorting785083 -Node: Controlling Array Traversal785783 -Ref: Controlling Array Traversal-Footnote-1794149 -Node: Array Sorting Functions794267 -Ref: Array Sorting Functions-Footnote-1798153 -Node: Two-way I/O798349 -Ref: Two-way I/O-Footnote-1803294 -Ref: Two-way I/O-Footnote-2803480 -Node: TCP/IP Networking803562 -Node: Profiling806434 -Node: Advanced Features Summary814705 -Node: Internationalization816638 -Node: I18N and L10N818118 -Node: Explaining gettext818804 -Ref: Explaining gettext-Footnote-1823829 -Ref: Explaining gettext-Footnote-2824013 -Node: Programmer i18n824178 -Ref: Programmer i18n-Footnote-1829054 -Node: Translator i18n829103 -Node: String Extraction829897 -Ref: String Extraction-Footnote-1831028 -Node: Printf Ordering831114 -Ref: Printf Ordering-Footnote-1833900 -Node: I18N Portability833964 -Ref: I18N Portability-Footnote-1836420 -Node: I18N Example836483 -Ref: I18N Example-Footnote-1839286 -Node: Gawk I18N839358 -Node: I18N Summary840002 -Node: Debugger841342 -Node: Debugging842364 -Node: Debugging Concepts842805 -Node: Debugging Terms844615 -Node: Awk Debugging847187 -Node: Sample Debugging Session848093 -Node: Debugger Invocation848627 -Node: Finding The Bug850012 -Node: List of Debugger Commands856491 -Node: Breakpoint Control857823 -Node: Debugger Execution Control861500 -Node: Viewing And Changing Data864859 -Node: Execution Stack868235 -Node: Debugger Info869870 -Node: Miscellaneous Debugger Commands873915 -Node: Readline Support878916 -Node: Limitations879810 -Node: Debugging Summary881925 -Node: Arbitrary Precision Arithmetic883099 -Node: Computer Arithmetic884515 -Ref: table-numeric-ranges888092 -Ref: Computer Arithmetic-Footnote-1888616 -Node: Math Definitions888673 -Ref: table-ieee-formats891968 -Ref: Math Definitions-Footnote-1892572 -Node: MPFR features892677 -Node: FP Math Caution894348 -Ref: FP Math Caution-Footnote-1895398 -Node: Inexactness of computations895767 -Node: Inexact representation896726 -Node: Comparing FP Values898084 -Node: Errors accumulate899166 -Node: Getting Accuracy900598 -Node: Try To Round903302 -Node: Setting precision904201 -Ref: table-predefined-precision-strings904885 -Node: Setting the rounding mode906714 -Ref: table-gawk-rounding-modes907078 -Ref: Setting the rounding mode-Footnote-1910530 -Node: Arbitrary Precision Integers910709 -Ref: Arbitrary Precision Integers-Footnote-1915607 -Node: POSIX Floating Point Problems915756 -Ref: POSIX Floating Point Problems-Footnote-1919635 -Node: Floating point summary919673 -Node: Dynamic Extensions921860 -Node: Extension Intro923412 -Node: Plugin License924677 -Node: Extension Mechanism Outline925474 -Ref: figure-load-extension925902 -Ref: figure-register-new-function927382 -Ref: figure-call-new-function928386 -Node: Extension API Description930373 -Node: Extension API Functions Introduction931907 -Node: General Data Types936776 -Ref: General Data Types-Footnote-1942676 -Node: Memory Allocation Functions942975 -Ref: Memory Allocation Functions-Footnote-1945814 -Node: Constructor Functions945913 -Node: Registration Functions947652 -Node: Extension Functions948337 -Node: Exit Callback Functions950634 -Node: Extension Version String951882 -Node: Input Parsers952545 -Node: Output Wrappers962420 -Node: Two-way processors966933 -Node: Printing Messages969196 -Ref: Printing Messages-Footnote-1970272 -Node: Updating `ERRNO'970424 -Node: Requesting Values971164 -Ref: table-value-types-returned971891 -Node: Accessing Parameters972848 -Node: Symbol Table Access974082 -Node: Symbol table by name974596 -Node: Symbol table by cookie976616 -Ref: Symbol table by cookie-Footnote-1980761 -Node: Cached values980824 -Ref: Cached values-Footnote-1984320 -Node: Array Manipulation984411 -Ref: Array Manipulation-Footnote-1985501 -Node: Array Data Types985538 -Ref: Array Data Types-Footnote-1988193 -Node: Array Functions988285 -Node: Flattening Arrays992144 -Node: Creating Arrays999046 -Node: Redirection API1003817 -Node: Extension API Variables1006588 -Node: Extension Versioning1007221 -Node: Extension API Informational Variables1009112 -Node: Extension API Boilerplate1010177 -Node: Finding Extensions1013986 -Node: Extension Example1014546 -Node: Internal File Description1015318 -Node: Internal File Ops1019385 -Ref: Internal File Ops-Footnote-11031136 -Node: Using Internal File Ops1031276 -Ref: Using Internal File Ops-Footnote-11033659 -Node: Extension Samples1033932 -Node: Extension Sample File Functions1035460 -Node: Extension Sample Fnmatch1043141 -Node: Extension Sample Fork1044629 -Node: Extension Sample Inplace1045844 -Node: Extension Sample Ord1047930 -Node: Extension Sample Readdir1048766 -Ref: table-readdir-file-types1049643 -Node: Extension Sample Revout1050454 -Node: Extension Sample Rev2way1051043 -Node: Extension Sample Read write array1051783 -Node: Extension Sample Readfile1053723 -Node: Extension Sample Time1054818 -Node: Extension Sample API Tests1056166 -Node: gawkextlib1056657 -Node: Extension summary1059335 -Node: Extension Exercises1063024 -Node: Language History1064520 -Node: V7/SVR3.11066176 -Node: SVR41068329 -Node: POSIX1069763 -Node: BTL1071144 -Node: POSIX/GNU1071875 -Node: Feature History1077711 -Node: Common Extensions1091505 -Node: Ranges and Locales1092877 -Ref: Ranges and Locales-Footnote-11097496 -Ref: Ranges and Locales-Footnote-21097523 -Ref: Ranges and Locales-Footnote-31097758 -Node: Contributors1097979 -Node: History summary1103519 -Node: Installation1104898 -Node: Gawk Distribution1105844 -Node: Getting1106328 -Node: Extracting1107151 -Node: Distribution contents1108788 -Node: Unix Installation1114890 -Node: Quick Installation1115573 -Node: Shell Startup Files1117984 -Node: Additional Configuration Options1119063 -Node: Configuration Philosophy1120867 -Node: Non-Unix Installation1123236 -Node: PC Installation1123694 -Node: PC Binary Installation1125014 -Node: PC Compiling1126862 -Ref: PC Compiling-Footnote-11129883 -Node: PC Testing1129992 -Node: PC Using1131168 -Node: Cygwin1135283 -Node: MSYS1136053 -Node: VMS Installation1136554 -Node: VMS Compilation1137346 -Ref: VMS Compilation-Footnote-11138575 -Node: VMS Dynamic Extensions1138633 -Node: VMS Installation Details1140317 -Node: VMS Running1142568 -Node: VMS GNV1145408 -Node: VMS Old Gawk1146143 -Node: Bugs1146613 -Node: Other Versions1150502 -Node: Installation summary1156936 -Node: Notes1157995 -Node: Compatibility Mode1158860 -Node: Additions1159642 -Node: Accessing The Source1160567 -Node: Adding Code1162002 -Node: New Ports1168159 -Node: Derived Files1172641 -Ref: Derived Files-Footnote-11178116 -Ref: Derived Files-Footnote-21178150 -Ref: Derived Files-Footnote-31178746 -Node: Future Extensions1178860 -Node: Implementation Limitations1179466 -Node: Extension Design1180714 -Node: Old Extension Problems1181868 -Ref: Old Extension Problems-Footnote-11183385 -Node: Extension New Mechanism Goals1183442 -Ref: Extension New Mechanism Goals-Footnote-11186802 -Node: Extension Other Design Decisions1186991 -Node: Extension Future Growth1189099 -Node: Old Extension Mechanism1189935 -Node: Notes summary1191697 -Node: Basic Concepts1192883 -Node: Basic High Level1193564 -Ref: figure-general-flow1193836 -Ref: figure-process-flow1194435 -Ref: Basic High Level-Footnote-11197664 -Node: Basic Data Typing1197849 -Node: Glossary1201177 -Node: Copying1233106 -Node: GNU Free Documentation License1270662 -Node: Index1295798 +Node: Plain Getline245376 +Node: Getline/Variable248016 +Node: Getline/File249165 +Node: Getline/Variable/File250550 +Ref: Getline/Variable/File-Footnote-1252153 +Node: Getline/Pipe252240 +Node: Getline/Variable/Pipe254918 +Node: Getline/Coprocess256049 +Node: Getline/Variable/Coprocess257313 +Node: Getline Notes258052 +Node: Getline Summary260846 +Ref: table-getline-variants261258 +Node: Read Timeout262087 +Ref: Read Timeout-Footnote-1265990 +Node: Retrying Input266048 +Node: Command-line directories267238 +Node: Input Summary268145 +Node: Input Exercises271530 +Node: Printing272258 +Node: Print274093 +Node: Print Examples275550 +Node: Output Separators278329 +Node: OFMT280347 +Node: Printf281702 +Node: Basic Printf282487 +Node: Control Letters284059 +Node: Format Modifiers288044 +Node: Printf Examples294050 +Node: Redirection296536 +Node: Special FD303374 +Ref: Special FD-Footnote-1306540 +Node: Special Files306614 +Node: Other Inherited Files307231 +Node: Special Network308231 +Node: Special Caveats309093 +Node: Close Files And Pipes310042 +Ref: Close Files And Pipes-Footnote-1317227 +Ref: Close Files And Pipes-Footnote-2317375 +Node: Nonfatal317525 +Node: Output Summary319850 +Node: Output Exercises321071 +Node: Expressions321751 +Node: Values322940 +Node: Constants323617 +Node: Scalar Constants324308 +Ref: Scalar Constants-Footnote-1325170 +Node: Nondecimal-numbers325420 +Node: Regexp Constants328430 +Node: Using Constant Regexps328956 +Node: Variables332119 +Node: Using Variables332776 +Node: Assignment Options334687 +Node: Conversion336562 +Node: Strings And Numbers337086 +Ref: Strings And Numbers-Footnote-1340151 +Node: Locale influences conversions340260 +Ref: table-locale-affects343006 +Node: All Operators343598 +Node: Arithmetic Ops344227 +Node: Concatenation346732 +Ref: Concatenation-Footnote-1349551 +Node: Assignment Ops349658 +Ref: table-assign-ops354637 +Node: Increment Ops355947 +Node: Truth Values and Conditions359378 +Node: Truth Values360461 +Node: Typing and Comparison361510 +Node: Variable Typing362326 +Node: Comparison Operators365993 +Ref: table-relational-ops366403 +Node: POSIX String Comparison369898 +Ref: POSIX String Comparison-Footnote-1370970 +Node: Boolean Ops371109 +Ref: Boolean Ops-Footnote-1375587 +Node: Conditional Exp375678 +Node: Function Calls377416 +Node: Precedence381296 +Node: Locales384956 +Node: Expressions Summary386588 +Node: Patterns and Actions389159 +Node: Pattern Overview390279 +Node: Regexp Patterns391958 +Node: Expression Patterns392501 +Node: Ranges396281 +Node: BEGIN/END399388 +Node: Using BEGIN/END400149 +Ref: Using BEGIN/END-Footnote-1402885 +Node: I/O And BEGIN/END402991 +Node: BEGINFILE/ENDFILE405306 +Node: Empty408203 +Node: Using Shell Variables408520 +Node: Action Overview410793 +Node: Statements413119 +Node: If Statement414967 +Node: While Statement416462 +Node: Do Statement418490 +Node: For Statement419638 +Node: Switch Statement422796 +Node: Break Statement425178 +Node: Continue Statement427271 +Node: Next Statement429098 +Node: Nextfile Statement431479 +Node: Exit Statement434107 +Node: Built-in Variables436518 +Node: User-modified437651 +Ref: User-modified-Footnote-1445285 +Node: Auto-set445347 +Ref: Auto-set-Footnote-1459580 +Ref: Auto-set-Footnote-2459785 +Node: ARGC and ARGV459841 +Node: Pattern Action Summary464059 +Node: Arrays466492 +Node: Array Basics467821 +Node: Array Intro468665 +Ref: figure-array-elements470602 +Ref: Array Intro-Footnote-1473225 +Node: Reference to Elements473353 +Node: Assigning Elements475815 +Node: Array Example476306 +Node: Scanning an Array478065 +Node: Controlling Scanning481088 +Ref: Controlling Scanning-Footnote-1486482 +Node: Numeric Array Subscripts486798 +Node: Uninitialized Subscripts488983 +Node: Delete490600 +Ref: Delete-Footnote-1493349 +Node: Multidimensional493406 +Node: Multiscanning496503 +Node: Arrays of Arrays498092 +Node: Arrays Summary502846 +Node: Functions504937 +Node: Built-in505976 +Node: Calling Built-in507054 +Node: Numeric Functions509049 +Ref: Numeric Functions-Footnote-1513867 +Ref: Numeric Functions-Footnote-2514224 +Ref: Numeric Functions-Footnote-3514272 +Node: String Functions514544 +Ref: String Functions-Footnote-1538045 +Ref: String Functions-Footnote-2538174 +Ref: String Functions-Footnote-3538422 +Node: Gory Details538509 +Ref: table-sub-escapes540290 +Ref: table-sub-proposed541805 +Ref: table-posix-sub543167 +Ref: table-gensub-escapes544704 +Ref: Gory Details-Footnote-1545537 +Node: I/O Functions545688 +Ref: I/O Functions-Footnote-1552924 +Node: Time Functions553071 +Ref: Time Functions-Footnote-1563580 +Ref: Time Functions-Footnote-2563648 +Ref: Time Functions-Footnote-3563806 +Ref: Time Functions-Footnote-4563917 +Ref: Time Functions-Footnote-5564029 +Ref: Time Functions-Footnote-6564256 +Node: Bitwise Functions564522 +Ref: table-bitwise-ops565084 +Ref: Bitwise Functions-Footnote-1569412 +Node: Type Functions569584 +Node: I18N Functions570736 +Node: User-defined572383 +Node: Definition Syntax573188 +Ref: Definition Syntax-Footnote-1578847 +Node: Function Example578918 +Ref: Function Example-Footnote-1581839 +Node: Function Caveats581861 +Node: Calling A Function582379 +Node: Variable Scope583337 +Node: Pass By Value/Reference586330 +Node: Return Statement589827 +Node: Dynamic Typing592806 +Node: Indirect Calls593735 +Ref: Indirect Calls-Footnote-1603600 +Node: Functions Summary603728 +Node: Library Functions606430 +Ref: Library Functions-Footnote-1610038 +Ref: Library Functions-Footnote-2610181 +Node: Library Names610352 +Ref: Library Names-Footnote-1613810 +Ref: Library Names-Footnote-2614033 +Node: General Functions614119 +Node: Strtonum Function615222 +Node: Assert Function618244 +Node: Round Function621568 +Node: Cliff Random Function623109 +Node: Ordinal Functions624125 +Ref: Ordinal Functions-Footnote-1627188 +Ref: Ordinal Functions-Footnote-2627440 +Node: Join Function627651 +Ref: Join Function-Footnote-1629421 +Node: Getlocaltime Function629621 +Node: Readfile Function633365 +Node: Shell Quoting635337 +Node: Data File Management636738 +Node: Filetrans Function637370 +Node: Rewind Function641466 +Node: File Checking642852 +Ref: File Checking-Footnote-1644185 +Node: Empty Files644386 +Node: Ignoring Assigns646365 +Node: Getopt Function647915 +Ref: Getopt Function-Footnote-1659379 +Node: Passwd Functions659579 +Ref: Passwd Functions-Footnote-1668419 +Node: Group Functions668507 +Ref: Group Functions-Footnote-1676404 +Node: Walking Arrays676609 +Node: Library Functions Summary679615 +Node: Library Exercises681017 +Node: Sample Programs682297 +Node: Running Examples683067 +Node: Clones683795 +Node: Cut Program685019 +Node: Egrep Program694739 +Ref: Egrep Program-Footnote-1702242 +Node: Id Program702352 +Node: Split Program706028 +Ref: Split Program-Footnote-1709482 +Node: Tee Program709610 +Node: Uniq Program712399 +Node: Wc Program719818 +Ref: Wc Program-Footnote-1724068 +Node: Miscellaneous Programs724162 +Node: Dupword Program725375 +Node: Alarm Program727406 +Node: Translate Program732211 +Ref: Translate Program-Footnote-1736774 +Node: Labels Program737044 +Ref: Labels Program-Footnote-1740395 +Node: Word Sorting740479 +Node: History Sorting744549 +Node: Extract Program746384 +Node: Simple Sed753908 +Node: Igawk Program756978 +Ref: Igawk Program-Footnote-1771304 +Ref: Igawk Program-Footnote-2771505 +Ref: Igawk Program-Footnote-3771627 +Node: Anagram Program771742 +Node: Signature Program774803 +Node: Programs Summary776050 +Node: Programs Exercises777271 +Ref: Programs Exercises-Footnote-1781402 +Node: Advanced Features781493 +Node: Nondecimal Data783475 +Node: Array Sorting785065 +Node: Controlling Array Traversal785765 +Ref: Controlling Array Traversal-Footnote-1794131 +Node: Array Sorting Functions794249 +Ref: Array Sorting Functions-Footnote-1798135 +Node: Two-way I/O798331 +Ref: Two-way I/O-Footnote-1803276 +Ref: Two-way I/O-Footnote-2803462 +Node: TCP/IP Networking803544 +Node: Profiling806416 +Node: Advanced Features Summary814687 +Node: Internationalization816620 +Node: I18N and L10N818100 +Node: Explaining gettext818786 +Ref: Explaining gettext-Footnote-1823811 +Ref: Explaining gettext-Footnote-2823995 +Node: Programmer i18n824160 +Ref: Programmer i18n-Footnote-1829036 +Node: Translator i18n829085 +Node: String Extraction829879 +Ref: String Extraction-Footnote-1831010 +Node: Printf Ordering831096 +Ref: Printf Ordering-Footnote-1833882 +Node: I18N Portability833946 +Ref: I18N Portability-Footnote-1836402 +Node: I18N Example836465 +Ref: I18N Example-Footnote-1839268 +Node: Gawk I18N839340 +Node: I18N Summary839984 +Node: Debugger841324 +Node: Debugging842346 +Node: Debugging Concepts842787 +Node: Debugging Terms844597 +Node: Awk Debugging847169 +Node: Sample Debugging Session848075 +Node: Debugger Invocation848609 +Node: Finding The Bug849994 +Node: List of Debugger Commands856473 +Node: Breakpoint Control857805 +Node: Debugger Execution Control861482 +Node: Viewing And Changing Data864841 +Node: Execution Stack868217 +Node: Debugger Info869852 +Node: Miscellaneous Debugger Commands873897 +Node: Readline Support878898 +Node: Limitations879792 +Node: Debugging Summary881907 +Node: Arbitrary Precision Arithmetic883081 +Node: Computer Arithmetic884497 +Ref: table-numeric-ranges888074 +Ref: Computer Arithmetic-Footnote-1888598 +Node: Math Definitions888655 +Ref: table-ieee-formats891950 +Ref: Math Definitions-Footnote-1892554 +Node: MPFR features892659 +Node: FP Math Caution894330 +Ref: FP Math Caution-Footnote-1895380 +Node: Inexactness of computations895749 +Node: Inexact representation896708 +Node: Comparing FP Values898066 +Node: Errors accumulate899148 +Node: Getting Accuracy900580 +Node: Try To Round903284 +Node: Setting precision904183 +Ref: table-predefined-precision-strings904867 +Node: Setting the rounding mode906696 +Ref: table-gawk-rounding-modes907060 +Ref: Setting the rounding mode-Footnote-1910512 +Node: Arbitrary Precision Integers910691 +Ref: Arbitrary Precision Integers-Footnote-1915589 +Node: POSIX Floating Point Problems915738 +Ref: POSIX Floating Point Problems-Footnote-1919617 +Node: Floating point summary919655 +Node: Dynamic Extensions921842 +Node: Extension Intro923394 +Node: Plugin License924659 +Node: Extension Mechanism Outline925456 +Ref: figure-load-extension925884 +Ref: figure-register-new-function927364 +Ref: figure-call-new-function928368 +Node: Extension API Description930355 +Node: Extension API Functions Introduction931889 +Node: General Data Types936758 +Ref: General Data Types-Footnote-1942658 +Node: Memory Allocation Functions942957 +Ref: Memory Allocation Functions-Footnote-1945796 +Node: Constructor Functions945895 +Node: Registration Functions947634 +Node: Extension Functions948319 +Node: Exit Callback Functions950616 +Node: Extension Version String951864 +Node: Input Parsers952527 +Node: Output Wrappers962402 +Node: Two-way processors966915 +Node: Printing Messages969178 +Ref: Printing Messages-Footnote-1970254 +Node: Updating `ERRNO'970406 +Node: Requesting Values971146 +Ref: table-value-types-returned971873 +Node: Accessing Parameters972830 +Node: Symbol Table Access974064 +Node: Symbol table by name974578 +Node: Symbol table by cookie976598 +Ref: Symbol table by cookie-Footnote-1980743 +Node: Cached values980806 +Ref: Cached values-Footnote-1984302 +Node: Array Manipulation984393 +Ref: Array Manipulation-Footnote-1985483 +Node: Array Data Types985520 +Ref: Array Data Types-Footnote-1988175 +Node: Array Functions988267 +Node: Flattening Arrays992126 +Node: Creating Arrays999028 +Node: Redirection API1003799 +Node: Extension API Variables1006624 +Node: Extension Versioning1007257 +Node: Extension API Informational Variables1009148 +Node: Extension API Boilerplate1010213 +Node: Finding Extensions1014022 +Node: Extension Example1014582 +Node: Internal File Description1015354 +Node: Internal File Ops1019421 +Ref: Internal File Ops-Footnote-11031172 +Node: Using Internal File Ops1031312 +Ref: Using Internal File Ops-Footnote-11033695 +Node: Extension Samples1033968 +Node: Extension Sample File Functions1035496 +Node: Extension Sample Fnmatch1043177 +Node: Extension Sample Fork1044665 +Node: Extension Sample Inplace1045880 +Node: Extension Sample Ord1047966 +Node: Extension Sample Readdir1048802 +Ref: table-readdir-file-types1049679 +Node: Extension Sample Revout1050490 +Node: Extension Sample Rev2way1051079 +Node: Extension Sample Read write array1051819 +Node: Extension Sample Readfile1053759 +Node: Extension Sample Time1054854 +Node: Extension Sample API Tests1056202 +Node: gawkextlib1056693 +Node: Extension summary1059371 +Node: Extension Exercises1063060 +Node: Language History1064556 +Node: V7/SVR3.11066212 +Node: SVR41068365 +Node: POSIX1069799 +Node: BTL1071180 +Node: POSIX/GNU1071911 +Node: Feature History1077747 +Node: Common Extensions1091541 +Node: Ranges and Locales1092913 +Ref: Ranges and Locales-Footnote-11097532 +Ref: Ranges and Locales-Footnote-21097559 +Ref: Ranges and Locales-Footnote-31097794 +Node: Contributors1098015 +Node: History summary1103555 +Node: Installation1104934 +Node: Gawk Distribution1105880 +Node: Getting1106364 +Node: Extracting1107187 +Node: Distribution contents1108824 +Node: Unix Installation1114926 +Node: Quick Installation1115609 +Node: Shell Startup Files1118020 +Node: Additional Configuration Options1119099 +Node: Configuration Philosophy1120903 +Node: Non-Unix Installation1123272 +Node: PC Installation1123730 +Node: PC Binary Installation1125050 +Node: PC Compiling1126898 +Ref: PC Compiling-Footnote-11129919 +Node: PC Testing1130028 +Node: PC Using1131204 +Node: Cygwin1135319 +Node: MSYS1136089 +Node: VMS Installation1136590 +Node: VMS Compilation1137382 +Ref: VMS Compilation-Footnote-11138611 +Node: VMS Dynamic Extensions1138669 +Node: VMS Installation Details1140353 +Node: VMS Running1142604 +Node: VMS GNV1145444 +Node: VMS Old Gawk1146179 +Node: Bugs1146649 +Node: Other Versions1150538 +Node: Installation summary1156972 +Node: Notes1158031 +Node: Compatibility Mode1158896 +Node: Additions1159678 +Node: Accessing The Source1160603 +Node: Adding Code1162038 +Node: New Ports1168195 +Node: Derived Files1172677 +Ref: Derived Files-Footnote-11178152 +Ref: Derived Files-Footnote-21178186 +Ref: Derived Files-Footnote-31178782 +Node: Future Extensions1178896 +Node: Implementation Limitations1179502 +Node: Extension Design1180750 +Node: Old Extension Problems1181904 +Ref: Old Extension Problems-Footnote-11183421 +Node: Extension New Mechanism Goals1183478 +Ref: Extension New Mechanism Goals-Footnote-11186838 +Node: Extension Other Design Decisions1187027 +Node: Extension Future Growth1189135 +Node: Old Extension Mechanism1189971 +Node: Notes summary1191733 +Node: Basic Concepts1192919 +Node: Basic High Level1193600 +Ref: figure-general-flow1193872 +Ref: figure-process-flow1194471 +Ref: Basic High Level-Footnote-11197700 +Node: Basic Data Typing1197885 +Node: Glossary1201213 +Node: Copying1233142 +Node: GNU Free Documentation License1270698 +Node: Index1295834  End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index ff730b21..0c21d923 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -8115,7 +8115,7 @@ it encounters the end of the file. If there is some error in getting a record, such as a file that cannot be opened, then @code{getline} returns @minus{}1. In this case, @command{gawk} sets the variable @code{ERRNO} to a string describing the error that occurred. -If the @code{errno} variable indicates that the I/O operation may be +If @code{ERRNO} indicates that the I/O operation may be retried, and @code{PROCINFO["input", "RETRY"]} is set, then @minus{}2 will be returned instead of @minus{}1, and further calls to @code{getline} may be attemped. @DBXREF{Retrying Input} for further information about @@ -8793,26 +8793,26 @@ indefinitely until some other process opens it for writing. @cindex differences in @command{awk} and @command{gawk}, retrying input This @value{SECTION} describes a feature that is specific to @command{gawk}. -When @command{gawk} encounters an error while reading input, it will by default -return @minus{}1 from getline, and subsequent attempts to read from that file -will result in an end-of-file indication. However, you may optionally instruct -@command{gawk} to allow I/O to be retried when certain errors are encountered -by setting setting a special element -in the @code{PROCINFO} array (@pxref{Auto-set}): +When @command{gawk} encounters an error while reading input, by +default @code{getline} returns @minus{}1, and subsequent attempts to +read from that file result in an end-of-file indication. However, you +may optionally instruct @command{gawk} to allow I/O to be retried when +certain errors are encountered by setting setting a special element in +the @code{PROCINFO} array (@pxref{Auto-set}): @example -PROCINFO["input_name", "RETRY"] +PROCINFO["@var{input_name}", "RETRY"] = 1 @end example -When set, this causes @command{gawk} to check the value of the system +When this element exists, @command{gawk} checks the value of the system @code{errno} variable when an I/O error occurs. If @code{errno} indicates -a subsequent I/O attempt may succeed, @code{getline} will instead return +a subsequent I/O attempt may succeed, @code{getline} instead returns @minus{}2 and further calls to @code{getline} may succeed. This applies to @code{errno} -values EAGAIN, EWOULDBLOCK, EINTR, or ETIMEDOUT. +values @code{EAGAIN}, @code{EWOULDBLOCK}, @code{EINTR}, or @code{ETIMEDOUT}. This feature is useful in conjunction with -@code{PROCINFO["input_name", "READ_TIMEOUT"]} or situations where a file +@code{PROCINFO["@var{input_name}", "READ_TIMEOUT"]} or situations where a file descriptor has been configured to behave in a non-blocking fashion. @node Command-line directories @@ -33685,45 +33685,58 @@ The following function allows extensions to access and manipulate redirections. @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ int fd, @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ const awk_input_buf_t **ibufp, @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ const awk_output_buf_t **obufp); -Look up a file in @command{gawk}'s internal redirection table. If @code{name} is NULL or @code{name_len} is 0, it returns -data for the currently open input file corresponding to @code{FILENAME} -(and it will not access the @code{filetype} argument, so that may be -undefined). -If the file is not already open, it tries to open it. -The @code{filetype} argument must be NUL-terminated and should be one of: +Look up a file in @command{gawk}'s internal redirection table. +If @code{name} is @code{NULL} or @code{name_len} is zero, return +data for the currently open input file corresponding to @code{FILENAME}. +(This does not access the @code{filetype} argument, so that may be undefined). +If the file is not already open, attempt to open it. +The @code{filetype} argument must be zero-terminated and should be one of: + @table @code -@item > +@item ">" A file opened for output. -@item >> + +@item ">>" A file opened for append. -@item < + +@item "<" A file opened for input. -@item |> + +@item "|>" A pipe opened for output. -@item |< + +@item "|<" A pipe opened for input. -@item |& + +@item "|&" A two-way coprocess. @end table -On error, a @code{false} value is returned. Otherwise, the return status -is @code{true}, and additional information about the redirection is -returned in the @code{ibufp} and @code{obufp} pointers. For input redirections, -the @code{*ibufp} value should be non-NULL, and @code{*obufp} should be NULL. -For output redirections, -the @code{*obufp} value should be non-NULL, and @code{*ibufp} should be NULL. -For two-way coprocesses, both values should be non-NULL. In the usual case, -the extension is interested in @code{(*ibufp)->fd} and/or @code{fileno((*obufp)->fp)}. -If the file is not already open, and the fd argument is non-negative, -@command{gawk} will use that file descriptor instead of opening the file -in the usual way. If the fd is non-negative, but the file exists -already, @command{gawk} ignores the fd and returns the existing file. It is -the caller's responsibility to notice that neither the fd in the returned -@code{awk_input_buf_t} nor the fd in the returned @code{awk_output_buf_t} matches the requested value. Note that -supplying a file descriptor is currently NOT supported for pipes. -It should work for input, output, append, and two-way (coprocess) -sockets. If @code{filetype} is two-way, we assume that it is a socket! -Note that in the two-way case, the input and output file descriptors -may differ. To check for success, one must check whether either matches. + +On error, return a @code{false} value. Otherwise, return +@code{true}, and return additional information about the redirection +in the @code{ibufp} and @code{obufp} pointers. For input +redirections, the @code{*ibufp} value should be non-@code{NULL}, +and @code{*obufp} should be @code{NULL}. For output redirections, +the @code{*obufp} value should be non-@code{NULL}, and @code{*ibufp} +should be @code{NULL}. For two-way coprocesses, both values should +be non-@code{NULL}. + +In the usual case, the extension is interested in @code{(*ibufp)->fd} +and/or @code{fileno((*obufp)->fp)}. If the file is not already +open, and the @code{fd} argument is non-negative, @command{gawk} +will use that file descriptor instead of opening the file in the +usual way. If @code{fd} is non-negative, but the file exists already, +@command{gawk} ignores @code{fd} and returns the existing file. It is +the caller's responsibility to notice that neither the @code{fd} in +the returned @code{awk_input_buf_t} nor the @code{fd} in the returned +@code{awk_output_buf_t} matches the requested value. + +Note that supplying a file descriptor is currently @emph{not} supported +for pipes. However, supplying a file descriptor should work for input, +output, append, and two-way (coprocess) sockets. If @code{filetype} +is two-way, @command{gawk} assumes that it is a socket! Note that in +the two-way case, the input and output file descriptors may differ. +To check for success, you must check whether either matches. @end table It is anticipated that this API function will be used to implement I/O diff --git a/doc/gawktexi.in b/doc/gawktexi.in index eda9fc9d..7aa427aa 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -7715,7 +7715,7 @@ it encounters the end of the file. If there is some error in getting a record, such as a file that cannot be opened, then @code{getline} returns @minus{}1. In this case, @command{gawk} sets the variable @code{ERRNO} to a string describing the error that occurred. -If the @code{errno} variable indicates that the I/O operation may be +If @code{ERRNO} indicates that the I/O operation may be retried, and @code{PROCINFO["input", "RETRY"]} is set, then @minus{}2 will be returned instead of @minus{}1, and further calls to @code{getline} may be attemped. @DBXREF{Retrying Input} for further information about @@ -8393,26 +8393,26 @@ indefinitely until some other process opens it for writing. @cindex differences in @command{awk} and @command{gawk}, retrying input This @value{SECTION} describes a feature that is specific to @command{gawk}. -When @command{gawk} encounters an error while reading input, it will by default -return @minus{}1 from getline, and subsequent attempts to read from that file -will result in an end-of-file indication. However, you may optionally instruct -@command{gawk} to allow I/O to be retried when certain errors are encountered -by setting setting a special element -in the @code{PROCINFO} array (@pxref{Auto-set}): +When @command{gawk} encounters an error while reading input, by +default @code{getline} returns @minus{}1, and subsequent attempts to +read from that file result in an end-of-file indication. However, you +may optionally instruct @command{gawk} to allow I/O to be retried when +certain errors are encountered by setting setting a special element in +the @code{PROCINFO} array (@pxref{Auto-set}): @example -PROCINFO["input_name", "RETRY"] +PROCINFO["@var{input_name}", "RETRY"] = 1 @end example -When set, this causes @command{gawk} to check the value of the system +When this element exists, @command{gawk} checks the value of the system @code{errno} variable when an I/O error occurs. If @code{errno} indicates -a subsequent I/O attempt may succeed, @code{getline} will instead return +a subsequent I/O attempt may succeed, @code{getline} instead returns @minus{}2 and further calls to @code{getline} may succeed. This applies to @code{errno} -values EAGAIN, EWOULDBLOCK, EINTR, or ETIMEDOUT. +values @code{EAGAIN}, @code{EWOULDBLOCK}, @code{EINTR}, or @code{ETIMEDOUT}. This feature is useful in conjunction with -@code{PROCINFO["input_name", "READ_TIMEOUT"]} or situations where a file +@code{PROCINFO["@var{input_name}", "READ_TIMEOUT"]} or situations where a file descriptor has been configured to behave in a non-blocking fashion. @node Command-line directories @@ -32776,45 +32776,58 @@ The following function allows extensions to access and manipulate redirections. @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ int fd, @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ const awk_input_buf_t **ibufp, @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ const awk_output_buf_t **obufp); -Look up a file in @command{gawk}'s internal redirection table. If @code{name} is NULL or @code{name_len} is 0, it returns -data for the currently open input file corresponding to @code{FILENAME} -(and it will not access the @code{filetype} argument, so that may be -undefined). -If the file is not already open, it tries to open it. -The @code{filetype} argument must be NUL-terminated and should be one of: +Look up a file in @command{gawk}'s internal redirection table. +If @code{name} is @code{NULL} or @code{name_len} is zero, return +data for the currently open input file corresponding to @code{FILENAME}. +(This does not access the @code{filetype} argument, so that may be undefined). +If the file is not already open, attempt to open it. +The @code{filetype} argument must be zero-terminated and should be one of: + @table @code -@item > +@item ">" A file opened for output. -@item >> + +@item ">>" A file opened for append. -@item < + +@item "<" A file opened for input. -@item |> + +@item "|>" A pipe opened for output. -@item |< + +@item "|<" A pipe opened for input. -@item |& + +@item "|&" A two-way coprocess. @end table -On error, a @code{false} value is returned. Otherwise, the return status -is @code{true}, and additional information about the redirection is -returned in the @code{ibufp} and @code{obufp} pointers. For input redirections, -the @code{*ibufp} value should be non-NULL, and @code{*obufp} should be NULL. -For output redirections, -the @code{*obufp} value should be non-NULL, and @code{*ibufp} should be NULL. -For two-way coprocesses, both values should be non-NULL. In the usual case, -the extension is interested in @code{(*ibufp)->fd} and/or @code{fileno((*obufp)->fp)}. -If the file is not already open, and the fd argument is non-negative, -@command{gawk} will use that file descriptor instead of opening the file -in the usual way. If the fd is non-negative, but the file exists -already, @command{gawk} ignores the fd and returns the existing file. It is -the caller's responsibility to notice that neither the fd in the returned -@code{awk_input_buf_t} nor the fd in the returned @code{awk_output_buf_t} matches the requested value. Note that -supplying a file descriptor is currently NOT supported for pipes. -It should work for input, output, append, and two-way (coprocess) -sockets. If @code{filetype} is two-way, we assume that it is a socket! -Note that in the two-way case, the input and output file descriptors -may differ. To check for success, one must check whether either matches. + +On error, return a @code{false} value. Otherwise, return +@code{true}, and return additional information about the redirection +in the @code{ibufp} and @code{obufp} pointers. For input +redirections, the @code{*ibufp} value should be non-@code{NULL}, +and @code{*obufp} should be @code{NULL}. For output redirections, +the @code{*obufp} value should be non-@code{NULL}, and @code{*ibufp} +should be @code{NULL}. For two-way coprocesses, both values should +be non-@code{NULL}. + +In the usual case, the extension is interested in @code{(*ibufp)->fd} +and/or @code{fileno((*obufp)->fp)}. If the file is not already +open, and the @code{fd} argument is non-negative, @command{gawk} +will use that file descriptor instead of opening the file in the +usual way. If @code{fd} is non-negative, but the file exists already, +@command{gawk} ignores @code{fd} and returns the existing file. It is +the caller's responsibility to notice that neither the @code{fd} in +the returned @code{awk_input_buf_t} nor the @code{fd} in the returned +@code{awk_output_buf_t} matches the requested value. + +Note that supplying a file descriptor is currently @emph{not} supported +for pipes. However, supplying a file descriptor should work for input, +output, append, and two-way (coprocess) sockets. If @code{filetype} +is two-way, @command{gawk} assumes that it is a socket! Note that in +the two-way case, the input and output file descriptors may differ. +To check for success, you must check whether either matches. @end table It is anticipated that this API function will be used to implement I/O diff --git a/gawkapi.c b/gawkapi.c index 01bfa765..01ccdf2b 100644 --- a/gawkapi.c +++ b/gawkapi.c @@ -1044,42 +1044,48 @@ api_release_value(awk_ext_id_t id, awk_value_cookie_t value) /* api_get_file --- return a handle to an existing or newly opened file */ static awk_bool_t -api_get_file(awk_ext_id_t id, const char *name, size_t namelen, const char *filetype, int fd, const awk_input_buf_t **ibufp, const awk_output_buf_t **obufp) +api_get_file(awk_ext_id_t id, const char *name, size_t namelen, const char *filetype, + int fd, const awk_input_buf_t **ibufp, const awk_output_buf_t **obufp) { const struct redirect *f; int flag; /* not used, sigh */ enum redirval redirtype; - if ((name == NULL) || (namelen == 0)) { + if (name == NULL || namelen == 0) { if (curfile == NULL) { + INSTRUCTION *pc; + int save_rule; + char *save_source; + if (nextfile(& curfile, false) <= 0) return awk_false; - { - INSTRUCTION *pc = main_beginfile; - /* save execution state */ - int save_rule = currule; - char *save_source = source; - - while (1) { - if (!pc) - fatal(_("cannot find end of BEGINFILE rule")); - if (pc->opcode == Op_after_beginfile) - break; - pc = pc->nexti; - } - pc->opcode = Op_stop; - (void) (*interpret)(main_beginfile); - pc->opcode = Op_after_beginfile; - after_beginfile(& curfile); - /* restore execution state */ - currule = save_rule; - source = save_source; + + pc = main_beginfile; + /* save execution state */ + save_rule = currule; + save_source = source; + + while (1) { + if (!pc) + fatal(_("cannot find end of BEGINFILE rule")); + if (pc->opcode == Op_after_beginfile) + break; + pc = pc->nexti; } + pc->opcode = Op_stop; + (void) (*interpret)(main_beginfile); + pc->opcode = Op_after_beginfile; + after_beginfile(& curfile); + /* restore execution state */ + currule = save_rule; + source = save_source; } *ibufp = &curfile->public; *obufp = NULL; + return awk_true; } + redirtype = redirect_none; switch (filetype[0]) { case '<': @@ -1113,13 +1119,16 @@ api_get_file(awk_ext_id_t id, const char *name, size_t namelen, const char *file } break; } + if (redirtype == redirect_none) { warning(_("cannot open unrecognized file type `%s' for `%s'"), filetype, name); return awk_false; } + if ((f = redirect_string(name, namelen, 0, redirtype, &flag, fd, false)) == NULL) return awk_false; + *ibufp = f->iop ? & f->iop->public : NULL; *obufp = f->output.fp ? & f->output : NULL; return awk_true; diff --git a/io.c b/io.c index 5f977355..4dbe16fb 100644 --- a/io.c +++ b/io.c @@ -724,7 +724,7 @@ redflags2str(int flags) return genflags2str(flags, redtab); } -/* redirect --- Redirection for printf and print commands */ +/* redirect_string --- Redirection for printf and print commands, use string info */ struct redirect * redirect_string(const char *str, size_t explen, bool not_string, @@ -1065,6 +1065,8 @@ redirect_string(const char *str, size_t explen, bool not_string, return rp; } +/* redirect --- Redirection for printf and print commands */ + struct redirect * redirect(NODE *redir_exp, int redirtype, int *errflg, bool failure_fatal) { @@ -2303,7 +2305,7 @@ wait_any(int interesting) /* pid of interest, if any */ break; } } -#else +#else /* ! __MINGW32__ */ #ifndef HAVE_SIGPROCMASK hstat = signal(SIGHUP, SIG_IGN); qstat = signal(SIGQUIT, SIG_IGN); @@ -2340,7 +2342,7 @@ wait_any(int interesting) /* pid of interest, if any */ signal(SIGHUP, hstat); signal(SIGQUIT, qstat); #endif -#endif +#endif /* ! __MINGW32__ */ #ifndef HAVE_SIGPROCMASK signal(SIGINT, istat); #else @@ -3509,14 +3511,15 @@ find_longest_terminator: return REC_OK; } -/* return true if PROCINFO[, "RETRY"] exists */ +/* retryable --- return true if PROCINFO[, "RETRY"] exists */ + static inline int retryable(IOBUF *iop) { return PROCINFO_node && in_PROCINFO(iop->public.name, "RETRY", NULL); } -/* Does the I/O error indicate that the operation should be retried later? */ +/* errno_io_retry --- Does the I/O error indicate that the operation should be retried later? */ static inline int errno_io_retry(void) -- cgit v1.2.1