FreeBSD Man Pages

lwres_getaddrinfo(3)

NAME

       lwres_getaddrinfo,  lwres_freeaddrinfo  -  socket  address structure to
       host and service name

SYNOPSIS

       #include <lwres/netdb.h>

       int lwres_getaddrinfo(const char *hostname, const char *servname, const
       struct addrinfo *hints, struct addrinfo **res);

       void lwres_freeaddrinfo(struct addrinfo *ai);

       If the operating system does not provide a struct addrinfo, the follow-
       ing structure is used:

       struct  addrinfo {
	       int	       ai_flags;       /* AI_PASSIVE, AI_CANONNAME */
	       int	       ai_family;      /* PF_xxx */
	       int	       ai_socktype;    /* SOCK_xxx */
	       int	       ai_protocol;    /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
	       size_t	       ai_addrlen;     /* length of ai_addr */
	       char	       *ai_canonname;  /* canonical name for hostname */
	       struct sockaddr *ai_addr;       /* binary address */
	       struct addrinfo *ai_next;       /* next structure in linked list */
       };

DESCRIPTION

       lwres_getaddrinfo() is used to get a list of IP addresses and port num-
       bers  for  host	hostname  and  service	servname.  The function is the
       lightweight resolver's implementation of getaddrinfo()  as  defined  in
       RFC2133.  hostname and servname are pointers to null-terminated strings
       or NULL.  hostname is either a host name  or  a	numeric  host  address
       string:	a dotted decimal IPv4 address or an IPv6 address.  servname is
       either a decimal port number or a service name as listed  in  /etc/ser-
       vices.

       hints  is an optional pointer to a struct addrinfo.  This structure can
       be used to provide hints concerning the type of socket that the	caller
       supports  or wishes to use.  The caller can supply the following struc-
       ture elements in *hints:

       ai_family
	      The protocol family that should be used.	When ai_family is  set
	      to  PF_UNSPEC, it means the caller will accept any protocol fam-
	      ily supported by the operating system.

       ai_socktype
	      denotes  the  type  of  socket  --  SOCK_STREAM,	SOCK_DGRAM  or
	      SOCK_RAW -- that is wanted.  When ai_socktype is zero the caller
	      will accept any socket type.

       ai_protocol
	      indicates which transport protocol  is  wanted:  IPPROTO_UDP  or
	      the AI_PASSIVE bit indicates that the  returned  socket  address
	      structure  is  intended  for used in a call to bind(2).  In this
	      case, if the hostname argument is a NULL pointer,  then  the  IP
	      address  portion	of the socket address structure will be set to
	      INADDR_ANY for an IPv4 address or IN6ADDR_ANY_INIT for  an  IPv6
	      address.

	      When  ai_flags  does  not  set  the AI_PASSIVE bit, the returned
	      socket address structure will be ready for use in a call to con-
	      nect(2)	for  a	connection-oriented  protocol  or  connect(2),
	      sendto(2), or sendmsg(2) if a connectionless protocol  was  cho-
	      sen.   The  IP  address  portion of the socket address structure
	      will be set to the  loopback  address  if  hostname  is  a  NULL
	      pointer and AI_PASSIVE is not set in ai_flags.

	      If  ai_flags is set to AI_NUMERICHOST it indicates that hostname
	      should be treated as a numeric string defining an IPv4  or  IPv6
	      address and no name resolution should be attempted.

       All  other  elements  of  the  struct addrinfo passed via hints must be
       zero.

       A hints of NULL is treated as if the caller provided a struct  addrinfo
       initialized to zero with ai_familyset to PF_UNSPEC.

       After  a successful call to lwres_getaddrinfo(), *res is a pointer to a
       linked list of one or more addrinfo structures.	Each  struct  addrinfo
       in  this list cn be processed by following the ai_next pointer, until a
       NULL pointer is encountered.  The three members ai_family, ai_socktype,
       and  ai_protocol in each returned addrinfo structure contain the corre-
       sponding arguments for a call to socket(2).  For each  addrinfo	struc-
       ture  in  the  list,  the  ai_addr  member points to a filled-in socket
       address structure of length ai_addrlen.

       All of the information returned by lwres_getaddrinfo()  is  dynamically
       allocated:  the	addrinfo structures, and the socket address structures
       and canonical host name strings pointed to by  the  addrinfostructures.
       Memory  allocated for the dynamically allocated structures created by a
       successful call to lwres_getaddrinfo()  is  released  by  lwres_freead-
       drinfo().   ai  is  a pointer to a struct addrinfo created by a call to
       lwres_getaddrinfo().

RETURN VALUES

       lwres_getaddrinfo() returns zero on success or one of the  error  codes
       listed  in  gai_strerror(3)  if	an error occurs.  If both hostname and
       servname are NULL lwres_getaddrinfo() returns EAI_NONAME.

SEE ALSO

       lwres(3), lwres_getaddrinfo(3),	lwres_freeaddrinfo(3),	lwres_gai_str-
       error(3),  RFC2133,  getservbyname(3),  bind(2), connect(2), sendto(2),
       sendmsg(2), socket(2).

BIND9				 Jun 30, 2000		  LWRES_GETADDRINFO(3)

SPONSORED LINKS