Unix/Linux Go Back    


Linux 2.6 - man page for getnameinfo (linux section 3posix)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


GETNAMEINFO(P)			    POSIX Programmer's Manual			   GETNAMEINFO(P)

NAME
       getnameinfo - get name information

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

       int getnameinfo(const struct sockaddr *restrict sa, socklen_t salen,
	      char *restrict node, socklen_t nodelen, char *restrict service,
	      socklen_t servicelen, int flags);

DESCRIPTION
       The  getnameinfo()  function  shall  translate a socket address to a node name and service
       location, all of which are defined as in getaddrinfo() .

       The sa argument points to a socket address structure to be translated.

       If the socket address structure contains an IPv4-mapped IPv6 address or an IPv4-compatible
       IPv6  address,  the  implementation shall extract the embedded IPv4 address and lookup the
       node name for that IPv4 address.

       Note:  The IPv6 unspecified address ( "::" ) and the IPv6 loopback address ( "::1"  )  are
	      not  IPv4-compatible  addresses.	If  the address is the IPv6 unspecified address (
	      "::" ), a lookup is not performed, and the [EAI_NONAME] error is returned.

       If the node argument is non-NULL and the nodelen argument is non-zero, then the node argu-
       ment  points  to  a buffer able to contain up to nodelen characters that receives the node
       name as a null-terminated string. If the node argument is NULL or the nodelen argument  is
       zero,  the  node  name  shall  not  be returned. If the node's name cannot be located, the
       numeric form of the address contained in the socket address structure pointed to by the sa
       argument is returned instead of its name.

       If the service argument is non-NULL and the servicelen argument is non-zero, then the ser-
       vice argument points to a buffer able to contain up to servicelen bytes that receives  the
       service	name as a null-terminated string. If the service argument is NULL or the service-
       len argument is zero, the service name shall not be returned. If the service's name cannot
       be  located,  the numeric form of the service address (for example, its port number) shall
       be returned instead of its name.

       The flags argument is a flag that changes the default actions of the function. By  default
       the fully-qualified domain name (FQDN) for the host shall be returned, but:

	* If  the  flag  bit  NI_NOFQDN  is  set, only the node name portion of the FQDN shall be
	  returned for local hosts.

	* If the flag bit NI_NUMERICHOST is set, the numeric form of the address contained in the
	  socket address structure pointed to by the sa argument shall be returned instead of its
	  name, under all circumstances.

	* If the flag bit NI_NAMEREQD is set, an error shall be returned if the host's name  can-
	  not be located.

	* If the flag bit NI_NUMERICSERV is set, the numeric form of the service address shall be
	  returned (for example, its port number) instead of its name, under all circumstances.

	* If the flag bit NI_NUMERICSCOPE is set, the numeric form of the scope identifier  shall
	  be  returned	(for  example,	interface  index) instead of its name. This flag shall be
	  ignored if the sa argument is not an IPv6 address.

	* If the flag bit NI_DGRAM is set, this indicates that the service is a datagram  service
	  (SOCK_DGRAM).  The  default  behavior shall assume that the service is a stream service
	  (SOCK_STREAM).

       Notes:

	       1. The two NI_NUMERICxxx flags are required to support the -n flag that many  com-
		  mands provide.

	       2. The  NI_DGRAM  flag  is  required for the few AF_INET and AF_INET6 port numbers
		  (for example, [512,514]) that represent different services for UDP and TCP.

       The getnameinfo() function shall be thread-safe.

RETURN VALUE
       A zero return value for getnameinfo() indicates successful completion; a  non-zero  return
       value  indicates  failure.  The	possible values for the failures are listed in the ERRORS
       section.

       Upon successful completion, getnameinfo() shall return the  node  and  service  names,  if
       requested, in the buffers provided. The returned names are always null-terminated strings.

ERRORS
       The getnameinfo() function shall fail and return the corresponding value if:

       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 parameters.

       NI_NAMEREQD is set and the host's name cannot be located, or both  nodename  and  servname
       were null.

       EAI_OVERFLOW

	      An  argument  buffer  overflowed. The buffer pointed to by the node argument or the
	      service argument was too small.

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

       The following sections are informative.

EXAMPLES
       None.

APPLICATION USAGE
       If the returned values are to be used as part of any further name resolution (for example,
       passed  to  getaddrinfo()),  applications should provide buffers large enough to store any
       result possible on the system.

       Given the IPv4-mapped IPv6 address "::ffff:1.2.3.4" , the implementation performs a lookup
       as if the socket address structure contains the IPv4 address "1.2.3.4" .

RATIONALE
       None.

FUTURE DIRECTIONS
       None.

SEE ALSO
       gai_strerror() , getaddrinfo() , getservbyname() , inet_ntop() , socket() , the Base Defi-
       nitions volume of IEEE Std 1003.1-2001, <netdb.h>, <sys/socket.h>

COPYRIGHT
       Portions of this text are reprinted and	reproduced  in	electronic  form  from	IEEE  Std
       1003.1,	2003  Edition,	Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE  and  The  Open  Group
       Standard, the original IEEE and The Open Group Standard is the referee document. The orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003				   GETNAMEINFO(P)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 03:35 PM.