getnameinfo  -  address-to-name  translation  in protocol-
       independent manner


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-inde­
       pendent  address-to-nodename translation.  It combines the
       functionality of gethostbyaddr(3) and getservbyport(3) and
       is  the  inverse  of getaddrinfo(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
       repectively) 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) argu­
       ment 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 getname­
       info(3) as follows:

       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.

       On success 0 is returned, and node and service  names,  if
       requested,  are filled with NUL-terminated strings, possi­
       bly truncated to fit the  specified  buffer  lengths.   On
       error a nonzero value is returned, and errno is set appro­
       priately.


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  fam­
              ily.

       EAI_MEMORY
              Out of memory.

       EAI_NONAME
              The  name does not resolve for the supplied parame­
              ters.  NI_NAMEREQD is set and the host's name  can­
              not  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 con­
       stants
              # 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 services listed in the current Assigned Num­
       bers RFC.


EXAMPLES

       The following code tries to get the numeric  hostname  and

       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), get­
       servbyport(3),  inet_ntop(3),  socket(3),  hosts(5),  ser­
       vices(5), hostname(7), named(8)

       R.  Gilligan,  S.  Thomson, J. Bound and W. Stevens, Basic
       Socket Interface 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-format-02.txt

       Craig Metz, Protocol Independence Using the  Sockets  API,
       Proceedings of the freenix track: 2000 USENIX annual tech­
       nical conference, June 2000.  http://www.usenix.org/publi­
       cations/library/proceedings/usenix2000/freenix/metzproto­
       col.html


Man(1) output converted with man2html