Commit | Line | Data |
---|---|---|
a0d0e21e | 1 | package Socket; |
73c78b0a | 2 | |
e71d7b85 | 3 | use strict; |
9dea6244 | 4 | { use 5.006001; } |
e71d7b85 | 5 | |
ac89c499 | 6 | our $VERSION = '2.020_03'; # patched in perl5.git |
3b35bae3 AD |
7 | |
8 | =head1 NAME | |
9 | ||
c2654555 | 10 | C<Socket> - networking constants and support functions |
3b35bae3 AD |
11 | |
12 | =head1 SYNOPSIS | |
13 | ||
c2654555 CBW |
14 | C<Socket> a low-level module used by, among other things, the L<IO::Socket> |
15 | family of modules. The following examples demonstrate some low-level uses but | |
16 | a practical program would likely use the higher-level API provided by | |
17 | C<IO::Socket> or similar instead. | |
18 | ||
19 | use Socket qw(PF_INET SOCK_STREAM pack_sockaddr_in inet_aton); | |
20 | ||
21 | socket(my $socket, PF_INET, SOCK_STREAM, 0) | |
22 | or die "socket: $!"; | |
23 | ||
24 | my $port = getservbyname "echo", "tcp"; | |
25 | connect($socket, pack_sockaddr_in($port, inet_aton("localhost"))) | |
26 | or die "connect: $!"; | |
27 | ||
28 | print $socket "Hello, world!\n"; | |
29 | print <$socket>; | |
30 | ||
31 | See also the L</EXAMPLES> section. | |
3b35bae3 AD |
32 | |
33 | =head1 DESCRIPTION | |
34 | ||
c2654555 CBW |
35 | This module provides a variety of constants, structure manipulators and other |
36 | functions related to socket-based networking. The values and functions | |
37 | provided are useful when used in conjunction with Perl core functions such as | |
38 | socket(), setsockopt() and bind(). It also provides several other support | |
39 | functions, mostly for dealing with conversions of network addresses between | |
40 | human-readable and native binary forms, and for hostname resolver operations. | |
3b35bae3 | 41 | |
c2654555 CBW |
42 | Some constants and functions are exported by default by this module; but for |
43 | backward-compatibility any recently-added symbols are not exported by default | |
44 | and must be requested explicitly. When an import list is provided to the | |
45 | C<use Socket> line, the default exports are not automatically imported. It is | |
46 | therefore best practice to always to explicitly list all the symbols required. | |
fdb41d65 | 47 | |
c2654555 CBW |
48 | Also, some common socket "newline" constants are provided: the constants |
49 | C<CR>, C<LF>, and C<CRLF>, as well as C<$CR>, C<$LF>, and C<$CRLF>, which map | |
50 | to C<\015>, C<\012>, and C<\015\012>. If you do not want to use the literal | |
51 | characters in your programs, then use the constants provided here. They are | |
52 | not exported by default, but can be imported individually, and with the | |
53 | C<:crlf> export tag: | |
fdb41d65 | 54 | |
c2654555 | 55 | use Socket qw(:DEFAULT :crlf); |
8e07c86e | 56 | |
c2654555 | 57 | $sock->print("GET / HTTP/1.0$CRLF"); |
2ae324a7 | 58 | |
c2654555 CBW |
59 | The entire getaddrinfo() subsystem can be exported using the tag C<:addrinfo>; |
60 | this exports the getaddrinfo() and getnameinfo() functions, and all the | |
61 | C<AI_*>, C<NI_*>, C<NIx_*> and C<EAI_*> constants. | |
8e07c86e | 62 | |
c2654555 | 63 | =cut |
8e07c86e | 64 | |
c2654555 | 65 | =head1 CONSTANTS |
2528d3bc | 66 | |
c2654555 CBW |
67 | In each of the following groups, there may be many more constants provided |
68 | than just the ones given as examples in the section heading. If the heading | |
69 | ends C<...> then this means there are likely more; the exact constants | |
70 | provided will depend on the OS and headers found at compile-time. | |
8e07c86e | 71 | |
c2654555 | 72 | =cut |
8e07c86e | 73 | |
c2654555 | 74 | =head2 PF_INET, PF_INET6, PF_UNIX, ... |
8e07c86e | 75 | |
c2654555 | 76 | Protocol family constants to use as the first argument to socket() or the |
eabcd9c8 | 77 | value of the C<SO_DOMAIN> or C<SO_FAMILY> socket option. |
8e07c86e | 78 | |
c2654555 | 79 | =head2 AF_INET, AF_INET6, AF_UNIX, ... |
8e07c86e | 80 | |
c2654555 CBW |
81 | Address family constants used by the socket address structures, to pass to |
82 | such functions as inet_pton() or getaddrinfo(), or are returned by such | |
83 | functions as sockaddr_family(). | |
7e1af8bc | 84 | |
c2654555 | 85 | =head2 SOCK_STREAM, SOCK_DGRAM, SOCK_RAW, ... |
7e1af8bc | 86 | |
c2654555 CBW |
87 | Socket type constants to use as the second argument to socket(), or the value |
88 | of the C<SO_TYPE> socket option. | |
7e1af8bc | 89 | |
3be135d8 TC |
90 | =head2 SOCK_NONBLOCK. SOCK_CLOEXEC |
91 | ||
92 | Linux-specific shortcuts to specify the C<O_NONBLOCK> and C<FD_CLOEXEC> flags | |
93 | during a C<socket(2)> call. | |
94 | ||
95 | socket( my $sockh, PF_INET, SOCK_DGRAM|SOCK_NONBLOCK, 0 ) | |
96 | ||
c2654555 | 97 | =head2 SOL_SOCKET |
8e07c86e | 98 | |
c2654555 | 99 | Socket option level constant for setsockopt() and getsockopt(). |
8e07c86e | 100 | |
c2654555 | 101 | =head2 SO_ACCEPTCONN, SO_BROADCAST, SO_ERROR, ... |
3b35bae3 | 102 | |
c2654555 CBW |
103 | Socket option name constants for setsockopt() and getsockopt() at the |
104 | C<SOL_SOCKET> level. | |
8e07c86e | 105 | |
c2654555 | 106 | =head2 IP_OPTIONS, IP_TOS, IP_TTL, ... |
8e07c86e | 107 | |
c2654555 CBW |
108 | Socket option name constants for IPv4 socket options at the C<IPPROTO_IP> |
109 | level. | |
8e07c86e | 110 | |
a5c69419 AP |
111 | =head2 IPTOS_LOWDELAY, IPTOS_THROUGHPUT, IPTOS_RELIABILITY, ... |
112 | ||
113 | Socket option value constants for C<IP_TOS> socket option. | |
114 | ||
c2654555 | 115 | =head2 MSG_BCAST, MSG_OOB, MSG_TRUNC, ... |
d3f248d3 | 116 | |
c2654555 | 117 | Message flag constants for send() and recv(). |
d3f248d3 | 118 | |
c2654555 | 119 | =head2 SHUT_RD, SHUT_RDWR, SHUT_WR |
d3f248d3 | 120 | |
c2654555 | 121 | Direction constants for shutdown(). |
d3f248d3 | 122 | |
c2654555 | 123 | =head2 INADDR_ANY, INADDR_BROADCAST, INADDR_LOOPBACK, INADDR_NONE |
2a84dff3 | 124 | |
c2654555 CBW |
125 | Constants giving the special C<AF_INET> addresses for wildcard, broadcast, |
126 | local loopback, and invalid addresses. | |
127 | ||
128 | Normally equivalent to inet_aton('0.0.0.0'), inet_aton('255.255.255.255'), | |
129 | inet_aton('localhost') and inet_aton('255.255.255.255') respectively. | |
130 | ||
131 | =head2 IPPROTO_IP, IPPROTO_IPV6, IPPROTO_TCP, ... | |
132 | ||
133 | IP protocol constants to use as the third argument to socket(), the level | |
134 | argument to getsockopt() or setsockopt(), or the value of the C<SO_PROTOCOL> | |
135 | socket option. | |
136 | ||
137 | =head2 TCP_CORK, TCP_KEEPALIVE, TCP_NODELAY, ... | |
138 | ||
139 | Socket option name constants for TCP socket options at the C<IPPROTO_TCP> | |
140 | level. | |
141 | ||
142 | =head2 IN6ADDR_ANY, IN6ADDR_LOOPBACK | |
143 | ||
144 | Constants giving the special C<AF_INET6> addresses for wildcard and local | |
145 | loopback. | |
146 | ||
147 | Normally equivalent to inet_pton(AF_INET6, "::") and | |
148 | inet_pton(AF_INET6, "::1") respectively. | |
149 | ||
150 | =head2 IPV6_ADD_MEMBERSHIP, IPV6_MTU, IPV6_V6ONLY, ... | |
151 | ||
152 | Socket option name constants for IPv6 socket options at the C<IPPROTO_IPV6> | |
153 | level. | |
154 | ||
155 | =cut | |
156 | ||
157 | # Still undocumented: SCM_*, SOMAXCONN, IOV_MAX, UIO_MAXIOV | |
158 | ||
159 | =head1 STRUCTURE MANIPULATORS | |
160 | ||
161 | The following functions convert between lists of Perl values and packed binary | |
162 | strings representing structures. | |
163 | ||
164 | =cut | |
2a84dff3 | 165 | |
c2654555 | 166 | =head2 $family = sockaddr_family $sockaddr |
4633a7c4 | 167 | |
c2654555 CBW |
168 | Takes a packed socket address (as returned by pack_sockaddr_in(), |
169 | pack_sockaddr_un() or the perl builtin functions getsockname() and | |
170 | getpeername()). Returns the address family tag. This will be one of the | |
171 | C<AF_*> constants, such as C<AF_INET> for a C<sockaddr_in> addresses or | |
172 | C<AF_UNIX> for a C<sockaddr_un>. It can be used to figure out what unpack to | |
173 | use for a sockaddr of unknown type. | |
4633a7c4 | 174 | |
c2654555 | 175 | =head2 $sockaddr = pack_sockaddr_in $port, $ip_address |
4633a7c4 | 176 | |
c2654555 CBW |
177 | Takes two arguments, a port number and an opaque string (as returned by |
178 | inet_aton(), or a v-string). Returns the C<sockaddr_in> structure with those | |
179 | arguments packed in and C<AF_INET> filled in. For Internet domain sockets, | |
180 | this structure is normally what you need for the arguments in bind(), | |
181 | connect(), and send(). | |
8e07c86e | 182 | |
c2654555 | 183 | =head2 ($port, $ip_address) = unpack_sockaddr_in $sockaddr |
8e07c86e | 184 | |
c2654555 CBW |
185 | Takes a C<sockaddr_in> structure (as returned by pack_sockaddr_in(), |
186 | getpeername() or recv()). Returns a list of two elements: the port and an | |
187 | opaque string representing the IP address (you can use inet_ntoa() to convert | |
188 | the address to the four-dotted numeric format). Will croak if the structure | |
189 | does not represent an C<AF_INET> address. | |
8e07c86e | 190 | |
aff163d9 SH |
191 | In scalar context will return just the IP address. |
192 | ||
c2654555 | 193 | =head2 $sockaddr = sockaddr_in $port, $ip_address |
4633a7c4 | 194 | |
c2654555 | 195 | =head2 ($port, $ip_address) = sockaddr_in $sockaddr |
4bc6101e | 196 | |
c2654555 CBW |
197 | A wrapper of pack_sockaddr_in() or unpack_sockaddr_in(). In list context, |
198 | unpacks its argument and returns a list consisting of the port and IP address. | |
199 | In scalar context, packs its port and IP address arguments as a C<sockaddr_in> | |
200 | and returns it. | |
4bc6101e | 201 | |
c2654555 CBW |
202 | Provided largely for legacy compatibility; it is better to use |
203 | pack_sockaddr_in() or unpack_sockaddr_in() explicitly. | |
4bc6101e | 204 | |
c2654555 | 205 | =head2 $sockaddr = pack_sockaddr_in6 $port, $ip6_address, [$scope_id, [$flowinfo]] |
c73aa44c PE |
206 | |
207 | Takes two to four arguments, a port number, an opaque string (as returned by | |
208 | inet_pton()), optionally a scope ID number, and optionally a flow label | |
c2654555 CBW |
209 | number. Returns the C<sockaddr_in6> structure with those arguments packed in |
210 | and C<AF_INET6> filled in. IPv6 equivalent of pack_sockaddr_in(). | |
211 | ||
212 | =head2 ($port, $ip6_address, $scope_id, $flowinfo) = unpack_sockaddr_in6 $sockaddr | |
213 | ||
214 | Takes a C<sockaddr_in6> structure. Returns a list of four elements: the port | |
215 | number, an opaque string representing the IPv6 address, the scope ID, and the | |
216 | flow label. (You can use inet_ntop() to convert the address to the usual | |
217 | string format). Will croak if the structure does not represent an C<AF_INET6> | |
218 | address. | |
219 | ||
aff163d9 SH |
220 | In scalar context will return just the IP address. |
221 | ||
c2654555 CBW |
222 | =head2 $sockaddr = sockaddr_in6 $port, $ip6_address, [$scope_id, [$flowinfo]] |
223 | ||
224 | =head2 ($port, $ip6_address, $scope_id, $flowinfo) = sockaddr_in6 $sockaddr | |
225 | ||
226 | A wrapper of pack_sockaddr_in6() or unpack_sockaddr_in6(). In list context, | |
227 | unpacks its argument according to unpack_sockaddr_in6(). In scalar context, | |
228 | packs its arguments according to pack_sockaddr_in6(). | |
229 | ||
230 | Provided largely for legacy compatibility; it is better to use | |
231 | pack_sockaddr_in6() or unpack_sockaddr_in6() explicitly. | |
232 | ||
233 | =head2 $sockaddr = pack_sockaddr_un $path | |
234 | ||
235 | Takes one argument, a pathname. Returns the C<sockaddr_un> structure with that | |
236 | path packed in with C<AF_UNIX> filled in. For C<PF_UNIX> sockets, this | |
237 | structure is normally what you need for the arguments in bind(), connect(), | |
238 | and send(). | |
239 | ||
240 | =head2 ($path) = unpack_sockaddr_un $sockaddr | |
241 | ||
242 | Takes a C<sockaddr_un> structure (as returned by pack_sockaddr_un(), | |
243 | getpeername() or recv()). Returns a list of one element: the pathname. Will | |
244 | croak if the structure does not represent an C<AF_UNIX> address. | |
c73aa44c | 245 | |
c2654555 | 246 | =head2 $sockaddr = sockaddr_un $path |
c73aa44c | 247 | |
c2654555 | 248 | =head2 ($path) = sockaddr_un $sockaddr |
c73aa44c | 249 | |
c2654555 CBW |
250 | A wrapper of pack_sockaddr_un() or unpack_sockaddr_un(). In a list context, |
251 | unpacks its argument and returns a list consisting of the pathname. In a | |
252 | scalar context, packs its pathname as a C<sockaddr_un> and returns it. | |
4633a7c4 | 253 | |
c2654555 CBW |
254 | Provided largely for legacy compatibility; it is better to use |
255 | pack_sockaddr_un() or unpack_sockaddr_un() explicitly. | |
4633a7c4 | 256 | |
1fef88e7 | 257 | These are only supported if your system has E<lt>F<sys/un.h>E<gt>. |
4633a7c4 | 258 | |
3be135d8 TC |
259 | =head2 $ip_mreq = pack_ip_mreq $multiaddr, $interface |
260 | ||
261 | Takes an IPv4 multicast address and optionally an interface address (or | |
262 | C<INADDR_ANY>). Returns the C<ip_mreq> structure with those arguments packed | |
263 | in. Suitable for use with the C<IP_ADD_MEMBERSHIP> and C<IP_DROP_MEMBERSHIP> | |
264 | sockopts. | |
265 | ||
266 | =head2 ($multiaddr, $interface) = unpack_ip_mreq $ip_mreq | |
c2654555 | 267 | |
3be135d8 TC |
268 | Takes an C<ip_mreq> structure. Returns a list of two elements; the IPv4 |
269 | multicast address and interface address. | |
c2654555 | 270 | |
d4ada64a SH |
271 | =head2 $ip_mreq_source = pack_ip_mreq_source $multiaddr, $source, $interface |
272 | ||
273 | Takes an IPv4 multicast address, source address, and optionally an interface | |
274 | address (or C<INADDR_ANY>). Returns the C<ip_mreq_source> structure with those | |
275 | arguments packed in. Suitable for use with the C<IP_ADD_SOURCE_MEMBERSHIP> | |
276 | and C<IP_DROP_SOURCE_MEMBERSHIP> sockopts. | |
277 | ||
278 | =head2 ($multiaddr, $source, $interface) = unpack_ip_mreq_source $ip_mreq | |
279 | ||
280 | Takes an C<ip_mreq_source> structure. Returns a list of three elements; the | |
281 | IPv4 multicast address, source address and interface address. | |
282 | ||
3be135d8 TC |
283 | =head2 $ipv6_mreq = pack_ipv6_mreq $multiaddr6, $ifindex |
284 | ||
285 | Takes an IPv6 multicast address and an interface number. Returns the | |
286 | C<ipv6_mreq> structure with those arguments packed in. Suitable for use with | |
287 | the C<IPV6_ADD_MEMBERSHIP> and C<IPV6_DROP_MEMBERSHIP> sockopts. | |
288 | ||
289 | =head2 ($multiaddr6, $ifindex) = unpack_ipv6_mreq $ipv6_mreq | |
c2654555 CBW |
290 | |
291 | Takes an C<ipv6_mreq> structure. Returns a list of two elements; the IPv6 | |
292 | address and an interface number. | |
293 | ||
294 | =cut | |
295 | ||
296 | =head1 FUNCTIONS | |
297 | ||
298 | =cut | |
299 | ||
300 | =head2 $ip_address = inet_aton $string | |
301 | ||
302 | Takes a string giving the name of a host, or a textual representation of an IP | |
303 | address and translates that to an packed binary address structure suitable to | |
304 | pass to pack_sockaddr_in(). If passed a hostname that cannot be resolved, | |
305 | returns C<undef>. For multi-homed hosts (hosts with more than one address), | |
306 | the first address found is returned. | |
4633a7c4 | 307 | |
c2654555 CBW |
308 | For portability do not assume that the result of inet_aton() is 32 bits wide, |
309 | in other words, that it would contain only the IPv4 address in network order. | |
4633a7c4 | 310 | |
c2654555 CBW |
311 | This IPv4-only function is provided largely for legacy reasons. Newly-written |
312 | code should use getaddrinfo() or inet_pton() instead for IPv6 support. | |
4633a7c4 | 313 | |
c2654555 | 314 | =head2 $string = inet_ntoa $ip_address |
3b35bae3 | 315 | |
c2654555 CBW |
316 | Takes a packed binary address structure such as returned by |
317 | unpack_sockaddr_in() (or a v-string representing the four octets of the IPv4 | |
318 | address in network order) and translates it into a string of the form | |
319 | C<d.d.d.d> where the C<d>s are numbers less than 256 (the normal | |
320 | human-readable four dotted number notation for Internet addresses). | |
036d8bd4 | 321 | |
c2654555 CBW |
322 | This IPv4-only function is provided largely for legacy reasons. Newly-written |
323 | code should use getnameinfo() or inet_ntop() instead for IPv6 support. | |
036d8bd4 | 324 | |
c2654555 | 325 | =head2 $address = inet_pton $family, $string |
d6896be3 | 326 | |
c2654555 | 327 | Takes an address family (such as C<AF_INET> or C<AF_INET6>) and a string |
23296748 | 328 | containing a textual representation of an address in that family and |
c2654555 | 329 | translates that to an packed binary address structure. |
036d8bd4 | 330 | |
c2654555 CBW |
331 | See also getaddrinfo() for a more powerful and flexible function to look up |
332 | socket addresses given hostnames or textual addresses. | |
036d8bd4 | 333 | |
c2654555 | 334 | =head2 $string = inet_ntop $family, $address |
d6896be3 | 335 | |
c2654555 CBW |
336 | Takes an address family and a packed binary address structure and translates |
337 | it into a human-readable textual representation of the address; typically in | |
338 | C<d.d.d.d> form for C<AF_INET> or C<hhhh:hhhh::hhhh> form for C<AF_INET6>. | |
e57a891d | 339 | |
c2654555 CBW |
340 | See also getnameinfo() for a more powerful and flexible function to turn |
341 | socket addresses into human-readable textual representations. | |
e57a891d | 342 | |
c2654555 CBW |
343 | =head2 ($err, @result) = getaddrinfo $host, $service, [$hints] |
344 | ||
345 | Given both a hostname and service name, this function attempts to resolve the | |
346 | host name into a list of network addresses, and the service name into a | |
347 | protocol and port number, and then returns a list of address structures | |
348 | suitable to connect() to it. | |
349 | ||
350 | Given just a host name, this function attempts to resolve it to a list of | |
351 | network addresses, and then returns a list of address structures giving these | |
352 | addresses. | |
353 | ||
354 | Given just a service name, this function attempts to resolve it to a protocol | |
355 | and port number, and then returns a list of address structures that represent | |
356 | it suitable to bind() to. This use should be combined with the C<AI_PASSIVE> | |
357 | flag; see below. | |
358 | ||
359 | Given neither name, it generates an error. | |
360 | ||
361 | If present, $hints should be a reference to a hash, where the following keys | |
362 | are recognised: | |
363 | ||
364 | =over 4 | |
e57a891d PE |
365 | |
366 | =item flags => INT | |
367 | ||
c2654555 | 368 | A bitfield containing C<AI_*> constants; see below. |
e57a891d PE |
369 | |
370 | =item family => INT | |
371 | ||
372 | Restrict to only generating addresses in this address family | |
373 | ||
374 | =item socktype => INT | |
375 | ||
376 | Restrict to only generating addresses of this socket type | |
377 | ||
378 | =item protocol => INT | |
379 | ||
380 | Restrict to only generating addresses for this protocol | |
381 | ||
382 | =back | |
383 | ||
384 | The return value will be a list; the first value being an error indication, | |
c2654555 | 385 | followed by a list of address structures (if no error occurred). |
e57a891d | 386 | |
06a9195c | 387 | The error value will be a dualvar; comparable to the C<EI_*> error constants, |
c2654555 CBW |
388 | or printable as a human-readable error message string. If no error occurred it |
389 | will be zero numerically and an empty string. | |
390 | ||
391 | Each value in the results list will be a hash reference containing the following | |
392 | fields: | |
e57a891d | 393 | |
c2654555 | 394 | =over 4 |
e57a891d PE |
395 | |
396 | =item family => INT | |
397 | ||
c2654555 | 398 | The address family (e.g. C<AF_INET>) |
e57a891d PE |
399 | |
400 | =item socktype => INT | |
401 | ||
c2654555 | 402 | The socket type (e.g. C<SOCK_STREAM>) |
e57a891d PE |
403 | |
404 | =item protocol => INT | |
405 | ||
c2654555 | 406 | The protocol (e.g. C<IPPROTO_TCP>) |
e57a891d PE |
407 | |
408 | =item addr => STRING | |
409 | ||
c2654555 CBW |
410 | The address in a packed string (such as would be returned by |
411 | pack_sockaddr_in()) | |
e57a891d PE |
412 | |
413 | =item canonname => STRING | |
414 | ||
415 | The canonical name for the host if the C<AI_CANONNAME> flag was provided, or | |
0cd14f2e PE |
416 | C<undef> otherwise. This field will only be present on the first returned |
417 | address. | |
e57a891d PE |
418 | |
419 | =back | |
420 | ||
c2654555 CBW |
421 | The following flag constants are recognised in the $hints hash. Other flag |
422 | constants may exist as provided by the OS. | |
423 | ||
424 | =over 4 | |
425 | ||
426 | =item AI_PASSIVE | |
e57a891d | 427 | |
c2654555 CBW |
428 | Indicates that this resolution is for a local bind() for a passive (i.e. |
429 | listening) socket, rather than an active (i.e. connecting) socket. | |
430 | ||
431 | =item AI_CANONNAME | |
432 | ||
433 | Indicates that the caller wishes the canonical hostname (C<canonname>) field | |
434 | of the result to be filled in. | |
435 | ||
436 | =item AI_NUMERICHOST | |
437 | ||
438 | Indicates that the caller will pass a numeric address, rather than a hostname, | |
439 | and that getaddrinfo() must not perform a resolve operation on this name. This | |
440 | flag will prevent a possibly-slow network lookup operation, and instead return | |
441 | an error if a hostname is passed. | |
442 | ||
443 | =back | |
444 | ||
445 | =head2 ($err, $hostname, $servicename) = getnameinfo $sockaddr, [$flags, [$xflags]] | |
446 | ||
447 | Given a packed socket address (such as from getsockname(), getpeername(), or | |
448 | returned by getaddrinfo() in a C<addr> field), returns the hostname and | |
449 | symbolic service name it represents. $flags may be a bitmask of C<NI_*> | |
e57a891d PE |
450 | constants, or defaults to 0 if unspecified. |
451 | ||
452 | The return value will be a list; the first value being an error condition, | |
453 | followed by the hostname and service name. | |
454 | ||
06a9195c | 455 | The error value will be a dualvar; comparable to the C<EI_*> error constants, |
e57a891d PE |
456 | or printable as a human-readable error message string. The host and service |
457 | names will be plain strings. | |
458 | ||
c2654555 CBW |
459 | The following flag constants are recognised as $flags. Other flag constants may |
460 | exist as provided by the OS. | |
461 | ||
462 | =over 4 | |
463 | ||
464 | =item NI_NUMERICHOST | |
465 | ||
466 | Requests that a human-readable string representation of the numeric address be | |
467 | returned directly, rather than performing a name resolve operation that may | |
468 | convert it into a hostname. This will also avoid potentially-blocking network | |
469 | IO. | |
470 | ||
471 | =item NI_NUMERICSERV | |
472 | ||
473 | Requests that the port number be returned directly as a number representation | |
474 | rather than performing a name resolve operation that may convert it into a | |
475 | service name. | |
476 | ||
477 | =item NI_NAMEREQD | |
478 | ||
479 | If a name resolve operation fails to provide a name, then this flag will cause | |
480 | getnameinfo() to indicate an error, rather than returning the numeric | |
481 | representation as a human-readable string. | |
482 | ||
483 | =item NI_DGRAM | |
484 | ||
485 | Indicates that the socket address relates to a C<SOCK_DGRAM> socket, for the | |
486 | services whose name differs between TCP and UDP protocols. | |
487 | ||
2ae324a7 | 488 | =back |
489 | ||
c2654555 CBW |
490 | The following constants may be supplied as $xflags. |
491 | ||
492 | =over 4 | |
4f5bb87f | 493 | |
c2654555 | 494 | =item NIx_NOHOST |
4f5bb87f | 495 | |
c2654555 CBW |
496 | Indicates that the caller is not interested in the hostname of the result, so |
497 | it does not have to be converted. C<undef> will be returned as the hostname. | |
4f5bb87f | 498 | |
c2654555 | 499 | =item NIx_NOSERV |
4f5bb87f | 500 | |
c2654555 CBW |
501 | Indicates that the caller is not interested in the service name of the result, |
502 | so it does not have to be converted. C<undef> will be returned as the service | |
503 | name. | |
504 | ||
505 | =back | |
506 | ||
507 | =head1 getaddrinfo() / getnameinfo() ERROR CONSTANTS | |
508 | ||
509 | The following constants may be returned by getaddrinfo() or getnameinfo(). | |
510 | Others may be provided by the OS. | |
511 | ||
512 | =over 4 | |
513 | ||
514 | =item EAI_AGAIN | |
515 | ||
516 | A temporary failure occurred during name resolution. The operation may be | |
517 | successful if it is retried later. | |
518 | ||
519 | =item EAI_BADFLAGS | |
520 | ||
521 | The value of the C<flags> hint to getaddrinfo(), or the $flags parameter to | |
522 | getnameinfo() contains unrecognised flags. | |
523 | ||
524 | =item EAI_FAMILY | |
525 | ||
526 | The C<family> hint to getaddrinfo(), or the family of the socket address | |
527 | passed to getnameinfo() is not supported. | |
528 | ||
529 | =item EAI_NODATA | |
530 | ||
531 | The host name supplied to getaddrinfo() did not provide any usable address | |
532 | data. | |
533 | ||
534 | =item EAI_NONAME | |
535 | ||
536 | The host name supplied to getaddrinfo() does not exist, or the address | |
537 | supplied to getnameinfo() is not associated with a host name and the | |
538 | C<NI_NAMEREQD> flag was supplied. | |
539 | ||
540 | =item EAI_SERVICE | |
541 | ||
542 | The service name supplied to getaddrinfo() is not available for the socket | |
543 | type given in the $hints. | |
4f5bb87f PE |
544 | |
545 | =back | |
546 | ||
3b35bae3 AD |
547 | =cut |
548 | ||
c2654555 CBW |
549 | =head1 EXAMPLES |
550 | ||
551 | =head2 Lookup for connect() | |
552 | ||
553 | The getaddrinfo() function converts a hostname and a service name into a list | |
554 | of structures, each containing a potential way to connect() to the named | |
555 | service on the named host. | |
556 | ||
557 | use IO::Socket; | |
558 | use Socket qw(SOCK_STREAM getaddrinfo); | |
559 | ||
560 | my %hints = (socktype => SOCK_STREAM); | |
561 | my ($err, @res) = getaddrinfo("localhost", "echo", \%hints); | |
562 | die "Cannot getaddrinfo - $err" if $err; | |
563 | ||
564 | my $sock; | |
565 | ||
566 | foreach my $ai (@res) { | |
567 | my $candidate = IO::Socket->new(); | |
568 | ||
569 | $candidate->socket($ai->{family}, $ai->{socktype}, $ai->{protocol}) | |
570 | or next; | |
571 | ||
572 | $candidate->connect($ai->{addr}) | |
573 | or next; | |
574 | ||
575 | $sock = $candidate; | |
576 | last; | |
577 | } | |
578 | ||
579 | die "Cannot connect to localhost:echo" unless $sock; | |
580 | ||
581 | $sock->print("Hello, world!\n"); | |
582 | print <$sock>; | |
583 | ||
584 | Because a list of potential candidates is returned, the C<while> loop tries | |
a5c69419 AP |
585 | each in turn until it finds one that succeeds both the socket() and connect() |
586 | calls. | |
c2654555 CBW |
587 | |
588 | This function performs the work of the legacy functions gethostbyname(), | |
589 | getservbyname(), inet_aton() and pack_sockaddr_in(). | |
590 | ||
591 | In practice this logic is better performed by L<IO::Socket::IP>. | |
592 | ||
593 | =head2 Making a human-readable string out of an address | |
594 | ||
595 | The getnameinfo() function converts a socket address, such as returned by | |
596 | getsockname() or getpeername(), into a pair of human-readable strings | |
597 | representing the address and service name. | |
598 | ||
599 | use IO::Socket::IP; | |
600 | use Socket qw(getnameinfo); | |
601 | ||
602 | my $server = IO::Socket::IP->new(LocalPort => 12345, Listen => 1) or | |
603 | die "Cannot listen - $@"; | |
604 | ||
605 | my $socket = $server->accept or die "accept: $!"; | |
606 | ||
607 | my ($err, $hostname, $servicename) = getnameinfo($socket->peername); | |
608 | die "Cannot getnameinfo - $err" if $err; | |
609 | ||
610 | print "The peer is connected from $hostname\n"; | |
611 | ||
612 | Since in this example only the hostname was used, the redundant conversion of | |
613 | the port number into a service name may be omitted by passing the | |
614 | C<NIx_NOSERV> flag. | |
615 | ||
616 | use Socket qw(getnameinfo NIx_NOSERV); | |
617 | ||
618 | my ($err, $hostname) = getnameinfo($socket->peername, 0, NIx_NOSERV); | |
619 | ||
620 | This function performs the work of the legacy functions unpack_sockaddr_in(), | |
621 | inet_ntoa(), gethostbyaddr() and getservbyport(). | |
622 | ||
623 | In practice this logic is better performed by L<IO::Socket::IP>. | |
624 | ||
625 | =head2 Resolving hostnames into IP addresses | |
626 | ||
627 | To turn a hostname into a human-readable plain IP address use getaddrinfo() | |
628 | to turn the hostname into a list of socket structures, then getnameinfo() on | |
629 | each one to make it a readable IP address again. | |
630 | ||
631 | use Socket qw(:addrinfo SOCK_RAW); | |
632 | ||
633 | my ($err, @res) = getaddrinfo($hostname, "", {socktype => SOCK_RAW}); | |
634 | die "Cannot getaddrinfo - $err" if $err; | |
635 | ||
636 | while( my $ai = shift @res ) { | |
637 | my ($err, $ipaddr) = getnameinfo($ai->{addr}, NI_NUMERICHOST, NIx_NOSERV); | |
638 | die "Cannot getnameinfo - $err" if $err; | |
639 | ||
640 | print "$ipaddr\n"; | |
641 | } | |
642 | ||
643 | The C<socktype> hint to getaddrinfo() filters the results to only include one | |
644 | socket type and protocol. Without this most OSes return three combinations, | |
645 | for C<SOCK_STREAM>, C<SOCK_DGRAM> and C<SOCK_RAW>, resulting in triplicate | |
646 | output of addresses. The C<NI_NUMERICHOST> flag to getnameinfo() causes it to | |
647 | return a string-formatted plain IP address, rather than reverse resolving it | |
648 | back into a hostname. | |
649 | ||
650 | This combination performs the work of the legacy functions gethostbyname() | |
651 | and inet_ntoa(). | |
652 | ||
653 | =head2 Accessing socket options | |
654 | ||
655 | The many C<SO_*> and other constants provide the socket option names for | |
656 | getsockopt() and setsockopt(). | |
657 | ||
658 | use IO::Socket::INET; | |
659 | use Socket qw(SOL_SOCKET SO_RCVBUF IPPROTO_IP IP_TTL); | |
660 | ||
661 | my $socket = IO::Socket::INET->new(LocalPort => 0, Proto => 'udp') | |
662 | or die "Cannot create socket: $@"; | |
663 | ||
664 | $socket->setsockopt(SOL_SOCKET, SO_RCVBUF, 64*1024) or | |
665 | die "setsockopt: $!"; | |
666 | ||
667 | print "Receive buffer is ", $socket->getsockopt(SOL_SOCKET, SO_RCVBUF), | |
668 | " bytes\n"; | |
669 | ||
670 | print "IP TTL is ", $socket->getsockopt(IPPROTO_IP, IP_TTL), "\n"; | |
671 | ||
672 | As a convenience, L<IO::Socket>'s setsockopt() method will convert a number | |
673 | into a packed byte buffer, and getsockopt() will unpack a byte buffer of the | |
674 | correct size back into a number. | |
675 | ||
676 | =cut | |
677 | ||
678 | =head1 AUTHOR | |
679 | ||
680 | This module was originally maintained in Perl core by the Perl 5 Porters. | |
681 | ||
682 | It was extracted to dual-life on CPAN at version 1.95 by | |
683 | Paul Evans <leonerd@leonerd.org.uk> | |
684 | ||
685 | =cut | |
686 | ||
a0d0e21e | 687 | use Carp; |
d3a7d8c7 | 688 | use warnings::register; |
a0d0e21e LW |
689 | |
690 | require Exporter; | |
da4061d3 | 691 | require XSLoader; |
c2654555 | 692 | our @ISA = qw(Exporter); |
80531fbd LB |
693 | |
694 | # <@Nicholas> you can't change @EXPORT without breaking the implicit API | |
695 | # Please put any new constants in @EXPORT_OK! | |
c2654555 CBW |
696 | |
697 | # List re-ordered to match documentation above. Try to keep the ordering | |
698 | # consistent so it's easier to see which ones are or aren't documented. | |
699 | our @EXPORT = qw( | |
700 | PF_802 PF_AAL PF_APPLETALK PF_CCITT PF_CHAOS PF_CTF PF_DATAKIT | |
701 | PF_DECnet PF_DLI PF_ECMA PF_GOSIP PF_HYLINK PF_IMPLINK PF_INET PF_INET6 | |
702 | PF_ISO PF_KEY PF_LAST PF_LAT PF_LINK PF_MAX PF_NBS PF_NIT PF_NS PF_OSI | |
703 | PF_OSINET PF_PUP PF_ROUTE PF_SNA PF_UNIX PF_UNSPEC PF_USER PF_WAN | |
a0d0e21e | 704 | PF_X25 |
c2654555 CBW |
705 | |
706 | AF_802 AF_AAL AF_APPLETALK AF_CCITT AF_CHAOS AF_CTF AF_DATAKIT | |
707 | AF_DECnet AF_DLI AF_ECMA AF_GOSIP AF_HYLINK AF_IMPLINK AF_INET AF_INET6 | |
708 | AF_ISO AF_KEY AF_LAST AF_LAT AF_LINK AF_MAX AF_NBS AF_NIT AF_NS AF_OSI | |
709 | AF_OSINET AF_PUP AF_ROUTE AF_SNA AF_UNIX AF_UNSPEC AF_USER AF_WAN | |
710 | AF_X25 | |
711 | ||
712 | SOCK_DGRAM SOCK_RAW SOCK_RDM SOCK_SEQPACKET SOCK_STREAM | |
713 | ||
a0d0e21e | 714 | SOL_SOCKET |
c2654555 CBW |
715 | |
716 | SO_ACCEPTCONN SO_ATTACH_FILTER SO_BACKLOG SO_BROADCAST SO_CHAMELEON | |
eabcd9c8 A |
717 | SO_DEBUG SO_DETACH_FILTER SO_DGRAM_ERRIND SO_DOMAIN SO_DONTLINGER |
718 | SO_DONTROUTE SO_ERROR SO_FAMILY SO_KEEPALIVE SO_LINGER SO_OOBINLINE | |
719 | SO_PASSCRED SO_PASSIFNAME SO_PEERCRED SO_PROTOCOL SO_PROTOTYPE | |
720 | SO_RCVBUF SO_RCVLOWAT SO_RCVTIMEO SO_REUSEADDR SO_REUSEPORT | |
c2654555 CBW |
721 | SO_SECURITY_AUTHENTICATION SO_SECURITY_ENCRYPTION_NETWORK |
722 | SO_SECURITY_ENCRYPTION_TRANSPORT SO_SNDBUF SO_SNDLOWAT SO_SNDTIMEO | |
723 | SO_STATE SO_TYPE SO_USELOOPBACK SO_XOPEN SO_XSE | |
724 | ||
725 | IP_OPTIONS IP_HDRINCL IP_TOS IP_TTL IP_RECVOPTS IP_RECVRETOPTS | |
726 | IP_RETOPTS | |
727 | ||
728 | MSG_BCAST MSG_BTAG MSG_CTLFLAGS MSG_CTLIGNORE MSG_CTRUNC MSG_DONTROUTE | |
06a9195c | 729 | MSG_DONTWAIT MSG_EOF MSG_EOR MSG_ERRQUEUE MSG_ETAG MSG_FIN |
c2654555 CBW |
730 | MSG_MAXIOVLEN MSG_MCAST MSG_NOSIGNAL MSG_OOB MSG_PEEK MSG_PROXY MSG_RST |
731 | MSG_SYN MSG_TRUNC MSG_URG MSG_WAITALL MSG_WIRE | |
732 | ||
733 | SHUT_RD SHUT_RDWR SHUT_WR | |
734 | ||
735 | INADDR_ANY INADDR_BROADCAST INADDR_LOOPBACK INADDR_NONE | |
736 | ||
737 | SCM_CONNECT SCM_CREDENTIALS SCM_CREDS SCM_RIGHTS SCM_TIMESTAMP | |
738 | ||
a0d0e21e | 739 | SOMAXCONN |
c2654555 CBW |
740 | |
741 | IOV_MAX | |
6b1016b5 | 742 | UIO_MAXIOV |
c2654555 CBW |
743 | |
744 | sockaddr_family | |
745 | pack_sockaddr_in unpack_sockaddr_in sockaddr_in | |
746 | pack_sockaddr_in6 unpack_sockaddr_in6 sockaddr_in6 | |
747 | pack_sockaddr_un unpack_sockaddr_un sockaddr_un | |
748 | ||
749 | inet_aton inet_ntoa | |
750 | ); | |
751 | ||
752 | # List re-ordered to match documentation above. Try to keep the ordering | |
753 | # consistent so it's easier to see which ones are or aren't documented. | |
754 | our @EXPORT_OK = qw( | |
755 | CR LF CRLF $CR $LF $CRLF | |
756 | ||
3be135d8 TC |
757 | SOCK_NONBLOCK SOCK_CLOEXEC |
758 | ||
d4ada64a SH |
759 | IP_ADD_MEMBERSHIP IP_ADD_SOURCE_MEMBERSHIP IP_DROP_MEMBERSHIP |
760 | IP_DROP_SOURCE_MEMBERSHIP IP_MULTICAST_IF IP_MULTICAST_LOOP | |
761 | IP_MULTICAST_TTL | |
3be135d8 | 762 | |
50e79584 SH |
763 | IPPROTO_IP IPPROTO_IPV6 IPPROTO_RAW IPPROTO_ICMP IPPROTO_IGMP |
764 | IPPROTO_TCP IPPROTO_UDP IPPROTO_GRE IPPROTO_ESP IPPROTO_AH | |
765 | IPPROTO_SCTP | |
c2654555 | 766 | |
a5c69419 AP |
767 | IPTOS_LOWDELAY IPTOS_THROUGHPUT IPTOS_RELIABILITY IPTOS_MINCOST |
768 | ||
06a9195c SH |
769 | TCP_CONGESTION TCP_CONNECTIONTIMEOUT TCP_CORK TCP_DEFER_ACCEPT TCP_INFO |
770 | TCP_INIT_CWND TCP_KEEPALIVE TCP_KEEPCNT TCP_KEEPIDLE TCP_KEEPINTVL | |
771 | TCP_LINGER2 TCP_MAXRT TCP_MAXSEG TCP_MD5SIG TCP_NODELAY TCP_NOOPT | |
772 | TCP_NOPUSH TCP_QUICKACK TCP_SACK_ENABLE TCP_STDURG TCP_SYNCNT | |
773 | TCP_WINDOW_CLAMP | |
c2654555 CBW |
774 | |
775 | IN6ADDR_ANY IN6ADDR_LOOPBACK | |
776 | ||
d4ada64a SH |
777 | IPV6_ADD_MEMBERSHIP IPV6_DROP_MEMBERSHIP IPV6_JOIN_GROUP |
778 | IPV6_LEAVE_GROUP IPV6_MTU IPV6_MTU_DISCOVER IPV6_MULTICAST_HOPS | |
779 | IPV6_MULTICAST_IF IPV6_MULTICAST_LOOP IPV6_UNICAST_HOPS IPV6_V6ONLY | |
c2654555 | 780 | |
d4ada64a | 781 | pack_ip_mreq unpack_ip_mreq pack_ip_mreq_source unpack_ip_mreq_source |
3be135d8 | 782 | |
c2654555 CBW |
783 | pack_ipv6_mreq unpack_ipv6_mreq |
784 | ||
785 | inet_pton inet_ntop | |
786 | ||
787 | getaddrinfo getnameinfo | |
788 | ||
789 | AI_ADDRCONFIG AI_ALL AI_CANONIDN AI_CANONNAME AI_IDN | |
790 | AI_IDN_ALLOW_UNASSIGNED AI_IDN_USE_STD3_ASCII_RULES AI_NUMERICHOST | |
791 | AI_NUMERICSERV AI_PASSIVE AI_V4MAPPED | |
792 | ||
793 | NI_DGRAM NI_IDN NI_IDN_ALLOW_UNASSIGNED NI_IDN_USE_STD3_ASCII_RULES | |
794 | NI_NAMEREQD NI_NOFQDN NI_NUMERICHOST NI_NUMERICSERV | |
795 | ||
796 | NIx_NOHOST NIx_NOSERV | |
797 | ||
798 | EAI_ADDRFAMILY EAI_AGAIN EAI_BADFLAGS EAI_BADHINTS EAI_FAIL EAI_FAMILY | |
799 | EAI_NODATA EAI_NONAME EAI_PROTOCOL EAI_SERVICE EAI_SOCKTYPE EAI_SYSTEM | |
a0d0e21e LW |
800 | ); |
801 | ||
c2654555 CBW |
802 | our %EXPORT_TAGS = ( |
803 | crlf => [qw(CR LF CRLF $CR $LF $CRLF)], | |
804 | addrinfo => [qw(getaddrinfo getnameinfo), grep m/^(?:AI|NI|NIx|EAI)_/, @EXPORT_OK], | |
805 | all => [@EXPORT, @EXPORT_OK], | |
fdb41d65 CN |
806 | ); |
807 | ||
808 | BEGIN { | |
809 | sub CR () {"\015"} | |
810 | sub LF () {"\012"} | |
811 | sub CRLF () {"\015\012"} | |
c2654555 CBW |
812 | |
813 | # These are not gni() constants; they're extensions for the perl API | |
814 | # The definitions in Socket.pm and Socket.xs must match | |
815 | sub NIx_NOHOST() {1 << 0} | |
816 | sub NIx_NOSERV() {1 << 1} | |
fdb41d65 CN |
817 | } |
818 | ||
819 | *CR = \CR(); | |
820 | *LF = \LF(); | |
821 | *CRLF = \CRLF(); | |
822 | ||
4633a7c4 LW |
823 | sub sockaddr_in { |
824 | if (@_ == 6 && !wantarray) { # perl5.001m compat; use this && die | |
825 | my($af, $port, @quad) = @_; | |
c2654555 | 826 | warnings::warn "6-ARG sockaddr_in call is deprecated" |
d3a7d8c7 | 827 | if warnings::enabled(); |
4633a7c4 LW |
828 | pack_sockaddr_in($port, inet_aton(join('.', @quad))); |
829 | } elsif (wantarray) { | |
830 | croak "usage: (port,iaddr) = sockaddr_in(sin_sv)" unless @_ == 1; | |
831 | unpack_sockaddr_in(@_); | |
832 | } else { | |
833 | croak "usage: sin_sv = sockaddr_in(port,iaddr))" unless @_ == 2; | |
834 | pack_sockaddr_in(@_); | |
835 | } | |
836 | } | |
837 | ||
4bc6101e PE |
838 | sub sockaddr_in6 { |
839 | if (wantarray) { | |
840 | croak "usage: (port,in6addr,scope_id,flowinfo) = sockaddr_in6(sin6_sv)" unless @_ == 1; | |
841 | unpack_sockaddr_in6(@_); | |
842 | } | |
843 | else { | |
844 | croak "usage: sin6_sv = sockaddr_in6(port,in6addr,[scope_id,[flowinfo]])" unless @_ >= 2 and @_ <= 4; | |
845 | pack_sockaddr_in6(@_); | |
846 | } | |
847 | } | |
848 | ||
4633a7c4 LW |
849 | sub sockaddr_un { |
850 | if (wantarray) { | |
851 | croak "usage: (filename) = sockaddr_un(sun_sv)" unless @_ == 1; | |
852 | unpack_sockaddr_un(@_); | |
853 | } else { | |
37120919 AD |
854 | croak "usage: sun_sv = sockaddr_un(filename)" unless @_ == 1; |
855 | pack_sockaddr_un(@_); | |
4633a7c4 LW |
856 | } |
857 | } | |
858 | ||
4c3d8e12 | 859 | XSLoader::load(__PACKAGE__, $VERSION); |
a0d0e21e | 860 | |
c2219427 PE |
861 | my %errstr; |
862 | ||
32b40adf NC |
863 | if( defined &getaddrinfo ) { |
864 | # These are not part of the API, nothing uses them, and deleting them | |
865 | # reduces the size of %Socket:: by about 12K | |
866 | delete $Socket::{fake_getaddrinfo}; | |
867 | delete $Socket::{fake_getnameinfo}; | |
868 | } else { | |
0f41f5e2 PE |
869 | require Scalar::Util; |
870 | ||
871 | *getaddrinfo = \&fake_getaddrinfo; | |
872 | *getnameinfo = \&fake_getnameinfo; | |
873 | ||
874 | # These numbers borrowed from GNU libc's implementation, but since | |
875 | # they're only used by our emulation, it doesn't matter if the real | |
876 | # platform's values differ | |
877 | my %constants = ( | |
878 | AI_PASSIVE => 1, | |
879 | AI_CANONNAME => 2, | |
880 | AI_NUMERICHOST => 4, | |
0369a5a5 PE |
881 | AI_V4MAPPED => 8, |
882 | AI_ALL => 16, | |
883 | AI_ADDRCONFIG => 32, | |
0f41f5e2 PE |
884 | # RFC 2553 doesn't define this but Linux does - lets be nice and |
885 | # provide it since we can | |
886 | AI_NUMERICSERV => 1024, | |
887 | ||
888 | EAI_BADFLAGS => -1, | |
889 | EAI_NONAME => -2, | |
890 | EAI_NODATA => -5, | |
891 | EAI_FAMILY => -6, | |
892 | EAI_SERVICE => -8, | |
893 | ||
894 | NI_NUMERICHOST => 1, | |
895 | NI_NUMERICSERV => 2, | |
0369a5a5 | 896 | NI_NOFQDN => 4, |
0f41f5e2 PE |
897 | NI_NAMEREQD => 8, |
898 | NI_DGRAM => 16, | |
0369a5a5 PE |
899 | |
900 | # Constants we don't support. Export them, but croak if anyone tries to | |
901 | # use them | |
902 | AI_IDN => 64, | |
903 | AI_CANONIDN => 128, | |
904 | AI_IDN_ALLOW_UNASSIGNED => 256, | |
905 | AI_IDN_USE_STD3_ASCII_RULES => 512, | |
906 | NI_IDN => 32, | |
907 | NI_IDN_ALLOW_UNASSIGNED => 64, | |
908 | NI_IDN_USE_STD3_ASCII_RULES => 128, | |
909 | ||
910 | # Error constants we'll never return, so it doesn't matter what value | |
911 | # these have, nor that we don't provide strings for them | |
912 | EAI_SYSTEM => -11, | |
913 | EAI_BADHINTS => -1000, | |
914 | EAI_PROTOCOL => -1001 | |
0f41f5e2 PE |
915 | ); |
916 | ||
917 | foreach my $name ( keys %constants ) { | |
918 | my $value = $constants{$name}; | |
919 | ||
920 | no strict 'refs'; | |
921 | defined &$name or *$name = sub () { $value }; | |
922 | } | |
923 | ||
924 | %errstr = ( | |
925 | # These strings from RFC 2553 | |
926 | EAI_BADFLAGS() => "invalid value for ai_flags", | |
927 | EAI_NONAME() => "nodename nor servname provided, or not known", | |
928 | EAI_NODATA() => "no address associated with nodename", | |
929 | EAI_FAMILY() => "ai_family not supported", | |
930 | EAI_SERVICE() => "servname not supported for ai_socktype", | |
931 | ); | |
c2219427 PE |
932 | } |
933 | ||
934 | # The following functions are used if the system does not have a | |
935 | # getaddrinfo(3) function in libc; and are used to emulate it for the AF_INET | |
936 | # family | |
937 | ||
c2219427 | 938 | # Borrowed from Regexp::Common::net |
36998252 | 939 | my $REGEXP_IPv4_DECIMAL = qr/25[0-5]|2[0-4][0-9]|[0-1]?[0-9]{1,2}/; |
c2219427 PE |
940 | my $REGEXP_IPv4_DOTTEDQUAD = qr/$REGEXP_IPv4_DECIMAL\.$REGEXP_IPv4_DECIMAL\.$REGEXP_IPv4_DECIMAL\.$REGEXP_IPv4_DECIMAL/; |
941 | ||
942 | sub fake_makeerr | |
943 | { | |
0f41f5e2 PE |
944 | my ( $errno ) = @_; |
945 | my $errstr = $errno == 0 ? "" : ( $errstr{$errno} || $errno ); | |
946 | return Scalar::Util::dualvar( $errno, $errstr ); | |
c2219427 PE |
947 | } |
948 | ||
949 | sub fake_getaddrinfo | |
950 | { | |
0f41f5e2 PE |
951 | my ( $node, $service, $hints ) = @_; |
952 | ||
953 | $node = "" unless defined $node; | |
954 | ||
955 | $service = "" unless defined $service; | |
956 | ||
957 | my ( $family, $socktype, $protocol, $flags ) = @$hints{qw( family socktype protocol flags )}; | |
958 | ||
959 | $family ||= Socket::AF_INET(); # 0 == AF_UNSPEC, which we want too | |
960 | $family == Socket::AF_INET() or return fake_makeerr( EAI_FAMILY() ); | |
961 | ||
962 | $socktype ||= 0; | |
963 | ||
964 | $protocol ||= 0; | |
965 | ||
966 | $flags ||= 0; | |
967 | ||
968 | my $flag_passive = $flags & AI_PASSIVE(); $flags &= ~AI_PASSIVE(); | |
969 | my $flag_canonname = $flags & AI_CANONNAME(); $flags &= ~AI_CANONNAME(); | |
970 | my $flag_numerichost = $flags & AI_NUMERICHOST(); $flags &= ~AI_NUMERICHOST(); | |
971 | my $flag_numericserv = $flags & AI_NUMERICSERV(); $flags &= ~AI_NUMERICSERV(); | |
972 | ||
0369a5a5 PE |
973 | # These constants don't apply to AF_INET-only lookups, so we might as well |
974 | # just ignore them. For AI_ADDRCONFIG we just presume the host has ability | |
975 | # to talk AF_INET. If not we'd have to return no addresses at all. :) | |
976 | $flags &= ~(AI_V4MAPPED()|AI_ALL()|AI_ADDRCONFIG()); | |
977 | ||
978 | $flags & (AI_IDN()|AI_CANONIDN()|AI_IDN_ALLOW_UNASSIGNED()|AI_IDN_USE_STD3_ASCII_RULES()) and | |
979 | croak "Socket::getaddrinfo() does not support IDN"; | |
980 | ||
0f41f5e2 PE |
981 | $flags == 0 or return fake_makeerr( EAI_BADFLAGS() ); |
982 | ||
983 | $node eq "" and $service eq "" and return fake_makeerr( EAI_NONAME() ); | |
984 | ||
985 | my $canonname; | |
986 | my @addrs; | |
987 | if( $node ne "" ) { | |
988 | return fake_makeerr( EAI_NONAME() ) if( $flag_numerichost and $node !~ m/^$REGEXP_IPv4_DOTTEDQUAD$/ ); | |
989 | ( $canonname, undef, undef, undef, @addrs ) = gethostbyname( $node ); | |
990 | defined $canonname or return fake_makeerr( EAI_NONAME() ); | |
991 | ||
992 | undef $canonname unless $flag_canonname; | |
993 | } | |
994 | else { | |
995 | $addrs[0] = $flag_passive ? Socket::inet_aton( "0.0.0.0" ) | |
996 | : Socket::inet_aton( "127.0.0.1" ); | |
997 | } | |
998 | ||
999 | my @ports; # Actually ARRAYrefs of [ socktype, protocol, port ] | |
1000 | my $protname = ""; | |
1001 | if( $protocol ) { | |
c6d5e127 | 1002 | $protname = eval { getprotobynumber( $protocol ) }; |
0f41f5e2 PE |
1003 | } |
1004 | ||
1005 | if( $service ne "" and $service !~ m/^\d+$/ ) { | |
1006 | return fake_makeerr( EAI_NONAME() ) if( $flag_numericserv ); | |
1007 | getservbyname( $service, $protname ) or return fake_makeerr( EAI_SERVICE() ); | |
1008 | } | |
1009 | ||
1010 | foreach my $this_socktype ( Socket::SOCK_STREAM(), Socket::SOCK_DGRAM(), Socket::SOCK_RAW() ) { | |
1011 | next if $socktype and $this_socktype != $socktype; | |
1012 | ||
1013 | my $this_protname = "raw"; | |
1014 | $this_socktype == Socket::SOCK_STREAM() and $this_protname = "tcp"; | |
1015 | $this_socktype == Socket::SOCK_DGRAM() and $this_protname = "udp"; | |
1016 | ||
1017 | next if $protname and $this_protname ne $protname; | |
1018 | ||
1019 | my $port; | |
1020 | if( $service ne "" ) { | |
1021 | if( $service =~ m/^\d+$/ ) { | |
1022 | $port = "$service"; | |
1023 | } | |
1024 | else { | |
1025 | ( undef, undef, $port, $this_protname ) = getservbyname( $service, $this_protname ); | |
1026 | next unless defined $port; | |
1027 | } | |
1028 | } | |
1029 | else { | |
1030 | $port = 0; | |
1031 | } | |
1032 | ||
c6d5e127 | 1033 | push @ports, [ $this_socktype, eval { scalar getprotobyname( $this_protname ) } || 0, $port ]; |
0f41f5e2 PE |
1034 | } |
1035 | ||
1036 | my @ret; | |
1037 | foreach my $addr ( @addrs ) { | |
1038 | foreach my $portspec ( @ports ) { | |
1039 | my ( $socktype, $protocol, $port ) = @$portspec; | |
1040 | push @ret, { | |
1041 | family => $family, | |
1042 | socktype => $socktype, | |
1043 | protocol => $protocol, | |
1044 | addr => Socket::pack_sockaddr_in( $port, $addr ), | |
0cd14f2e | 1045 | canonname => undef, |
0f41f5e2 PE |
1046 | }; |
1047 | } | |
1048 | } | |
1049 | ||
0cd14f2e PE |
1050 | # Only supply canonname for the first result |
1051 | if( defined $canonname ) { | |
1052 | $ret[0]->{canonname} = $canonname; | |
1053 | } | |
1054 | ||
0f41f5e2 | 1055 | return ( fake_makeerr( 0 ), @ret ); |
c2219427 PE |
1056 | } |
1057 | ||
1058 | sub fake_getnameinfo | |
1059 | { | |
c2654555 | 1060 | my ( $addr, $flags, $xflags ) = @_; |
0f41f5e2 PE |
1061 | |
1062 | my ( $port, $inetaddr ); | |
1063 | eval { ( $port, $inetaddr ) = Socket::unpack_sockaddr_in( $addr ) } | |
1064 | or return fake_makeerr( EAI_FAMILY() ); | |
1065 | ||
1066 | my $family = Socket::AF_INET(); | |
1067 | ||
1068 | $flags ||= 0; | |
1069 | ||
1070 | my $flag_numerichost = $flags & NI_NUMERICHOST(); $flags &= ~NI_NUMERICHOST(); | |
1071 | my $flag_numericserv = $flags & NI_NUMERICSERV(); $flags &= ~NI_NUMERICSERV(); | |
0369a5a5 | 1072 | my $flag_nofqdn = $flags & NI_NOFQDN(); $flags &= ~NI_NOFQDN(); |
0f41f5e2 PE |
1073 | my $flag_namereqd = $flags & NI_NAMEREQD(); $flags &= ~NI_NAMEREQD(); |
1074 | my $flag_dgram = $flags & NI_DGRAM() ; $flags &= ~NI_DGRAM(); | |
1075 | ||
0369a5a5 PE |
1076 | $flags & (NI_IDN()|NI_IDN_ALLOW_UNASSIGNED()|NI_IDN_USE_STD3_ASCII_RULES()) and |
1077 | croak "Socket::getnameinfo() does not support IDN"; | |
1078 | ||
0f41f5e2 PE |
1079 | $flags == 0 or return fake_makeerr( EAI_BADFLAGS() ); |
1080 | ||
c2654555 CBW |
1081 | $xflags ||= 0; |
1082 | ||
0f41f5e2 | 1083 | my $node; |
c2654555 CBW |
1084 | if( $xflags & NIx_NOHOST ) { |
1085 | $node = undef; | |
1086 | } | |
1087 | elsif( $flag_numerichost ) { | |
0f41f5e2 PE |
1088 | $node = Socket::inet_ntoa( $inetaddr ); |
1089 | } | |
1090 | else { | |
1091 | $node = gethostbyaddr( $inetaddr, $family ); | |
1092 | if( !defined $node ) { | |
1093 | return fake_makeerr( EAI_NONAME() ) if $flag_namereqd; | |
1094 | $node = Socket::inet_ntoa( $inetaddr ); | |
1095 | } | |
0369a5a5 PE |
1096 | elsif( $flag_nofqdn ) { |
1097 | my ( $shortname ) = split m/\./, $node; | |
1098 | my ( $fqdn ) = gethostbyname $shortname; | |
1099 | $node = $shortname if defined $fqdn and $fqdn eq $node; | |
1100 | } | |
0f41f5e2 PE |
1101 | } |
1102 | ||
1103 | my $service; | |
c2654555 CBW |
1104 | if( $xflags & NIx_NOSERV ) { |
1105 | $service = undef; | |
1106 | } | |
1107 | elsif( $flag_numericserv ) { | |
0f41f5e2 PE |
1108 | $service = "$port"; |
1109 | } | |
1110 | else { | |
1111 | my $protname = $flag_dgram ? "udp" : ""; | |
1112 | $service = getservbyport( $port, $protname ); | |
1113 | if( !defined $service ) { | |
1114 | $service = "$port"; | |
1115 | } | |
1116 | } | |
1117 | ||
1118 | return ( fake_makeerr( 0 ), $node, $service ); | |
c2219427 PE |
1119 | } |
1120 | ||
a0d0e21e | 1121 | 1; |