*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->OpenBSD man pages -> getnameinfo (3)              



NAME    [Toc]    [Back]

     getnameinfo - address-to-nodename translation  in  protocolindependent

SYNOPSIS    [Toc]    [Back]

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

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

DESCRIPTION    [Toc]    [Back]

     The  getnameinfo() function is defined for protocol-independent addressto-nodename
 translation.  Its  functionality  is  a  reverse
conversion of
     getaddrinfo(3),  and  implements  similar  functionality  to
     and getservbyport(3) in a 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 return
value indicates

     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
     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 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 allocating buffers for
these two returned
  strings  the  following  constants  are  defined  in

     #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

     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
     gethostbyaddr()).   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

     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

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

   Extension for scoped IPv6 address    [Toc]    [Back]
     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    [Toc]    [Back]

     The following code tries to get a numeric hostname, and service name, for
     given  socket  address.   Observe 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),
               sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) {
                   errx(1, "could not get numeric hostname");
           printf("host=%s, serv=%s0, hbuf, sbuf);

     The  following  version checks if the socket address has reverse address

           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");
           printf("host=%s0, hbuf);

DIAGNOSTICS    [Toc]    [Back]

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

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

SEE ALSO    [Toc]    [Back]

     getaddrinfo(3),     gethostbyaddr(3),      getservbyport(3),
     resolv.conf(5), services(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, 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.

STANDARDS    [Toc]    [Back]

     The getnameinfo() function is defined in IEEE POSIX  1003.1g
draft specification,
  and documented in ``Basic Socket Interface Extensions for
     IPv6'' (RFC 2553).

HISTORY    [Toc]    [Back]

     The implementation first appeared  in  WIDE  Hydrangea  IPv6
protocol stack

CAVEATS    [Toc]    [Back]

     getnameinfo()  returns both numeric and FQDN notation of the
address specified
 in sa.  There is no return value that indicates if the
string returned
  in host is a result of binary to numeric-text translation (like
     inet_ntop(3)), or the result of DNS reverse lookup.   Therefore, malicious
     parties could set up a PTR record as below:


     and trick the caller of getnameinfo() into believing that sa
     when it actually is

     To prevent such attacks, the use of  NI_NAMEREQD  is  recommended when you
     use the result of getnameinfo() for access control purposes:

           struct sockaddr *sa;
           socklen_t salen;
           char addr[NI_MAXHOST];
           struct addrinfo hints, *res;
           int error;

           error = getnameinfo(sa, salen, addr, sizeof(addr),
               NULL, 0, NI_NAMEREQD);
           if (error == 0) {
                   memset(&hints, 0, sizeof(hints));
                   hints.ai_socktype = SOCK_DGRAM; /*dummy*/
                   hints.ai_flags = AI_NUMERICHOST;
                   if (getaddrinfo(addr, "0", &hints, &res) == 0)
                           /* malicious PTR record */
                           printf("bogus PTR record0);
                           return -1;
                   /* addr is FQDN as a result of PTR lookup */
           } else {
                   /* addr is numeric string */
                   error  =  getnameinfo(sa,  salen,  addr, sizeof(addr),
                       NULL, 0, NI_NUMERICHOST);

BUGS    [Toc]    [Back]

     The current implementation is not thread-safe.

     The text was shamelessly copied from RFC 2553.

     OpenBSD intentionally uses a different NI_MAXHOST value from
what RFC
     2553 suggests, to avoid buffer length handling mistakes.

OpenBSD      3.6                           May      25,      1995
[ Back ]
 Similar pages
Name OS Title
getnameinfo FreeBSD address-to-nodename translation in protocol-independent manner
getnameinfo NetBSD address-to-nodename translation in protocol-independent manner
getnameinfo Linux address-to-name translation in protocol-independent manner
getaddrinfo FreeBSD nodename-to-address translation
freeaddrinfo FreeBSD nodename-to-address translation
freeaddrinfo OpenBSD nodename-to-address translation
gai_strerror OpenBSD nodename-to-address translation
gai_strerror NetBSD nodename-to-address translation
getaddrinfo OpenBSD nodename-to-address translation
getaddrinfo NetBSD nodename-to-address translation
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service