| Filename | /home/ss5/perl5/perlbrew/perls/perl-5.22.0/lib/5.22.0/x86_64-linux/Socket.pm |
| Statements | Executed 29 statements in 1.83ms |
| Calls | P | F | Exclusive Time |
Inclusive Time |
Subroutine |
|---|---|---|---|---|---|
| 2002 | 1 | 1 | 110ms | 110ms | Socket::getaddrinfo (xsub) |
| 1 | 1 | 1 | 43µs | 43µs | Socket::CORE:regcomp (opcode) |
| 103 | 1 | 1 | 13µs | 13µs | Socket::CORE:match (opcode) |
| 1 | 1 | 1 | 8µs | 9µs | Socket::BEGIN@3 |
| 1 | 1 | 1 | 6µs | 6µs | Socket::BEGIN@4 |
| 1 | 1 | 1 | 6µs | 74µs | Socket::BEGIN@688 |
| 1 | 1 | 1 | 6µs | 27µs | Socket::BEGIN@687 |
| 1 | 1 | 1 | 5µs | 13µs | Socket::BEGIN@919 |
| 1 | 1 | 1 | 2µs | 2µs | Socket::BEGIN@807 |
| 2 | 2 | 1 | 2µs | 2µs | Socket::CORE:qr (opcode) |
| 0 | 0 | 0 | 0s | 0s | Socket::__ANON__[:920] |
| 0 | 0 | 0 | 0s | 0s | Socket::fake_getaddrinfo |
| 0 | 0 | 0 | 0s | 0s | Socket::fake_getnameinfo |
| 0 | 0 | 0 | 0s | 0s | Socket::fake_makeerr |
| 0 | 0 | 0 | 0s | 0s | Socket::sockaddr_in |
| 0 | 0 | 0 | 0s | 0s | Socket::sockaddr_in6 |
| 0 | 0 | 0 | 0s | 0s | Socket::sockaddr_un |
| Line | State ments |
Time on line |
Calls | Time in subs |
Code |
|---|---|---|---|---|---|
| 1 | package Socket; | ||||
| 2 | |||||
| 3 | 2 | 14µs | 2 | 11µs | # spent 9µs (8+1) within Socket::BEGIN@3 which was called:
# once (8µs+1µs) by IO::Socket::BEGIN@13 at line 3 # spent 9µs making 1 call to Socket::BEGIN@3
# spent 2µs making 1 call to strict::import |
| 4 | 2 | 238µs | 1 | 6µs | # spent 6µs within Socket::BEGIN@4 which was called:
# once (6µs+0s) by IO::Socket::BEGIN@13 at line 4 # spent 6µs making 1 call to Socket::BEGIN@4 |
| 5 | |||||
| 6 | 2 | 700ns | our $VERSION = '2.018'; | ||
| 7 | |||||
| 8 | =head1 NAME | ||||
| 9 | |||||
| 10 | C<Socket> - networking constants and support functions | ||||
| 11 | |||||
| 12 | =head1 SYNOPSIS | ||||
| 13 | |||||
| 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. | ||||
| 32 | |||||
| 33 | =head1 DESCRIPTION | ||||
| 34 | |||||
| 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. | ||||
| 41 | |||||
| 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. | ||||
| 47 | |||||
| 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: | ||||
| 54 | |||||
| 55 | use Socket qw(:DEFAULT :crlf); | ||||
| 56 | |||||
| 57 | $sock->print("GET / HTTP/1.0$CRLF"); | ||||
| 58 | |||||
| 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. | ||||
| 62 | |||||
| 63 | =cut | ||||
| 64 | |||||
| 65 | =head1 CONSTANTS | ||||
| 66 | |||||
| 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. | ||||
| 71 | |||||
| 72 | =cut | ||||
| 73 | |||||
| 74 | =head2 PF_INET, PF_INET6, PF_UNIX, ... | ||||
| 75 | |||||
| 76 | Protocol family constants to use as the first argument to socket() or the | ||||
| 77 | value of the C<SO_DOMAIN> or C<SO_FAMILY> socket option. | ||||
| 78 | |||||
| 79 | =head2 AF_INET, AF_INET6, AF_UNIX, ... | ||||
| 80 | |||||
| 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(). | ||||
| 84 | |||||
| 85 | =head2 SOCK_STREAM, SOCK_DGRAM, SOCK_RAW, ... | ||||
| 86 | |||||
| 87 | Socket type constants to use as the second argument to socket(), or the value | ||||
| 88 | of the C<SO_TYPE> socket option. | ||||
| 89 | |||||
| 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 | |||||
| 97 | =head2 SOL_SOCKET | ||||
| 98 | |||||
| 99 | Socket option level constant for setsockopt() and getsockopt(). | ||||
| 100 | |||||
| 101 | =head2 SO_ACCEPTCONN, SO_BROADCAST, SO_ERROR, ... | ||||
| 102 | |||||
| 103 | Socket option name constants for setsockopt() and getsockopt() at the | ||||
| 104 | C<SOL_SOCKET> level. | ||||
| 105 | |||||
| 106 | =head2 IP_OPTIONS, IP_TOS, IP_TTL, ... | ||||
| 107 | |||||
| 108 | Socket option name constants for IPv4 socket options at the C<IPPROTO_IP> | ||||
| 109 | level. | ||||
| 110 | |||||
| 111 | =head2 IPTOS_LOWDELAY, IPTOS_THROUGHPUT, IPTOS_RELIABILITY, ... | ||||
| 112 | |||||
| 113 | Socket option value constants for C<IP_TOS> socket option. | ||||
| 114 | |||||
| 115 | =head2 MSG_BCAST, MSG_OOB, MSG_TRUNC, ... | ||||
| 116 | |||||
| 117 | Message flag constants for send() and recv(). | ||||
| 118 | |||||
| 119 | =head2 SHUT_RD, SHUT_RDWR, SHUT_WR | ||||
| 120 | |||||
| 121 | Direction constants for shutdown(). | ||||
| 122 | |||||
| 123 | =head2 INADDR_ANY, INADDR_BROADCAST, INADDR_LOOPBACK, INADDR_NONE | ||||
| 124 | |||||
| 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 | ||||
| 165 | |||||
| 166 | =head2 $family = sockaddr_family $sockaddr | ||||
| 167 | |||||
| 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. | ||||
| 174 | |||||
| 175 | =head2 $sockaddr = pack_sockaddr_in $port, $ip_address | ||||
| 176 | |||||
| 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(). | ||||
| 182 | |||||
| 183 | =head2 ($port, $ip_address) = unpack_sockaddr_in $sockaddr | ||||
| 184 | |||||
| 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. | ||||
| 190 | |||||
| 191 | In scalar context will return just the IP address. | ||||
| 192 | |||||
| 193 | =head2 $sockaddr = sockaddr_in $port, $ip_address | ||||
| 194 | |||||
| 195 | =head2 ($port, $ip_address) = sockaddr_in $sockaddr | ||||
| 196 | |||||
| 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. | ||||
| 201 | |||||
| 202 | Provided largely for legacy compatibility; it is better to use | ||||
| 203 | pack_sockaddr_in() or unpack_sockaddr_in() explicitly. | ||||
| 204 | |||||
| 205 | =head2 $sockaddr = pack_sockaddr_in6 $port, $ip6_address, [$scope_id, [$flowinfo]] | ||||
| 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 | ||||
| 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 | |||||
| 220 | In scalar context will return just the IP address. | ||||
| 221 | |||||
| 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. | ||||
| 245 | |||||
| 246 | =head2 $sockaddr = sockaddr_un $path | ||||
| 247 | |||||
| 248 | =head2 ($path) = sockaddr_un $sockaddr | ||||
| 249 | |||||
| 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. | ||||
| 253 | |||||
| 254 | Provided largely for legacy compatibility; it is better to use | ||||
| 255 | pack_sockaddr_un() or unpack_sockaddr_un() explicitly. | ||||
| 256 | |||||
| 257 | These are only supported if your system has E<lt>F<sys/un.h>E<gt>. | ||||
| 258 | |||||
| 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 | ||||
| 267 | |||||
| 268 | Takes an C<ip_mreq> structure. Returns a list of two elements; the IPv4 | ||||
| 269 | multicast address and interface address. | ||||
| 270 | |||||
| 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 | |||||
| 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 | ||||
| 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. | ||||
| 307 | |||||
| 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. | ||||
| 310 | |||||
| 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. | ||||
| 313 | |||||
| 314 | =head2 $string = inet_ntoa $ip_address | ||||
| 315 | |||||
| 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). | ||||
| 321 | |||||
| 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. | ||||
| 324 | |||||
| 325 | =head2 $address = inet_pton $family, $string | ||||
| 326 | |||||
| 327 | Takes an address family (such as C<AF_INET> or C<AF_INET6>) and a string | ||||
| 328 | containing a textual representation of an address in that family and | ||||
| 329 | translates that to an packed binary address structure. | ||||
| 330 | |||||
| 331 | See also getaddrinfo() for a more powerful and flexible function to look up | ||||
| 332 | socket addresses given hostnames or textual addresses. | ||||
| 333 | |||||
| 334 | =head2 $string = inet_ntop $family, $address | ||||
| 335 | |||||
| 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>. | ||||
| 339 | |||||
| 340 | See also getnameinfo() for a more powerful and flexible function to turn | ||||
| 341 | socket addresses into human-readable textual representations. | ||||
| 342 | |||||
| 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 | ||||
| 365 | |||||
| 366 | =item flags => INT | ||||
| 367 | |||||
| 368 | A bitfield containing C<AI_*> constants; see below. | ||||
| 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, | ||||
| 385 | followed by a list of address structures (if no error occurred). | ||||
| 386 | |||||
| 387 | The error value will be a dualvar; comparable to the C<EI_*> error constants, | ||||
| 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: | ||||
| 393 | |||||
| 394 | =over 4 | ||||
| 395 | |||||
| 396 | =item family => INT | ||||
| 397 | |||||
| 398 | The address family (e.g. C<AF_INET>) | ||||
| 399 | |||||
| 400 | =item socktype => INT | ||||
| 401 | |||||
| 402 | The socket type (e.g. C<SOCK_STREAM>) | ||||
| 403 | |||||
| 404 | =item protocol => INT | ||||
| 405 | |||||
| 406 | The protocol (e.g. C<IPPROTO_TCP>) | ||||
| 407 | |||||
| 408 | =item addr => STRING | ||||
| 409 | |||||
| 410 | The address in a packed string (such as would be returned by | ||||
| 411 | pack_sockaddr_in()) | ||||
| 412 | |||||
| 413 | =item canonname => STRING | ||||
| 414 | |||||
| 415 | The canonical name for the host if the C<AI_CANONNAME> flag was provided, or | ||||
| 416 | C<undef> otherwise. This field will only be present on the first returned | ||||
| 417 | address. | ||||
| 418 | |||||
| 419 | =back | ||||
| 420 | |||||
| 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 | ||||
| 427 | |||||
| 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_*> | ||||
| 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 | |||||
| 455 | The error value will be a dualvar; comparable to the C<EI_*> error constants, | ||||
| 456 | or printable as a human-readable error message string. The host and service | ||||
| 457 | names will be plain strings. | ||||
| 458 | |||||
| 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 | |||||
| 488 | =back | ||||
| 489 | |||||
| 490 | The following constants may be supplied as $xflags. | ||||
| 491 | |||||
| 492 | =over 4 | ||||
| 493 | |||||
| 494 | =item NIx_NOHOST | ||||
| 495 | |||||
| 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. | ||||
| 498 | |||||
| 499 | =item NIx_NOSERV | ||||
| 500 | |||||
| 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. | ||||
| 544 | |||||
| 545 | =back | ||||
| 546 | |||||
| 547 | =cut | ||||
| 548 | |||||
| 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 | ||||
| 585 | each in turn until it finds one that succeeds both the socket() and connect() | ||||
| 586 | calls. | ||||
| 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 | |||||
| 687 | 2 | 16µs | 2 | 48µs | # spent 27µs (6+21) within Socket::BEGIN@687 which was called:
# once (6µs+21µs) by IO::Socket::BEGIN@13 at line 687 # spent 27µs making 1 call to Socket::BEGIN@687
# spent 21µs making 1 call to Exporter::import |
| 688 | 2 | 203µs | 2 | 142µs | # spent 74µs (6+68) within Socket::BEGIN@688 which was called:
# once (6µs+68µs) by IO::Socket::BEGIN@13 at line 688 # spent 74µs making 1 call to Socket::BEGIN@688
# spent 68µs making 1 call to warnings::register::import |
| 689 | |||||
| 690 | 1 | 400ns | require Exporter; | ||
| 691 | 1 | 200ns | require XSLoader; | ||
| 692 | 1 | 4µs | our @ISA = qw(Exporter); | ||
| 693 | |||||
| 694 | # <@Nicholas> you can't change @EXPORT without breaking the implicit API | ||||
| 695 | # Please put any new constants in @EXPORT_OK! | ||||
| 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 | 1 | 8µs | 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 | ||||
| 704 | PF_X25 | ||||
| 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 | |||||
| 714 | SOL_SOCKET | ||||
| 715 | |||||
| 716 | SO_ACCEPTCONN SO_ATTACH_FILTER SO_BACKLOG SO_BROADCAST SO_CHAMELEON | ||||
| 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 | ||||
| 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 | ||||
| 729 | MSG_DONTWAIT MSG_EOF MSG_EOR MSG_ERRQUEUE MSG_ETAG MSG_FIN | ||||
| 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 | |||||
| 739 | SOMAXCONN | ||||
| 740 | |||||
| 741 | IOV_MAX | ||||
| 742 | UIO_MAXIOV | ||||
| 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 | 1 | 4µs | our @EXPORT_OK = qw( | ||
| 755 | CR LF CRLF $CR $LF $CRLF | ||||
| 756 | |||||
| 757 | SOCK_NONBLOCK SOCK_CLOEXEC | ||||
| 758 | |||||
| 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 | ||||
| 762 | |||||
| 763 | IPPROTO_IP IPPROTO_IPV6 IPPROTO_RAW IPPROTO_ICMP IPPROTO_TCP | ||||
| 764 | IPPROTO_UDP | ||||
| 765 | |||||
| 766 | IPTOS_LOWDELAY IPTOS_THROUGHPUT IPTOS_RELIABILITY IPTOS_MINCOST | ||||
| 767 | |||||
| 768 | TCP_CONGESTION TCP_CONNECTIONTIMEOUT TCP_CORK TCP_DEFER_ACCEPT TCP_INFO | ||||
| 769 | TCP_INIT_CWND TCP_KEEPALIVE TCP_KEEPCNT TCP_KEEPIDLE TCP_KEEPINTVL | ||||
| 770 | TCP_LINGER2 TCP_MAXRT TCP_MAXSEG TCP_MD5SIG TCP_NODELAY TCP_NOOPT | ||||
| 771 | TCP_NOPUSH TCP_QUICKACK TCP_SACK_ENABLE TCP_STDURG TCP_SYNCNT | ||||
| 772 | TCP_WINDOW_CLAMP | ||||
| 773 | |||||
| 774 | IN6ADDR_ANY IN6ADDR_LOOPBACK | ||||
| 775 | |||||
| 776 | IPV6_ADD_MEMBERSHIP IPV6_DROP_MEMBERSHIP IPV6_JOIN_GROUP | ||||
| 777 | IPV6_LEAVE_GROUP IPV6_MTU IPV6_MTU_DISCOVER IPV6_MULTICAST_HOPS | ||||
| 778 | IPV6_MULTICAST_IF IPV6_MULTICAST_LOOP IPV6_UNICAST_HOPS IPV6_V6ONLY | ||||
| 779 | |||||
| 780 | pack_ip_mreq unpack_ip_mreq pack_ip_mreq_source unpack_ip_mreq_source | ||||
| 781 | |||||
| 782 | pack_ipv6_mreq unpack_ipv6_mreq | ||||
| 783 | |||||
| 784 | inet_pton inet_ntop | ||||
| 785 | |||||
| 786 | getaddrinfo getnameinfo | ||||
| 787 | |||||
| 788 | AI_ADDRCONFIG AI_ALL AI_CANONIDN AI_CANONNAME AI_IDN | ||||
| 789 | AI_IDN_ALLOW_UNASSIGNED AI_IDN_USE_STD3_ASCII_RULES AI_NUMERICHOST | ||||
| 790 | AI_NUMERICSERV AI_PASSIVE AI_V4MAPPED | ||||
| 791 | |||||
| 792 | NI_DGRAM NI_IDN NI_IDN_ALLOW_UNASSIGNED NI_IDN_USE_STD3_ASCII_RULES | ||||
| 793 | NI_NAMEREQD NI_NOFQDN NI_NUMERICHOST NI_NUMERICSERV | ||||
| 794 | |||||
| 795 | NIx_NOHOST NIx_NOSERV | ||||
| 796 | |||||
| 797 | EAI_ADDRFAMILY EAI_AGAIN EAI_BADFLAGS EAI_BADHINTS EAI_FAIL EAI_FAMILY | ||||
| 798 | EAI_NODATA EAI_NONAME EAI_PROTOCOL EAI_SERVICE EAI_SOCKTYPE EAI_SYSTEM | ||||
| 799 | ); | ||||
| 800 | |||||
| 801 | 1 | 91µs | 103 | 13µs | our %EXPORT_TAGS = ( # spent 13µs making 103 calls to Socket::CORE:match, avg 122ns/call |
| 802 | crlf => [qw(CR LF CRLF $CR $LF $CRLF)], | ||||
| 803 | addrinfo => [qw(getaddrinfo getnameinfo), grep m/^(?:AI|NI|NIx|EAI)_/, @EXPORT_OK], | ||||
| 804 | all => [@EXPORT, @EXPORT_OK], | ||||
| 805 | ); | ||||
| 806 | |||||
| 807 | # spent 2µs within Socket::BEGIN@807 which was called:
# once (2µs+0s) by IO::Socket::BEGIN@13 at line 816 | ||||
| 808 | sub CR () {"\015"} | ||||
| 809 | sub LF () {"\012"} | ||||
| 810 | sub CRLF () {"\015\012"} | ||||
| 811 | |||||
| 812 | # These are not gni() constants; they're extensions for the perl API | ||||
| 813 | # The definitions in Socket.pm and Socket.xs must match | ||||
| 814 | sub NIx_NOHOST() {1 << 0} | ||||
| 815 | sub NIx_NOSERV() {1 << 1} | ||||
| 816 | 1 | 234µs | 1 | 2µs | } # spent 2µs making 1 call to Socket::BEGIN@807 |
| 817 | |||||
| 818 | 1 | 700ns | *CR = \CR(); | ||
| 819 | 1 | 200ns | *LF = \LF(); | ||
| 820 | 1 | 200ns | *CRLF = \CRLF(); | ||
| 821 | |||||
| 822 | sub sockaddr_in { | ||||
| 823 | if (@_ == 6 && !wantarray) { # perl5.001m compat; use this && die | ||||
| 824 | my($af, $port, @quad) = @_; | ||||
| 825 | warnings::warn "6-ARG sockaddr_in call is deprecated" | ||||
| 826 | if warnings::enabled(); | ||||
| 827 | pack_sockaddr_in($port, inet_aton(join('.', @quad))); | ||||
| 828 | } elsif (wantarray) { | ||||
| 829 | croak "usage: (port,iaddr) = sockaddr_in(sin_sv)" unless @_ == 1; | ||||
| 830 | unpack_sockaddr_in(@_); | ||||
| 831 | } else { | ||||
| 832 | croak "usage: sin_sv = sockaddr_in(port,iaddr))" unless @_ == 2; | ||||
| 833 | pack_sockaddr_in(@_); | ||||
| 834 | } | ||||
| 835 | } | ||||
| 836 | |||||
| 837 | sub sockaddr_in6 { | ||||
| 838 | if (wantarray) { | ||||
| 839 | croak "usage: (port,in6addr,scope_id,flowinfo) = sockaddr_in6(sin6_sv)" unless @_ == 1; | ||||
| 840 | unpack_sockaddr_in6(@_); | ||||
| 841 | } | ||||
| 842 | else { | ||||
| 843 | croak "usage: sin6_sv = sockaddr_in6(port,in6addr,[scope_id,[flowinfo]])" unless @_ >= 2 and @_ <= 4; | ||||
| 844 | pack_sockaddr_in6(@_); | ||||
| 845 | } | ||||
| 846 | } | ||||
| 847 | |||||
| 848 | sub sockaddr_un { | ||||
| 849 | if (wantarray) { | ||||
| 850 | croak "usage: (filename) = sockaddr_un(sun_sv)" unless @_ == 1; | ||||
| 851 | unpack_sockaddr_un(@_); | ||||
| 852 | } else { | ||||
| 853 | croak "usage: sun_sv = sockaddr_un(filename)" unless @_ == 1; | ||||
| 854 | pack_sockaddr_un(@_); | ||||
| 855 | } | ||||
| 856 | } | ||||
| 857 | |||||
| 858 | 1 | 244µs | 1 | 240µs | XSLoader::load(__PACKAGE__, $VERSION); # spent 240µs making 1 call to XSLoader::load |
| 859 | |||||
| 860 | 1 | 200ns | my %errstr; | ||
| 861 | |||||
| 862 | 1 | 400ns | if( defined &getaddrinfo ) { | ||
| 863 | # These are not part of the API, nothing uses them, and deleting them | ||||
| 864 | # reduces the size of %Socket:: by about 12K | ||||
| 865 | 1 | 500ns | delete $Socket::{fake_getaddrinfo}; | ||
| 866 | 1 | 400ns | delete $Socket::{fake_getnameinfo}; | ||
| 867 | } else { | ||||
| 868 | require Scalar::Util; | ||||
| 869 | |||||
| 870 | *getaddrinfo = \&fake_getaddrinfo; | ||||
| 871 | *getnameinfo = \&fake_getnameinfo; | ||||
| 872 | |||||
| 873 | # These numbers borrowed from GNU libc's implementation, but since | ||||
| 874 | # they're only used by our emulation, it doesn't matter if the real | ||||
| 875 | # platform's values differ | ||||
| 876 | my %constants = ( | ||||
| 877 | AI_PASSIVE => 1, | ||||
| 878 | AI_CANONNAME => 2, | ||||
| 879 | AI_NUMERICHOST => 4, | ||||
| 880 | AI_V4MAPPED => 8, | ||||
| 881 | AI_ALL => 16, | ||||
| 882 | AI_ADDRCONFIG => 32, | ||||
| 883 | # RFC 2553 doesn't define this but Linux does - lets be nice and | ||||
| 884 | # provide it since we can | ||||
| 885 | AI_NUMERICSERV => 1024, | ||||
| 886 | |||||
| 887 | EAI_BADFLAGS => -1, | ||||
| 888 | EAI_NONAME => -2, | ||||
| 889 | EAI_NODATA => -5, | ||||
| 890 | EAI_FAMILY => -6, | ||||
| 891 | EAI_SERVICE => -8, | ||||
| 892 | |||||
| 893 | NI_NUMERICHOST => 1, | ||||
| 894 | NI_NUMERICSERV => 2, | ||||
| 895 | NI_NOFQDN => 4, | ||||
| 896 | NI_NAMEREQD => 8, | ||||
| 897 | NI_DGRAM => 16, | ||||
| 898 | |||||
| 899 | # Constants we don't support. Export them, but croak if anyone tries to | ||||
| 900 | # use them | ||||
| 901 | AI_IDN => 64, | ||||
| 902 | AI_CANONIDN => 128, | ||||
| 903 | AI_IDN_ALLOW_UNASSIGNED => 256, | ||||
| 904 | AI_IDN_USE_STD3_ASCII_RULES => 512, | ||||
| 905 | NI_IDN => 32, | ||||
| 906 | NI_IDN_ALLOW_UNASSIGNED => 64, | ||||
| 907 | NI_IDN_USE_STD3_ASCII_RULES => 128, | ||||
| 908 | |||||
| 909 | # Error constants we'll never return, so it doesn't matter what value | ||||
| 910 | # these have, nor that we don't provide strings for them | ||||
| 911 | EAI_SYSTEM => -11, | ||||
| 912 | EAI_BADHINTS => -1000, | ||||
| 913 | EAI_PROTOCOL => -1001 | ||||
| 914 | ); | ||||
| 915 | |||||
| 916 | foreach my $name ( keys %constants ) { | ||||
| 917 | my $value = $constants{$name}; | ||||
| 918 | |||||
| 919 | 2 | 626µs | 2 | 20µs | # spent 13µs (5+7) within Socket::BEGIN@919 which was called:
# once (5µs+7µs) by IO::Socket::BEGIN@13 at line 919 # spent 13µs making 1 call to Socket::BEGIN@919
# spent 7µs making 1 call to strict::unimport |
| 920 | defined &$name or *$name = sub () { $value }; | ||||
| 921 | } | ||||
| 922 | |||||
| 923 | %errstr = ( | ||||
| 924 | # These strings from RFC 2553 | ||||
| 925 | EAI_BADFLAGS() => "invalid value for ai_flags", | ||||
| 926 | EAI_NONAME() => "nodename nor servname provided, or not known", | ||||
| 927 | EAI_NODATA() => "no address associated with nodename", | ||||
| 928 | EAI_FAMILY() => "ai_family not supported", | ||||
| 929 | EAI_SERVICE() => "servname not supported for ai_socktype", | ||||
| 930 | ); | ||||
| 931 | } | ||||
| 932 | |||||
| 933 | # The following functions are used if the system does not have a | ||||
| 934 | # getaddrinfo(3) function in libc; and are used to emulate it for the AF_INET | ||||
| 935 | # family | ||||
| 936 | |||||
| 937 | # Borrowed from Regexp::Common::net | ||||
| 938 | 1 | 6µs | 1 | 1µs | my $REGEXP_IPv4_DECIMAL = qr/25[0-5]|2[0-4][0-9]|[0-1]?[0-9]{1,2}/; # spent 1µs making 1 call to Socket::CORE:qr |
| 939 | 1 | 60µs | 2 | 44µs | my $REGEXP_IPv4_DOTTEDQUAD = qr/$REGEXP_IPv4_DECIMAL\.$REGEXP_IPv4_DECIMAL\.$REGEXP_IPv4_DECIMAL\.$REGEXP_IPv4_DECIMAL/; # spent 43µs making 1 call to Socket::CORE:regcomp
# spent 600ns making 1 call to Socket::CORE:qr |
| 940 | |||||
| 941 | sub fake_makeerr | ||||
| 942 | { | ||||
| 943 | my ( $errno ) = @_; | ||||
| 944 | my $errstr = $errno == 0 ? "" : ( $errstr{$errno} || $errno ); | ||||
| 945 | return Scalar::Util::dualvar( $errno, $errstr ); | ||||
| 946 | } | ||||
| 947 | |||||
| 948 | sub fake_getaddrinfo | ||||
| 949 | { | ||||
| 950 | my ( $node, $service, $hints ) = @_; | ||||
| 951 | |||||
| 952 | $node = "" unless defined $node; | ||||
| 953 | |||||
| 954 | $service = "" unless defined $service; | ||||
| 955 | |||||
| 956 | my ( $family, $socktype, $protocol, $flags ) = @$hints{qw( family socktype protocol flags )}; | ||||
| 957 | |||||
| 958 | $family ||= Socket::AF_INET(); # 0 == AF_UNSPEC, which we want too | ||||
| 959 | $family == Socket::AF_INET() or return fake_makeerr( EAI_FAMILY() ); | ||||
| 960 | |||||
| 961 | $socktype ||= 0; | ||||
| 962 | |||||
| 963 | $protocol ||= 0; | ||||
| 964 | |||||
| 965 | $flags ||= 0; | ||||
| 966 | |||||
| 967 | my $flag_passive = $flags & AI_PASSIVE(); $flags &= ~AI_PASSIVE(); | ||||
| 968 | my $flag_canonname = $flags & AI_CANONNAME(); $flags &= ~AI_CANONNAME(); | ||||
| 969 | my $flag_numerichost = $flags & AI_NUMERICHOST(); $flags &= ~AI_NUMERICHOST(); | ||||
| 970 | my $flag_numericserv = $flags & AI_NUMERICSERV(); $flags &= ~AI_NUMERICSERV(); | ||||
| 971 | |||||
| 972 | # These constants don't apply to AF_INET-only lookups, so we might as well | ||||
| 973 | # just ignore them. For AI_ADDRCONFIG we just presume the host has ability | ||||
| 974 | # to talk AF_INET. If not we'd have to return no addresses at all. :) | ||||
| 975 | $flags &= ~(AI_V4MAPPED()|AI_ALL()|AI_ADDRCONFIG()); | ||||
| 976 | |||||
| 977 | $flags & (AI_IDN()|AI_CANONIDN()|AI_IDN_ALLOW_UNASSIGNED()|AI_IDN_USE_STD3_ASCII_RULES()) and | ||||
| 978 | croak "Socket::getaddrinfo() does not support IDN"; | ||||
| 979 | |||||
| 980 | $flags == 0 or return fake_makeerr( EAI_BADFLAGS() ); | ||||
| 981 | |||||
| 982 | $node eq "" and $service eq "" and return fake_makeerr( EAI_NONAME() ); | ||||
| 983 | |||||
| 984 | my $canonname; | ||||
| 985 | my @addrs; | ||||
| 986 | if( $node ne "" ) { | ||||
| 987 | return fake_makeerr( EAI_NONAME() ) if( $flag_numerichost and $node !~ m/^$REGEXP_IPv4_DOTTEDQUAD$/ ); | ||||
| 988 | ( $canonname, undef, undef, undef, @addrs ) = gethostbyname( $node ); | ||||
| 989 | defined $canonname or return fake_makeerr( EAI_NONAME() ); | ||||
| 990 | |||||
| 991 | undef $canonname unless $flag_canonname; | ||||
| 992 | } | ||||
| 993 | else { | ||||
| 994 | $addrs[0] = $flag_passive ? Socket::inet_aton( "0.0.0.0" ) | ||||
| 995 | : Socket::inet_aton( "127.0.0.1" ); | ||||
| 996 | } | ||||
| 997 | |||||
| 998 | my @ports; # Actually ARRAYrefs of [ socktype, protocol, port ] | ||||
| 999 | my $protname = ""; | ||||
| 1000 | if( $protocol ) { | ||||
| 1001 | $protname = eval { getprotobynumber( $protocol ) }; | ||||
| 1002 | } | ||||
| 1003 | |||||
| 1004 | if( $service ne "" and $service !~ m/^\d+$/ ) { | ||||
| 1005 | return fake_makeerr( EAI_NONAME() ) if( $flag_numericserv ); | ||||
| 1006 | getservbyname( $service, $protname ) or return fake_makeerr( EAI_SERVICE() ); | ||||
| 1007 | } | ||||
| 1008 | |||||
| 1009 | foreach my $this_socktype ( Socket::SOCK_STREAM(), Socket::SOCK_DGRAM(), Socket::SOCK_RAW() ) { | ||||
| 1010 | next if $socktype and $this_socktype != $socktype; | ||||
| 1011 | |||||
| 1012 | my $this_protname = "raw"; | ||||
| 1013 | $this_socktype == Socket::SOCK_STREAM() and $this_protname = "tcp"; | ||||
| 1014 | $this_socktype == Socket::SOCK_DGRAM() and $this_protname = "udp"; | ||||
| 1015 | |||||
| 1016 | next if $protname and $this_protname ne $protname; | ||||
| 1017 | |||||
| 1018 | my $port; | ||||
| 1019 | if( $service ne "" ) { | ||||
| 1020 | if( $service =~ m/^\d+$/ ) { | ||||
| 1021 | $port = "$service"; | ||||
| 1022 | } | ||||
| 1023 | else { | ||||
| 1024 | ( undef, undef, $port, $this_protname ) = getservbyname( $service, $this_protname ); | ||||
| 1025 | next unless defined $port; | ||||
| 1026 | } | ||||
| 1027 | } | ||||
| 1028 | else { | ||||
| 1029 | $port = 0; | ||||
| 1030 | } | ||||
| 1031 | |||||
| 1032 | push @ports, [ $this_socktype, eval { scalar getprotobyname( $this_protname ) } || 0, $port ]; | ||||
| 1033 | } | ||||
| 1034 | |||||
| 1035 | my @ret; | ||||
| 1036 | foreach my $addr ( @addrs ) { | ||||
| 1037 | foreach my $portspec ( @ports ) { | ||||
| 1038 | my ( $socktype, $protocol, $port ) = @$portspec; | ||||
| 1039 | push @ret, { | ||||
| 1040 | family => $family, | ||||
| 1041 | socktype => $socktype, | ||||
| 1042 | protocol => $protocol, | ||||
| 1043 | addr => Socket::pack_sockaddr_in( $port, $addr ), | ||||
| 1044 | canonname => undef, | ||||
| 1045 | }; | ||||
| 1046 | } | ||||
| 1047 | } | ||||
| 1048 | |||||
| 1049 | # Only supply canonname for the first result | ||||
| 1050 | if( defined $canonname ) { | ||||
| 1051 | $ret[0]->{canonname} = $canonname; | ||||
| 1052 | } | ||||
| 1053 | |||||
| 1054 | return ( fake_makeerr( 0 ), @ret ); | ||||
| 1055 | } | ||||
| 1056 | |||||
| 1057 | sub fake_getnameinfo | ||||
| 1058 | { | ||||
| 1059 | my ( $addr, $flags, $xflags ) = @_; | ||||
| 1060 | |||||
| 1061 | my ( $port, $inetaddr ); | ||||
| 1062 | eval { ( $port, $inetaddr ) = Socket::unpack_sockaddr_in( $addr ) } | ||||
| 1063 | or return fake_makeerr( EAI_FAMILY() ); | ||||
| 1064 | |||||
| 1065 | my $family = Socket::AF_INET(); | ||||
| 1066 | |||||
| 1067 | $flags ||= 0; | ||||
| 1068 | |||||
| 1069 | my $flag_numerichost = $flags & NI_NUMERICHOST(); $flags &= ~NI_NUMERICHOST(); | ||||
| 1070 | my $flag_numericserv = $flags & NI_NUMERICSERV(); $flags &= ~NI_NUMERICSERV(); | ||||
| 1071 | my $flag_nofqdn = $flags & NI_NOFQDN(); $flags &= ~NI_NOFQDN(); | ||||
| 1072 | my $flag_namereqd = $flags & NI_NAMEREQD(); $flags &= ~NI_NAMEREQD(); | ||||
| 1073 | my $flag_dgram = $flags & NI_DGRAM() ; $flags &= ~NI_DGRAM(); | ||||
| 1074 | |||||
| 1075 | $flags & (NI_IDN()|NI_IDN_ALLOW_UNASSIGNED()|NI_IDN_USE_STD3_ASCII_RULES()) and | ||||
| 1076 | croak "Socket::getnameinfo() does not support IDN"; | ||||
| 1077 | |||||
| 1078 | $flags == 0 or return fake_makeerr( EAI_BADFLAGS() ); | ||||
| 1079 | |||||
| 1080 | $xflags ||= 0; | ||||
| 1081 | |||||
| 1082 | my $node; | ||||
| 1083 | if( $xflags & NIx_NOHOST ) { | ||||
| 1084 | $node = undef; | ||||
| 1085 | } | ||||
| 1086 | elsif( $flag_numerichost ) { | ||||
| 1087 | $node = Socket::inet_ntoa( $inetaddr ); | ||||
| 1088 | } | ||||
| 1089 | else { | ||||
| 1090 | $node = gethostbyaddr( $inetaddr, $family ); | ||||
| 1091 | if( !defined $node ) { | ||||
| 1092 | return fake_makeerr( EAI_NONAME() ) if $flag_namereqd; | ||||
| 1093 | $node = Socket::inet_ntoa( $inetaddr ); | ||||
| 1094 | } | ||||
| 1095 | elsif( $flag_nofqdn ) { | ||||
| 1096 | my ( $shortname ) = split m/\./, $node; | ||||
| 1097 | my ( $fqdn ) = gethostbyname $shortname; | ||||
| 1098 | $node = $shortname if defined $fqdn and $fqdn eq $node; | ||||
| 1099 | } | ||||
| 1100 | } | ||||
| 1101 | |||||
| 1102 | my $service; | ||||
| 1103 | if( $xflags & NIx_NOSERV ) { | ||||
| 1104 | $service = undef; | ||||
| 1105 | } | ||||
| 1106 | elsif( $flag_numericserv ) { | ||||
| 1107 | $service = "$port"; | ||||
| 1108 | } | ||||
| 1109 | else { | ||||
| 1110 | my $protname = $flag_dgram ? "udp" : ""; | ||||
| 1111 | $service = getservbyport( $port, $protname ); | ||||
| 1112 | if( !defined $service ) { | ||||
| 1113 | $service = "$port"; | ||||
| 1114 | } | ||||
| 1115 | } | ||||
| 1116 | |||||
| 1117 | return ( fake_makeerr( 0 ), $node, $service ); | ||||
| 1118 | } | ||||
| 1119 | |||||
| 1120 | 1 | 82µs | 1; | ||
# spent 13µs within Socket::CORE:match which was called 103 times, avg 122ns/call:
# 103 times (13µs+0s) by IO::Socket::BEGIN@13 at line 801, avg 122ns/call | |||||
sub Socket::CORE:qr; # opcode | |||||
# spent 43µs within Socket::CORE:regcomp which was called:
# once (43µs+0s) by IO::Socket::BEGIN@13 at line 939 | |||||
# spent 110ms within Socket::getaddrinfo which was called 2002 times, avg 55µs/call:
# 2002 times (110ms+0s) by IO::Socket::IP::_io_socket_ip__configure at line 494 of IO/Socket/IP.pm, avg 55µs/call |