GETNAMEINFO(3)



GETNAMEINFO(3)             Linux Programmer's Manual            GETNAMEINFO(3)

NAME
       getnameinfo  - address-to-name translation in protocol-independent man-
       ner

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

       int getnameinfo(const struct sockaddr *addr, socklen_t addrlen,
                       char *host, socklen_t hostlen,
                       char *serv, socklen_t servlen, int flags);

   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

       getnameinfo():
           Since glibc 2.22: _POSIX_C_SOURCE >= 201112L
           Glibc 2.21 and earlier: _POSIX_C_SOURCE

DESCRIPTION
       The getnameinfo() function is the inverse of  getaddrinfo(3):  it  con-
       verts a socket address to a corresponding host and service, in a proto-
       col-independent manner.  It  combines  the  functionality  of  gethost-
       byaddr(3)  and  getservbyport(3),  but unlike those functions, getname-
       info() is reentrant and allows programs to  eliminate  IPv4-versus-IPv6
       dependencies.

       The  addr  argument  is a pointer to a generic socket address structure
       (of type sockaddr_in or sockaddr_in6) of size addrlen  that  holds  the
       input  IP  address  and  port  number.  The arguments host and serv are
       pointers to caller-allocated buffers (of size hostlen and  servlen  re-
       spectively)  into  which  getnameinfo()  places null-terminated strings
       containing the host and service names respectively.

       The caller can specify that no hostname (or no  service  name)  is  re-
       quired  by  providing  a NULL host (or serv) argument or a zero hostlen
       (or servlen) argument.  However, at least one of  hostname  or  service
       name must be requested.

       The flags argument modifies the behavior of getnameinfo() as follows:

       NI_NAMEREQD
              If  set, then an error is returned if the hostname cannot be de-
              termined.

       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.

       NI_NOFQDN
              If set, return only the hostname part of the fully qualified do-
              main name 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 determined.)

       NI_NUMERICSERV
              If  set,  then  the  numeric  form of the service address is re-
              turned.  (When not set, this will still happen in case the  ser-
              vice's name cannot be determined.)

   Extensions to getnameinfo() for Internationalized Domain Names
       Starting  with  glibc  2.3.4, getnameinfo() has been extended to selec-
       tively allow hostnames to be transparently converted to  and  from  the
       Internationalized  Domain Name (IDN) format (see RFC 3490, Internation-
       alizing Domain Names in Applications (IDNA)).  Three new flags are  de-
       fined:

       NI_IDN If  this flag is used, then the name found in the lookup process
              is converted from IDN format to the locale's encoding if  neces-
              sary.   ASCII-only  names  are  not  affected by the conversion,
              which makes this flag usable in existing programs  and  environ-
              ments.

       NI_IDN_ALLOW_UNASSIGNED, NI_IDN_USE_STD3_ASCII_RULES
              Setting these flags will enable the IDNA_ALLOW_UNASSIGNED (allow
              unassigned Unicode code  points)  and  IDNA_USE_STD3_ASCII_RULES
              (check  output  to  make  sure it is a STD3 conforming hostname)
              flags respectively to be used in the IDNA handling.

RETURN VALUE
       On success, 0 is returned, and node and service  names,  if  requested,
       are  filled with null-terminated strings, possibly truncated to fit the
       specified buffer lengths.  On error, one of the following nonzero error
       codes is returned:

       EAI_AGAIN
              The name could not be resolved at this time.  Try again later.

       EAI_BADFLAGS
              The flags argument has an invalid value.

       EAI_FAIL
              A nonrecoverable error occurred.

       EAI_FAMILY
              The address family was not recognized, or the address length was
              invalid for the specified family.

       EAI_MEMORY
              Out of memory.

       EAI_NONAME
              The  name  does  not  resolve  for   the   supplied   arguments.
              NI_NAMEREQD  is  set  and  the host's name cannot be located, or
              neither hostname nor service name were requested.

       EAI_OVERFLOW
              The buffer pointed to by host or serv was too small.

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

       The gai_strerror(3) function translates these error codes  to  a  human
       readable string, suitable for error reporting.

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

VERSIONS
       getnameinfo() is provided in glibc since version 2.1.

ATTRIBUTES
       For  an  explanation  of  the  terms  used  in  this  section,  see at-
       tributes(7).

       +--------------+---------------+--------------------+
       |Interface     | Attribute     | Value              |
       +--------------+---------------+--------------------+
       |getnameinfo() | Thread safety | MT-Safe env locale |
       +--------------+---------------+--------------------+

CONFORMING TO
       POSIX.1-2001, POSIX.1-2008, RFC 2553.

NOTES
       In order to assist the programmer in choosing reasonable sizes for  the
       supplied buffers, <netdb.h> defines the constants

           #define NI_MAXHOST      1025
           #define NI_MAXSERV      32

       Since glibc 2.8, these definitions are exposed only if suitable feature
       test macros are defined, namely:  _GNU_SOURCE,  _DEFAULT_SOURCE  (since
       glibc   2.19),  or  (in  glibc  versions  up  to  and  including  2.19)
       _BSD_SOURCE or _SVID_SOURCE.

       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 ser-
       vices listed in the current Assigned Numbers RFC.

       Before glibc version 2.2, the hostlen and servlen arguments were  typed
       as size_t.

EXAMPLES
       The  following code tries to get the numeric hostname and service name,
       for a given socket address.  Note that there is no hardcoded  reference
       to a particular address family.

           struct sockaddr *addr;     /* input */
           socklen_t addrlen;         /* input */
           char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];

           if (getnameinfo(addr, addrlen, 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 ad-
       dress mapping.

           struct sockaddr *addr;     /* input */
           socklen_t addrlen;         /* input */
           char hbuf[NI_MAXHOST];

           if (getnameinfo(addr, addrlen, hbuf, sizeof(hbuf),
                       NULL, 0, NI_NAMEREQD))
               printf("could not resolve hostname");
           else
               printf("host=%s\n", hbuf);

       An example program using getnameinfo() can be found in getaddrinfo(3).

SEE ALSO
       accept(2),  getpeername(2),  getsockname(2),  recvfrom(2),   socket(2),
       getaddrinfo(3),  gethostbyaddr(3),  getservbyname(3), getservbyport(3),
       inet_ntop(3), hosts(5), services(5), hostname(7), named(8)

       R. Gilligan, S. Thomson, J. Bound and W. Stevens, Basic  Socket  Inter-
       face 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 technical conference, June 2000
       <http://www.usenix.org/publications/library/proceedings/usenix2000
       /freenix/metzprotocol.html>.

COLOPHON
       This page is part of release 5.07 of the Linux man-pages project.  A
       description of the project, information about reporting bugs, and the
       latest version of this page, can be found at
       https://www.kernel.org/doc/man-pages/.

GNU                               2020-06-09                    GETNAMEINFO(3)

Man(1) output converted with man2html
list of all man pages