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
53         # fetch the operating level socket
54         my $fd=$sock->fileno;
55

Description

57       "APR::Socket" provides the Perl interface to APR sockets.
58

API

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

Unsupported API

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

See Also

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

Authors

504       The mod_perl development team and numerous contributors.
505
506
507
508perl v5.28.0                      2016-10-27         docs::api::APR::Socket(3)
Impressum