FREEADDRINFO(3)            POSIX Programmer's Manual           FREEADDRINFO(3)



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


NNAAMMEE
       freeaddrinfo, getaddrinfo -- get address information

SSYYNNOOPPSSIISS
       #include <sys/socket.h>
       #include <netdb.h>

       void freeaddrinfo(struct addrinfo *_a_i);
       int getaddrinfo(const char *restrict _n_o_d_e_n_a_m_e,
           const char *restrict _s_e_r_v_n_a_m_e,
           const struct addrinfo *restrict _h_i_n_t_s,
           struct addrinfo **restrict _r_e_s);

DDEESSCCRRIIPPTTIIOONN
       The _f_r_e_e_a_d_d_r_i_n_f_o() function shall free one or more aaddddrriinnffoo structures
       returned by _g_e_t_a_d_d_r_i_n_f_o(), along with any additional storage associated
       with those structures. If the _a_i___n_e_x_t field of the structure is not
       null, the entire list of structures shall be freed. The _f_r_e_e_a_d_d_r_i_n_f_o()
       function shall support the freeing of arbitrary sublists of an aaddddrriinnffoo
       list originally returned by _g_e_t_a_d_d_r_i_n_f_o().

       The _g_e_t_a_d_d_r_i_n_f_o() 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.

       NNoottee::     In many cases it is implemented by the Domain Name System, as
                 documented in RFC 1034, RFC 1035, and RFC 1886.

       The _f_r_e_e_a_d_d_r_i_n_f_o() and _g_e_t_a_d_d_r_i_n_f_o() functions shall be thread-safe.

       The _n_o_d_e_n_a_m_e and _s_e_r_v_n_a_m_e 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 _n_o_d_e_n_a_m_e 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 _i_n_e_t___a_d_d_r() are
       valid.

       If the specified address family is AF_INET6 or AF_UNSPEC, standard IPv6
       text forms described in _i_n_e_t___n_t_o_p() are valid.

       If _n_o_d_e_n_a_m_e is not null, the requested service location is named by
       _n_o_d_e_n_a_m_e; otherwise, the requested service location is local to the
       caller.

       If _s_e_r_v_n_a_m_e is null, the call shall return network-level addresses for
       the specified _n_o_d_e_n_a_m_e_.  If _s_e_r_v_n_a_m_e 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 _h_i_n_t_s 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. In this _h_i_n_t_s structure
       every member other than _a_i___f_l_a_g_s, _a_i___f_a_m_i_l_y, _a_i___s_o_c_k_t_y_p_e, and
       _a_i___p_r_o_t_o_c_o_l shall be set to zero or a null pointer. A value of
       AF_UNSPEC for _a_i___f_a_m_i_l_y means that the caller shall accept any address
       family. A value of zero for _a_i___s_o_c_k_t_y_p_e means that the caller shall
       accept any socket type. A value of zero for _a_i___p_r_o_t_o_c_o_l means that the
       caller shall accept any protocol. If _h_i_n_t_s is a null pointer, the
       behavior shall be as if it referred to a structure containing the value
       zero for the _a_i___f_l_a_g_s, _a_i___s_o_c_k_t_y_p_e, and _a_i___p_r_o_t_o_c_o_l fields, and
       AF_UNSPEC for the _a_i___f_a_m_i_l_y field.

       The _a_i___f_l_a_g_s field to which the _h_i_n_t_s 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 _n_o_d_e_n_a_m_e
       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 _c_o_n_n_e_c_t() (for a connection-mode protocol) or for a call to
       _c_o_n_n_e_c_t(), _s_e_n_d_t_o(), or _s_e_n_d_m_s_g() (for a connectionless protocol). In
       this case, if the _n_o_d_e_n_a_m_e 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 _n_o_d_e_n_a_m_e argument
       is not null.

       If the AI_CANONNAME flag is specified and the _n_o_d_e_n_a_m_e argument is not
       null, the function shall attempt to determine the canonical name
       corresponding to _n_o_d_e_n_a_m_e (for example, if _n_o_d_e_n_a_m_e is an alias or
       shorthand notation for a complete name).

       NNoottee::     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 _n_o_d_e_n_a_m_e
       string supplied shall be a numeric host address string. Otherwise, an
       [[EEAAII__NNOONNAAMMEE]] 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 _s_e_r_v_n_a_m_e
       string supplied shall be a numeric port string. Otherwise, an
       [[EEAAII__NNOONNAAMMEE]] error shall be returned. This flag shall prevent any type
       of name resolution service (for example, NIS+) from being invoked.

       If the AI_V4MAPPED flag is specified along with an _a_i___f_a_m_i_l_y of
       AF_INET6, then _g_e_t_a_d_d_r_i_n_f_o() shall return IPv4-mapped IPv6 addresses on
       finding no matching IPv6 addresses (_a_i___a_d_d_r_l_e_n shall be 16). The
       AI_V4MAPPED flag shall be ignored unless _a_i___f_a_m_i_l_y equals AF_INET6. If
       the AI_ALL flag is used with the AI_V4MAPPED flag, then _g_e_t_a_d_d_r_i_n_f_o()
       shall return all matching IPv6 and IPv4 addresses. The AI_ALL flag
       without the AI_V4MAPPED flag is 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 _a_i___s_o_c_k_t_y_p_e field to which argument _h_i_n_t_s points specifies the
       socket type for the service, as defined in _s_o_c_k_e_t().  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 _a_i___f_a_m_i_l_y field to which _h_i_n_t_s points has the value AF_UNSPEC,
       addresses shall be returned for use with any address family that can be
       used with the specified _n_o_d_e_n_a_m_e and/or _s_e_r_v_n_a_m_e.  Otherwise, addresses
       shall be returned for use only with the specified address family. If
       _a_i___f_a_m_i_l_y is not AF_UNSPEC and _a_i___p_r_o_t_o_c_o_l is not zero, then addresses
       shall be returned for use only with the specified address family and
       protocol; the value of _a_i___p_r_o_t_o_c_o_l shall be interpreted as in a call to
       the _s_o_c_k_e_t() function with the corresponding values of _a_i___f_a_m_i_l_y and
       _a_i___p_r_o_t_o_c_o_l.

RREETTUURRNN VVAALLUUEE
       A zero return value for _g_e_t_a_d_d_r_i_n_f_o() 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 _g_e_t_a_d_d_r_i_n_f_o(), the location to which _r_e_s
       points shall refer to a linked list of aaddddrriinnffoo 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 aaddddrriinnffoo structure. The _a_i___n_e_x_t 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 _s_o_c_k_e_t()
       function, and a socket address for use with the _c_o_n_n_e_c_t() function or,
       if the AI_PASSIVE flag was specified, for use with the _b_i_n_d() function.
       The fields _a_i___f_a_m_i_l_y, _a_i___s_o_c_k_t_y_p_e, and _a_i___p_r_o_t_o_c_o_l shall be usable as
       the arguments to the _s_o_c_k_e_t() function to create a socket suitable for
       use with the returned address. The fields _a_i___a_d_d_r and _a_i___a_d_d_r_l_e_n are
       usable as the arguments to the _c_o_n_n_e_c_t() or _b_i_n_d() functions with such
       a socket, according to the AI_PASSIVE flag.

       If _n_o_d_e_n_a_m_e is not null, and if requested by the AI_CANONNAME flag, the
       _a_i___c_a_n_o_n_n_a_m_e field of the first returned aaddddrriinnffoo structure shall point
       to a null-terminated string containing the canonical name corresponding
       to the input _n_o_d_e_n_a_m_e; if the canonical name is not available, then
       _a_i___c_a_n_o_n_n_a_m_e shall refer to the _n_o_d_e_n_a_m_e argument or a string with the
       same contents. The contents of the _a_i___f_l_a_g_s field of the returned
       structures are undefined.

       All fields in socket address structures returned by _g_e_t_a_d_d_r_i_n_f_o() that
       are not filled in through an explicit argument (for example,
       _s_i_n_6___f_l_o_w_i_n_f_o) shall be set to zero.

       NNoottee::     This makes it easier to compare socket address structures.

EERRRROORRSS
       The _g_e_t_a_d_d_r_i_n_f_o() 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 _f_l_a_g_s 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 _n_o_d_e_n_a_m_e nor _s_e_r_v_n_a_m_e 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
                   _e_r_r_n_o.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       The following (incomplete) program demonstrates the use of
       _g_e_t_a_d_d_r_i_n_f_o() 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 _b_i_n_d().

           ##iinncclluuddee <<ssttddiioo..hh>>
           ##iinncclluuddee <<ssttddlliibb..hh>>
           ##iinncclluuddee <<uunniissttdd..hh>>
           ##iinncclluuddee <<ssttrriinngg..hh>>
           ##iinncclluuddee <<ssyyss//ssoocckkeett..hh>>
           ##iinncclluuddee <<nneettddbb..hh>>

           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 = {};
               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 ... */
           }

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       If the caller handles only TCP and not UDP, for example, then the
       _a_i___p_r_o_t_o_c_o_l member of the _h_i_n_t_s structure should be set to IPPROTO_TCP
       when _g_e_t_a_d_d_r_i_n_f_o() is called.

       If the caller handles only IPv4 and not IPv6, then the _a_i___f_a_m_i_l_y member
       of the _h_i_n_t_s structure should be set to AF_INET when _g_e_t_a_d_d_r_i_n_f_o() is
       called.

       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.

RRAATTIIOONNAALLEE
       None.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _c_o_n_n_e_c_t(), _e_n_d_s_e_r_v_e_n_t(), _g_a_i___s_t_r_e_r_r_o_r(), _g_e_t_n_a_m_e_i_n_f_o(), _s_o_c_k_e_t()

       The Base Definitions volume of POSIX.1-2008, <<nneettddbb..hh>>, <<ssyyss__ssoocckkeett..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group Standard
       is the referee document. The original Standard can be obtained online
       at http://www.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2013                      FREEADDRINFO(3)
