Debian Codegraph @

upstream/debian-unstable/man3/Socket.3perl

raw
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]>