freeaddrinfo(3XNET)				   X/Open Networking Services Library Functions 			       freeaddrinfo(3XNET)

NAME

       freeaddrinfo, getaddrinfo - get address information

SYNOPSIS

       cc [ flag ... ] file ... -lxnet [ library ... ]
       #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 frees one or more addrinfo structures returned by getaddrinfo(), along with any additional storage associated
       with those structures. If the ai_next member of the structure is not null, the entire list of structures is freed. The freeaddrinfo() func-
       tion supports the freeing of arbitrary sublists of an addrinfo list originally returned by getaddrinfo().

       The  getaddrinfo() function translates the name of a service location (for example, a host name) and/or a service name and returns a set of
       socket addresses and associated information to be used in creating a socket with which to address the specified service.

       The nodename and servname arguments are either null pointers or pointers to null-terminated strings. One or both of these two arguments are
       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 attempts to resolve the name in all supported families and, in  absence	of
       errors, one or more results are 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(3XNET) are valid.

       If the specified address family is AF_INET6 or AF_UNSPEC, standard IPv6 text forms described in inet_ntop(3XNET) 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 returns network-level addresses for the specified nodename. If servname is not null, it is a  null-terminated
       character  string  identifying the requested service. This string 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 can 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 is set to 0 or a null pointer. A value of AF_UNSPEC for ai_family means that the
       caller accepts any address family. A value of 0 for ai_socktype means that the caller accepts any socket type. A value of 0 for ai_protocol
       means  that  the  caller  accepts any protocol. If hints is a null pointer, the behavior is as if it referred to a structure containing the
       value 0 for the ai_flags, ai_socktype, and ai_protocol members, and AF_UNSPEC for the ai_family member.

       The ai_flags member to which the hints parameter points is set to 0 or be the bitwise-inclusive OR of one or more of the values AI_PASSIVE,
       AI_CANONNAME, AI_NUMERICHOST, and AI_NUMERICSERV.

       If  the	AI_PASSIVE flag is specified, the returned address information is suitable for use in binding a socket for accepting incoming con-
       nections for the specified service. In this case, if the nodename argument is null, then the IP	address  portion  of  the  socket  address
       structure  is  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 is suitable for a call to connect(3XNET) (for  a  connection-mode  protocol)  or  for  a  call  to	connect(),
       sendto(3XNET),  or sendmsg(3XNET) (for a connectionless protocol). In this case, if the nodename argument is null, then the IP address por-
       tion of the socket address structure is set to the loopback address.

       If the AI_CANONNAME flag is specified and the nodename argument is not null, the function attempts to determine the canonical  name  corre-
       sponding to nodename (for example, if nodename is an alias or shorthand notation for a complete name).

       If  the	AI_NUMERICHOST flag is specified, then a non-null nodename string supplied is a numeric host address string. Otherwise, an EAI_NO-
       NAME error is returned. This flag prevents 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 is a numeric port string. Otherwise, an EAI_NONAME  error
       is returned. This flag prevents 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() returns IPv4-mapped IPv6 addresses on finding
       no matching IPv6 addresses (ai_addrlen is 16). The AI_V4MAPPED flag is ignored unless ai_family equals AF_INET6. If the AI_ALL flag is used
       with the AI_V4MAPPED flag, then getaddrinfo() returns all matching IPv6 and IPv4 addresses. The AI_ALL flag without the AI_V4MAPPED flag is
       ignored.

       The ai_socktype member to which argument hints points specifies the socket type for the service, as defined in socket(3XNET). If a specific
       socket  type  is  not  given  (for example, a value of 0) and the service name could be interpreted as valid with multiple supported socket
       types, the implementation attempts to resolve the service name for all supported socket types and, in the absence of errors,  all  possible
       results are returned. A non-zero socket type value limits the returned information to values with the specified socket type.

       If  the	ai_family member to which hints points has the value AF_UNSPEC, addresses are returned for use with any address family that can be
       used with the specified nodename and/or servname. Otherwise, addresses are returned for use only with  the  specified  address  family.	If
       ai_family  is not AF_UNSPEC and ai_protocol is not 0, then addresses are returned for use only with the specified address family and proto-
       col; the value of ai_protocol is interpreted as in a call to the socket() function with the corresponding values of ai_family and ai_proto-
       col.

RETURN VALUES

       A  0 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 refers to a linked list of addrinfo  structures,  each  of  which
       specifies  a  socket address and information for use in creating a socket with which to use that socket address. The list includes at least
       one addrinfo structure. The ai_next member 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 includes 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(3XNET) function. The ai_family  ,
       ai_socktype,  and  ai_protocol  members	are  usable as the arguments to the socket() function to create a socket suitable for use with the
       returned address. The ai_addr and ai_addrlen members 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 member of the first returned addrinfo structure points
       to a null-terminated string containing the canonical name corresponding to the input nodename. If the canonical name is not available, then
       ai_canonname refers to the nodename argument or a string with the same contents. The contents of the ai_flags member of the returned struc-
       tures are undefined.

       All members in socket address structures returned by getaddrinfo() that are not filled  in  through  an	explicit  argument  (for  example,
       sin6_flowinfo) are set to 0, making it easier to compare socket address structures.

ERRORS

       The getaddrinfo() function will fail if:

       EAI_AGAIN       The name could not be resolved at this time. Future attempts might succeed.

       EAI_BADFLAGS    The ai_flags member of the addrinfo structure 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      he  name  does not resolve for the supplied parameters.	Neither nodename nor servname were supplied. At least one of these
		       must 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.

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.

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       connect(3XNET), gai_strerror(3XNET), gethostbyname(3XNET), getnameinfo(3XNET),  getservbyname(3XNET),  inet_addr(3XNET),  inet_ntop(3XNET),
       socket(3XNET), attributes(5), standards(5)

SunOS 5.11							    1 Nov 2003						       freeaddrinfo(3XNET)