# freeaddrinfo

## PROLOG



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


## NAME



           freeaddrinfo, getaddrinfo — get address information
    


## SYNOPSIS



           #include <sys/socket.h>
           #include <netdb.h>
    
           void freeaddrinfo(struct addrinfo *_ai_);
           int getaddrinfo(const char *restrict _nodename_ ,
               const char *restrict _servname_ ,
               const struct addrinfo *restrict _hints_ ,
               struct addrinfo **restrict _res_);
    


## DESCRIPTION



           The _freeaddrinfo_() function shall free one or more **addrinfo**
           structures returned by _getaddrinfo_(), along with any additional
           storage associated with those structures. If the _ai_next_ field of
           the structure is not null, the entire list of structures shall be
           freed. The _freeaddrinfo_() function shall support the freeing of
           arbitrary sublists of an **addrinfo** list originally returned by
           _getaddrinfo_().
    
           The _getaddrinfo_() function shall translate the name of a service
           location (for example, a host name) and/or a service name and
           shall return a set of socket addresses and associated information
           to be used in creating a socket with which to address the
           specified service.
    
           **Note:** In many cases it is implemented by the Domain Name System,
                  as documented in RFC 1034, RFC 1035, and RFC 1886.
    
           The _freeaddrinfo_() and _getaddrinfo_() functions shall be thread-
           safe.
    
           The _nodename_ and _servname_ arguments are either null pointers or
           pointers to null-terminated strings. One or both of these two
           arguments shall be supplied by the application as a non-null
           pointer.
    
           The format of a valid name depends on the address family or
           families.  If a specific family is not given and the name could be
           interpreted as valid within multiple supported families, the
           implementation shall attempt to resolve the name in all supported
           families and, in absence of errors, one or more results shall be
           returned.
    
           If the _nodename_ argument is not null, it can be a descriptive name
           or can be an address string.  If the specified address family is
           AF_INET, AF_INET6, or AF_UNSPEC, valid descriptive names include
           host names. If the specified address family is AF_INET or
           AF_UNSPEC, address strings using Internet standard dot notation as
           specified in inet_addr(3p) are valid.
    
           If the specified address family is AF_INET6 or AF_UNSPEC, standard
           IPv6 text forms described in inet_ntop(3p) are valid.
    
           If _nodename_ is not null, the requested service location is named
           by _nodename_ ; otherwise, the requested service location is local to
           the caller.
    
           If _servname_ is null, the call shall return network-level addresses
           for the specified _nodename._  If _servname_ is not null, it is a
           null-terminated character string identifying the requested
           service. This can be either a descriptive name or a numeric
           representation suitable for use with the address family or
           families.  If the specified address family is AF_INET, AF_INET6,
           or AF_UNSPEC, the service can be specified as a string specifying
           a decimal port number.
    
           If the _hints_ argument is not null, it refers to a structure
           containing input values that directs the operation by providing
           options and by limiting the returned information to a specific
           socket type, address family, and/or protocol, as described below.
           The application shall ensure that each of the _ai_addrlen_ , _ai_addr_ ,
           _ai_canonname_ , and _ai_next_ members, as well as each of the non-
           standard additional members, if any, of this _hints_ structure is
           initialized. If any of these members has a value other than the
           value that would result from default initialization, the behavior
           is implementation-defined. A value of AF_UNSPEC for _ai_family_
           means that the caller shall accept any address family. A value of
           zero for _ai_socktype_ means that the caller shall accept any socket
           type. A value of zero for _ai_protocol_ means that the caller shall
           accept any protocol. If _hints_ is a null pointer, the behavior
           shall be as if it referred to a structure containing the value
           zero for the _ai_flags_ , _ai_socktype_ , and _ai_protocol_ fields, and
           AF_UNSPEC for the _ai_family_ field.
    
           The _ai_flags_ field to which the _hints_ parameter points shall be
           set to zero or be the bitwise-inclusive OR of one or more of the
           values AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST, AI_NUMERICSERV,
           AI_V4MAPPED, AI_ALL, and AI_ADDRCONFIG.
    
           If the AI_PASSIVE flag is specified, the returned address
           information shall be suitable for use in binding a socket for
           accepting incoming connections for the specified service. In this
           case, if the _nodename_ argument is null, then the IP address
           portion of the socket address structure shall be set to INADDR_ANY
           for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6 address. If
           the AI_PASSIVE flag is not specified, the returned address
           information shall be suitable for a call to _connect_() (for a
           connection-mode protocol) or for a call to _connect_(), _sendto_(), or
           _sendmsg_() (for a connectionless protocol). In this case, if the
           _nodename_ argument is null, then the IP address portion of the
           socket address structure shall be set to the loopback address. The
           AI_PASSIVE flag shall be ignored if the _nodename_ argument is not
           null.
    
           If the AI_CANONNAME flag is specified and the _nodename_ argument is
           not null, the function shall attempt to determine the canonical
           name corresponding to _nodename_ (for example, if _nodename_ is an
           alias or shorthand notation for a complete name).
    
           **Note:** Since different implementations use different conceptual
                  models, the terms ``canonical name'' and ``alias'' cannot
                  be precisely defined for the general case. However, Domain
                  Name System implementations are expected to interpret them
                  as they are used in RFC 1034.
    
                     A numeric host address string is not a ``name'', and
                     thus does not have a ``canonical name'' form; no address
                     to host name translation is performed. See below for
                     handling of the case where a canonical name cannot be
                     obtained.
    
           If the AI_NUMERICHOST flag is specified, then a non-null _nodename_
           string supplied shall be a numeric host address string. Otherwise,
           an **[EAI_NONAME]** error is returned. This flag shall prevent any
           type of name resolution service (for example, the DNS) from being
           invoked.
    
           If the AI_NUMERICSERV flag is specified, then a non-null _servname_
           string supplied shall be a numeric port string. Otherwise, an
           **[EAI_NONAME]** error shall be returned. This flag shall prevent any
           type of name resolution service (for example, NIS+) from being
           invoked.
    
           By default, with an _ai_family_ of AF_INET6, _getaddrinfo_() shall
           return only IPv6 addresses. If the AI_V4MAPPED flag is specified
           along with an _ai_family_ of AF_INET6, then _getaddrinfo_() shall
           return IPv4-mapped IPv6 addresses on finding no matching IPv6
           addresses. The AI_V4MAPPED flag shall be ignored unless _ai_family_
           equals AF_INET6. If the AI_ALL flag is used with the AI_V4MAPPED
           flag, then _getaddrinfo_() shall return all matching IPv6 and IPv4
           addresses. The AI_ALL flag without the AI_V4MAPPED flag shall be
           ignored.
    
           If the AI_ADDRCONFIG flag is specified, IPv4 addresses shall be
           returned only if an IPv4 address is configured on the local
           system, and IPv6 addresses shall be returned only if an IPv6
           address is configured on the local system.
    
           The _ai_socktype_ field to which argument _hints_ points specifies the
           socket type for the service, as defined in socket(3p).  If a
           specific socket type is not given (for example, a value of zero)
           and the service name could be interpreted as valid with multiple
           supported socket types, the implementation shall attempt to
           resolve the service name for all supported socket types and, in
           the absence of errors, all possible results shall be returned. A
           non-zero socket type value shall limit the returned information to
           values with the specified socket type.
    
           If the _ai_family_ field to which _hints_ points has the value
           AF_UNSPEC, addresses shall be returned for use with any address
           family that can be used with the specified _nodename_ and/or
           _servname_.  Otherwise, addresses shall be returned for use only
           with the specified address family. If _ai_family_ is not AF_UNSPEC
           and _ai_protocol_ is not zero, then addresses shall be returned for
           use only with the specified address family and protocol; the value
           of _ai_protocol_ shall be interpreted as in a call to the _socket_()
           function with the corresponding values of _ai_family_ and
           _ai_protocol_.
    


## RETURN VALUE



           A zero return value for _getaddrinfo_() indicates successful
           completion; a non-zero return value indicates failure. The
           possible values for the failures are listed in the ERRORS section.
    
           Upon successful return of _getaddrinfo_(), the location to which _res_
           points shall refer to a linked list of **addrinfo** structures, each
           of which shall specify a socket address and information for use in
           creating a socket with which to use that socket address. The list
           shall include at least one **addrinfo** structure. The _ai_next_ field
           of each structure contains a pointer to the next structure on the
           list, or a null pointer if it is the last structure on the list.
           Each structure on the list shall include values for use with a
           call to the _socket_() function, and a socket address for use with
           the _connect_() function or, if the AI_PASSIVE flag was specified,
           for use with the _bind_() function. The fields _ai_family_ ,
           _ai_socktype_ , and _ai_protocol_ shall be usable as the arguments to
           the _socket_() function to create a socket suitable for use with the
           returned address. The fields _ai_addr_ and _ai_addrlen_ are usable as
           the arguments to the _connect_() or _bind_() functions with such a
           socket, according to the AI_PASSIVE flag.
    
           If _nodename_ is not null, and if requested by the AI_CANONNAME
           flag, the _ai_canonname_ field of the first returned **addrinfo**
           structure shall point to a null-terminated string containing the
           canonical name corresponding to the input _nodename_ ; if the
           canonical name is not available, then _ai_canonname_ shall refer to
           the _nodename_ argument or a string with the same contents. The
           contents of the _ai_flags_ field of the returned structures are
           undefined.
    
           All fields in socket address structures returned by _getaddrinfo_()
           that are not filled in through an explicit argument (for example,
           _sin6_flowinfo_) shall be set to zero.
    
           **Note:** This makes it easier to compare socket address structures.
    


## ERRORS



           The _getaddrinfo_() function shall fail and return the corresponding
           error value if:
    
           [EAI_AGAIN] The name could not be resolved at this time. Future
                       attempts may succeed.
    
           [EAI_BADFLAGS]
                       The _flags_ parameter had an invalid value.
    
           [EAI_FAIL]  A non-recoverable error occurred when attempting to
                       resolve the name.
    
           [EAI_FAMILY]
                       The address family was not recognized.
    
           [EAI_MEMORY]
                       There was a memory allocation failure when trying to
                       allocate storage for the return value.
    
           [EAI_NONAME]
                       The name does not resolve for the supplied parameters.
    
                       Neither _nodename_ nor _servname_ were supplied. At least
                       one of these shall be supplied.
    
           [EAI_SERVICE]
                       The service passed was not recognized for the
                       specified socket type.
    
           [EAI_SOCKTYPE]
                       The intended socket type was not recognized.
    
           [EAI_SYSTEM]
                       A system error occurred; the error code can be found
                       in _errno_.
    
           _The following sections are informative._
    


## EXAMPLES



           The following (incomplete) program demonstrates the use of
           _getaddrinfo_() to obtain the socket address structure(s) for the
           service named in the program's command-line argument. The program
           then loops through each of the address structures attempting to
           create and bind a socket to the address, until it performs a
           successful _bind_().
    
               #include <stdio.h>
               #include <stdlib.h>
               #include <unistd.h>
               #include <string.h>
               #include <sys/socket.h>
               #include <netdb.h>
    
               int
               main(int argc, char *argv[])
               {
                   struct addrinfo *result, *rp;
                   int sfd, s;
    
                   if (argc != 2) {
                       fprintf(stderr, "Usage: %s port\n", argv[0]);
                       exit(EXIT_FAILURE);
                   }
    
                   struct addrinfo hints = {0};
                   hints.ai_family = AF_UNSPEC;
                   hints.ai_socktype = SOCK_DGRAM;
                   hints.ai_flags = AI_PASSIVE;
                   hints.ai_protocol = 0;
    
                   s = getaddrinfo(NULL, argv[1], &hints, &result);
                   if (s != 0) {
                       fprintf(stderr, "getaddrinfo: %s\n", gai_strerror(s));
                       exit(EXIT_FAILURE);
                   }
    
                   /* getaddrinfo() returns a list of address structures.
                      Try each address until a successful bind().
                      If socket(2) (or bind(2)) fails, close the socket
                      and try the next address. */
    
                   for (rp = result; rp != NULL; rp = rp->ai_next) {
                       sfd = socket(rp->ai_family, rp->ai_socktype,
                           rp->ai_protocol);
                       if (sfd == -1)
                           continue;
    
                       if (bind(sfd, rp->ai_addr, rp->ai_addrlen) == 0)
                           break;            /* Success */
    
                       close(sfd);
                   }
    
                   if (rp == NULL) {         /* No address succeeded */
                       fprintf(stderr, "Could not bind\n");
                       exit(EXIT_FAILURE);
                   }
    
                   freeaddrinfo(result);     /* No longer needed */
    
                            /* ... use socket bound to sfd ... */
               }
    


## APPLICATION USAGE



           If the caller handles only TCP and not UDP, for example, then the
           _ai_protocol_ member of the _hints_ structure should be set to
           IPPROTO_TCP when _getaddrinfo_() is called.
    
           If the caller handles only IPv4 and not IPv6, then the _ai_family_
           member of the _hints_ structure should be set to AF_INET when
           _getaddrinfo_() is called.
    
           Although it is common practice to initialize the _hints_ structure
           using:
    
               struct addrinfo hints;
               memset(&hints, 0, sizeof hints);
    
           this method is not portable according to this standard, because
           the structure can contain pointer or floating-point members that
           are not required to have an all-bits-zero representation after
           default initialization. Portable methods make use of default
           initialization; for example:
    
               struct addrinfo hints = { 0 };
    
           or:
    
               static struct addrinfo hints_init;
               struct addrinfo hints = hints_init;
    
           A future version of this standard may require that a pointer
           object with an all-bits-zero representation is a null pointer, and
           that **addrinfo** does not have any floating-point members if a
           floating-point object with an all-bits-zero representation does
           not have the value 0.0.
    
           The term ``canonical name'' is misleading; it is taken from the
           Domain Name System (RFC 2181). It should be noted that the
           canonical name is a result of alias processing, and not
           necessarily a unique attribute of a host, address, or set of
           addresses. See RFC 2181 for more discussion of this in the Domain
           Name System context.
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           None.
    


* * *