path: root/newlib/libc/sys/linux/net/getnameinfo.3

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 transla-
     tion.  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 successful completion by a zero return value; a non-zero re-
     turn 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 ar-
     gument 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.  Other-
     wise, the caller must provide buffers large enough to hold the nodename and the service
     name, including the terminating null characters.

     Unfortunately most systems do not provide constants that specify the maximum size of either
     a fully-qualified domain name or a service name.  Therefore to aid the application in allo-
     cating buffers for these two returned 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 sec-
     ond 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 lo-
     cal 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
     returned 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 commands provide.

     A fifth flag bit, NI_DGRAM, specifies that the service is a datagram service, 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
     The implementation allows experimental numeric IPv6 address notation with scope identifier.
     IPv6 link-local address will appear as string like "fe80::1%ne0", if NI_WITHSCOPEID bit is
     enabled in flags argument.  Refer to getaddrinfo(3) for the notation.

EXAMPLES
     The following code tries to get numeric hostname, and service name, for given socket ad-
     dress.  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 suc-
                        ceed.

     [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_SYSTEM]       A system error occurred.  The error code can be found in errno.

SEE ALSO
     getaddrinfo(3), gethostbyaddr(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
     The current implementation is not thread-safe.

     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                                        May 25, 1995                                       BSD