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

FreeBSD Manual Pages

  
 
  

home | help
GETNAMEINFO(3)		 BSD Library Functions Manual		GETNAMEINFO(3)

NAME
     getnameinfo -- address-to-nodename	translation in protocol-independent
     manner

LIBRARY
     Standard C	Library	(libc, -lc)

SYNOPSIS
     #include <sys/types.h>
     #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() function	is defined for protocol-independent address-
     to-nodename translation.  Its functionality is a reverse conversion of
     getaddrinfo(3), and implements similar functionality with
     gethostbyaddr(3) and getservbyport(3) in more sophisticated manner.

     This function looks up an IP address and port number provided by the
     caller in the DNS and system-specific database, and returns text strings
     for both in buffers provided by the caller.  The function indicates suc-
     cessful completion	by a zero return value;	a non-zero return value	indi-
     cates 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 sockaddr_in
     or	sockaddr_in6 structure.

     The function returns the nodename associated with the IP address in the
     buffer pointed to by the host argument.  The caller provides the size of
     this buffer via the hostlen argument.  The	service	name associated	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	zero value for the hostlen or
     servlen arguments.	 Otherwise, the	caller must provide buffers large
     enough to hold the	nodename and the service name, including the terminat-
     ing null characters.

     Unfortunately most	systems	do not provide constants that specify the max-
     imum size of either a fully-qualified domain name or a service name.
     Therefore to aid the application in allocating buffers for	these two re-
     turned strings the	following constants are	defined	in <netdb.h>:

     #define NI_MAXHOST	 1025
     #define NI_MAXSERV	   32

     The first value is	actually defined as the	constant MAXDNAME in recent
     versions of BIND's	<arpa/nameser.h> header	(older versions	of BIND	define
     this constant to be 256) and the second is	a guess	based on the services
     listed in the current Assigned Numbers RFC.

     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 DNS and returned.  If the flag	bit NI_NOFQDN is set,
     only the nodename 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 DNS, the numeric form of the host's	address	is returned
     instead of	its name (e.g.,	by calling inet_ntop() instead of
     getnodebyaddr()).	If the flag bit	NI_NAMEREQD is set, an error is	re-
     turned if the host's name cannot be located in the	DNS.

     If	the flag bit NI_NUMERICSERV is set, the	numeric	form of	the service
     address is	returned (e.g.,	its port number) instead of its	name.  The two
     NI_NUMERICxxx flags are required to support the -n	flag that many com-
     mands provide.

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

     These NI_xxx flags	are defined in <netdb.h>.

   Extension for scoped	IPv6 address
     The implementation	allows experimental numeric IPv6 address notation with
     scope identifier.	IPv6 link-local	address	will appear as a string	like
     "fe80::1%ne0".  Refer to getaddrinfo(3) for the notation.

EXAMPLES
     The following code	tries to get numeric hostname, and service name, for
     given socket address.  Observe that there is no hardcoded reference to
     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)) {
		   errx(1, "could not get numeric hostname");
		   /*NOTREACHED*/
	   }
	   printf("host=%s, serv=%s\n",	hbuf, sbuf);

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

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

	   if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0,
	       NI_NAMEREQD)) {
		   errx(1, "could not resolve hostname");
		   /*NOTREACHED*/
	   }
	   printf("host=%s\n", hbuf);

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

DIAGNOSTICS
     The function indicates successful completion by a zero return value; a
     non-zero return value indicates failure.  Error codes are as below:

     [EAI_AGAIN]	The name could not be resolved at this time.  Future
			attempts may succeed.

     [EAI_BADFLAGS]	The flags had 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]	There was a memory allocation failure.

     [EAI_NONAME]	The name does not resolve for the supplied arguments.
			NI_NAMEREQD is set and the host's name cannot be lo-
			cated, or both nodename	and servname were null.

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

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

     R.	Gilligan, S. Thomson, J. Bound,	and W. Stevens,	Basic Socket Interface
     Extensions	for IPv6, RFC2553, March 1999.

     Tatsuya Jinmei and	Atsushi	Onoe, An Extension of Format for IPv6 Scoped
     Addresses,	internet draft,	draft-ietf-ipngwg-scopedaddr-format-02.txt,
     work in progress material.

     Craig Metz, "Protocol Independence	Using the Sockets API",	Proceedings of
     the freenix track:	2000 USENIX annual technical conference, June 2000.

HISTORY
     The implementation	first appeared in WIDE Hydrangea IPv6 protocol stack
     kit.

STANDARDS
     The getaddrinfo() function	is defined in IEEE Std 1003.1g-2000
     ("POSIX.1"), and documented in "Basic Socket Interface Extensions for
     IPv6" (RFC2553).

BUGS
     Though the	current	implementation should be thread-safe, using
     getnameinfo() in conjunction with gethostby*() breaks thread-safeness.

     The text was shamelessly copied from RFC2553.

     The type of the 2nd argument should be socklen_t for RFC2553 conformance.
     The current code is based on pre-RFC2553 specification.

BSD				August 6, 2004				   BSD

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | EXAMPLES | FILES | DIAGNOSTICS | SEE ALSO | HISTORY | STANDARDS | BUGS

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

home | help