| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "Socket 3perl" |
| 58 |
.TH Socket 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
"Socket" \- networking constants and support functions |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
\&\f(CW\*(C`Socket\*(C'\fR a low-level module used by, among other things, the IO::Socket |
| 68 |
family of modules. The following examples demonstrate some low-level uses but |
| 69 |
a practical program would likely use the higher-level API provided by |
| 70 |
\&\f(CW\*(C`IO::Socket\*(C'\fR or similar instead. |
| 71 |
.PP |
| 72 |
.Vb 1 |
| 73 |
\& use Socket qw(PF_INET SOCK_STREAM pack_sockaddr_in inet_aton); |
| 74 |
\& |
| 75 |
\& socket(my $socket, PF_INET, SOCK_STREAM, 0) |
| 76 |
\& or die "socket: $!"; |
| 77 |
\& |
| 78 |
\& my $port = getservbyname "echo", "tcp"; |
| 79 |
\& connect($socket, pack_sockaddr_in($port, inet_aton("localhost"))) |
| 80 |
\& or die "connect: $!"; |
| 81 |
\& |
| 82 |
\& print $socket "Hello, world!\en"; |
| 83 |
\& print <$socket>; |
| 84 |
.Ve |
| 85 |
.PP |
| 86 |
See also the "EXAMPLES" section. |
| 87 |
.SH DESCRIPTION |
| 88 |
.IX Header "DESCRIPTION" |
| 89 |
This module provides a variety of constants, structure manipulators and other |
| 90 |
functions related to socket-based networking. The values and functions |
| 91 |
provided are useful when used in conjunction with Perl core functions such as |
| 92 |
\&\fBsocket()\fR, \fBsetsockopt()\fR and \fBbind()\fR. It also provides several other support |
| 93 |
functions, mostly for dealing with conversions of network addresses between |
| 94 |
human-readable and native binary forms, and for hostname resolver operations. |
| 95 |
.PP |
| 96 |
Some constants and functions are exported by default by this module; but for |
| 97 |
backward-compatibility any recently-added symbols are not exported by default |
| 98 |
and must be requested explicitly. When an import list is provided to the |
| 99 |
\&\f(CW\*(C`use Socket\*(C'\fR line, the default exports are not automatically imported. It is |
| 100 |
therefore best practice to always to explicitly list all the symbols required. |
| 101 |
.PP |
| 102 |
Also, some common socket "newline" constants are provided: the constants |
| 103 |
\&\f(CW\*(C`CR\*(C'\fR, \f(CW\*(C`LF\*(C'\fR, and \f(CW\*(C`CRLF\*(C'\fR, as well as \f(CW$CR\fR, \f(CW$LF\fR, and \f(CW$CRLF\fR, which map |
| 104 |
to \f(CW\*(C`\e015\*(C'\fR, \f(CW\*(C`\e012\*(C'\fR, and \f(CW\*(C`\e015\e012\*(C'\fR. If you do not want to use the literal |
| 105 |
characters in your programs, then use the constants provided here. They are |
| 106 |
not exported by default, but can be imported individually, and with the |
| 107 |
\&\f(CW\*(C`:crlf\*(C'\fR export tag: |
| 108 |
.PP |
| 109 |
.Vb 1 |
| 110 |
\& use Socket qw(:DEFAULT :crlf); |
| 111 |
\& |
| 112 |
\& $sock\->print("GET / HTTP/1.0$CRLF"); |
| 113 |
.Ve |
| 114 |
.PP |
| 115 |
The entire \fBgetaddrinfo()\fR subsystem can be exported using the tag \f(CW\*(C`:addrinfo\*(C'\fR; |
| 116 |
this exports the \fBgetaddrinfo()\fR and \fBgetnameinfo()\fR functions, and all the |
| 117 |
\&\f(CW\*(C`AI_*\*(C'\fR, \f(CW\*(C`NI_*\*(C'\fR, \f(CW\*(C`NIx_*\*(C'\fR and \f(CW\*(C`EAI_*\*(C'\fR constants. |
| 118 |
.SH CONSTANTS |
| 119 |
.IX Header "CONSTANTS" |
| 120 |
In each of the following groups, there may be many more constants provided |
| 121 |
than just the ones given as examples in the section heading. If the heading |
| 122 |
ends \f(CW\*(C`...\*(C'\fR then this means there are likely more; the exact constants |
| 123 |
provided will depend on the OS and headers found at compile-time. |
| 124 |
.SS "PF_INET, PF_INET6, PF_UNIX, ..." |
| 125 |
.IX Subsection "PF_INET, PF_INET6, PF_UNIX, ..." |
| 126 |
Protocol family constants to use as the first argument to \fBsocket()\fR or the |
| 127 |
value of the \f(CW\*(C`SO_DOMAIN\*(C'\fR or \f(CW\*(C`SO_FAMILY\*(C'\fR socket option. |
| 128 |
.SS "AF_INET, AF_INET6, AF_UNIX, ..." |
| 129 |
.IX Subsection "AF_INET, AF_INET6, AF_UNIX, ..." |
| 130 |
Address family constants used by the socket address structures, to pass to |
| 131 |
such functions as \fBinet_pton()\fR or \fBgetaddrinfo()\fR, or are returned by such |
| 132 |
functions as \fBsockaddr_family()\fR. |
| 133 |
.SS "SOCK_STREAM, SOCK_DGRAM, SOCK_RAW, ..." |
| 134 |
.IX Subsection "SOCK_STREAM, SOCK_DGRAM, SOCK_RAW, ..." |
| 135 |
Socket type constants to use as the second argument to \fBsocket()\fR, or the value |
| 136 |
of the \f(CW\*(C`SO_TYPE\*(C'\fR socket option. |
| 137 |
.SS "SOCK_NONBLOCK. SOCK_CLOEXEC" |
| 138 |
.IX Subsection "SOCK_NONBLOCK. SOCK_CLOEXEC" |
| 139 |
Linux-specific shortcuts to specify the \f(CW\*(C`O_NONBLOCK\*(C'\fR and \f(CW\*(C`FD_CLOEXEC\*(C'\fR flags |
| 140 |
during a \f(CWsocket(2)\fR call. |
| 141 |
.PP |
| 142 |
.Vb 1 |
| 143 |
\& socket( my $sockh, PF_INET, SOCK_DGRAM|SOCK_NONBLOCK, 0 ) |
| 144 |
.Ve |
| 145 |
.SS SOL_SOCKET |
| 146 |
.IX Subsection "SOL_SOCKET" |
| 147 |
Socket option level constant for \fBsetsockopt()\fR and \fBgetsockopt()\fR. |
| 148 |
.SS "SO_ACCEPTCONN, SO_BROADCAST, SO_ERROR, ..." |
| 149 |
.IX Subsection "SO_ACCEPTCONN, SO_BROADCAST, SO_ERROR, ..." |
| 150 |
Socket option name constants for \fBsetsockopt()\fR and \fBgetsockopt()\fR at the |
| 151 |
\&\f(CW\*(C`SOL_SOCKET\*(C'\fR level. |
| 152 |
.SS "IP_OPTIONS, IP_TOS, IP_TTL, ..." |
| 153 |
.IX Subsection "IP_OPTIONS, IP_TOS, IP_TTL, ..." |
| 154 |
Socket option name constants for IPv4 socket options at the \f(CW\*(C`IPPROTO_IP\*(C'\fR |
| 155 |
level. |
| 156 |
.SS "IP_PMTUDISC_WANT, IP_PMTUDISC_DONT, ..." |
| 157 |
.IX Subsection "IP_PMTUDISC_WANT, IP_PMTUDISC_DONT, ..." |
| 158 |
Socket option value constants for \f(CW\*(C`IP_MTU_DISCOVER\*(C'\fR socket option. |
| 159 |
.SS "IPTOS_LOWDELAY, IPTOS_THROUGHPUT, IPTOS_RELIABILITY, ..." |
| 160 |
.IX Subsection "IPTOS_LOWDELAY, IPTOS_THROUGHPUT, IPTOS_RELIABILITY, ..." |
| 161 |
Socket option value constants for \f(CW\*(C`IP_TOS\*(C'\fR socket option. |
| 162 |
.SS "MSG_BCAST, MSG_OOB, MSG_TRUNC, ..." |
| 163 |
.IX Subsection "MSG_BCAST, MSG_OOB, MSG_TRUNC, ..." |
| 164 |
Message flag constants for \fBsend()\fR and \fBrecv()\fR. |
| 165 |
.SS "SHUT_RD, SHUT_RDWR, SHUT_WR" |
| 166 |
.IX Subsection "SHUT_RD, SHUT_RDWR, SHUT_WR" |
| 167 |
Direction constants for \fBshutdown()\fR. |
| 168 |
.SS "INADDR_ANY, INADDR_BROADCAST, INADDR_LOOPBACK, INADDR_NONE" |
| 169 |
.IX Subsection "INADDR_ANY, INADDR_BROADCAST, INADDR_LOOPBACK, INADDR_NONE" |
| 170 |
Constants giving the special \f(CW\*(C`AF_INET\*(C'\fR addresses for wildcard, broadcast, |
| 171 |
local loopback, and invalid addresses. |
| 172 |
.PP |
| 173 |
Normally equivalent to inet_aton('0.0.0.0'), inet_aton('255.255.255.255'), |
| 174 |
inet_aton('localhost') and inet_aton('255.255.255.255') respectively. |
| 175 |
.SS "IPPROTO_IP, IPPROTO_IPV6, IPPROTO_TCP, ..." |
| 176 |
.IX Subsection "IPPROTO_IP, IPPROTO_IPV6, IPPROTO_TCP, ..." |
| 177 |
IP protocol constants to use as the third argument to \fBsocket()\fR, the level |
| 178 |
argument to \fBgetsockopt()\fR or \fBsetsockopt()\fR, or the value of the \f(CW\*(C`SO_PROTOCOL\*(C'\fR |
| 179 |
socket option. |
| 180 |
.SS "TCP_CORK, TCP_KEEPALIVE, TCP_NODELAY, ..." |
| 181 |
.IX Subsection "TCP_CORK, TCP_KEEPALIVE, TCP_NODELAY, ..." |
| 182 |
Socket option name constants for TCP socket options at the \f(CW\*(C`IPPROTO_TCP\*(C'\fR |
| 183 |
level. |
| 184 |
.SS "IN6ADDR_ANY, IN6ADDR_LOOPBACK" |
| 185 |
.IX Subsection "IN6ADDR_ANY, IN6ADDR_LOOPBACK" |
| 186 |
Constants giving the special \f(CW\*(C`AF_INET6\*(C'\fR addresses for wildcard and local |
| 187 |
loopback. |
| 188 |
.PP |
| 189 |
Normally equivalent to inet_pton(AF_INET6, "::") and |
| 190 |
inet_pton(AF_INET6, "::1") respectively. |
| 191 |
.SS "IPV6_ADD_MEMBERSHIP, IPV6_MTU, IPV6_V6ONLY, ..." |
| 192 |
.IX Subsection "IPV6_ADD_MEMBERSHIP, IPV6_MTU, IPV6_V6ONLY, ..." |
| 193 |
Socket option name constants for IPv6 socket options at the \f(CW\*(C`IPPROTO_IPV6\*(C'\fR |
| 194 |
level. |
| 195 |
.SH "STRUCTURE MANIPULATORS" |
| 196 |
.IX Header "STRUCTURE MANIPULATORS" |
| 197 |
The following functions convert between lists of Perl values and packed binary |
| 198 |
strings representing structures. |
| 199 |
.ie n .SS "$family = sockaddr_family $sockaddr" |
| 200 |
.el .SS "\f(CW$family\fP = sockaddr_family \f(CW$sockaddr\fP" |
| 201 |
.IX Subsection "$family = sockaddr_family $sockaddr" |
| 202 |
Takes a packed socket address (as returned by \fBpack_sockaddr_in()\fR, |
| 203 |
\&\fBpack_sockaddr_un()\fR or the perl builtin functions \fBgetsockname()\fR and |
| 204 |
\&\fBgetpeername()\fR). Returns the address family tag. This will be one of the |
| 205 |
\&\f(CW\*(C`AF_*\*(C'\fR constants, such as \f(CW\*(C`AF_INET\*(C'\fR for a \f(CW\*(C`sockaddr_in\*(C'\fR addresses or |
| 206 |
\&\f(CW\*(C`AF_UNIX\*(C'\fR for a \f(CW\*(C`sockaddr_un\*(C'\fR. It can be used to figure out what unpack to |
| 207 |
use for a sockaddr of unknown type. |
| 208 |
.ie n .SS "$sockaddr = pack_sockaddr_in $port, $ip_address" |
| 209 |
.el .SS "\f(CW$sockaddr\fP = pack_sockaddr_in \f(CW$port\fP, \f(CW$ip_address\fP" |
| 210 |
.IX Subsection "$sockaddr = pack_sockaddr_in $port, $ip_address" |
| 211 |
Takes two arguments, a port number and an opaque string (as returned by |
| 212 |
\&\fBinet_aton()\fR, or a v\-string). Returns the \f(CW\*(C`sockaddr_in\*(C'\fR structure with those |
| 213 |
arguments packed in and \f(CW\*(C`AF_INET\*(C'\fR filled in. For Internet domain sockets, |
| 214 |
this structure is normally what you need for the arguments in \fBbind()\fR, |
| 215 |
\&\fBconnect()\fR, and \fBsend()\fR. |
| 216 |
.PP |
| 217 |
An undefined \f(CW$port\fR argument is taken as zero; an undefined \f(CW$ip_address\fR is |
| 218 |
considered a fatal error. |
| 219 |
.ie n .SS "($port, $ip_address) = unpack_sockaddr_in $sockaddr" |
| 220 |
.el .SS "($port, \f(CW$ip_address\fP) = unpack_sockaddr_in \f(CW$sockaddr\fP" |
| 221 |
.IX Subsection "($port, $ip_address) = unpack_sockaddr_in $sockaddr" |
| 222 |
Takes a \f(CW\*(C`sockaddr_in\*(C'\fR structure (as returned by \fBpack_sockaddr_in()\fR, |
| 223 |
\&\fBgetpeername()\fR or \fBrecv()\fR). Returns a list of two elements: the port and an |
| 224 |
opaque string representing the IP address (you can use \fBinet_ntoa()\fR to convert |
| 225 |
the address to the four-dotted numeric format). Will croak if the structure |
| 226 |
does not represent an \f(CW\*(C`AF_INET\*(C'\fR address. |
| 227 |
.PP |
| 228 |
In scalar context will return just the IP address. |
| 229 |
.ie n .SS "$sockaddr = sockaddr_in $port, $ip_address" |
| 230 |
.el .SS "\f(CW$sockaddr\fP = sockaddr_in \f(CW$port\fP, \f(CW$ip_address\fP" |
| 231 |
.IX Subsection "$sockaddr = sockaddr_in $port, $ip_address" |
| 232 |
.ie n .SS "($port, $ip_address) = sockaddr_in $sockaddr" |
| 233 |
.el .SS "($port, \f(CW$ip_address\fP) = sockaddr_in \f(CW$sockaddr\fP" |
| 234 |
.IX Subsection "($port, $ip_address) = sockaddr_in $sockaddr" |
| 235 |
A wrapper of \fBpack_sockaddr_in()\fR or \fBunpack_sockaddr_in()\fR. In list context, |
| 236 |
unpacks its argument and returns a list consisting of the port and IP address. |
| 237 |
In scalar context, packs its port and IP address arguments as a \f(CW\*(C`sockaddr_in\*(C'\fR |
| 238 |
and returns it. |
| 239 |
.PP |
| 240 |
Provided largely for legacy compatibility; it is better to use |
| 241 |
\&\fBpack_sockaddr_in()\fR or \fBunpack_sockaddr_in()\fR explicitly. |
| 242 |
.ie n .SS "$sockaddr = pack_sockaddr_in6 $port, $ip6_address, [$scope_id, [$flowinfo]]" |
| 243 |
.el .SS "\f(CW$sockaddr\fP = pack_sockaddr_in6 \f(CW$port\fP, \f(CW$ip6_address\fP, [$scope_id, [$flowinfo]]" |
| 244 |
.IX Subsection "$sockaddr = pack_sockaddr_in6 $port, $ip6_address, [$scope_id, [$flowinfo]]" |
| 245 |
Takes two to four arguments, a port number, an opaque string (as returned by |
| 246 |
\&\fBinet_pton()\fR), optionally a scope ID number, and optionally a flow label |
| 247 |
number. Returns the \f(CW\*(C`sockaddr_in6\*(C'\fR structure with those arguments packed in |
| 248 |
and \f(CW\*(C`AF_INET6\*(C'\fR filled in. IPv6 equivalent of \fBpack_sockaddr_in()\fR. |
| 249 |
.PP |
| 250 |
An undefined \f(CW$port\fR argument is taken as zero; an undefined \f(CW$ip6_address\fR is |
| 251 |
considered a fatal error. |
| 252 |
.ie n .SS "($port, $ip6_address, $scope_id, $flowinfo) = unpack_sockaddr_in6 $sockaddr" |
| 253 |
.el .SS "($port, \f(CW$ip6_address\fP, \f(CW$scope_id\fP, \f(CW$flowinfo\fP) = unpack_sockaddr_in6 \f(CW$sockaddr\fP" |
| 254 |
.IX Subsection "($port, $ip6_address, $scope_id, $flowinfo) = unpack_sockaddr_in6 $sockaddr" |
| 255 |
Takes a \f(CW\*(C`sockaddr_in6\*(C'\fR structure. Returns a list of four elements: the port |
| 256 |
number, an opaque string representing the IPv6 address, the scope ID, and the |
| 257 |
flow label. (You can use \fBinet_ntop()\fR to convert the address to the usual |
| 258 |
string format). Will croak if the structure does not represent an \f(CW\*(C`AF_INET6\*(C'\fR |
| 259 |
address. |
| 260 |
.PP |
| 261 |
In scalar context will return just the IP address. |
| 262 |
.ie n .SS "$sockaddr = sockaddr_in6 $port, $ip6_address, [$scope_id, [$flowinfo]]" |
| 263 |
.el .SS "\f(CW$sockaddr\fP = sockaddr_in6 \f(CW$port\fP, \f(CW$ip6_address\fP, [$scope_id, [$flowinfo]]" |
| 264 |
.IX Subsection "$sockaddr = sockaddr_in6 $port, $ip6_address, [$scope_id, [$flowinfo]]" |
| 265 |
.ie n .SS "($port, $ip6_address, $scope_id, $flowinfo) = sockaddr_in6 $sockaddr" |
| 266 |
.el .SS "($port, \f(CW$ip6_address\fP, \f(CW$scope_id\fP, \f(CW$flowinfo\fP) = sockaddr_in6 \f(CW$sockaddr\fP" |
| 267 |
.IX Subsection "($port, $ip6_address, $scope_id, $flowinfo) = sockaddr_in6 $sockaddr" |
| 268 |
A wrapper of \fBpack_sockaddr_in6()\fR or \fBunpack_sockaddr_in6()\fR. In list context, |
| 269 |
unpacks its argument according to \fBunpack_sockaddr_in6()\fR. In scalar context, |
| 270 |
packs its arguments according to \fBpack_sockaddr_in6()\fR. |
| 271 |
.PP |
| 272 |
Provided largely for legacy compatibility; it is better to use |
| 273 |
\&\fBpack_sockaddr_in6()\fR or \fBunpack_sockaddr_in6()\fR explicitly. |
| 274 |
.ie n .SS "$sockaddr = pack_sockaddr_un $path" |
| 275 |
.el .SS "\f(CW$sockaddr\fP = pack_sockaddr_un \f(CW$path\fP" |
| 276 |
.IX Subsection "$sockaddr = pack_sockaddr_un $path" |
| 277 |
Takes one argument, a pathname. Returns the \f(CW\*(C`sockaddr_un\*(C'\fR structure with that |
| 278 |
path packed in with \f(CW\*(C`AF_UNIX\*(C'\fR filled in. For \f(CW\*(C`PF_UNIX\*(C'\fR sockets, this |
| 279 |
structure is normally what you need for the arguments in \fBbind()\fR, \fBconnect()\fR, |
| 280 |
and \fBsend()\fR. |
| 281 |
.ie n .SS "($path) = unpack_sockaddr_un $sockaddr" |
| 282 |
.el .SS "($path) = unpack_sockaddr_un \f(CW$sockaddr\fP" |
| 283 |
.IX Subsection "($path) = unpack_sockaddr_un $sockaddr" |
| 284 |
Takes a \f(CW\*(C`sockaddr_un\*(C'\fR structure (as returned by \fBpack_sockaddr_un()\fR, |
| 285 |
\&\fBgetpeername()\fR or \fBrecv()\fR). Returns a list of one element: the pathname. Will |
| 286 |
croak if the structure does not represent an \f(CW\*(C`AF_UNIX\*(C'\fR address. |
| 287 |
.ie n .SS "$sockaddr = sockaddr_un $path" |
| 288 |
.el .SS "\f(CW$sockaddr\fP = sockaddr_un \f(CW$path\fP" |
| 289 |
.IX Subsection "$sockaddr = sockaddr_un $path" |
| 290 |
.ie n .SS "($path) = sockaddr_un $sockaddr" |
| 291 |
.el .SS "($path) = sockaddr_un \f(CW$sockaddr\fP" |
| 292 |
.IX Subsection "($path) = sockaddr_un $sockaddr" |
| 293 |
A wrapper of \fBpack_sockaddr_un()\fR or \fBunpack_sockaddr_un()\fR. In a list context, |
| 294 |
unpacks its argument and returns a list consisting of the pathname. In a |
| 295 |
scalar context, packs its pathname as a \f(CW\*(C`sockaddr_un\*(C'\fR and returns it. |
| 296 |
.PP |
| 297 |
Provided largely for legacy compatibility; it is better to use |
| 298 |
\&\fBpack_sockaddr_un()\fR or \fBunpack_sockaddr_un()\fR explicitly. |
| 299 |
.PP |
| 300 |
These are only supported if your system has <\fIsys/un.h\fR>. |
| 301 |
.ie n .SS "$ip_mreq = pack_ip_mreq $multiaddr, $interface" |
| 302 |
.el .SS "\f(CW$ip_mreq\fP = pack_ip_mreq \f(CW$multiaddr\fP, \f(CW$interface\fP" |
| 303 |
.IX Subsection "$ip_mreq = pack_ip_mreq $multiaddr, $interface" |
| 304 |
Takes an IPv4 multicast address and optionally an interface address (or |
| 305 |
\&\f(CW\*(C`INADDR_ANY\*(C'\fR). Returns the \f(CW\*(C`ip_mreq\*(C'\fR structure with those arguments packed |
| 306 |
in. Suitable for use with the \f(CW\*(C`IP_ADD_MEMBERSHIP\*(C'\fR and \f(CW\*(C`IP_DROP_MEMBERSHIP\*(C'\fR |
| 307 |
sockopts. |
| 308 |
.ie n .SS "($multiaddr, $interface) = unpack_ip_mreq $ip_mreq" |
| 309 |
.el .SS "($multiaddr, \f(CW$interface\fP) = unpack_ip_mreq \f(CW$ip_mreq\fP" |
| 310 |
.IX Subsection "($multiaddr, $interface) = unpack_ip_mreq $ip_mreq" |
| 311 |
Takes an \f(CW\*(C`ip_mreq\*(C'\fR structure. Returns a list of two elements; the IPv4 |
| 312 |
multicast address and interface address. |
| 313 |
.ie n .SS "$ip_mreq_source = pack_ip_mreq_source $multiaddr, $source, $interface" |
| 314 |
.el .SS "\f(CW$ip_mreq_source\fP = pack_ip_mreq_source \f(CW$multiaddr\fP, \f(CW$source\fP, \f(CW$interface\fP" |
| 315 |
.IX Subsection "$ip_mreq_source = pack_ip_mreq_source $multiaddr, $source, $interface" |
| 316 |
Takes an IPv4 multicast address, source address, and optionally an interface |
| 317 |
address (or \f(CW\*(C`INADDR_ANY\*(C'\fR). Returns the \f(CW\*(C`ip_mreq_source\*(C'\fR structure with those |
| 318 |
arguments packed in. Suitable for use with the \f(CW\*(C`IP_ADD_SOURCE_MEMBERSHIP\*(C'\fR |
| 319 |
and \f(CW\*(C`IP_DROP_SOURCE_MEMBERSHIP\*(C'\fR sockopts. |
| 320 |
.ie n .SS "($multiaddr, $source, $interface) = unpack_ip_mreq_source $ip_mreq" |
| 321 |
.el .SS "($multiaddr, \f(CW$source\fP, \f(CW$interface\fP) = unpack_ip_mreq_source \f(CW$ip_mreq\fP" |
| 322 |
.IX Subsection "($multiaddr, $source, $interface) = unpack_ip_mreq_source $ip_mreq" |
| 323 |
Takes an \f(CW\*(C`ip_mreq_source\*(C'\fR structure. Returns a list of three elements; the |
| 324 |
IPv4 multicast address, source address and interface address. |
| 325 |
.ie n .SS "$ipv6_mreq = pack_ipv6_mreq $multiaddr6, $ifindex" |
| 326 |
.el .SS "\f(CW$ipv6_mreq\fP = pack_ipv6_mreq \f(CW$multiaddr6\fP, \f(CW$ifindex\fP" |
| 327 |
.IX Subsection "$ipv6_mreq = pack_ipv6_mreq $multiaddr6, $ifindex" |
| 328 |
Takes an IPv6 multicast address and an interface number. Returns the |
| 329 |
\&\f(CW\*(C`ipv6_mreq\*(C'\fR structure with those arguments packed in. Suitable for use with |
| 330 |
the \f(CW\*(C`IPV6_ADD_MEMBERSHIP\*(C'\fR and \f(CW\*(C`IPV6_DROP_MEMBERSHIP\*(C'\fR sockopts. |
| 331 |
.ie n .SS "($multiaddr6, $ifindex) = unpack_ipv6_mreq $ipv6_mreq" |
| 332 |
.el .SS "($multiaddr6, \f(CW$ifindex\fP) = unpack_ipv6_mreq \f(CW$ipv6_mreq\fP" |
| 333 |
.IX Subsection "($multiaddr6, $ifindex) = unpack_ipv6_mreq $ipv6_mreq" |
| 334 |
Takes an \f(CW\*(C`ipv6_mreq\*(C'\fR structure. Returns a list of two elements; the IPv6 |
| 335 |
address and an interface number. |
| 336 |
.SH FUNCTIONS |
| 337 |
.IX Header "FUNCTIONS" |
| 338 |
.ie n .SS "$ip_address = inet_aton $string" |
| 339 |
.el .SS "\f(CW$ip_address\fP = inet_aton \f(CW$string\fP" |
| 340 |
.IX Subsection "$ip_address = inet_aton $string" |
| 341 |
Takes a string giving the name of a host, or a textual representation of an IP |
| 342 |
address and translates that to an packed binary address structure suitable to |
| 343 |
pass to \fBpack_sockaddr_in()\fR. If passed a hostname that cannot be resolved, |
| 344 |
returns \f(CW\*(C`undef\*(C'\fR. For multi-homed hosts (hosts with more than one address), |
| 345 |
the first address found is returned. |
| 346 |
.PP |
| 347 |
For portability do not assume that the result of \fBinet_aton()\fR is 32 bits wide, |
| 348 |
in other words, that it would contain only the IPv4 address in network order. |
| 349 |
.PP |
| 350 |
This IPv4\-only function is provided largely for legacy reasons. Newly-written |
| 351 |
code should use \fBgetaddrinfo()\fR or \fBinet_pton()\fR instead for IPv6 support. |
| 352 |
.ie n .SS "$string = inet_ntoa $ip_address" |
| 353 |
.el .SS "\f(CW$string\fP = inet_ntoa \f(CW$ip_address\fP" |
| 354 |
.IX Subsection "$string = inet_ntoa $ip_address" |
| 355 |
Takes a packed binary address structure such as returned by |
| 356 |
\&\fBunpack_sockaddr_in()\fR (or a v\-string representing the four octets of the IPv4 |
| 357 |
address in network order) and translates it into a string of the form |
| 358 |
\&\f(CW\*(C`d.d.d.d\*(C'\fR where the \f(CW\*(C`d\*(C'\fRs are numbers less than 256 (the normal |
| 359 |
human-readable four dotted number notation for Internet addresses). |
| 360 |
.PP |
| 361 |
This IPv4\-only function is provided largely for legacy reasons. Newly-written |
| 362 |
code should use \fBgetnameinfo()\fR or \fBinet_ntop()\fR instead for IPv6 support. |
| 363 |
.ie n .SS "$address = inet_pton $family, $string" |
| 364 |
.el .SS "\f(CW$address\fP = inet_pton \f(CW$family\fP, \f(CW$string\fP" |
| 365 |
.IX Subsection "$address = inet_pton $family, $string" |
| 366 |
Takes an address family (such as \f(CW\*(C`AF_INET\*(C'\fR or \f(CW\*(C`AF_INET6\*(C'\fR) and a string |
| 367 |
containing a textual representation of an address in that family and |
| 368 |
translates that to an packed binary address structure. |
| 369 |
.PP |
| 370 |
See also \fBgetaddrinfo()\fR for a more powerful and flexible function to look up |
| 371 |
socket addresses given hostnames or textual addresses. |
| 372 |
.ie n .SS "$string = inet_ntop $family, $address" |
| 373 |
.el .SS "\f(CW$string\fP = inet_ntop \f(CW$family\fP, \f(CW$address\fP" |
| 374 |
.IX Subsection "$string = inet_ntop $family, $address" |
| 375 |
Takes an address family and a packed binary address structure and translates |
| 376 |
it into a human-readable textual representation of the address; typically in |
| 377 |
\&\f(CW\*(C`d.d.d.d\*(C'\fR form for \f(CW\*(C`AF_INET\*(C'\fR or \f(CW\*(C`hhhh:hhhh::hhhh\*(C'\fR form for \f(CW\*(C`AF_INET6\*(C'\fR. |
| 378 |
.PP |
| 379 |
See also \fBgetnameinfo()\fR for a more powerful and flexible function to turn |
| 380 |
socket addresses into human-readable textual representations. |
| 381 |
.ie n .SS "($err, @result) = getaddrinfo $host, $service, [$hints]" |
| 382 |
.el .SS "($err, \f(CW@result\fP) = getaddrinfo \f(CW$host\fP, \f(CW$service\fP, [$hints]" |
| 383 |
.IX Subsection "($err, @result) = getaddrinfo $host, $service, [$hints]" |
| 384 |
Given both a hostname and service name, this function attempts to resolve the |
| 385 |
host name into a list of network addresses, and the service name into a |
| 386 |
protocol and port number, and then returns a list of address structures |
| 387 |
suitable to \fBconnect()\fR to it. |
| 388 |
.PP |
| 389 |
Given just a host name, this function attempts to resolve it to a list of |
| 390 |
network addresses, and then returns a list of address structures giving these |
| 391 |
addresses. |
| 392 |
.PP |
| 393 |
Given just a service name, this function attempts to resolve it to a protocol |
| 394 |
and port number, and then returns a list of address structures that represent |
| 395 |
it suitable to \fBbind()\fR to. This use should be combined with the \f(CW\*(C`AI_PASSIVE\*(C'\fR |
| 396 |
flag; see below. |
| 397 |
.PP |
| 398 |
Given neither name, it generates an error. |
| 399 |
.PP |
| 400 |
If present, \f(CW$hints\fR should be a reference to a hash, where the following keys |
| 401 |
are recognised: |
| 402 |
.IP "flags => INT" 4 |
| 403 |
.IX Item "flags => INT" |
| 404 |
A bitfield containing \f(CW\*(C`AI_*\*(C'\fR constants; see below. |
| 405 |
.IP "family => INT" 4 |
| 406 |
.IX Item "family => INT" |
| 407 |
Restrict to only generating addresses in this address family |
| 408 |
.IP "socktype => INT" 4 |
| 409 |
.IX Item "socktype => INT" |
| 410 |
Restrict to only generating addresses of this socket type |
| 411 |
.IP "protocol => INT" 4 |
| 412 |
.IX Item "protocol => INT" |
| 413 |
Restrict to only generating addresses for this protocol |
| 414 |
.PP |
| 415 |
The return value will be a list; the first value being an error indication, |
| 416 |
followed by a list of address structures (if no error occurred). |
| 417 |
.PP |
| 418 |
The error value will be a dualvar; comparable to the \f(CW\*(C`EAI_*\*(C'\fR error constants, |
| 419 |
or printable as a human-readable error message string. If no error occurred it |
| 420 |
will be zero numerically and an empty string. |
| 421 |
.PP |
| 422 |
Each value in the results list will be a hash reference containing the following |
| 423 |
fields: |
| 424 |
.IP "family => INT" 4 |
| 425 |
.IX Item "family => INT" |
| 426 |
The address family (e.g. \f(CW\*(C`AF_INET\*(C'\fR) |
| 427 |
.IP "socktype => INT" 4 |
| 428 |
.IX Item "socktype => INT" |
| 429 |
The socket type (e.g. \f(CW\*(C`SOCK_STREAM\*(C'\fR) |
| 430 |
.IP "protocol => INT" 4 |
| 431 |
.IX Item "protocol => INT" |
| 432 |
The protocol (e.g. \f(CW\*(C`IPPROTO_TCP\*(C'\fR) |
| 433 |
.IP "addr => STRING" 4 |
| 434 |
.IX Item "addr => STRING" |
| 435 |
The address in a packed string (such as would be returned by |
| 436 |
\&\fBpack_sockaddr_in()\fR) |
| 437 |
.IP "canonname => STRING" 4 |
| 438 |
.IX Item "canonname => STRING" |
| 439 |
The canonical name for the host if the \f(CW\*(C`AI_CANONNAME\*(C'\fR flag was provided, or |
| 440 |
\&\f(CW\*(C`undef\*(C'\fR otherwise. This field will only be present on the first returned |
| 441 |
address. |
| 442 |
.PP |
| 443 |
The following flag constants are recognised in the \f(CW$hints\fR hash. Other flag |
| 444 |
constants may exist as provided by the OS. |
| 445 |
.IP AI_PASSIVE 4 |
| 446 |
.IX Item "AI_PASSIVE" |
| 447 |
Indicates that this resolution is for a local \fBbind()\fR for a passive (i.e. |
| 448 |
listening) socket, rather than an active (i.e. connecting) socket. |
| 449 |
.IP AI_CANONNAME 4 |
| 450 |
.IX Item "AI_CANONNAME" |
| 451 |
Indicates that the caller wishes the canonical hostname (\f(CW\*(C`canonname\*(C'\fR) field |
| 452 |
of the result to be filled in. |
| 453 |
.IP AI_NUMERICHOST 4 |
| 454 |
.IX Item "AI_NUMERICHOST" |
| 455 |
Indicates that the caller will pass a numeric address, rather than a hostname, |
| 456 |
and that \fBgetaddrinfo()\fR must not perform a resolve operation on this name. This |
| 457 |
flag will prevent a possibly-slow network lookup operation, and instead return |
| 458 |
an error if a hostname is passed. |
| 459 |
.ie n .SS "($err, $hostname, $servicename) = getnameinfo $sockaddr, [$flags, [$xflags]]" |
| 460 |
.el .SS "($err, \f(CW$hostname\fP, \f(CW$servicename\fP) = getnameinfo \f(CW$sockaddr\fP, [$flags, [$xflags]]" |
| 461 |
.IX Subsection "($err, $hostname, $servicename) = getnameinfo $sockaddr, [$flags, [$xflags]]" |
| 462 |
Given a packed socket address (such as from \fBgetsockname()\fR, \fBgetpeername()\fR, or |
| 463 |
returned by \fBgetaddrinfo()\fR in a \f(CW\*(C`addr\*(C'\fR field), returns the hostname and |
| 464 |
symbolic service name it represents. \f(CW$flags\fR may be a bitmask of \f(CW\*(C`NI_*\*(C'\fR |
| 465 |
constants, or defaults to 0 if unspecified. |
| 466 |
.PP |
| 467 |
The return value will be a list; the first value being an error condition, |
| 468 |
followed by the hostname and service name. |
| 469 |
.PP |
| 470 |
The error value will be a dualvar; comparable to the \f(CW\*(C`EAI_*\*(C'\fR error constants, |
| 471 |
or printable as a human-readable error message string. The host and service |
| 472 |
names will be plain strings. |
| 473 |
.PP |
| 474 |
The following flag constants are recognised as \f(CW$flags\fR. Other flag constants may |
| 475 |
exist as provided by the OS. |
| 476 |
.IP NI_NUMERICHOST 4 |
| 477 |
.IX Item "NI_NUMERICHOST" |
| 478 |
Requests that a human-readable string representation of the numeric address be |
| 479 |
returned directly, rather than performing a name resolve operation that may |
| 480 |
convert it into a hostname. This will also avoid potentially-blocking network |
| 481 |
IO. |
| 482 |
.IP NI_NUMERICSERV 4 |
| 483 |
.IX Item "NI_NUMERICSERV" |
| 484 |
Requests that the port number be returned directly as a number representation |
| 485 |
rather than performing a name resolve operation that may convert it into a |
| 486 |
service name. |
| 487 |
.IP NI_NAMEREQD 4 |
| 488 |
.IX Item "NI_NAMEREQD" |
| 489 |
If a name resolve operation fails to provide a name, then this flag will cause |
| 490 |
\&\fBgetnameinfo()\fR to indicate an error, rather than returning the numeric |
| 491 |
representation as a human-readable string. |
| 492 |
.IP NI_DGRAM 4 |
| 493 |
.IX Item "NI_DGRAM" |
| 494 |
Indicates that the socket address relates to a \f(CW\*(C`SOCK_DGRAM\*(C'\fR socket, for the |
| 495 |
services whose name differs between TCP and UDP protocols. |
| 496 |
.PP |
| 497 |
The following constants may be supplied as \f(CW$xflags\fR. |
| 498 |
.IP NIx_NOHOST 4 |
| 499 |
.IX Item "NIx_NOHOST" |
| 500 |
Indicates that the caller is not interested in the hostname of the result, so |
| 501 |
it does not have to be converted. \f(CW\*(C`undef\*(C'\fR will be returned as the hostname. |
| 502 |
.IP NIx_NOSERV 4 |
| 503 |
.IX Item "NIx_NOSERV" |
| 504 |
Indicates that the caller is not interested in the service name of the result, |
| 505 |
so it does not have to be converted. \f(CW\*(C`undef\*(C'\fR will be returned as the service |
| 506 |
name. |
| 507 |
.SH "\fBgetaddrinfo()\fP / \fBgetnameinfo()\fP ERROR CONSTANTS" |
| 508 |
.IX Header "getaddrinfo() / getnameinfo() ERROR CONSTANTS" |
| 509 |
The following constants may be returned by \fBgetaddrinfo()\fR or \fBgetnameinfo()\fR. |
| 510 |
Others may be provided by the OS. |
| 511 |
.IP EAI_AGAIN 4 |
| 512 |
.IX Item "EAI_AGAIN" |
| 513 |
A temporary failure occurred during name resolution. The operation may be |
| 514 |
successful if it is retried later. |
| 515 |
.IP EAI_BADFLAGS 4 |
| 516 |
.IX Item "EAI_BADFLAGS" |
| 517 |
The value of the \f(CW\*(C`flags\*(C'\fR hint to \fBgetaddrinfo()\fR, or the \f(CW$flags\fR parameter to |
| 518 |
\&\fBgetnameinfo()\fR contains unrecognised flags. |
| 519 |
.IP EAI_FAMILY 4 |
| 520 |
.IX Item "EAI_FAMILY" |
| 521 |
The \f(CW\*(C`family\*(C'\fR hint to \fBgetaddrinfo()\fR, or the family of the socket address |
| 522 |
passed to \fBgetnameinfo()\fR is not supported. |
| 523 |
.IP EAI_NODATA 4 |
| 524 |
.IX Item "EAI_NODATA" |
| 525 |
The host name supplied to \fBgetaddrinfo()\fR did not provide any usable address |
| 526 |
data. |
| 527 |
.IP EAI_NONAME 4 |
| 528 |
.IX Item "EAI_NONAME" |
| 529 |
The host name supplied to \fBgetaddrinfo()\fR does not exist, or the address |
| 530 |
supplied to \fBgetnameinfo()\fR is not associated with a host name and the |
| 531 |
\&\f(CW\*(C`NI_NAMEREQD\*(C'\fR flag was supplied. |
| 532 |
.IP EAI_SERVICE 4 |
| 533 |
.IX Item "EAI_SERVICE" |
| 534 |
The service name supplied to \fBgetaddrinfo()\fR is not available for the socket |
| 535 |
type given in the \f(CW$hints\fR. |
| 536 |
.SH EXAMPLES |
| 537 |
.IX Header "EXAMPLES" |
| 538 |
.SS "Lookup for \fBconnect()\fP" |
| 539 |
.IX Subsection "Lookup for connect()" |
| 540 |
The \fBgetaddrinfo()\fR function converts a hostname and a service name into a list |
| 541 |
of structures, each containing a potential way to \fBconnect()\fR to the named |
| 542 |
service on the named host. |
| 543 |
.PP |
| 544 |
.Vb 2 |
| 545 |
\& use IO::Socket; |
| 546 |
\& use Socket qw(SOCK_STREAM getaddrinfo); |
| 547 |
\& |
| 548 |
\& my %hints = (socktype => SOCK_STREAM); |
| 549 |
\& my ($err, @res) = getaddrinfo("localhost", "echo", \e%hints); |
| 550 |
\& die "Cannot getaddrinfo \- $err" if $err; |
| 551 |
\& |
| 552 |
\& my $sock; |
| 553 |
\& |
| 554 |
\& foreach my $ai (@res) { |
| 555 |
\& my $candidate = IO::Socket\->new(); |
| 556 |
\& |
| 557 |
\& $candidate\->socket($ai\->{family}, $ai\->{socktype}, $ai\->{protocol}) |
| 558 |
\& or next; |
| 559 |
\& |
| 560 |
\& $candidate\->connect($ai\->{addr}) |
| 561 |
\& or next; |
| 562 |
\& |
| 563 |
\& $sock = $candidate; |
| 564 |
\& last; |
| 565 |
\& } |
| 566 |
\& |
| 567 |
\& die "Cannot connect to localhost:echo" unless $sock; |
| 568 |
\& |
| 569 |
\& $sock\->print("Hello, world!\en"); |
| 570 |
\& print <$sock>; |
| 571 |
.Ve |
| 572 |
.PP |
| 573 |
Because a list of potential candidates is returned, the \f(CW\*(C`while\*(C'\fR loop tries |
| 574 |
each in turn until it finds one that succeeds both the \fBsocket()\fR and \fBconnect()\fR |
| 575 |
calls. |
| 576 |
.PP |
| 577 |
This function performs the work of the legacy functions \fBgethostbyname()\fR, |
| 578 |
\&\fBgetservbyname()\fR, \fBinet_aton()\fR and \fBpack_sockaddr_in()\fR. |
| 579 |
.PP |
| 580 |
In practice this logic is better performed by IO::Socket::IP. |
| 581 |
.SS "Making a human-readable string out of an address" |
| 582 |
.IX Subsection "Making a human-readable string out of an address" |
| 583 |
The \fBgetnameinfo()\fR function converts a socket address, such as returned by |
| 584 |
\&\fBgetsockname()\fR or \fBgetpeername()\fR, into a pair of human-readable strings |
| 585 |
representing the address and service name. |
| 586 |
.PP |
| 587 |
.Vb 2 |
| 588 |
\& use IO::Socket::IP; |
| 589 |
\& use Socket qw(getnameinfo); |
| 590 |
\& |
| 591 |
\& my $server = IO::Socket::IP\->new(LocalPort => 12345, Listen => 1) or |
| 592 |
\& die "Cannot listen \- $@"; |
| 593 |
\& |
| 594 |
\& my $socket = $server\->accept or die "accept: $!"; |
| 595 |
\& |
| 596 |
\& my ($err, $hostname, $servicename) = getnameinfo($socket\->peername); |
| 597 |
\& die "Cannot getnameinfo \- $err" if $err; |
| 598 |
\& |
| 599 |
\& print "The peer is connected from $hostname\en"; |
| 600 |
.Ve |
| 601 |
.PP |
| 602 |
Since in this example only the hostname was used, the redundant conversion of |
| 603 |
the port number into a service name may be omitted by passing the |
| 604 |
\&\f(CW\*(C`NIx_NOSERV\*(C'\fR flag. |
| 605 |
.PP |
| 606 |
.Vb 1 |
| 607 |
\& use Socket qw(getnameinfo NIx_NOSERV); |
| 608 |
\& |
| 609 |
\& my ($err, $hostname) = getnameinfo($socket\->peername, 0, NIx_NOSERV); |
| 610 |
.Ve |
| 611 |
.PP |
| 612 |
This function performs the work of the legacy functions \fBunpack_sockaddr_in()\fR, |
| 613 |
\&\fBinet_ntoa()\fR, \fBgethostbyaddr()\fR and \fBgetservbyport()\fR. |
| 614 |
.PP |
| 615 |
In practice this logic is better performed by IO::Socket::IP. |
| 616 |
.SS "Resolving hostnames into IP addresses" |
| 617 |
.IX Subsection "Resolving hostnames into IP addresses" |
| 618 |
To turn a hostname into a human-readable plain IP address use \fBgetaddrinfo()\fR |
| 619 |
to turn the hostname into a list of socket structures, then \fBgetnameinfo()\fR on |
| 620 |
each one to make it a readable IP address again. |
| 621 |
.PP |
| 622 |
.Vb 1 |
| 623 |
\& use Socket qw(:addrinfo SOCK_RAW); |
| 624 |
\& |
| 625 |
\& my ($err, @res) = getaddrinfo($hostname, "", {socktype => SOCK_RAW}); |
| 626 |
\& die "Cannot getaddrinfo \- $err" if $err; |
| 627 |
\& |
| 628 |
\& while( my $ai = shift @res ) { |
| 629 |
\& my ($err, $ipaddr) = getnameinfo($ai\->{addr}, NI_NUMERICHOST, NIx_NOSERV); |
| 630 |
\& die "Cannot getnameinfo \- $err" if $err; |
| 631 |
\& |
| 632 |
\& print "$ipaddr\en"; |
| 633 |
\& } |
| 634 |
.Ve |
| 635 |
.PP |
| 636 |
The \f(CW\*(C`socktype\*(C'\fR hint to \fBgetaddrinfo()\fR filters the results to only include one |
| 637 |
socket type and protocol. Without this most OSes return three combinations, |
| 638 |
for \f(CW\*(C`SOCK_STREAM\*(C'\fR, \f(CW\*(C`SOCK_DGRAM\*(C'\fR and \f(CW\*(C`SOCK_RAW\*(C'\fR, resulting in triplicate |
| 639 |
output of addresses. The \f(CW\*(C`NI_NUMERICHOST\*(C'\fR flag to \fBgetnameinfo()\fR causes it to |
| 640 |
return a string-formatted plain IP address, rather than reverse resolving it |
| 641 |
back into a hostname. |
| 642 |
.PP |
| 643 |
This combination performs the work of the legacy functions \fBgethostbyname()\fR |
| 644 |
and \fBinet_ntoa()\fR. |
| 645 |
.SS "Accessing socket options" |
| 646 |
.IX Subsection "Accessing socket options" |
| 647 |
The many \f(CW\*(C`SO_*\*(C'\fR and other constants provide the socket option names for |
| 648 |
\&\fBgetsockopt()\fR and \fBsetsockopt()\fR. |
| 649 |
.PP |
| 650 |
.Vb 2 |
| 651 |
\& use IO::Socket::INET; |
| 652 |
\& use Socket qw(SOL_SOCKET SO_RCVBUF IPPROTO_IP IP_TTL); |
| 653 |
\& |
| 654 |
\& my $socket = IO::Socket::INET\->new(LocalPort => 0, Proto => \*(Aqudp\*(Aq) |
| 655 |
\& or die "Cannot create socket: $@"; |
| 656 |
\& |
| 657 |
\& $socket\->setsockopt(SOL_SOCKET, SO_RCVBUF, 64*1024) or |
| 658 |
\& die "setsockopt: $!"; |
| 659 |
\& |
| 660 |
\& print "Receive buffer is ", $socket\->getsockopt(SOL_SOCKET, SO_RCVBUF), |
| 661 |
\& " bytes\en"; |
| 662 |
\& |
| 663 |
\& print "IP TTL is ", $socket\->getsockopt(IPPROTO_IP, IP_TTL), "\en"; |
| 664 |
.Ve |
| 665 |
.PP |
| 666 |
As a convenience, IO::Socket's \fBsetsockopt()\fR method will convert a number |
| 667 |
into a packed byte buffer, and \fBgetsockopt()\fR will unpack a byte buffer of the |
| 668 |
correct size back into a number. |
| 669 |
.SH AUTHOR |
| 670 |
.IX Header "AUTHOR" |
| 671 |
This module was originally maintained in Perl core by the Perl 5 Porters. |
| 672 |
.PP |
| 673 |
It was extracted to dual-life on CPAN at version 1.95 by |
| 674 |
Paul Evans <[email protected]> |