Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
LWRES_GETADDRINFO(3)		     BIND9		  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
       following 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
       numbers 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/services.

       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
       structure 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 family
	   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
	   IPPROTO_TCP.	If ai_protocol is zero the caller will accept any
	   protocol.

       ai_flags
	   Flag	bits. If the AI_CANONNAME bit is set, a	successful call	to
	   lwres_getaddrinfo() will return a null-terminated string containing
	   the canonical name of the specified hostname	in ai_canonname	of the
	   first addrinfo structure returned. Setting 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	connect(2) for
	   a connection-oriented protocol or connect(2), sendto(2), or
	   sendmsg(2) if a connectionless protocol was chosen. 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
       corresponding arguments for a call to socket(2).	For each addrinfo
       structure 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_freeaddrinfo().  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 NULLlwres_getaddrinfo() returns EAI_NONAME.

SEE ALSO
       lwres(3), lwres_getaddrinfo(3), lwres_freeaddrinfo(3),
       lwres_gai_strerror(3), RFC2133(), getservbyname(3), bind(2),
       connect(2), sendto(2), sendmsg(2), socket(2).

AUTHOR
       Internet	Systems	Consortium, Inc.

COPYRIGHT
       Copyright (C) 2004, 2005, 2007, 2014-2016 Internet Systems Consortium,
       Inc. ("ISC")
       Copyright (C) 2000, 2001, 2003 Internet Software	Consortium.

ISC				  2007-06-18		  LWRES_GETADDRINFO(3)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=lwres_getaddrinfo&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help