1SELECT(3am) GNU Awk Extension Modules SELECT(3am)
2
6 select - gawk extension to enable I/O multiplexing, non-blocking I/O,
7 and signal trapping
8
10 @load "select"
11 result = kill(<pid>, <signal number or name>)
12 string = select_signal(<signal number or name>, {default|ignore|trap} [, <override>])
13 fd = input_fd(<file or command> [, <redirection type>])
14 fd = output_fd(<file or command>, <redirection type>)
15 result = set_non_blocking(<file or command or fd number> [, <redirection type>])
16 result = select(<readfds>, <writefds>, <exceptfds> [, <timeout> [, <signals>]])
17
19 The select extension adds six functions as follows:
20 kill() This function calls kill(2) to send a signal to a process. The
22 second argument may be specified as an integer or as a standard
23 signal name defined on this system. The names are not case-sen‐
24 sitive, and the leading "SIG" is optional. It returns the value
25 returned by the kill(2) system call. If the return code is neg‐
26 ative, it updates ERRNO.
27 select_signal()
29 This function uses sigaction(2) to change signal actions. The
30 first signal argument may be specified as an integer or as a
31 standard signal name defined on this system. The names are not
32 case-sensitive, and the leading "SIG" is optional. The second
33 argument must be a string equal to "default", "ignore", or
34 "trap". If the previously installed handler is the default han‐
35 dler or "ignore", or our standard trapping handler, then the new
36 value is installed. If the previous handler is not recognized,
37 then the new handler is not installed unless the third override
38 argument is present, is numeric, and is non-zero. This function
39 returns "" on error, otherwise a string describing the previ‐
40 ously installed handler: "default", "ignore", "trap", or "un‐
41 known". Any trapped signals will be reported synchronously in
42 the results from the select() function.
43 input_fd()
45 Look up the file or command and return the associated input file
46 descriptor value or -1 on error. The file or command will be
47 opened or started if gawk has not done so previously. If the
48 first argument is "", then it returns the fd for the currently
49 open file corresponding to FILENAME. Otherwise, the second ar‐
50 gument is required and must have one of the following values:
51 ">" a file opened for output;
53 ">>" a file opened for append;
55 "<" a file opened for input;
57 "|>" a pipe used for output;
59 "|<" a pipe used for input;
61 "|&" a two-way coprocess.
63 output_fd()
65 This is similar to input_fd() but returns a file descriptor
66 suitable for output. Note that gawk may choose to use a differ‐
67 ent file descriptor for coprocess input and output. For this
68 function, two arguments are required. On error, -1 is returned.
69 set_non_blocking()
71 If the first argument is "", then the second argument is not re‐
72 quired, and the currently open file corresponding to FILENAME
73 will be set to non-blocking by using fcntl(2) to turn on O_NON‐
74 BLOCK. Similarly, if the first argument is numeric, we simply
75 set that file descriptor to be non-blocking. Otherwise, we look
76 up the <file or command> and <redirection type>. This returns 0
77 on success or -1 on error. If this argument is a two-way copro‐
78 cess that defines different input and output file descriptors,
79 we set the input side to be non-blocking. For finer control,
80 please use input_fd() or output_fd() to specify which file de‐
81 scriptor to configure for non-blocking behavior. If the first
82 argument is a name and not a file descriptor, and we are able to
83 configure non-blocking mode successfully, and it is not an out‐
84 put-only file, we also automatically create the array entry
85 PROCINFO[<file or command>, "RETRY"] so that I/O will automati‐
86 cally be retried for input from this file.
87 select()
89 This function returns -1 on error or the number of file descrip‐
90 tors that matched. On return, the <signals> array, if supplied,
91 contains a list of signals that were trapped since the last
92 call. The index is the signal number, and the value will be the
93 symbolic signal name (e.g. "INT") if we are able to look it up.
94 If <timeout> is present and numeric, that is the maximum number
95 of seconds to wait. Otherwise, it will block indefinitely. The
96 <readfds>, <writefds>, and <exceptfds> arrays will have the
97 <command> in the index, and the <command type> as the value.
98 This works the same way as the set_non_blocking function. If
99 the index value is numeric and the value is "", it will be
100 treated as a file descriptor.
101
103 One note regarding signal behavior: the extension uses sigaction(2) to
104 request that signal calls be restarted. But on Linux, the "select" is
105 always interrupted in any case. So that's nice—the signals get deliv‐
106 ered quickly. On Cygwin, I noticed that select does seem to restart,
107 so the signal is not delivered to the application right away.
108
110 Please refer to multiplex.awk and multiplex2.awk which are included in
111 the distribution.
112
114 kill(2), sigaction(2), select(2), fcntl(2)
115
117 Andrew Schorr
118
120 Copyright © 2012, 2013, Free Software Foundation, Inc.
121 Permission is granted to make and distribute verbatim copies of this
123 manual page provided the copyright notice and this permission notice
124 are preserved on all copies.
125 Permission is granted to copy and distribute modified versions of this
127 manual page under the conditions for verbatim copying, provided that
128 the entire resulting derived work is distributed under the terms of a
129 permission notice identical to this one.
130 Permission is granted to copy and distribute translations of this man‐
132 ual page into another language, under the above conditions for modified
133 versions, except that this permission notice may be stated in a trans‐
134 lation approved by the Foundation.
135Free Software Foundation Jan 15 2013 SELECT(3am)