gawk: Redirection API

1 
1 16.4.12 Accessing and Manipulating Redirections
1 -----------------------------------------------
1 
1 The following function allows extensions to access and manipulate
1 redirections.
1 
1 'awk_bool_t get_file(const char *name,'
1 '                    size_t name_len,'
1 '                    const char *filetype,'
1 '                    int fd,'
1 '                    const awk_input_buf_t **ibufp,'
1 '                    const awk_output_buf_t **obufp);'
1      Look up file 'name' in 'gawk''s internal redirection table.  If
1      'name' is 'NULL' or 'name_len' is zero, return data for the
1      currently open input file corresponding to 'FILENAME'.  (This does
1      not access the 'filetype' argument, so that may be undefined).  If
1      the file is not already open, attempt to open it.  The 'filetype'
1      argument must be zero-terminated and should be one of:
1 
1      '">"'
1           A file opened for output.
1 
1      '">>"'
1           A file opened for append.
1 
1      '"<"'
1           A file opened for input.
1 
1      '"|>"'
1           A pipe opened for output.
1 
1      '"|<"'
1           A pipe opened for input.
1 
1      '"|&"'
1           A two-way coprocess.
1 
1      On error, return 'awk_false'.  Otherwise, return 'awk_true', and
1      return additional information about the redirection in the 'ibufp'
1      and 'obufp' pointers.
1 
1      For input redirections, the '*ibufp' value should be non-'NULL',
1      and '*obufp' should be 'NULL'.  For output redirections, the
1      '*obufp' value should be non-'NULL', and '*ibufp' should be 'NULL'.
1      For two-way coprocesses, both values should be non-'NULL'.
1 
1      In the usual case, the extension is interested in '(*ibufp)->fd'
1      and/or 'fileno((*obufp)->fp)'.  If the file is not already open,
1      and the 'fd' argument is nonnegative, 'gawk' will use that file
1      descriptor instead of opening the file in the usual way.  If 'fd'
1      is nonnegative, but the file exists already, 'gawk' ignores 'fd'
1      and returns the existing file.  It is the caller's responsibility
1      to notice that neither the 'fd' in the returned 'awk_input_buf_t'
1      nor the 'fd' in the returned 'awk_output_buf_t' matches the
1      requested value.
1 
1      Note that supplying a file descriptor is currently _not_ supported
1      for pipes.  However, supplying a file descriptor should work for
1      input, output, append, and two-way (coprocess) sockets.  If
1      'filetype' is two-way, 'gawk' assumes that it is a socket!  Note
1      that in the two-way case, the input and output file descriptors may
1      differ.  To check for success, you must check whether either
1      matches.
1 
1    It is anticipated that this API function will be used to implement
1 I/O multiplexing and a socket library.
1