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