getaddrinfo(3p) - phpMan

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 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 loca-
       tion (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 cre-
       ating 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 point-
       ers 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() 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-termi-
       nated  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 may direct the operation 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 proto-
       col. 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 por-
       tion 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 corre-
       sponding 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 imple-
              mentations 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  per-
       formed.  See below for handling of the case where a canonical name can-
       not 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_NO-
       NAME] 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  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 config-
       ured 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 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
       are  returned for use only with the specified address family and proto-
       col; 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  creat-
       ing  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() func-
       tion, 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_flow-
       info) 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(),  getservby-
       name(),  socket(), the Base Definitions volume 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, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
       Specifications  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 Standard, 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)