Redirection API (The GNU Awk User’s Guide)
Next: Extension API Variables, Previous: Array Manipulation, Up: Extension API Description [Contents][Index]
17.4.12 Accessing and Manipulating Redirections
The following function allows extensions to access and manipulate redirections.
awk_bool_t get_file(const char *name,
size_t name_len,
const char *filetype,
int fd,
const awk_input_buf_t **ibufp,
const awk_output_buf_t **obufp);
Look up file
name
ingawk
’s internal redirection table. Ifname
isNULL
orname_len
is zero, return data for the currently open input file corresponding toFILENAME
. (This does not access thefiletype
argument, so that may be undefined). If the file is not already open, attempt to open it. Thefiletype
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, return
awk_false
. Otherwise, returnawk_true
, and return additional information about the redirection in theibufp
andobufp
pointers.For input redirections, the
*ibufp
value should be non-NULL
, and*obufp
should beNULL
. For output redirections, the*obufp
value should be non-NULL
, and*ibufp
should beNULL
. For two-way coprocesses, both values should be non-NULL
.In the usual case, the extension is interested in
(*ibufp)->fd
and/orfileno((*obufp)->fp)
. If the file is not already open, and thefd
argument is nonnegative,gawk
will use that file descriptor instead of opening the file in the usual way. Iffd
is nonnegative, but the file exists already,gawk
ignoresfd
and returns the existing file. It is the caller’s responsibility to notice that neither thefd
in the returnedawk_input_buf_t
nor thefd
in the returnedawk_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.
Next: Extension API Variables, Previous: Array Manipulation, Up: Extension API Description [Contents][Index]