1Socket::GetAddrInfo(3)User Contributed Perl DocumentationSocket::GetAddrInfo(3)
2
6 "Socket::GetAddrInfo" - RFC 2553's "getaddrinfo" and "getnameinfo"
7 functions.
8
10 use Socket qw( SOCK_STREAM );
11 use Socket::GetAddrInfo qw( :newapi getaddrinfo getnameinfo );
12 use IO::Socket;
13 my $sock;
15 my %hints = ( socktype => SOCK_STREAM );
17 my ( $err, @res ) = getaddrinfo( "www.google.com", "www", \%hints );
18 die "Cannot resolve name - $err" if $err;
20 while( my $ai = shift @res ) {
22 $sock = IO::Socket->new();
24 $sock->socket( $ai->{family}, $ai->{socktype}, $ai->{protocol} ) or
25 undef $sock, next;
26 $sock->connect( $ai->{addr} ) or undef $sock, next;
28 last;
30 }
31 if( $sock ) {
33 my ( $err, $host, $service ) = getnameinfo( $sock->peername );
34 print "Connected to $host:$service\n" if !$err;
35 }
36
38 The RFC 2553 functions "getaddrinfo" and "getnameinfo" provide an
39 abstracted way to convert between a pair of host name/service name and
40 socket addresses, or vice versa. "getaddrinfo" converts names into a
41 set of arguments to pass to the "socket()" and "connect()" syscalls,
42 and "getnameinfo" converts a socket address back into its host
43 name/service name pair.
44 These functions provide a useful interface for performing either of
46 these name resolution operation, without having to deal with IPv4/IPv6
47 transparency, or whether the underlying host can support IPv6 at all,
48 or other such issues. However, not all platforms can support the
49 underlying calls at the C layer, which means a dilema for authors
50 wishing to write forward-compatible code. Either to support these
51 functions, and cause the code not to work on older platforms, or stick
52 to the older "legacy" resolvers such as "gethostbyname()", which means
53 the code becomes more portable.
54 This module attempts to solve this problem, by detecting at compiletime
56 whether the underlying OS will support these functions, and only
57 compiling the XS code if it can. At runtime, when the module is loaded,
58 if the XS implementation is not available, emulations of the functions
59 using the legacy resolver functions instead. The emulations support the
60 same interface as the real functions, and behave as close as is
61 resonably possible to emulate using the legacy resolvers. See below for
62 details on the limits of this emulation.
63
65 The functions in this module are provided in one of two API styles,
66 selectable at the time they are imported into the caller, by the use of
67 the following tags:
68 use Socket::GetAddrInfo qw( :newapi getaddrinfo );
70 use Socket::GetAddrInfo qw( :Socket6api getaddrinfo );
72 The choice is implemented by importing different functions into the
74 caller, which means different importing packages may choose different
75 API styles. It is recommended that new code import the ":newapi" style
76 to take advantage of neater argument / return results, and error
77 reporting. The ":Socket6api" style is provided as backward-
78 compatibility for code that wants to use "Socket6".
79 If neither style is selected, then this module will provide a
81 Socket6-like API to be compatible with earlier versions of
82 "Socket::GetAddrInfo". This behaviour will change in a later version of
83 the module - make sure to always specify the required API type.
84 ( $err, @res ) = getaddrinfo( $host, $service, $hints )
86 When given both host and service, this function attempts to resolve the
87 host name to a set of network addresses, and the service name into a
88 protocol and port number, and then returns a list of address structures
89 suitable to connect() to it.
90 When given just a host name, this function attempts to resolve it to a
92 set of network addresses, and then returns a list of these addresses in
93 the returned structures.
94 When given just a service name, this function attempts to resolve it to
96 a protocol and port number, and then returns a list of address
97 structures that represent it suitable to bind() to.
98 When given neither name, it generates an error.
100 The optional $hints parameter can be passed a HASH reference to
102 indicate how the results are generated. It may contain any of the
103 following four fields:
104 flags => INT
106 A bitfield containing "AI_*" constants
107 family => INT
109 Restrict to only generating addresses in this address family
110 socktype => INT
112 Restrict to only generating addresses of this socket type
113 protocol => INT
115 Restrict to only generating addresses for this protocol
116 Errors are indicated by the $err value returned; which will be non-zero
118 in numeric context, and contain a string error message as a string. The
119 value can be compared against any of the "EAI_*" constants to determine
120 what the error is.
121 If no error occurs, @res will contain HASH references, each
123 representing one address. It will contain the following five fields:
124 family => INT
126 The address family (e.g. AF_INET)
127 socktype => INT
129 The socket type (e.g. SOCK_STREAM)
130 protocol => INT
132 The protocol (e.g. IPPROTO_TCP)
133 addr => STRING
135 The address in a packed string (such as would be returned by
136 pack_sockaddr_in)
137 canonname => STRING
139 The canonical name for the host if the "AI_CANONNAME" flag was
140 provided, or "undef" otherwise.
141 ( $err, $host, $service ) = getnameinfo( $addr, $flags )
143 This function attempts to resolve the given socket address into a pair
144 of host and service names.
145 The optional $flags parameter is a bitfield containing "NI_*"
147 constants.
148 Errors are indicated by the $err value returned; which will be non-zero
150 in numeric context, and contain a string error message as a string. The
151 value can be compared against any of the "EAI_*" constants to determine
152 what the error is.
153
155 @res = getaddrinfo( $host, $service, $family, $socktype, $protocol, $flags
156 )
157 This version of the API takes the hints values as separate ordered
158 parameters. Unspecified parameters should be passed as 0.
159 If successful, this function returns a flat list of values, five for
161 each returned address structure. Each group of five elements will
162 contain, in order, the "family", "socktype", "protocol", "addr" and
163 "canonname" values of the address structure.
164 If unsuccessful, it will return a single value, containing the string
166 error message. To remain compatible with the "Socket6" interface, this
167 value does not have the error integer part.
168 ( $host, $service ) = getnameinfo( $addr, $flags )
170 This version of the API returns only the host name and service name, if
171 successfully resolved. On error, it will return an empty list. To
172 remain compatible with the "Socket6" interface, no error information
173 will be supplied.
174
176 These emulations are not a complete replacement of the real functions,
177 because they only support IPv4 (the "AF_INET" socket family).
178 getaddrinfo
180 · If $family is supplied, it must be "AF_INET". Any other value will
181 result in an error thrown by "croak".
182 · The only supported $flags values are "AI_PASSIVE", "AI_CANONNAME",
184 and "AI_NUMERICHOST".
185 getnameinfo
187 · If the sockaddr family of $addr is anything other than "AF_INET",
188 an error will be thrown with "croak".
189 · The only supported $flags values are "NI_NUMERICHOST",
191 "NI_NUMERICSERV", "NI_NAMEREQD" and "NI_DGRAM".
192
194 · At the time of writing, there are no test reports from the
195 "MSWin32" platform either PASS or FAIL. I suspect the code will not
196 currently work as it stands on that platform, but it should be
197 fairly easy to fix, as "Socket6" is known to work there. Patches
198 welcomed. :)
199
201 · <http://tools.ietf.org/html/rfc2553> - Basic Socket Interface
202 Extensions for IPv6
203
205 With thanks to Zefram <zefram@fysh.org> for help with fixing some bugs
206 in the XS code.
207
209 Paul Evans <leonerd@leonerd.org.uk>
210perl v5.12.1 2010-09-01 Socket::GetAddrInfo(3)