1docs::api::APR::Socket(U3s)er Contributed Perl Documentatdioocns::api::APR::Socket(3)
2
6 APR::Socket - Perl API for APR sockets
7
9 use APR::Socket ();
10 ### 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 ### 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 # 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
54 "APR::Socket" provides the Perl interface to APR sockets.
55
57 "APR::Socket" provides the following methods:
58 "opt_get"
60 Query socket options for the specified socket
62 $val = $sock->opt_get($opt);
64 obj: $sock ( "APR::Socket object" )
66 the socket object to query
67 arg1: $opt ( "APR::Const constant" )
69 the socket option we would like to configure. Here are the avail‐
70 able socket options.
71 ret: $val ( integer )
73 the currently set value for the socket option you've queried for
74 excpt: "APR::Error"
76 since: 2.0.00
77 Examples can be found in the socket options constants section. For
79 example setting the IO to the blocking mode.
80 "opt_set"
82 Setup socket options for the specified socket
84 $sock->opt_set($opt, $val);
86 obj: $sock ( "APR::Socket object" object )
88 the socket object to set up.
89 arg1: $opt ( "APR::Const" constant )
91 the socket option we would like to configure. Here are the avail‐
92 able socket options.
93 arg2: $val ( integer )
95 value for the option. Refer to the socket options section to learn
96 about the expected values.
97 ret: no return value
99 excpt: "APR::Error"
100 since: 2.0.00
101 Examples can be found in the socket options constants section. For
103 example setting the IO to the blocking mode.
104 "poll"
106 Poll the socket for events:
108 $rc = $sock->poll($pool, $timeout, $events);
110 obj: $sock ( "APR::Socket object" )
112 The socket to poll
113 arg1: $pool ( "APR::Pool object" )
115 usually "$c->pool".
116 arg2: $timeout ( integer )
118 The amount of time to wait (in milliseconds) for the specified
119 events to occur.
120 arg3: $events ( "APR::Const :poll constants" )
122 The events for which to wait.
123 For example use "APR::Const::POLLIN" to wait for incoming data to
125 be available, "APR::Const::POLLOUT" to wait until it's possible to
126 write data to the socket and "APR::Const::POLLPRI" to wait for pri‐
127 ority data to become available.
128 ret: $rc ( "APR::Const constant" )
130 If "APR::Const::SUCCESS" is received than the polling was success‐
131 ful. If not -- the error code is returned, which can be converted
132 to the error string with help of "APR::Error::strerror".
133 since: 2.0.00
135 For example poll a non-blocking socket up to 1 second when reading data
137 from the client:
138 use APR::Socket ();
140 use APR::Connection ();
141 use APR::Error ();
142 use APR::Const -compile => qw(SO_NONBLOCK POLLIN SUCCESS TIMEUP);
144 $sock->opt_set(APR::Const::SO_NONBLOCK => 1);
146 my $rc = $sock->poll($c->pool, 1_000_000, APR::Const::POLLIN);
148 if ($rc == APR::Const::SUCCESS) {
149 # Data is waiting on the socket to be read.
150 # $sock->recv(my $buf, BUFF_LEN)
151 }
152 elsif ($rc == APR::Const::TIMEUP) {
153 # One second elapsed and still there is no data waiting to be
154 # read. for example could try again.
155 }
156 else {
157 die "poll error: " . APR::Error::strerror($rc);
158 }
159 "recv"
161 Read incoming data from the socket
163 $len = $sock->recv($buffer, $wanted);
165 obj: $sock ( "APR::SockAddr object" object )
167 The socket to read from
168 arg1: $buffer ( SCALAR )
170 The buffer to fill. All previous data will be lost.
171 arg2: $wanted ( int )
173 How many bytes to attempt to read.
174 ret: $len ( number )
176 How many bytes were actually read.
177 $buffer gets populated with the string that is read. It will con‐
179 tain an empty string if there was nothing to read.
180 excpt: "APR::Error"
182 If you get the '(11) Resource temporarily unavailable' error
183 (exception "APR::Const::EAGAIN") (or another equivalent, which
184 might be different on non-POSIX systems), then you didn't ensure
185 that the socket is in a blocking IO mode before using it. Note that
186 you should use "APR::Status::is_EAGAIN" to perform this check
187 (since different error codes may be returned for the same event on
188 different OSes). For example if the socket is set to the non-block‐
189 ing mode and there is no data right away, you may get this excep‐
190 tion thrown. So here is how to check for it and retry a few times
191 after short delays:
192 use APR::Status ();
194 $sock->opt_set(APR::Const::SO_NONBLOCK, 1);
195 # ....
196 my $tries = 0;
197 my $buffer;
198 RETRY: my $rlen = eval { $socket->recv($buffer, SIZE) };
199 if ($@)
200 die $@ unless ref $@ && APR::Status::is_EAGAIN($@);
201 if ($tries++ < 3) {
202 # sleep 250msec
203 select undef, undef, undef, 0.25;
204 goto RETRY;
205 }
206 else {
207 # do something else
208 }
209 }
210 warn "read $rlen bytes\n"
211 If timeout was set via "timeout_set⎪/C_timeout_set_", you may need
213 to catch the "APR::Const::TIMEUP" exception. For example:
214 use APR::Const -compile => qw(TIMEUP);
216 $sock->timeout_set(1_000_000); # 1 sec
217 my $buffer;
218 eval { $sock->recv($buffer, $wanted) };
219 if ($@ && $@ == APR::Const::TIMEUP) {
220 # timeout, do something, e.g.
221 }
222 If not handled -- you may get the error "'70007: The timeout speci‐
224 fied has expired'".
225 Another error condition that may occur is the "'(104) Connection
227 reset by peer'" error, which is up to your application logic to
228 decide whether it's an error or not. This error usually happens
229 when the client aborts the connection.
230 use APR::Const -compile => qw(ECONNABORTED);
232 my $buffer;
233 eval { $sock->recv($buffer, $wanted) };
234 if ($@ == APR::Const::ECONNABORTED) {
235 # ignore it or deal with it
236 }
237 since: 2.0.00
239 Here is the quick prototype example, which doesn't handle any errors
241 (mod_perl will do that for you):
242 use APR::Socket ();
244 # set the socket to the blocking mode if it isn't already
246 use APR::Const -compile => qw(SO_NONBLOCK);
247 if ($sock->opt_get(APR::Const::SO_NONBLOCK)) {
248 $sock->opt_set(APR::Const::SO_NONBLOCK => 0);
249 }
250 # read from/write to the socket (w/o handling possible failures)
251 my $wanted = 1024;
252 while ($sock->recv(my $buffer, $wanted)) {
253 $sock->send($buffer);
254 }
255 If you want to handle errors by yourself, the loop may look like:
257 use APR::Const -compile => qw(ECONNABORTED);
259 # ...
260 while (1) {
261 my $buf;
262 my $len = eval { $sock->recv($buf, $wanted) };
263 if ($@) {
264 # handle the error, e.g. to ignore aborted connections but
265 # rethrow any other errors:
266 if ($@ == APR::Const::ECONNABORTED) {
267 # ignore
268 last;
269 }
270 else {
271 die $@; # retrow
272 }
273 }
274 if ($len) {
276 $sock->send($buffer);
277 }
278 else {
279 last;
280 }
281 }
282 "send"
284 Write data to the socket
286 $wlen = $sock->send($buf, $opt_len);
288 obj: $sock ( "APR::Socket object" )
290 The socket to write to
291 arg1: $buf ( scalar )
293 The data to send
294 opt arg2: $opt_len ( int )
296 There is no need to pass this argument, unless you want to send
297 less data than contained in $buf.
298 ret: $wlen ( integer )
300 How many bytes were sent
301 since: 2.0.00
303 For examples see the "recv" item.
305 "timeout_get"
307 Get socket timeout settings
309 $usecs = $sock->timeout_get();
311 obj: $sock ( "APR::Socket object" )
313 The socket to set up.
314 ret: $usecs ( number)
316 Currently set timeout in microseconds (and also the blocking IO
317 behavior). See ("APR::timeout_set") for possible values and their
318 meaning.
319 excpt: "APR::Error"
321 since: 2.0.00
322 "timeout_set"
324 Setup socket timeout.
326 $sock->timeout_set($usecs);
328 obj: $sock ( "APR::Socket object" )
330 The socket to set up.
331 arg1: $usecs ( number )
333 Value for the timeout in microseconds and also the blocking IO
334 behavior.
335 The possible values are:
337 t > 0
339 "send()" and "recv()" throw ("APR::Const::TIMEUP" exception) if
340 specified time elapses with no data sent or received.
341 Notice that the positive value is in micro seconds. So if you
343 want to set the timeout for 5 seconds, the value should be:
344 5_000_000.
345 This mode sets the socket into a non-blocking IO mode.
347 t == 0
349 "send()" and "recv()" calls never block.
350 t < 0
352 "send()" and "recv()" calls block.
353 Usually just -1 is used for this case, but any negative value
355 will do.
356 This mode sets the socket into a blocking IO mode.
358 ret: no return value
360 excpt: "APR::Error"
361 since: 2.0.00
362
364 "APR::Socket" also provides auto-generated Perl interface for a few
365 other methods which aren't tested at the moment and therefore their API
366 is a subject to change. These methods will be finalized later as a need
367 arises. If you want to rely on any of the following methods please con‐
368 tact the the mod_perl development mailing list so we can help each
369 other take the steps necessary to shift the method to an officially
370 supported API.
371 "bind"
373 META: Autogenerated - needs to be reviewed/completed
375 Bind the socket to its associated port
377 $ret = $sock->bind($sa);
379 obj: $sock ( "APR::Socket object" )
381 The socket to bind
382 arg1: $sa ( "APR::SockAddr object" )
384 The socket address to bind to
385 ret: $ret ( integer )
387 since: subject to change
388 This may be where we will find out if there is any other process using
390 the selected port.
391 "close"
393 META: Autogenerated - needs to be reviewed/completed
395 Close a socket.
397 $ret = $sock->close();
399 obj: $sock ( "APR::Socket object" )
401 The socket to close
402 ret: $ret ( integer )
404 since: subject to change
405 "connect"
407 META: Autogenerated - needs to be reviewed/completed
409 Issue a connection request to a socket either on the same machine or a
411 different one.
412 $ret = $sock->connect($sa);
414 obj: $sock ( "APR::Socket object" )
416 The socket we wish to use for our side of the connection
417 arg1: $sa ( "APR::SockAddr object" )
419 The address of the machine we wish to connect to. If NULL, APR
420 assumes that the sockaddr_in in the apr_socket is completely filled
421 out.
422 ret: $ret ( integer )
424 since: subject to change
425 "listen"
427 META: Autogenerated - needs to be reviewed/completed
429 Listen to a bound socket for connections.
431 $ret = $sock->listen($backlog);
433 obj: $sock ( "APR::Socket object" )
435 The socket to listen on
436 arg1: $backlog ( integer )
438 The number of outstanding connections allowed in the sockets listen
439 queue. If this value is less than zero, the listen queue size is
440 set to zero.
441 ret: $ret ( integer )
443 since: subject to change
444 "recvfrom"
446 META: Autogenerated - needs to be reviewed/completed
448 $ret = $from->recvfrom($sock, $flags, $buf, $len);
450 obj: $from ( "APR::SockAddr object" )
452 The apr_sockaddr_t to fill in the recipient info
453 arg1: $sock ( "APR::SockAddr object" )
455 The socket to use
456 arg2: $flags ( integer )
458 The flags to use
459 arg3: $buf ( integer )
461 The buffer to use
462 arg4: $len ( string )
464 The length of the available buffer
465 ret: $ret ( integer )
467 since: subject to change
468 "sendto"
470 META: Autogenerated - needs to be reviewed/completed
472 $ret = $sock->sendto($where, $flags, $buf, $len);
474 obj: $sock ( "APR::Socket object" )
476 The socket to send from
477 arg1: $where ( "APR::Socket object" )
479 The apr_sockaddr_t describing where to send the data
480 arg2: $flags ( integer )
482 The flags to use
483 arg3: $buf ( scalar )
485 The data to send
486 arg4: $len ( string )
488 The length of the data to send
489 ret: $ret ( integer )
491 since: subject to change
492
494 mod_perl 2.0 documentation.
495
497 mod_perl 2.0 and its core modules are copyrighted under The Apache
498 Software License, Version 2.0.
499
501 The mod_perl development team and numerous contributors.
502perl v5.8.8 2006-11-19 docs::api::APR::Socket(3)