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

FreeBSD Manual Pages

  
 
  

home | help
getaddrinfo(3SOCKET)	       Network Functions	  getaddrinfo(3SOCKET)

NAME
       getaddrinfo,  getnameinfo,  freeaddrinfo,  gai_strerror - translate be-
       tween node name and address

SYNOPSIS
       cc [flag	...] file ... -lsocket -lnsl [library ...]
       #include	<sys/socket.h>
       #include	<netdb.h>

       int getaddrinfo(const  char  *nodename,	const  char  *servname,	 const
       struct addrinfo *hints, struct addrinfo **res);

       int getnameinfo(const struct sockaddr *sa, socklen_t salen, char	*host,
       size_t hostlen, char *serv, size_t servlen, int flags);

       void freeaddrinfo(struct	addrinfo *ai);

       char *gai_strerror(int errcode);

DESCRIPTION
       These functions perform translations from node name to address and from
       address to node name in a protocol-independent manner.

       The  getaddrinfo()  function performs the node name to address transla-
       tion.  The nodename and servname	arguments are pointers to  null-termi-
       nated  strings  or NULL.	 One or	both of	these arguments	must be	a non-
       null pointer.  In the normal client scenario,  both  the	 nodename  and
       servname	 are specified.	 In the	normal server scenario,	only the serv-
       name is specified.  A non-null nodename string can  be  either  a  node
       name or a numeric host address string (a	dotted-decimal IPv4 address or
       an IPv6 hex address).  A	non-null servname string can be	either a  ser-
       vice name or a decimal port number.

       The caller can optionally pass an addrinfo structure, pointed to	by the
       third argument, to provide hints	concerning the type of socket that the
       caller supports.

       The addrinfo structure is defined as:

       struct addrinfo {
       int		ai_flags;      /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */
       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 nodename */
       struct sockaddr	*ai_addr;      /* binary address */
       struct addrinfo	*ai_next;      /* next structure in linked list	*/
	};

       In  this	 hints	structure, all members other than ai_flags, ai_family,
       ai_socktype, and	ai_protocol must be 0 or a null	pointer.  A  value  of
       PF_UNSPEC  for ai_family	indicates that the caller will accept any pro-
       tocol family.  A	value of 0 for ai_socktype indicates that  the	caller
       will  accept  any  socket type.	A value	of 0 for ai_protocol indicates
       that the	caller will accept any protocol.  For example, if  the	caller
       handles	only TCP and not UDP, then the ai_socktype member of the hints
       structure should	be set to SOCK_STREAM 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 PF_INET when  getaddrinfo()  is
       called.	 If the	third argument to getaddrinfo()	is a null pointer,  it
       is  as if the caller had	filled in an addrinfo structure	initialized to
       0 with ai_family	set to PF_UNSPEC.

       Upon success, a pointer to a linked list	of one or more addrinfo	struc-
       tures is	returned through the final argument.  The caller  can  process
       each  addrinfo structure	in this	list by	following the ai_next pointer,
       until a null pointer is encountered.  In	each returned addrinfo	struc-
       ture  the three members ai_family, ai_socktype, and ai_protocol are the
       corresponding arguments for a call to the socket(3SOCKET) function.  In
       each addrinfo structure the ai_addr member points to a filled-in	socket
       address structure whose length is specified by the ai_addrlen member.

       If the AI_PASSIVE bit is	set in the ai_flags member of the hints	struc-
       ture,  the caller plans to use the returned socket address structure in
       a call to bind(3SOCKET).	In this	case, if the nodename  argument	 is  a
       null  pointer,  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.

       If  the	AI_PASSIVE  bit	is not set in the ai_flags member of the hints
       structure, then the returned socket address structure will be ready for
       a  call to connect(3SOCKET) (for	a connection-oriented protocol)	or ei-
       ther connect(3SOCKET), sendto(3SOCKET), or sendmsg(3SOCKET) (for	a con-
       nectionless  protocol). If the nodename argument	is a null pointer, the
       IP address portion of the socket	address	structure will be set  to  the
       loopback	address.

       If  the	AI_CANONNAME  bit  is  set in the ai_flags member of the hints
       structure, then upon successful return the ai_canonname member  of  the
       first addrinfo structure	in the linked list will	point to a null-termi-
       nated string containing the canonical name of the specified nodename.

       If the AI_NUMERICHOST bit is set	in the ai_flags	member	of  the	 hints
       structure,  then	 a non-null nodename string must be a numeric host ad-
       dress string.  Otherwise	an error of EAI_NONAME is returned.  This flag
       prevents	 any  type of name resolution service (such as DNS) from being
       called.

       All of the information returned by getaddrinfo()	is  dynamically	 allo-
       cated: the addrinfo structures as well as the socket address structures
       and canonical node name strings pointed to by the addrinfo  structures.
       The freeaddrinfo() function is called to	return this information	to the
       system the  function  .	For  freeaddrinfo(),  the  addrinfo  structure
       pointed	to by the ai argument is freed,	along with any dynamic storage
       pointed to by the structure.  This operation is repeated	until  a  null
       ai_next pointer is encountered.

       To aid applications in printing error messages based on the EAI_* codes
       returned	by getaddrinfo(), the gai_strerror() is	defined.  The argument
       is one of the EAI_* values defined below	and the	return value points to
       a string	describing the error.  If the argument is not one of the EAI_*
       values, the function still returns a pointer to a string	whose contents
       indicate	an unknown error.

       The getnameinfo() function looks	up an IP address and port number  pro-
       vided  by  the  caller in the name service database and system-specific
       database, and returns text strings for both in buffers provided by  the
       caller.	 The  function	indicates  successful completion by a 0	return
       value; a	non-zero return	value indicates	failure.

       The first argument, sa, points to either	a sockaddr_in  structure  (for
       IPv4)  or a sockaddr_in6	structure (for IPv6) that holds	the IP address
       and port	number.	 The salen argument gives  the	length	of  the	 sock-
       addr_in or sockaddr_in6 structure.

       The  function  returns  the node	name associated	with the IP address in
       the buffer pointed to by	the host argument.  The	 caller	 provides  the
       size  of	this buffer with the hostlen argument.	The service name asso-
       ciated with the port number is returned in the  buffer  pointed	to  by
       serv,  and  the	servlen	argument gives the length of this buffer.  The
       caller specifies	not to return either string by providing a 0 value for
       the  hostlen  or	servlen	arguments.  Otherwise, the caller must provide
       buffers large enough to hold the	node name and the  service  name,  in-
       cluding the terminating null characters.

       To  aid	the  application  in allocating	buffers	for these two returned
       strings,	the following constants	are defined in <netdb.h>:

       #define NI_MAXHOST  1025
       #define NI_MAXSERV    32

       The final argument is a flag that changes the default actions  of  this
       function.   By  default,	the fully-qualified domain name	(FQDN) for the
       host is looked up in the	name service database and  returned.   If  the
       flag  bit  NI_NOFQDN  is	set, only the node name	portion	of the FQDN is
       returned	for local hosts.

       If the flag bit NI_NUMERICHOST is set, or if the	host's name cannot  be
       located	in the name service, the numeric form of the host's address is
       returned	instead	of its name, for example, by calling inet_ntop()  (see
       inet(3SOCKET))  instead	of  getipnodebyname(3SOCKET).  If the flag bit
       NI_NAMEREQD is set, an error is returned	if the host's name  cannot  be
       located in the name service database.

       If  the flag bit	NI_NUMERICSERV is set, the numeric form	of the service
       address is returned (for	example, its port number) instead of its name.
       The  two	 NI_NUMERIC*  flags are	required to support the	"-n" flag that
       many commands provide.

       A fifth flag bit, NI_DGRAM, specifies that the service  is  a  datagram
       service,	 and  causes getservbyport(3SOCKET) to be called with a	second
       argument	of "udp" instead of the	default	"tcp".	This is	 required  for
       the  few	 ports (for example, 512-514) that have	different services for
       UDP and TCP.

       These NI_* flags	are defined in <netdb.h> along with the	AI_* flags al-
       ready defined for getaddrinfo().

RETURN VALUES
       For  getaddrinfo(),  if	the query is successful, a pointer to a	linked
       list of one or more addrinfo structures is returned by the fourth argu-
       ment  and  the function returns 0. If the query fails, a	non-zero error
       code will be returned. For getnameinfo(), if  successful,  the  strings
       hostname	 and  service  are copied into host and	serv, respectively. If
       unsuccessful, zero values for either hostlen or servlen	will  suppress
       the associated lookup; in this case no data is copied into the applica-
       ble buffer.  If gai_strerror() is successful,  a	pointer	 to  a	string
       containing  an  error  message  appropriate for the EAI_* errors	is re-
       turned.	If errcode is not one of the EAI_*  values,  a	pointer	 to  a
       string indicating an unknown error is returned.

ERRORS
       The  following names are	the error values returned by getaddrinfo() and
       are defined in <netdb.h>:

       EAI_ADDRFAMILY  address family for nodename not supported
       EAI_AGAIN       temporary failure in name resolution
       EAI_BADFLAGS    invalid value for ai_flags
       EAI_FAIL	       non-recoverable failure in name resolution
       EAI_FAMILY      ai_family not supported
       EAI_MEMORY      memory allocation failure
       EAI_NODATA      no address associated with nodename
       EAI_NONAME      nodename	nor servname provided, or not known
       EAI_SERVICE     servname	not supported for ai_socktype
       EAI_SOCKTYPE    ai_socktype not supported
       EAI_SYSTEM      system error returned in	errno

FILES
       /etc/inet/hosts

       /etc/inet/ipnodes

       /etc/netconfig

       /etc/nsswitch.conf

SEE ALSO
       gethostbyname(3NSL),	getipnodebyname(3SOCKET),      htonl(3SOCKET),
       inet(3SOCKET),  netdb(3HEAD),  socket(3SOCKET),	hosts(4),  ipnodes(4),
       nsswitch.conf(4)

SunOS 5.9			  15 Dec 2000		  getaddrinfo(3SOCKET)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | FILES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=getaddrinfo&sektion=3socket&manpath=SunOS+5.9>

home | help