Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Socket.3pm

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