1docs::api::APR::Socket(U3s)er Contributed Perl Documentatdioocns::api::APR::Socket(3)
2
3
4
6 APR::Socket - Perl API for APR sockets
7
9 use APR::Socket ();
10
11 ### set the socket to the blocking mode if it isn't already
12 ### and read in the loop and echo it back
13 use APR::Const -compile => qw(SO_NONBLOCK);
14 if ($sock->opt_get(APR::Const::SO_NONBLOCK)) {
15 $sock->opt_set(APR::Const::SO_NONBLOCK => 0);
16 }
17 # read from/write to the socket (w/o handling possible failures)
18 my $wanted = 1024;
19 while ($sock->recv(my $buff, $wanted)) {
20 $sock->send($buff);
21 }
22
23 ### get/set IO timeout and try to read some data
24 use APR::Const -compile => qw(TIMEUP);
25 # timeout is in usecs!
26 my $timeout = $sock->timeout_get();
27 if ($timeout < 10_000_000) {
28 $sock->timeout_set(20_000_000); # 20 secs
29 }
30 # now read, while handling timeouts
31 my $wanted = 1024;
32 my $buff;
33 my $rlen = eval { $sock->recv($buff, $wanted) };
34 if ($@ && ref $@ && $@ == APR::Const::TIMEUP) {
35 # timeout, do something, e.g.
36 warn "timed out, will try again later";
37 }
38 else {
39 warn "asked for $wanted bytes, read $rlen bytes\n";
40 # do something with the data
41 }
42
43 # non-blocking io poll
44 $sock->opt_set(APR::Const::SO_NONBLOCK => 1);
45 my $rc = $sock->poll($c->pool, 1_000_000, APR::Const::POLLIN);
46 if ($rc == APR::Const::SUCCESS) {
47 # read the data
48 }
49 else {
50 # handle the condition
51 }
52
53 # fetch the operating level socket
54 my $fd=$sock->fileno;
55
57 "APR::Socket" provides the Perl interface to APR sockets.
58
60 "APR::Socket" provides the following methods:
61
62 "fileno"
63 Get the operating system socket, the file descriptor on UNIX.
64
65 $fd = $sock->fileno;
66
67 obj: $sock ( "APR::Socket object" )
68 The socket
69
70 ret: $fd ( integer )
71 The OS-level file descriptor.
72
73 since: 2.0.5 (not implemented on Windows)
74
75 "opt_get"
76 Query socket options for the specified socket
77
78 $val = $sock->opt_get($opt);
79
80 obj: $sock ( "APR::Socket object" )
81 the socket object to query
82
83 arg1: $opt ( "APR::Const constant" )
84 the socket option we would like to configure. Here are the
85 available socket options.
86
87 ret: $val ( integer )
88 the currently set value for the socket option you've queried for
89
90 excpt: "APR::Error"
91 since: 2.0.00
92
93 Examples can be found in the socket options constants section. For
94 example setting the IO to the blocking mode.
95
96 "opt_set"
97 Setup socket options for the specified socket
98
99 $sock->opt_set($opt, $val);
100
101 obj: $sock ( "APR::Socket object" object )
102 the socket object to set up.
103
104 arg1: $opt ( "APR::Const" constant )
105 the socket option we would like to configure. Here are the
106 available socket options.
107
108 arg2: $val ( integer )
109 value for the option. Refer to the socket options section to learn
110 about the expected values.
111
112 ret: no return value
113 excpt: "APR::Error"
114 since: 2.0.00
115
116 Examples can be found in the socket options constants section. For
117 example setting the IO to the blocking mode.
118
119 "poll"
120 Poll the socket for events:
121
122 $rc = $sock->poll($pool, $timeout, $events);
123
124 obj: $sock ( "APR::Socket object" )
125 The socket to poll
126
127 arg1: $pool ( "APR::Pool object" )
128 usually "$c->pool".
129
130 arg2: $timeout ( integer )
131 The amount of time to wait (in milliseconds) for the specified
132 events to occur.
133
134 arg3: $events ( "APR::Const :poll constants" )
135 The events for which to wait.
136
137 For example use "APR::Const::POLLIN" to wait for incoming data to
138 be available, "APR::Const::POLLOUT" to wait until it's possible to
139 write data to the socket and "APR::Const::POLLPRI" to wait for
140 priority data to become available.
141
142 ret: $rc ( "APR::Const constant" )
143 If "APR::Const::SUCCESS" is received than the polling was
144 successful. If not -- the error code is returned, which can be
145 converted to the error string with help of "APR::Error::strerror".
146
147 since: 2.0.00
148
149 For example poll a non-blocking socket up to 1 second when reading data
150 from the client:
151
152 use APR::Socket ();
153 use APR::Connection ();
154 use APR::Error ();
155
156 use APR::Const -compile => qw(SO_NONBLOCK POLLIN SUCCESS TIMEUP);
157
158 $sock->opt_set(APR::Const::SO_NONBLOCK => 1);
159
160 my $rc = $sock->poll($c->pool, 1_000_000, APR::Const::POLLIN);
161 if ($rc == APR::Const::SUCCESS) {
162 # Data is waiting on the socket to be read.
163 # $sock->recv(my $buf, BUFF_LEN)
164 }
165 elsif ($rc == APR::Const::TIMEUP) {
166 # One second elapsed and still there is no data waiting to be
167 # read. for example could try again.
168 }
169 else {
170 die "poll error: " . APR::Error::strerror($rc);
171 }
172
173 "recv"
174 Read incoming data from the socket
175
176 $len = $sock->recv($buffer, $wanted);
177
178 obj: $sock ( "APR::SockAddr object" object )
179 The socket to read from
180
181 arg1: $buffer ( SCALAR )
182 The buffer to fill. All previous data will be lost.
183
184 arg2: $wanted ( int )
185 How many bytes to attempt to read.
186
187 ret: $len ( number )
188 How many bytes were actually read.
189
190 $buffer gets populated with the string that is read. It will
191 contain an empty string if there was nothing to read.
192
193 excpt: "APR::Error"
194 If you get the '(11) Resource temporarily unavailable' error
195 (exception "APR::Const::EAGAIN") (or another equivalent, which
196 might be different on non-POSIX systems), then you didn't ensure
197 that the socket is in a blocking IO mode before using it. Note that
198 you should use "APR::Status::is_EAGAIN" to perform this check
199 (since different error codes may be returned for the same event on
200 different OSes). For example if the socket is set to the non-
201 blocking mode and there is no data right away, you may get this
202 exception thrown. So here is how to check for it and retry a few
203 times after short delays:
204
205 use APR::Status ();
206 $sock->opt_set(APR::Const::SO_NONBLOCK, 1);
207 # ....
208 my $tries = 0;
209 my $buffer;
210 RETRY: my $rlen = eval { $socket->recv($buffer, SIZE) };
211 if ($@)
212 die $@ unless ref $@ && APR::Status::is_EAGAIN($@);
213 if ($tries++ < 3) {
214 # sleep 250msec
215 select undef, undef, undef, 0.25;
216 goto RETRY;
217 }
218 else {
219 # do something else
220 }
221 }
222 warn "read $rlen bytes\n"
223
224 If timeout was set via "timeout_set|/C_timeout_set_", you may need
225 to catch the "APR::Const::TIMEUP" exception. For example:
226
227 use APR::Const -compile => qw(TIMEUP);
228 $sock->timeout_set(1_000_000); # 1 sec
229 my $buffer;
230 eval { $sock->recv($buffer, $wanted) };
231 if ($@ && $@ == APR::Const::TIMEUP) {
232 # timeout, do something, e.g.
233 }
234
235 If not handled -- you may get the error '70007: The timeout
236 specified has expired'.
237
238 Another error condition that may occur is the '(104) Connection
239 reset by peer' error, which is up to your application logic to
240 decide whether it's an error or not. This error usually happens
241 when the client aborts the connection.
242
243 use APR::Const -compile => qw(ECONNABORTED);
244 my $buffer;
245 eval { $sock->recv($buffer, $wanted) };
246 if ($@ == APR::Const::ECONNABORTED) {
247 # ignore it or deal with it
248 }
249
250 since: 2.0.00
251
252 Here is the quick prototype example, which doesn't handle any errors
253 (mod_perl will do that for you):
254
255 use APR::Socket ();
256
257 # set the socket to the blocking mode if it isn't already
258 use APR::Const -compile => qw(SO_NONBLOCK);
259 if ($sock->opt_get(APR::Const::SO_NONBLOCK)) {
260 $sock->opt_set(APR::Const::SO_NONBLOCK => 0);
261 }
262 # read from/write to the socket (w/o handling possible failures)
263 my $wanted = 1024;
264 while ($sock->recv(my $buffer, $wanted)) {
265 $sock->send($buffer);
266 }
267
268 If you want to handle errors by yourself, the loop may look like:
269
270 use APR::Const -compile => qw(ECONNABORTED);
271 # ...
272 while (1) {
273 my $buf;
274 my $len = eval { $sock->recv($buf, $wanted) };
275 if ($@) {
276 # handle the error, e.g. to ignore aborted connections but
277 # rethrow any other errors:
278 if ($@ == APR::Const::ECONNABORTED) {
279 # ignore
280 last;
281 }
282 else {
283 die $@; # retrow
284 }
285 }
286
287 if ($len) {
288 $sock->send($buffer);
289 }
290 else {
291 last;
292 }
293 }
294
295 "send"
296 Write data to the socket
297
298 $wlen = $sock->send($buf, $opt_len);
299
300 obj: $sock ( "APR::Socket object" )
301 The socket to write to
302
303 arg1: $buf ( scalar )
304 The data to send
305
306 opt arg2: $opt_len ( int )
307 There is no need to pass this argument, unless you want to send
308 less data than contained in $buf.
309
310 ret: $wlen ( integer )
311 How many bytes were sent
312
313 since: 2.0.00
314
315 For examples see the "recv" item.
316
317 "timeout_get"
318 Get socket timeout settings
319
320 $usecs = $sock->timeout_get();
321
322 obj: $sock ( "APR::Socket object" )
323 The socket to set up.
324
325 ret: $usecs ( number)
326 Currently set timeout in microseconds (and also the blocking IO
327 behavior). See ("APR::timeout_set") for possible values and their
328 meaning.
329
330 excpt: "APR::Error"
331 since: 2.0.00
332
333 "timeout_set"
334 Setup socket timeout.
335
336 $sock->timeout_set($usecs);
337
338 obj: $sock ( "APR::Socket object" )
339 The socket to set up.
340
341 arg1: $usecs ( number )
342 Value for the timeout in microseconds and also the blocking IO
343 behavior.
344
345 The possible values are:
346
347 t > 0
348 "send()" and "recv()" throw ("APR::Const::TIMEUP" exception) if
349 specified time elapses with no data sent or received.
350
351 Notice that the positive value is in micro seconds. So if you
352 want to set the timeout for 5 seconds, the value should be:
353 5_000_000.
354
355 This mode sets the socket into a non-blocking IO mode.
356
357 t == 0
358 "send()" and "recv()" calls never block.
359
360 t < 0
361 "send()" and "recv()" calls block.
362
363 Usually just -1 is used for this case, but any negative value
364 will do.
365
366 This mode sets the socket into a blocking IO mode.
367
368 ret: no return value
369 excpt: "APR::Error"
370 since: 2.0.00
371
373 "APR::Socket" also provides auto-generated Perl interface for a few
374 other methods which aren't tested at the moment and therefore their API
375 is a subject to change. These methods will be finalized later as a need
376 arises. If you want to rely on any of the following methods please
377 contact the the mod_perl development mailing list so we can help each
378 other take the steps necessary to shift the method to an officially
379 supported API.
380
381 "bind"
382 META: Autogenerated - needs to be reviewed/completed
383
384 Bind the socket to its associated port
385
386 $ret = $sock->bind($sa);
387
388 obj: $sock ( "APR::Socket object" )
389 The socket to bind
390
391 arg1: $sa ( "APR::SockAddr object" )
392 The socket address to bind to
393
394 ret: $ret ( integer )
395 since: subject to change
396
397 This may be where we will find out if there is any other process using
398 the selected port.
399
400 "close"
401 META: Autogenerated - needs to be reviewed/completed
402
403 Close a socket.
404
405 $ret = $sock->close();
406
407 obj: $sock ( "APR::Socket object" )
408 The socket to close
409
410 ret: $ret ( integer )
411 since: subject to change
412
413 "connect"
414 META: Autogenerated - needs to be reviewed/completed
415
416 Issue a connection request to a socket either on the same machine or a
417 different one.
418
419 $ret = $sock->connect($sa);
420
421 obj: $sock ( "APR::Socket object" )
422 The socket we wish to use for our side of the connection
423
424 arg1: $sa ( "APR::SockAddr object" )
425 The address of the machine we wish to connect to. If NULL, APR
426 assumes that the sockaddr_in in the apr_socket is completely filled
427 out.
428
429 ret: $ret ( integer )
430 since: subject to change
431
432 "listen"
433 META: Autogenerated - needs to be reviewed/completed
434
435 Listen to a bound socket for connections.
436
437 $ret = $sock->listen($backlog);
438
439 obj: $sock ( "APR::Socket object" )
440 The socket to listen on
441
442 arg1: $backlog ( integer )
443 The number of outstanding connections allowed in the sockets listen
444 queue. If this value is less than zero, the listen queue size is
445 set to zero.
446
447 ret: $ret ( integer )
448 since: subject to change
449
450 "recvfrom"
451 META: Autogenerated - needs to be reviewed/completed
452
453 $ret = $from->recvfrom($sock, $flags, $buf, $len);
454
455 obj: $from ( "APR::SockAddr object" )
456 The apr_sockaddr_t to fill in the recipient info
457
458 arg1: $sock ( "APR::SockAddr object" )
459 The socket to use
460
461 arg2: $flags ( integer )
462 The flags to use
463
464 arg3: $buf ( integer )
465 The buffer to use
466
467 arg4: $len ( string )
468 The length of the available buffer
469
470 ret: $ret ( integer )
471 since: subject to change
472
473 "sendto"
474 META: Autogenerated - needs to be reviewed/completed
475
476 $ret = $sock->sendto($where, $flags, $buf, $len);
477
478 obj: $sock ( "APR::Socket object" )
479 The socket to send from
480
481 arg1: $where ( "APR::Socket object" )
482 The apr_sockaddr_t describing where to send the data
483
484 arg2: $flags ( integer )
485 The flags to use
486
487 arg3: $buf ( scalar )
488 The data to send
489
490 arg4: $len ( string )
491 The length of the data to send
492
493 ret: $ret ( integer )
494 since: subject to change
495
497 mod_perl 2.0 documentation.
498
500 mod_perl 2.0 and its core modules are copyrighted under The Apache
501 Software License, Version 2.0.
502
504 The mod_perl development team and numerous contributors.
505
506
507
508perl v5.30.1 2020-01-29 docs::api::APR::Socket(3)