1getipnodebyname(3SOCKET)   Sockets Library Functions  getipnodebyname(3SOCKET)
2
3
4

NAME

6       getipnodebyname, getipnodebyaddr, freehostent - get IP node entry
7

SYNOPSIS

9       cc [ flag... ] file... -lsocket  -lnsl  [ library... ]
10       #include <sys/socket.h>
11       #include <netdb.h>
12
13       struct hostent *getipnodebyname(const char *name, int af,
14            int flags, int *error_num);
15
16
17       struct hostent *getipnodebyaddr(const void *src, size_t len,
18            int af, int *error_num);
19
20
21       void freehostent(struct hostent *ptr);
22
23

PARAMETERS

25       af           Address family
26
27
28       flags        Various flags
29
30
31       name         Name of host
32
33
34       error_num    Error storage
35
36
37       src          Address for lookup
38
39
40       len          Length of address
41
42
43       ptr          Pointer to hostent structure
44
45

DESCRIPTION

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
56           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
61           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
66
67       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
71           o      AI_V4MAPPED
72
73           o      AI_ALL
74
75           o      AI_ADDRCONFIG
76
77
78       The special flags value, AI_DEFAULT, should handle  most  applications.
79       Porting simple applications to use IPv6 replaces the call
80
81         hptr = gethostbyname(name);
82
83
84
85       with
86
87         hptr = getipnodebyname(name, AF_INET6, AI_DEFAULT, &error_num);
88
89
90
91       The  flags  value  0  (zero)  implies a strict interpretation of the af
92       argument:
93
94           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
100           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
106
107       Logically OR other constants into the  flags  argument  to  modify  the
108       behavior of the getipnodebyname() function.
109
110           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
117           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
128           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
136               o      A  NULL  pointer is returned when only the AI_ADDRCONFIG
137                      value is specified.
138
139               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
143
144       The special flags value, AI_DEFAULT, is defined as
145
146         #define  AI_DEFAULT  (AI_V4MAPPED | AI_ADDRCONFIG)
147
148
149
150       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
155
156       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
162       h_name         Pointer to a copy of the name argument
163
164
165       h_aliases      NULL pointer.
166
167
168       h_addrtype     Copy of the af argument.
169
170
171       h_length       4 for AF_INET or 16 for AF_INET6.
172
173
174       h_addr_list    Array of pointers to 4-byte or 16-byte binary addresses.
175                      The array is terminated by a NULL pointer.
176
177

RETURN VALUES

179       Upon successful  completion,  getipnodebyname()  and  getipnodebyaddr()
180       return a hostent structure. Otherwise they return NULL.
181
182
183       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
187         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
195
196
197       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
201
202       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
209       HOST_NOT_FOUND    Host is unknown.
210
211
212       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
217
218       NO_RECOVERY       An  unexpected  server  failure  occurred, which is a
219                         non-recoverable error.
220
221
222       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
227
228
229       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
233           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
238           2.     If af is  AF_INET,  lookup  the  name  for  the  given  IPv4
239                  address.
240
241           3.     If  af  is  AF_INET6,  lookup  the  name  for the given IPv6
242                  address.
243
244           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
249
250       All four steps listed are performed in order.
251
252
253       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

EXAMPLES

258       Example  1  Getting  the  Canonical  Name,  Aliases,  and  Internet  IP
259       Addresses for a Given Hostname
260
261
262       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
266
267              #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
275              main(int argc, const char **argv)
276              {
277              char abuf[INET6_ADDRSTRLEN];
278              int error_num;
279              struct hostent *hp;
280              char **p;
281
282                  if (argc != 2) {
283                      (void) printf("usage: %s hostname0, argv[0]);
284                      exit (1);
285                  }
286
287              /* 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
304                 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
315

ATTRIBUTES

317       See attributes(5) for descriptions of the following attributes:
318
319
320
321
322       ┌─────────────────────────────┬─────────────────────────────┐
323       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
324       ├─────────────────────────────┼─────────────────────────────┤
325       │Interface Stability          │Committed                    │
326       ├─────────────────────────────┼─────────────────────────────┤
327       │MT-Level                     │Safe                         │
328       └─────────────────────────────┴─────────────────────────────┘
329

SEE ALSO

331       getaddrinfo(3SOCKET),       gethostbyname(3NSL),        htonl(3SOCKET),
332       inet(3SOCKET),      netdb.h(3HEAD),     hosts(4),     nsswitch.conf(4),
333       attributes(5)
334

NOTES

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
340
341       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
351
352       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
356
357       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
362
363       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.
369
370
371
372SunOS 5.11                        22 Aug 2007         getipnodebyname(3SOCKET)
Impressum