1docs::api::APR::Socket(U3s)er Contributed Perl Documentatdioocns::api::APR::Socket(3)
2
3
4

NAME

6       APR::Socket - Perl API for APR sockets
7

Synopsis

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

Description

54       "APR::Socket" provides the Perl interface to APR sockets.
55

API

57       "APR::Socket" provides the following methods:
58
59   "opt_get"
60       Query socket options for the specified socket
61
62         $val = $sock->opt_get($opt);
63
64       obj: $sock ( "APR::Socket object" )
65           the socket object to query
66
67       arg1: $opt ( "APR::Const constant" )
68           the socket option we would like to configure.  Here are the
69           available socket options.
70
71       ret: $val ( integer )
72           the currently set value for the socket option you've queried for
73
74       excpt: "APR::Error"
75       since: 2.0.00
76
77       Examples can be found in the socket options constants section. For
78       example setting the IO to the blocking mode.
79
80   "opt_set"
81       Setup socket options for the specified socket
82
83         $sock->opt_set($opt, $val);
84
85       obj: $sock ( "APR::Socket object" object )
86           the socket object to set up.
87
88       arg1: $opt ( "APR::Const" constant )
89           the socket option we would like to configure.  Here are the
90           available socket options.
91
92       arg2: $val ( integer )
93           value for the option. Refer to the socket options section to learn
94           about the expected values.
95
96       ret: no return value
97       excpt: "APR::Error"
98       since: 2.0.00
99
100       Examples can be found in the socket options constants section. For
101       example setting the IO to the blocking mode.
102
103   "poll"
104       Poll the socket for events:
105
106           $rc = $sock->poll($pool, $timeout, $events);
107
108       obj: $sock ( "APR::Socket object" )
109           The socket to poll
110
111       arg1: $pool ( "APR::Pool object" )
112           usually "$c->pool".
113
114       arg2: $timeout ( integer )
115           The amount of time to wait (in milliseconds) for the specified
116           events to occur.
117
118       arg3: $events ( "APR::Const :poll constants" )
119           The events for which to wait.
120
121           For example use "APR::Const::POLLIN" to wait for incoming data to
122           be available, "APR::Const::POLLOUT" to wait until it's possible to
123           write data to the socket and "APR::Const::POLLPRI" to wait for
124           priority data to become available.
125
126       ret: $rc ( "APR::Const constant" )
127           If "APR::Const::SUCCESS" is received than the polling was
128           successful. If not -- the error code is returned, which can be
129           converted to the error string with help of "APR::Error::strerror".
130
131       since: 2.0.00
132
133       For example poll a non-blocking socket up to 1 second when reading data
134       from the client:
135
136         use APR::Socket ();
137         use APR::Connection ();
138         use APR::Error ();
139
140         use APR::Const -compile => qw(SO_NONBLOCK POLLIN SUCCESS TIMEUP);
141
142         $sock->opt_set(APR::Const::SO_NONBLOCK => 1);
143
144         my $rc = $sock->poll($c->pool, 1_000_000, APR::Const::POLLIN);
145         if ($rc == APR::Const::SUCCESS) {
146             # Data is waiting on the socket to be read.
147             # $sock->recv(my $buf, BUFF_LEN)
148         }
149         elsif ($rc == APR::Const::TIMEUP) {
150             # One second elapsed and still there is no data waiting to be
151             # read. for example could try again.
152         }
153         else {
154             die "poll error: " . APR::Error::strerror($rc);
155         }
156
157   "recv"
158       Read incoming data from the socket
159
160         $len = $sock->recv($buffer, $wanted);
161
162       obj: $sock ( "APR::SockAddr object" object )
163           The socket to read from
164
165       arg1: $buffer ( SCALAR )
166           The buffer to fill. All previous data will be lost.
167
168       arg2: $wanted ( int )
169           How many bytes to attempt to read.
170
171       ret: $len ( number )
172           How many bytes were actually read.
173
174           $buffer gets populated with the string that is read. It will
175           contain an empty string if there was nothing to read.
176
177       excpt: "APR::Error"
178           If you get the '(11) Resource temporarily unavailable' error
179           (exception "APR::Const::EAGAIN") (or another equivalent, which
180           might be different on non-POSIX systems), then you didn't ensure
181           that the socket is in a blocking IO mode before using it. Note that
182           you should use "APR::Status::is_EAGAIN" to perform this check
183           (since different error codes may be returned for the same event on
184           different OSes). For example if the socket is set to the non-
185           blocking mode and there is no data right away, you may get this
186           exception thrown. So here is how to check for it and retry a few
187           times after short delays:
188
189             use APR::Status ();
190             $sock->opt_set(APR::Const::SO_NONBLOCK, 1);
191             # ....
192             my $tries = 0;
193             my $buffer;
194             RETRY: my $rlen = eval { $socket->recv($buffer, SIZE) };
195             if ($@)
196                 die $@ unless ref $@ && APR::Status::is_EAGAIN($@);
197                 if ($tries++ < 3) {
198                     # sleep 250msec
199                     select undef, undef, undef, 0.25;
200                     goto RETRY;
201                 }
202                 else {
203                     # do something else
204                 }
205             }
206             warn "read $rlen bytes\n"
207
208           If timeout was set via "timeout_set|/C_timeout_set_", you may need
209           to catch the "APR::Const::TIMEUP" exception. For example:
210
211             use APR::Const -compile => qw(TIMEUP);
212             $sock->timeout_set(1_000_000); # 1 sec
213             my $buffer;
214             eval { $sock->recv($buffer, $wanted) };
215             if ($@ && $@ == APR::Const::TIMEUP) {
216                 # timeout, do something, e.g.
217             }
218
219           If not handled -- you may get the error '70007: The timeout
220           specified has expired'.
221
222           Another error condition that may occur is the '(104) Connection
223           reset by peer' error, which is up to your application logic to
224           decide whether it's an error or not. This error usually happens
225           when the client aborts the connection.
226
227             use APR::Const -compile => qw(ECONNABORTED);
228             my $buffer;
229             eval { $sock->recv($buffer, $wanted) };
230             if ($@ == APR::Const::ECONNABORTED) {
231                 # ignore it or deal with it
232             }
233
234       since: 2.0.00
235
236       Here is the quick prototype example, which doesn't handle any errors
237       (mod_perl will do that for you):
238
239         use APR::Socket ();
240
241         # set the socket to the blocking mode if it isn't already
242         use APR::Const -compile => qw(SO_NONBLOCK);
243         if ($sock->opt_get(APR::Const::SO_NONBLOCK)) {
244             $sock->opt_set(APR::Const::SO_NONBLOCK => 0);
245         }
246         # read from/write to the socket (w/o handling possible failures)
247         my $wanted = 1024;
248         while ($sock->recv(my $buffer, $wanted)) {
249             $sock->send($buffer);
250         }
251
252       If you want to handle errors by yourself, the loop may look like:
253
254         use APR::Const -compile => qw(ECONNABORTED);
255         # ...
256         while (1) {
257             my $buf;
258             my $len = eval { $sock->recv($buf, $wanted) };
259             if ($@) {
260                 # handle the error, e.g. to ignore aborted connections but
261                 # rethrow any other errors:
262                 if ($@ == APR::Const::ECONNABORTED) {
263                     # ignore
264                     last;
265                 }
266                 else {
267                     die $@; # retrow
268                 }
269             }
270
271             if ($len) {
272                 $sock->send($buffer);
273             }
274             else {
275                 last;
276             }
277         }
278
279   "send"
280       Write data to the socket
281
282         $wlen = $sock->send($buf, $opt_len);
283
284       obj: $sock ( "APR::Socket object" )
285           The socket to write to
286
287       arg1: $buf ( scalar )
288           The data to send
289
290       opt arg2: $opt_len ( int )
291           There is no need to pass this argument, unless you want to send
292           less data than contained in $buf.
293
294       ret: $wlen ( integer )
295           How many bytes were sent
296
297       since: 2.0.00
298
299       For examples see the "recv" item.
300
301   "timeout_get"
302       Get socket timeout settings
303
304         $usecs = $sock->timeout_get();
305
306       obj: $sock ( "APR::Socket object" )
307           The socket to set up.
308
309       ret: $usecs ( number)
310           Currently set timeout in microseconds (and also the blocking IO
311           behavior). See ("APR::timeout_set") for possible values and their
312           meaning.
313
314       excpt: "APR::Error"
315       since: 2.0.00
316
317   "timeout_set"
318       Setup socket timeout.
319
320         $sock->timeout_set($usecs);
321
322       obj: $sock ( "APR::Socket object" )
323           The socket to set up.
324
325       arg1: $usecs ( number )
326           Value for the timeout in microseconds and also the blocking IO
327           behavior.
328
329           The possible values are:
330
331           t > 0
332               "send()" and "recv()" throw ("APR::Const::TIMEUP" exception) if
333               specified time elapses with no data sent or received.
334
335               Notice that the positive value is in micro seconds. So if you
336               want to set the timeout for 5 seconds, the value should be:
337               5_000_000.
338
339               This mode sets the socket into a non-blocking IO mode.
340
341           t == 0
342               "send()" and "recv()" calls never block.
343
344           t < 0
345               "send()" and "recv()" calls block.
346
347               Usually just -1 is used for this case, but any negative value
348               will do.
349
350               This mode sets the socket into a blocking IO mode.
351
352           ret: no return value
353       excpt: "APR::Error"
354       since: 2.0.00
355

Unsupported API

357       "APR::Socket" also provides auto-generated Perl interface for a few
358       other methods which aren't tested at the moment and therefore their API
359       is a subject to change. These methods will be finalized later as a need
360       arises. If you want to rely on any of the following methods please
361       contact the the mod_perl development mailing list so we can help each
362       other take the steps necessary to shift the method to an officially
363       supported API.
364
365   "bind"
366       META: Autogenerated - needs to be reviewed/completed
367
368       Bind the socket to its associated port
369
370         $ret = $sock->bind($sa);
371
372       obj: $sock ( "APR::Socket object" )
373           The socket to bind
374
375       arg1: $sa ( "APR::SockAddr object" )
376           The socket address to bind to
377
378       ret: $ret ( integer )
379       since: subject to change
380
381       This may be where we will find out if there is any other process using
382       the selected port.
383
384   "close"
385       META: Autogenerated - needs to be reviewed/completed
386
387       Close a socket.
388
389         $ret = $sock->close();
390
391       obj: $sock ( "APR::Socket object" )
392           The socket to close
393
394       ret: $ret ( integer )
395       since: subject to change
396
397   "connect"
398       META: Autogenerated - needs to be reviewed/completed
399
400       Issue a connection request to a socket either on the same machine or a
401       different one.
402
403         $ret = $sock->connect($sa);
404
405       obj: $sock ( "APR::Socket object" )
406           The socket we wish to use for our side of the connection
407
408       arg1: $sa ( "APR::SockAddr object" )
409           The address of the machine we wish to connect to.  If NULL, APR
410           assumes that the sockaddr_in in the apr_socket is completely filled
411           out.
412
413       ret: $ret ( integer )
414       since: subject to change
415
416   "listen"
417       META: Autogenerated - needs to be reviewed/completed
418
419       Listen to a bound socket for connections.
420
421         $ret = $sock->listen($backlog);
422
423       obj: $sock ( "APR::Socket object" )
424           The socket to listen on
425
426       arg1: $backlog ( integer )
427           The number of outstanding connections allowed in the sockets listen
428           queue.  If this value is less than zero, the listen queue size is
429           set to zero.
430
431       ret: $ret ( integer )
432       since: subject to change
433
434   "recvfrom"
435       META: Autogenerated - needs to be reviewed/completed
436
437         $ret = $from->recvfrom($sock, $flags, $buf, $len);
438
439       obj: $from ( "APR::SockAddr object" )
440           The apr_sockaddr_t to fill in the recipient info
441
442       arg1: $sock ( "APR::SockAddr object" )
443           The socket to use
444
445       arg2: $flags ( integer )
446           The flags to use
447
448       arg3: $buf ( integer )
449           The buffer to use
450
451       arg4: $len ( string )
452           The length of the available buffer
453
454       ret: $ret ( integer )
455       since: subject to change
456
457   "sendto"
458       META: Autogenerated - needs to be reviewed/completed
459
460         $ret = $sock->sendto($where, $flags, $buf, $len);
461
462       obj: $sock ( "APR::Socket object" )
463           The socket to send from
464
465       arg1: $where ( "APR::Socket object" )
466           The apr_sockaddr_t describing where to send the data
467
468       arg2: $flags ( integer )
469           The flags to use
470
471       arg3: $buf ( scalar )
472           The data to send
473
474       arg4: $len ( string )
475           The length of the data to send
476
477       ret: $ret ( integer )
478       since: subject to change
479

See Also

481       mod_perl 2.0 documentation.
482
484       mod_perl 2.0 and its core modules are copyrighted under The Apache
485       Software License, Version 2.0.
486

Authors

488       The mod_perl development team and numerous contributors.
489
490
491
492perl v5.12.0                      2008-04-17         docs::api::APR::Socket(3)
Impressum