1NAME
2 Net::NBsocket -- Non-Blocking Sockets
3
4SYNOPSIS
5 use Net::NBsocket qw(
6 open_UDP
7 open_udpNB
8 open_Listen
9 open_listenNB
10 connectBlk
11 connect_NB
12 accept_Blk
13 accept_NB
14 set_NB
15 set_so_linger
16 dyn_bind
17 inet_aton
18 inet_ntoa
19 sockaddr_in
20 sockaddr_un
21 inet_pton
22 inet_ntop
23 ipv6_aton
24 ipv6_n2x
25 ipv6_n2d
26 INADDR_ANY
27 INADDR_BROADCAST
28 INADDR_LOOPBACK
29 INADDR_NONE
30 AF_INET
31 AF_INET6
32 in6addr_any
33 in6addr_loopback
34 havesock6
35 isupport6
36 pack_sockaddr_in6
37 unpack_sockaddr_in6
38 );
39
40 $sock = open_UDP($af_family);
41 $sock = open_udpNB($af_family);
42 DEPRECATED $sock = bind2pp($sock,$port_path,$netaddr);
43 $listener = open_Listen($port_path,$netaddr,$af_family);
44 $listener = open_listenNB($port_path,$netaddr,$af_family);
45 $client = connectBlk($port_path,$netaddr,$af_family);
46 $client = connect_NB($port_path,$netaddr,$af_family);
47 ($sock,$netaddr) = accept_Blk($srvsock);
48 ($sock,$netaddr) = accept_NB($srvsock);
49 $rv = set_NB($sock);
50 $rv = set_so_linger($sock,$seconds);
51 $port = dyn_bind($sock,$netaddr);
52
53 IPv4
54 $netaddr = inet_aton($dot_quad);
55 $dot_quad = inet_ntoa($netaddr);
56 $sin = sockaddr_in($port,$netaddr);
57 ($port,$netaddr) = sockaddr_in($sin);
58 $sun = sockaddr_un($path);
59 ($path) = sockaddr_un($sun);
60
61 IPv6
62 $netaddr = inet_pton($AF_family,$text_addr);
63 $text_addr = inet_ntop($AF_family,$netaddr);
64 $ipv6naddr = ipv6_aton($ipv6_text);
65 $hex_text = ipv6_n2x($ipv6naddr);
66 $dec_text = ipv6_n2d($ipv6naddr);
67
68 CONSTANTS
69 $constant = INADDR_ANY();
70 $constant = INADDR_BROADCAST();
71 $constant = INADDR_LOOPBACK();
72 $constant = INADDR_NONE();
73 $constant = AF_INET();
74 $constant = AF_INET6();
75 $constant = in6addr_any();
76 $constant = in6addr_loopback();
77
78 IPv6 conditional
79 $trueif = havesock6();
80 $trueif = isupport6();
81 $sockaddr_in6_struct=pack_sockaddr_in6($port,ipv6naddr);
82 ($port,$ipv6naddr)=unpack_sockaddr_in6($sockaddr_in6_struct);
83
84DESCRIPTION
85 Net::NBsocket provides a wrapper for Socket and Socket6 to supply
86 Non-Blocking sockets of various flavors;
87
88 FUNCTIONS
89
90 * $sock = open_UDP();
91 Open an unbound UDP socket as below.
92
93 * $sock = open_udpNB();
94 Open and return an unbound non-blocking UDP socket object
95
96 input: [optional] address family (required for IPv6)
97 returns: pointer to socket object
98 or undef on failure
99
100 * DEPRECATED $sock=bind2pp($sock,$port_path,$netaddr);
101 Bind to $port_path and an optional IPv4 bind address as returned by
102 inet_aton (defaults to INADDR_ANY).
103
104 input: port or unix domain socket path,
105 [optional] bind address
106 returns: socket on sucess, else undef;
107
108 Author's note: This function was not well thought out and is now
109 deprecated. It may be removed in future versions and is no longer in the
110 EXPORT_OK array though it is still in the module and may be accessed
111 with Net::NBsocket::bind2pp();
112
113 Does not support IPv6
114
115 * $listener = open_Listen($port_path,$netaddr,$af_family);
116 Open a blocking TCP listner as below.
117
118 * $listener = open_listenNB($port_path,$netaddr,$af_family);
119 Open and return a non-blocking TCP listener bound to $port_path and an
120 optional IPv4 or IPv6 bind address as returned by inet_pton (defaults to
121 INADDR_ANY or in6addr_any for AF_INET6).
122
123 Opens a unix-domain socket if port_path is a path instead of a number.
124
125 The user must set the appropriate UMASK prior to calling this routine.
126
127 input: port or unix domain socket path,
128 [optional] bind address
129 [optional] address family, default AF_INET
130 returns: pointer to listening socket
131 object or undef on failure
132
133 * $client = connectBlk($port_path,$netaddr,$af_family);
134 Begin a blocking TCP connection as below.
135
136 * $client = connect_NB($port_path,$netaddr,$af_family);
137 Begin a non-blocking TCP connection to the host designated by $netaddr
138 on $port_path, or to the unix domain socket designated by the path in
139 $port_path. $netaddr is unused for unix domain sockets.
140
141 input: port number or unix domain socket path,
142 netaddr as returned by inet_aton,
143 [optional] address family (default AF_INET)
144 returns: socket object or
145 undef on failure
146
147 * ($sock,$netaddr) = accept_Blk($srvsock);
148 Accept a connection and return a BLOCKING socket as below.
149
150 * ($sock,$netaddr) = accept_NB($srvsock);
151 Accept a connection from a remote client, return a non-blocking socket
152 and the network address of the remote host as returned by inet_aton or
153 the unix domain socket path if PF_INET or PF_UNIX respectively.
154
155 input: listening socket object
156 returns: client socket object,
157 client packed netaddr or
158 unix domain socket path
159
160 on failure returns and empty array or undef
161
162 * $rv = set_NB($sock);
163 Set a socket to Non-Blocking mode
164
165 input: SOCK object pointer
166 returns: true on success or
167 undef on failure
168
169 $rv = set_so_linger($sock,$seconds);
170 Set SO_LINGER on top level socket
171
172 input: sock object pointer, seconds
173 returns: true = success, false = fail
174
175 * $port = dyn_bind($sock,$netaddr,$af_family);
176 Attempt to bind a socket to the IP address and randomly assigned port
177 number, in the range 49152 through 65535. Fails after 100 attempts
178
179 input: socket
180 netaddr as returned by inet_pton
181 returns: port number or undef
182
183 IPv4 exported from Socket
184
185 * $netaddr = inet_aton($dot_quad);
186 Takes an argument of a hostname or dot quad ip address and returns a
187 four octet packed network address.
188
189 * $dot_quad = inet_ntoa($netaddr);
190 Takes a 4 octet packed network address and returns a dot quad text
191 string. Throws an error if fed a non-standard argument.
192
193 * $sin = sockaddr_in($port,$netaddr);
194 In SCALAR context, takes a port number and an IPv4 network address and
195 returns a sockaddr_in structure.
196
197 * ($port,$netaddr) = sockaddr_in($sin);
198 In ARRAY context, takes a sockaddr_in structure and return the port and
199 network address
200
201 * $sun = sockaddr_un($path);
202 In SCALAR context, takes its pathname and returns a sockaddr_un
203 structure.
204
205 * ($path) = sockaddr_un($sun);
206 In ARRAY context, takes a sockaddr_un structure and returns its
207 pathname.
208
209 IPv6 exported from Socket6 & NetAddr::IP::InetBase
210
211 * $netaddr = inet_pton($AF_family,$text_addr);
212 This function takes a dot quad IPv4 address or an RFC 1884 text IPv6
213 address and returns a 4 or 16 octet network address depending on the AF
214 family argument.
215
216 * $text_addr = inet_ntop($AF_family,$netaddr);
217 This function takes a 4 or 16 octet network address depending on the AF
218 family argument and returns a IPv4 dot quad or IPv6 text address
219 respectively.
220
221 * $ipv6naddr = ipv6_aton($ipv6_text);
222 This function takes an RFC 1884 IPv6 text address and returns a 16 octet
223 IPv6 network address.
224
225 * $hex_text = ipv6_n2x($ipv6naddr);
226 This function takes an IPv6 network address and returns an IPv6 hex text
227 address. Throws an error if fed a non-standard argument.
228
229 * $dec_text = ipv6_n2d($ipv6naddr);
230 This function takes an IPv6 network address and returns and IPv6 text
231 address with the last two octets in IPv4 dot quad representation.
232
233 CONSTANTS
234
235 * $constant = INADDR_ANY(); INADDR_ANY;
236 This constant returns the wildcard address, equivalent to
237 inet_aton('0.0.0.0');
238
239 * $constant = INADDR_BROADCAST(); INADDR_BROADCAST;
240 This constant returns the wildcard address, equivalent to
241 inet_aton('255.255.255.255');
242
243 * $constant = INADDR_LOOPBACK(); INADDR_LOOPBACK;
244 This constant returns the LOCALHOST address, equivalent to
245 inet_aton('127.0.0.1');
246
247 * $constant = INADDR_NONE(); INADDR_NONE;
248 This constant returns the "invalid" address, equivalent to
249 inet_aton('255.255.255.255');
250
251 * $constant = AF_INET(); AF_INET;
252 This constant returns the AF_INET family number.
253
254 * $constant = AF_INET6(); AF_INET6;
255 This constant retunrs the AF_INET6 family number for this operating
256 system.
257
258 * $constant = in6addr_any(); in6addr_any;
259 This constant returns the IPv6 16 octet wildcard address, equivalent to
260 ipv6_aton('::0');
261
262 * $constant = in6addr_loopback(); in6addr_loopback;
263 This constant returns the IPv6 16 octet LOCALHOST address, equivalent to
264 ipv6_aton('::1');
265
266 IPv6 Conditional
267
268 * $trueif = havesock6();
269 This function returns TRUE if Socket6 is loaded on this host, else
270 returns FALSE.
271
272 * $trueif = isupport6();
273 This function returns TRUE if Socket6 is loaded on this host and the
274 underlying operating system suports IPv6 sockets, else returns FALSE.
275
276 * $sockaddr_in6_struct=pack_sockaddr_in6($port,ipv6naddr);
277 If Socket6 is loaded on this host, in SCALAR context, takes a port
278 number and an IPv6 network address and returns a sockaddr_in6 structure.
279 If Socket6 is not loaded, returns "undef".
280
281 * ($port,$ipv6naddr)=unpack_sockaddr_in6($sockaddr_in6_struct);
282 If Socket6 is loaded on this host, in ARRAY context, takes a
283 sockaddr_in6 structure and returns the port number and IPv6 netaddr. If
284 Socket6 is not loaded, returns and empty array.
285
286DEPENDENCIES
287 POSIX
288 Socket
289 NetAddr::IP
290
291EXPORT_OK
292 open_UDP
293 open_udpNB
294 open_Listen
295 open_listenNB
296 connectBlk
297 connect_NB
298 accept_Blk
299 accept_NB
300 set_NB
301 set_so_linger
302 dyn_bind
303 inet_aton
304 inet_ntoa
305 sockaddr_in
306 sockaddr_un
307 inet_pton
308 inet_ntop
309 ipv6_aton
310 ipv6_n2x
311 ipv6_n2d
312 INADDR_ANY
313 INADDR_BROADCAST
314 INADDR_LOOPBACK
315 INADDR_NONE
316 in6addr_any
317 in6addr_loopback
318 AF_INET
319 AF_INET6
320 havesock6
321 isupport6
322 pack_sockaddr_in6
323 unpack_sockaddr_in6
324
325AUTHOR
326 Michael Robinton, michael@bizsystems.com
327
328COPYRIGHT 2004 - 2014
329 Michael Robinton
330
331 All rights reserved.
332
333 This program is free software; you can redistribute it and/or modify it
334 under the terms of either:
335
336 a) the GNU General Public License as published by the Free
337 Software Foundation; either version 2, or (at your option) any
338 later version, or
339
340 b) the "Artistic License" which comes with this distribution.
341
342 This program is distributed in the hope that it will be useful, but
343 WITHOUT ANY WARRANTY; without even the implied warranty of
344 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU
345 General Public License or the Artistic License for more details.
346
347 You should have received a copy of the Artistic License with this
348 distribution, in the file named "Artistic". If not, I'll be glad to
349 provide one.
350
351 You should also have received a copy of the GNU General Public License
352 along with this program in the file named "Copying". If not, write to
353 the
354
355 Free Software Foundation, Inc.
356 59 Temple Place, Suite 330
357 Boston, MA 02111-1307, USA
358
359 or visit their web page on the internet at:
360
361 http://www.gnu.org/copyleft/gpl.html.
362
363SEE ALSO
364 the POSIX manpage, the Socket manpage
365
366