1FREEADDRINFO(3P)           POSIX Programmer's Manual          FREEADDRINFO(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       freeaddrinfo, getaddrinfo — get address information
14

SYNOPSIS

16       #include <sys/socket.h>
17       #include <netdb.h>
18
19       void freeaddrinfo(struct addrinfo *ai);
20       int getaddrinfo(const char *restrict nodename,
21           const char *restrict servname,
22           const struct addrinfo *restrict hints,
23           struct addrinfo **restrict res);
24

DESCRIPTION

26       The freeaddrinfo() function shall free one or more addrinfo  structures
27       returned by getaddrinfo(), along with any additional storage associated
28       with those structures. If the ai_next field of  the  structure  is  not
29       null,  the entire list of structures shall be freed. The freeaddrinfo()
30       function shall support the freeing of arbitrary sublists of an addrinfo
31       list originally returned by getaddrinfo().
32
33       The  getaddrinfo() function shall translate the name of a service loca‐
34       tion (for example, a host name) and/or a service name and shall  return
35       a set of socket addresses and associated information to be used in cre‐
36       ating a socket with which to address the specified service.
37
38       Note:     In many cases it is implemented by the Domain Name System, as
39                 documented in RFC 1034, RFC 1035, and RFC 1886.
40
41       The freeaddrinfo() and getaddrinfo() functions shall be thread-safe.
42
43       The  nodename and servname arguments are either null pointers or point‐
44       ers to null-terminated strings. One or  both  of  these  two  arguments
45       shall be supplied by the application as a non-null pointer.
46
47       The  format  of a valid name depends on the address family or families.
48       If a specific family is not given and the name could be interpreted  as
49       valid  within  multiple  supported  families,  the implementation shall
50       attempt to resolve the name in all supported families and,  in  absence
51       of errors, one or more results shall be returned.
52
53       If  the  nodename argument is not null, it can be a descriptive name or
54       can be an address string.  If the specified address family is  AF_INET,
55       AF_INET6,  or AF_UNSPEC, valid descriptive names include host names. If
56       the specified address family is AF_INET or AF_UNSPEC,  address  strings
57       using  Internet  standard  dot notation as specified in inet_addr() are
58       valid.
59
60       If the specified address family is AF_INET6 or AF_UNSPEC, standard IPv6
61       text forms described in inet_ntop() are valid.
62
63       If  nodename  is  not  null, the requested service location is named by
64       nodename; otherwise, the requested service location  is  local  to  the
65       caller.
66
67       If  servname is null, the call shall return network-level addresses for
68       the specified nodename.  If servname is not null, it is  a  null-termi‐
69       nated  character  string identifying the requested service. This can be
70       either a descriptive name or a numeric representation suitable for  use
71       with  the  address family or families.  If the specified address family
72       is AF_INET, AF_INET6, or AF_UNSPEC, the service can be specified  as  a
73       string specifying a decimal port number.
74
75       If  the hints argument is not null, it refers to a structure containing
76       input values that directs the operation by  providing  options  and  by
77       limiting  the  returned  information to a specific socket type, address
78       family, and/or protocol, as described below. In  this  hints  structure
79       every member other than ai_flags, ai_family, ai_socktype, and ai_proto‐
80       col shall be set to zero or a null pointer. A value  of  AF_UNSPEC  for
81       ai_family  means  that  the  caller  shall accept any address family. A
82       value of zero for ai_socktype means that the caller  shall  accept  any
83       socket  type.  A  value  of  zero for ai_protocol means that the caller
84       shall accept any protocol. If hints is a  null  pointer,  the  behavior
85       shall be as if it referred to a structure containing the value zero for
86       the ai_flags, ai_socktype, and ai_protocol fields,  and  AF_UNSPEC  for
87       the ai_family field.
88
89       The  ai_flags field to which the hints parameter points shall be set to
90       zero or be the bitwise-inclusive OR  of  one  or  more  of  the  values
91       AI_PASSIVE,  AI_CANONNAME, AI_NUMERICHOST, AI_NUMERICSERV, AI_V4MAPPED,
92       AI_ALL, and AI_ADDRCONFIG.
93
94       If the AI_PASSIVE flag is specified, the returned  address  information
95       shall  be  suitable  for use in binding a socket for accepting incoming
96       connections for the specified service. In this case,  if  the  nodename
97       argument  is  null,  then  the IP address portion of the socket address
98       structure  shall  be  set  to  INADDR_ANY  for  an  IPv4   address   or
99       IN6ADDR_ANY_INIT  for  an  IPv6  address. If the AI_PASSIVE flag is not
100       specified, the returned address information shall  be  suitable  for  a
101       call  to  connect()  (for  a connection-mode protocol) or for a call to
102       connect(), sendto(), or sendmsg() (for a connectionless  protocol).  In
103       this  case,  if the nodename argument is null, then the IP address por‐
104       tion of the socket address structure  shall  be  set  to  the  loopback
105       address.  The AI_PASSIVE flag shall be ignored if the nodename argument
106       is not null.
107
108       If the AI_CANONNAME flag is specified and the nodename argument is  not
109       null, the function shall attempt to determine the canonical name corre‐
110       sponding to nodename (for example, if nodename is an alias or shorthand
111       notation for a complete name).
112
113       Note:     Since different implementations use different conceptual mod‐
114                 els, the terms ``canonical name''  and  ``alias''  cannot  be
115                 precisely  defined for the general case. However, Domain Name
116                 System implementations are expected to interpret them as they
117                 are used in RFC 1034.
118
119                 A  numeric  host  address  string is not a ``name'', and thus
120                 does not have a ``canonical name'' form; no address  to  host
121                 name  translation is performed. See below for handling of the
122                 case where a canonical name cannot be obtained.
123
124       If the AI_NUMERICHOST flag  is  specified,  then  a  non-null  nodename
125       string  supplied  shall be a numeric host address string. Otherwise, an
126       [EAI_NONAME] error is returned. This flag shall  prevent  any  type  of
127       name resolution service (for example, the DNS) from being invoked.
128
129       If  the  AI_NUMERICSERV  flag  is  specified,  then a non-null servname
130       string supplied shall be a numeric port string. Otherwise, an  [EAI_NO‐
131       NAME] error shall be returned. This flag shall prevent any type of name
132       resolution service (for example, NIS+) from being invoked.
133
134       If the AI_V4MAPPED  flag  is  specified  along  with  an  ai_family  of
135       AF_INET6, then getaddrinfo() shall return IPv4-mapped IPv6 addresses on
136       finding no matching  IPv6  addresses  (ai_addrlen  shall  be  16).  The
137       AI_V4MAPPED  flag shall be ignored unless ai_family equals AF_INET6. If
138       the AI_ALL flag is used with the AI_V4MAPPED flag,  then  getaddrinfo()
139       shall  return  all  matching  IPv6  and IPv4 addresses. The AI_ALL flag
140       without the AI_V4MAPPED flag is ignored.
141
142       If the  AI_ADDRCONFIG  flag  is  specified,  IPv4  addresses  shall  be
143       returned only if an IPv4 address is configured on the local system, and
144       IPv6 addresses shall be returned only if an IPv6 address is  configured
145       on the local system.
146
147       The  ai_socktype  field  to  which  argument hints points specifies the
148       socket type for the service, as defined in  socket().   If  a  specific
149       socket type is not given (for example, a value of zero) and the service
150       name could be interpreted  as  valid  with  multiple  supported  socket
151       types, the implementation shall attempt to resolve the service name for
152       all supported socket types and, in the absence of errors, all  possible
153       results shall be returned. A non-zero socket type value shall limit the
154       returned information to values with the specified socket type.
155
156       If the ai_family field to which hints points has the  value  AF_UNSPEC,
157       addresses shall be returned for use with any address family that can be
158       used with the specified nodename and/or servname.  Otherwise, addresses
159       shall  be  returned  for use only with the specified address family. If
160       ai_family is not AF_UNSPEC and ai_protocol is not zero, then  addresses
161       shall  be  returned  for use only with the specified address family and
162       protocol; the value of ai_protocol shall be interpreted as in a call to
163       the  socket()  function  with the corresponding values of ai_family and
164       ai_protocol.
165

RETURN VALUE

167       A zero return value for getaddrinfo() indicates successful  completion;
168       a  non-zero return value indicates failure. The possible values for the
169       failures are listed in the ERRORS section.
170
171       Upon successful return of getaddrinfo(),  the  location  to  which  res
172       points  shall  refer  to  a linked list of addrinfo structures, each of
173       which shall specify a socket address and information for use in  creat‐
174       ing  a  socket  with  which  to use that socket address. The list shall
175       include at least one addrinfo structure.  The  ai_next  field  of  each
176       structure  contains  a  pointer to the next structure on the list, or a
177       null pointer if it is the last structure on the list. Each structure on
178       the list shall include values for use with a call to the socket() func‐
179       tion, and a socket address for use with the connect() function  or,  if
180       the  AI_PASSIVE  flag  was specified, for use with the bind() function.
181       The fields ai_family, ai_socktype, and ai_protocol shall be  usable  as
182       the  arguments to the socket() function to create a socket suitable for
183       use with the returned address. The fields ai_addr  and  ai_addrlen  are
184       usable  as the arguments to the connect() or bind() functions with such
185       a socket, according to the AI_PASSIVE flag.
186
187       If nodename is not null, and if requested by the AI_CANONNAME flag, the
188       ai_canonname field of the first returned addrinfo structure shall point
189       to a null-terminated string containing the canonical name corresponding
190       to  the  input  nodename;  if the canonical name is not available, then
191       ai_canonname shall refer to the nodename argument or a string with  the
192       same  contents.  The  contents  of  the  ai_flags field of the returned
193       structures are undefined.
194
195       All fields in socket address structures returned by getaddrinfo()  that
196       are not filled in through an explicit argument (for example, sin6_flow‐
197       info) shall be set to zero.
198
199       Note:     This makes it easier to compare socket address structures.
200

ERRORS

202       The getaddrinfo() function shall  fail  and  return  the  corresponding
203       error value if:
204
205       [EAI_AGAIN] The  name  could  not  be  resolved  at  this  time. Future
206                   attempts may succeed.
207
208       [EAI_BADFLAGS]
209                   The flags parameter had an invalid value.
210
211       [EAI_FAIL]  A non-recoverable error occurred when attempting to resolve
212                   the name.
213
214       [EAI_FAMILY]
215                   The address family was not recognized.
216
217       [EAI_MEMORY]
218                   There  was a memory allocation failure when trying to allo‐
219                   cate storage for the return value.
220
221       [EAI_NONAME]
222                   The name does not resolve for the supplied parameters.
223
224                   Neither nodename nor servname were supplied. At  least  one
225                   of these shall be supplied.
226
227       [EAI_SERVICE]
228                   The  service  passed  was  not recognized for the specified
229                   socket type.
230
231       [EAI_SOCKTYPE]
232                   The intended socket type was not recognized.
233
234       [EAI_SYSTEM]
235                   A system error occurred; the error code  can  be  found  in
236                   errno.
237
238       The following sections are informative.
239

EXAMPLES

241       The  following  (incomplete)  program  demonstrates  the  use of getad‐
242       drinfo() to obtain the socket  address  structure(s)  for  the  service
243       named  in  the  program's command-line argument. The program then loops
244       through each of the address structures attempting to create and bind  a
245       socket to the address, until it performs a successful bind().
246
247           #include <stdio.h>
248           #include <stdlib.h>
249           #include <unistd.h>
250           #include <string.h>
251           #include <sys/socket.h>
252           #include <netdb.h>
253
254           int
255           main(int argc, char *argv[])
256           {
257               struct addrinfo *result, *rp;
258               int sfd, s;
259
260               if (argc != 2) {
261                   fprintf(stderr, "Usage: %s port\n", argv[0]);
262                   exit(EXIT_FAILURE);
263               }
264
265               struct addrinfo hints = {};
266               hints.ai_family = AF_UNSPEC;
267               hints.ai_socktype = SOCK_DGRAM;
268               hints.ai_flags = AI_PASSIVE;
269               hints.ai_protocol = 0;
270
271               s = getaddrinfo(NULL, argv[1], &hints, &result);
272               if (s != 0) {
273                   fprintf(stderr, "getaddrinfo: %s\n", gai_strerror(s));
274                   exit(EXIT_FAILURE);
275               }
276
277               /* getaddrinfo() returns a list of address structures.
278                  Try each address until a successful bind().
279                  If socket(2) (or bind(2)) fails, close the socket
280                  and try the next address. */
281
282               for (rp = result; rp != NULL; rp = rp->ai_next) {
283                   sfd = socket(rp->ai_family, rp->ai_socktype,
284                       rp->ai_protocol);
285                   if (sfd == -1)
286                       continue;
287
288                   if (bind(sfd, rp->ai_addr, rp->ai_addrlen) == 0)
289                       break;            /* Success */
290
291                   close(sfd);
292               }
293
294               if (rp == NULL) {         /* No address succeeded */
295                   fprintf(stderr, "Could not bind\n");
296                   exit(EXIT_FAILURE);
297               }
298
299               freeaddrinfo(result);     /* No longer needed */
300
301                        /* ... use socket bound to sfd ... */
302           }
303

APPLICATION USAGE

305       If  the  caller  handles  only  TCP  and not UDP, for example, then the
306       ai_protocol member of the hints structure should be set to  IPPROTO_TCP
307       when getaddrinfo() is called.
308
309       If the caller handles only IPv4 and not IPv6, then the ai_family member
310       of the hints structure should be set to AF_INET when  getaddrinfo()  is
311       called.
312
313       The  term ``canonical name'' is misleading; it is taken from the Domain
314       Name System (RFC 2181). It should be noted that the canonical name is a
315       result of alias processing, and not necessarily a unique attribute of a
316       host, address, or set of addresses. See RFC 2181 for more discussion of
317       this in the Domain Name System context.
318

RATIONALE

320       None.
321

FUTURE DIRECTIONS

323       None.
324

SEE ALSO

326       connect(), endservent(), gai_strerror(), getnameinfo(), socket()
327
328       The Base Definitions volume of POSIX.1‐2008, <netdb.h>, <sys_socket.h>
329
331       Portions  of  this text are reprinted and reproduced in electronic form
332       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
333       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
334       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
335       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
336       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  In  the
337       event of any discrepancy between this version and the original IEEE and
338       The Open Group Standard, the original IEEE and The Open Group  Standard
339       is  the  referee document. The original Standard can be obtained online
340       at http://www.unix.org/online.html .
341
342       Any typographical or formatting errors that appear  in  this  page  are
343       most likely to have been introduced during the conversion of the source
344       files to man page format. To report such errors,  see  https://www.ker
345       nel.org/doc/man-pages/reporting_bugs.html .
346
347
348
349IEEE/The Open Group                  2013                     FREEADDRINFO(3P)
Impressum