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