1getipnodebyname(3SOCKET) Sockets Library Functions getipnodebyname(3SOCKET)
2
6 getipnodebyname, getipnodebyaddr, freehostent - get IP node entry
7
9 cc [ flag... ] file... -lsocket -lnsl [ library... ]
10 #include <sys/socket.h>
11 #include <netdb.h>
12 struct hostent *getipnodebyname(const char *name, int af,
14 int flags, int *error_num);
15 struct hostent *getipnodebyaddr(const void *src, size_t len,
18 int af, int *error_num);
19 void freehostent(struct hostent *ptr);
22
25 af Address family
26 flags Various flags
29 name Name of host
32 error_num Error storage
35 src Address for lookup
38 len Length of address
41 ptr Pointer to hostent structure
44
47 The getipnodebyname() function searches the ipnodes database from the
48 beginning. The function finds the first h_name member that matches the
49 hostname specified by name. The function takes an af argument that
50 specifies the address family. The address family can be AF_INET for
51 IPv4 addresses or AF_INET6 for IPv6 addresses. The flags argument
52 determines what results are returned based on the value of flags. If
53 the flags argument is set to 0 (zero), the default operation of the
54 function is specified as follows:
55 o If the af argument is AF_INET, a query is made for an IPv4
57 address. If successful, IPv4 addresses are returned and the
58 h_length member of the hostent structure is 4. Otherwise,
59 the function returns a NULL pointer.
60 o If the af argument is AF_INET6, a query is made for an IPv6
62 address. If successful, IPv6 addresses are returned and the
63 h_length member of the hostent structure is 16. Otherwise,
64 the function returns a NULL pointer.
65 The flags argument changes the default actions of the function. Set the
68 flags argument with a logical OR operation on any of combination of the
69 following values:
70 o AI_V4MAPPED
72 o AI_ALL
74 o AI_ADDRCONFIG
76 The special flags value, AI_DEFAULT, should handle most applications.
79 Porting simple applications to use IPv6 replaces the call
80 hptr = gethostbyname(name);
82 with
86 hptr = getipnodebyname(name, AF_INET6, AI_DEFAULT, &error_num);
88 The flags value 0 (zero) implies a strict interpretation of the af
92 argument:
93 o If flags is 0 and af is AF_INET, the caller wants only IPv4
95 addresses. A query is made for A records. If successful,
96 IPv4 addresses are returned and the h_length member of the
97 hostent structure is 4. Otherwise, the function returns a
98 NULL pointer.
99 o If flags is 0 and af is AF_INET6, the caller wants only IPv6
101 addresses. A query is made for AAAA records. If successful,
102 IPv6 addresses are returned and the h_length member of the
103 hostent structure is 16. Otherwise, the function returns a
104 NULL pointer.
105 Logically OR other constants into the flags argument to modify the
108 behavior of the getipnodebyname() function.
109 o If the AI_V4MAPPED flag is specified with af set to
111 AF_INET6, the caller can accept IPv4-mapped IPv6 addresses.
112 If no AAAA records are found, a query is made for A records.
113 Any A records found are returned as IPv4-mapped IPv6
114 addresses and the h_length is 16. The AI_V4MAPPED flag is
115 ignored unless af equals AF_INET6.
116 o The AI_ALL flag is used in conjunction with the AI_V4MAPPED
118 flag, exclusively with the IPv6 address family. When AI_ALL
119 is logically ORed with AI_V4MAPPED flag, the caller wants
120 all addresses: IPv6 and IPv4-mapped IPv6 addresses. A query
121 is first made for AAAA records and, if successful, IPv6
122 addresses are returned. Another query is then made for A
123 records. Any A records found are returned as IPv4-mapped
124 IPv6 addresses and the h_length is 16. Only when both
125 queries fail does the function return a NULL pointer. The
126 AI_ALL flag is ignored unless af is set to AF_INET6.
127 o The AI_ADDRCONFIG flag specifies that a query for AAAA
129 records should occur only when the node is configured with
130 at least one IPv6 source address. A query for A records
131 should occur only when the node is configured with at least
132 one IPv4 source address. For example, if a node is config‐
133 ured with no IPv6 source addresses, af equals AF_INET6, and
134 the node name queried has both AAAA and A records, then:
135 o A NULL pointer is returned when only the AI_ADDRCONFIG
137 value is specified.
138 o The A records are returned as IPv4-mapped IPv6 addresses
140 when the AI_ADDRCONFIG and AI_V4MAPPED values are speci‐
141 fied.
142 The special flags value, AI_DEFAULT, is defined as
145 #define AI_DEFAULT (AI_V4MAPPED | AI_ADDRCONFIG)
147 The getipnodebyname() function allows the name argument to be a node
151 name or a literal address string: a dotted-decimal IPv4 address or an
152 IPv6 hex address. Applications do not have to call inet_pton(3SOCKET)
153 to handle literal address strings.
154 Four scenarios arise based on the type of literal address string and
157 the value of the af argument. The two simple cases occur when name is a
158 dotted-decimal IPv4 address and af equals AF_INET and when name is an
159 IPv6 hex address and af equals AF_INET6. The members of the returned
160 hostent structure are:
161 h_name Pointer to a copy of the name argument
163 h_aliases NULL pointer.
166 h_addrtype Copy of the af argument.
169 h_length 4 for AF_INET or 16 for AF_INET6.
172 h_addr_list Array of pointers to 4-byte or 16-byte binary addresses.
175 The array is terminated by a NULL pointer.
176
179 Upon successful completion, getipnodebyname() and getipnodebyaddr()
180 return a hostent structure. Otherwise they return NULL.
181 The hostent structure does not change from the existing definition when
184 used with gethostbyname(3NSL). For example, host entries are repre‐
185 sented by the struct hostent structure defined in <netdb.h>:
186 struct hostent {
188 char *h_name; /* canonical name of host */
189 char **h_aliases; /* alias list */
190 int h_addrtype; /* host address type */
191 int h_length; /* length of address */
192 char **h_addr_list; /* list of addresses */
193 };
194 An error occurs when name is an IPv6 hex address and af equals AF_INET.
198 The return value of the function is a NULL pointer and error_num equals
199 HOST_NOT_FOUND.
200 The getipnodebyaddr() function has the same arguments as the existing
203 gethostbyaddr(3NSL) function, but adds an error number. As with getipn‐
204 odebyname(), getipnodebyaddr() is thread-safe. The error_num value is
205 returned to the caller with the appropriate error code to support
206 thread-safe error code returns. The following error conditions can be
207 returned for error_num:
208 HOST_NOT_FOUND Host is unknown.
210 NO_DATA No address is available for the name specified in the
213 server request. This error is not a soft error.
214 Another type of name server request might be success‐
215 ful.
216 NO_RECOVERY An unexpected server failure occurred, which is a
219 non-recoverable error.
220 TRY_AGAIN This error is a soft error that indicates that the
223 local server did not receive a response from an
224 authoritative server. A retry at some later time
225 might be successful.
226 One possible source of confusion is the handling of IPv4-mapped IPv6
230 addresses and IPv4-compatible IPv6 addresses, but the following logic
231 should apply:
232 1. If af is AF_INET6, and if len equals 16, and if the IPv6
234 address is an IPv4-mapped IPv6 address or an IPv4-compatible
235 IPv6 address, then skip over the first 12 bytes of the IPv6
236 address, set af to AF_INET, and set len to 4.
237 2. If af is AF_INET, lookup the name for the given IPv4
239 address.
240 3. If af is AF_INET6, lookup the name for the given IPv6
242 address.
243 4. If the function is returning success, then the single
245 address that is returned in the hostent structure is a copy
246 of the first argument to the function with the same address
247 family that was passed as an argument to this function.
248 All four steps listed are performed in order.
251 This structure, and the information pointed to by this structure, are
254 dynamically allocated by getipnodebyname() and getipnodebyaddr(). The
255 freehostent() function frees this memory.
256
258 Example 1 Getting the Canonical Name, Aliases, and Internet IP
259 Addresses for a Given Hostname
260 The following is a sample program that retrieves the canonical name,
263 aliases, and all Internet IP addresses, both version 6 and version 4,
264 for a given hostname.
265 #include <stdio.h>
268 #include <string.h>
269 #include <sys/types.h>
270 #include <sys/socket.h>
271 #include <netinet/in.h>
272 #include <arpa/inet.h>
273 #include <netdb.h>
274 main(int argc, const char **argv)
276 {
277 char abuf[INET6_ADDRSTRLEN];
278 int error_num;
279 struct hostent *hp;
280 char **p;
281 if (argc != 2) {
283 (void) printf("usage: %s hostname0, argv[0]);
284 exit (1);
285 }
286 /* argv[1] can be a pointer to a hostname or literal IP address */
288 hp = getipnodebyname(argv[1], AF_INET6, AI_ALL | AI_ADDRCONFIG |
289 AI_V4MAPPED, &error_num);
290 if (hp == NULL) {
291 if (error_num == TRY_AGAIN) {
292 printf("%s: unknown host or invalid literal address "
293 "(try again later)0, argv[1]);
294 } else {
295 printf("%s: unknown host or invalid literal address0,
296 argv[1]);
297 }
298 exit (1);
299 }
300 for (p = hp->h_addr_list; *p != 0; p++) {
301 struct in6_addr in6;
302 char **q;
303 bcopy(*p, (caddr_t)&in6, hp->h_length);
305 (void) printf("%s%s", inet_ntop(AF_INET6, (void *)&in6,
306 abuf, sizeof(abuf)), hp->h_name);
307 for (q = hp->h_aliases; *q != 0; q++)
308 (void) printf(" %s", *q);
309 (void) putchar('0);
310 }
311 freehostent(hp);
312 exit (0);
313 }
314
317 See attributes(5) for descriptions of the following attributes:
318 ┌─────────────────────────────┬─────────────────────────────┐
323 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
324 ├─────────────────────────────┼─────────────────────────────┤
325 │Interface Stability │Committed │
326 ├─────────────────────────────┼─────────────────────────────┤
327 │MT-Level │Safe │
328 └─────────────────────────────┴─────────────────────────────┘
329
331 getaddrinfo(3SOCKET), gethostbyname(3NSL), htonl(3SOCKET),
332 inet(3SOCKET), netdb.h(3HEAD), hosts(4), nsswitch.conf(4),
333 attributes(5)
334
336 No enumeration functions are provided for IPv6. Existing enumeration
337 functions such as sethostent(3NSL) do not work in combination with the
338 getipnodebyname() and getipnodebyaddr() functions.
339 All the functions that return a struct hostent must always return the
342 canonical in the h_name field. This name, by definition, is the well-
343 known and official hostname shared between all aliases and all
344 addresses. The underlying source that satisfies the request determines
345 the mapping of the input name or address into the set of names and
346 addresses in hostent. Different sources might make such as determina‐
347 tion in different ways. If more than one alias and more than one
348 address in hostent exist, no pairing is implied between the alias and
349 address.
350 The current implementations of these functions return or accept only
353 addresses for the Internet address family (type AF_INET) or the Inter‐
354 net address family Version 6 (type AF_INET6).
355 IPv4-mapped addresses are not recommended. The getaddrinfo(3SOCKET)
358 function is preferred over getipnodebyaddr() because it allows applica‐
359 tions to lookup IPv4 and IPv6 addresses without relying on IPv4-mapped
360 addresses.
361 The form for an address of type AF_INET is a struct in_addr defined in
364 <netinet/in.h>. The form for an address of type AF_INET6 is a struct
365 in6_addr, also defined in <netinet/in.h>. The functions described in
366 inet_ntop(3SOCKET) and inet_pton(3SOCKET) that are illustrated in the
367 EXAMPLES section are helpful in constructing and manipulating addresses
368 in either of these forms.
369SunOS 5.11 22 Aug 2007 getipnodebyname(3SOCKET)