diff options
Diffstat (limited to 'doc/gawk.texi')
| -rw-r--r-- | doc/gawk.texi | 115 |
1 files changed, 114 insertions, 1 deletions
diff --git a/doc/gawk.texi b/doc/gawk.texi index 457a20f2..cc215c6a 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -603,6 +603,7 @@ particular records in a file and perform operations upon them. @code{getline}. * Getline Summary:: Summary of @code{getline} Variants. * Read Timeout:: Reading input with a timeout. +* Retrying Input:: Retrying input after certain errors. * Command-line directories:: What happens if you put a directory on the command line. * Input Summary:: Input summary. @@ -943,6 +944,7 @@ particular records in a file and perform operations upon them. * Array Functions:: Functions for working with arrays. * Flattening Arrays:: How to flatten arrays. * Creating Arrays:: How to create and populate arrays. +* Redirection API:: How to access and manipulate redirections. * Extension API Variables:: Variables provided by the API. * Extension Versioning:: API Version information. * Extension API Informational Variables:: Variables providing information about @@ -6318,6 +6320,7 @@ used with it do not have to be named on the @command{awk} command line * Getline:: Reading files under explicit program control using the @code{getline} function. * Read Timeout:: Reading input with a timeout. +* Retrying Input:: Retrying input after certain errors. * Command-line directories:: What happens if you put a directory on the command line. * Input Summary:: Input summary. @@ -8103,6 +8106,11 @@ 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 +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 +this feature. In the following examples, @var{command} stands for a string value that represents a shell command. @@ -8758,7 +8766,8 @@ on a per-command or per-connection basis. the attempt to read from the underlying device may succeed in a later attempt. This is a limitation, and it also means that you cannot use this to multiplex input from -two or more sources. +two or more sources. @DBXREF{Retrying Input} for a way to enable +later I/O attempts to succeed. Assigning a timeout value prevents read operations from blocking indefinitely. But bear in mind that there are other ways @@ -8768,6 +8777,35 @@ a connection before it can start reading any data, or the attempt to open a FIFO special file for reading can block indefinitely until some other process opens it for writing. +@node Retrying Input +@section Retrying Reads After Certain Input Errors +@cindex retrying input + +@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}): + +@example +PROCINFO["input_name", "RETRY"] +@end example + +When set, this causes @command{gawk} to check 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 +@minus{}2 and +further calls to @code{getline} may succeed. This applies to @code{errno} +values EAGAIN, EWOULDBLOCK, EINTR, or ETIMEDOUT. + +This feature is useful in conjunction with +@code{PROCINFO["input_name", "READ_TIMEOUT"]} or situations where a file +descriptor has been configured to behave in a non-blocking fashion. + @node Command-line directories @section Directories on the Command Line @cindex differences in @command{awk} and @command{gawk}, command-line directories @@ -14841,6 +14879,11 @@ value to be meaningful when an I/O operation returns a failure value, such as @code{getline} returning @minus{}1. You are, of course, free to clear it yourself before doing an I/O operation. +If the value of @code{ERRNO} corresponds to a system error in the C +@code{errno} variable, then @code{PROCINFO["errno"]} will be set to the value +of @code{errno}. For non-system errors, @code{PROCINFO["errno"]} will +be zero. + @cindex @code{FILENAME} variable @cindex dark corner, @code{FILENAME} variable @item @code{FILENAME} @@ -14909,6 +14952,10 @@ are guaranteed to be available: @item PROCINFO["egid"] The value of the @code{getegid()} system call. +@item PROCINFO["errno"] +The value of the C @code{errno} variable when @code{ERRNO} is set to +the associated error message. + @item PROCINFO["euid"] @cindex effective user ID of @command{gawk} user The value of the @code{geteuid()} system call. @@ -15048,6 +15095,11 @@ open input file, pipe, or coprocess. @DBXREF{Read Timeout} for more information. @item +It may be used to indicate that input may be retried when it fails due to +certain errors. +@DBXREF{Retrying Input} for more information. + +@item It may be used to cause coprocesses to communicate over pseudo-ttys instead of through two-way pipes; this is discussed further in @ref{Two-way I/O}. @@ -31465,6 +31517,7 @@ This (rather large) @value{SECTION} describes the API in detail. * Symbol Table Access:: Functions for accessing global variables. * Array Manipulation:: Functions for working with arrays. +* Redirection API:: How to access and manipulate redirections. * Extension API Variables:: Variables provided by the API. * Extension API Boilerplate:: Boilerplate code for using the API. @end menu @@ -31540,6 +31593,10 @@ Clearing an array @item Flattening an array for easy C style looping over all its indices and elements @end itemize + +@item +Accessing and manipulating redirections. + @end itemize Some points about using the API: @@ -33504,6 +33561,62 @@ $ @kbd{AWKLIBPATH=$PWD ./gawk -f subarray.awk} (@DBXREF{Finding Extensions} for more information on the @env{AWKLIBPATH} environment variable.) +@node Redirection API +@subsection Accessing and Manipulating Redirections + +The following function allows extensions to access and manipulate redirections. + +@table @code +@item awk_bool_t get_file(const char *name, +@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ size_t name_len, +@itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ const char *filetype, +@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: +@table @code +@item > +A file opened for output. +@item >> +A file opened for append. +@item < +A file opened for input. +@item |> +A pipe opened for output. +@item |< +A pipe opened for input. +@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. +@end table + +It is anticipated that this API function will be used to implement I/O +multiplexing and a socket library. + @node Extension API Variables @subsection API Variables |