getnameinfo

getnameinfo(3)		   UNIX Programmer’s Manual	       getnameinfo(3)



NAME
       getnameinfo - address-to-name translation in protocol-independent man-
       ner

SYNOPSIS
       #include <sys/socket.h>
       #include <netdb.h>

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

DESCRIPTION
       The  getnameinfo(3)  function  is  defined  for	 protocol-independent
       address-to-nodename  translation.   It  combines	 the functionality of
       gethostbyaddr(3) and getservbyport(3) and is  the  inverse  of  getad-
       drinfo(3).   The	 sa argument is a pointer to a generic socket address
       structure (of type sockaddr_in or sockaddr_in6)	of  size  salen	 that
       holds  the  input  IP address and port number.  The arguments host and
       serv are pointers to buffers (of	 size  hostlen	and  servlen  respec-
       tively) to hold the return values.

       The  caller  can	 specify  that	no  hostname  (or no service name) is
       required by providing a NULL host (or serv) argument or a zero hostlen
       (or  servlen)  parameter. However, at least one of hostname or service
       name must be requested.

       The flags argument modifies the behaviour of  getnameinfo(3)  as	 fol-
       lows:

       NI_NOFQDN
	      If  set,	return	only  the hostname part of the FQDN for local
	      hosts.

       NI_NUMERICHOST
	      If set, then the numeric form  of	 the  hostname	is  returned.
	      (When  not  set, this will still happen in case the node’s name
	      cannot be looked up.)

       NI_NAMEREQD
	      If set, then a error is returned	if  the	 hostname  cannot  be
	      looked up.

       NI_NUMERICSERV
	      If  set,	then the service address is returned in numeric form,
	      for example by its port number.

       NI_DGRAM
	      If set, then the service is datagram (UDP)  based	 rather	 than
	      stream  (TCP)  based.  This  is  required	 for  the  few	ports
	      (512-514) that have different services for UDP and TCP.

RETURN VALUE
       On success 0 is returned, and node and service  names,  if  requested,
       are  filled with NUL-terminated strings, possibly truncated to fit the
       specified buffer lengths.  On error a nonzero value is  returned,  and
       errno is set appropriately.

ERRORS
       EAI_AGAIN
	      The name could not be resolved at this time. Try again later.

       EAI_BADFLAGS
	      The flags parameter has an invalid value.

       EAI_FAIL
	      A non-recoverable error occurred.

       EAI_FAMILY
	      The  address  family  was not recognized, or the address length
	      was invalid for the specified family.

       EAI_MEMORY
	      Out of memory.

       EAI_NONAME
	      The  name	 does  not  resolve  for  the  supplied	  parameters.
	      NI_NAMEREQD  is  set  and the host’s name cannot be located, or
	      neither hostname nor service name were requested.

       EAI_SYSTEM
	      A system error occurred. The error code can be found in  errno.

FILES
       /etc/hosts
       /etc/nsswitch.conf
       /etc/resolv.conf

NOTE
       In order to assist the programmer in choosing reasonable sizes for the
       supplied buffers, <netdb.h> defines the constants
	      # define NI_MAXHOST      1025
	      # define NI_MAXSERV      32
       The former is the constant  MAXDNAME  in	 recent	 versions  of  BIND’s
       <arpa/nameser.h>	 header file. The latter is a guess based on the ser-
       vices listed in the current Assigned Numbers RFC.

EXAMPLES
       The following code tries to get the numeric hostname and service name,
       for  a given socket address. Note that there is no hardcoded reference
       to a particular address family.

		struct sockaddr *sa;	/* input */
		char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];

		if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf,
		    sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0)
			printf("host=%s, serv=%s\n", hbuf, sbuf);

       The following version checks if	the  socket  address  has  a  reverse
       address mapping.

		struct sockaddr *sa;	/* input */
		char hbuf[NI_MAXHOST];

		if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf),
		    NULL, 0, NI_NAMEREQD))
		       printf("could not resolve hostname");
		else
		       printf("host=%s\n", hbuf);

CONFORMING TO
       RFC 2553. (See also XNS, issue 5.2.)

SEE ALSO
       getaddrinfo(3),	gethostbyaddr(3), getservbyname(3), getservbyport(3),
       inet_ntop(3), socket(3), hosts(5), services(5), hostname(7), named(8)

       R. Gilligan, S. Thomson, J. Bound and W. Stevens, Basic Socket  Inter-
       face Extensions for IPv6, RFC 2553, March 1999.

       Tatsuya	Jinmei	and  Atsushi  Onoe,  An	 Extension of Format for IPv6
       Scoped	 Addresses,    internet	   draft,    work    in	    progress.
       ftp://ftp.ietf.org/internet-drafts/draft-ietf-ipngwg-scopedaddr-for-
       mat-02.txt

       Craig Metz, Protocol Independence Using the Sockets  API,  Proceedings
       of  the	freenix	 track: 2000 USENIX annual technical conference, June
       2000.		  http://www.usenix.org/publications/library/proceed-
       ings/usenix2000/freenix/metzprotocol.html



Linux Man Page			  2000-12-11		       getnameinfo(3)