Man Pages

getaddrinfo(3p) - phpMan getaddrinfo(3p) - phpMan

Command: man perldoc info search(apropos)  


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



PROLOG
       This manual page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may dif-
       fer (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  speci-
       fied  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 spec-
       ified in inet_addr() are valid.

       If the specified address family is AF_INET6 or AF_UNSPEC, standard IPv6 text forms described in inet_ntop() 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 spec-
       ified 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 may direct the opera-
       tion by providing options and by limiting the returned information to a specific socket type,  address  family,
       and/or  protocol.  In  this  hints  structure  every  member  other  than ai_flags, ai_family, ai_socktype, and
       ai_protocol shall be set to zero or a null pointer. 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  con-
       nect(), 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_PAS-
       SIVE 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 nota-
       tion 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 resolu-
       tion 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  resolu-
       tion service (for example, NIS+) from being invoked.

       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 ( ai_addrlen shall  be  16).  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 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  ai_socktype  field to which argument hints points specifies the socket type for the service, as defined in
       socket(). 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 ser-
       vice 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 are 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_fam-
       ily and ai_protocol.

RETURN VALUE
       A zero return value for getaddrinfo() indicates successful completion; a non-zero return value indicates  fail-
       ure. 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 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.

       EAI_OVERFLOW

              An argument buffer overflowed.


       The following sections are informative.

EXAMPLES
       None.

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.

       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.

SEE ALSO
       connect(), gai_strerror(), gethostbyaddr(), getnameinfo(), getservbyname(), socket(), the Base Definitions vol-
       ume of IEEE Std 1003.1-2001, <netdb.h>, <sys/socket.h>

COPYRIGHT
       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition, Stan-
       dard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base  Specifica-
       tions  Issue  6,  Copyright (C) 2001-2003 by the Institute of Electrical and Electronics Engineers, Inc and The
       Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Stan-
       dard,  the  original  IEEE  and  The  Open Group Standard is the referee document. The original Standard can be
       obtained online at http://www.opengroup.org/unix/online.html .



IEEE/The Open Group                  2003                     FREEADDRINFO(3P)