getnameinfo(3)

1getnameinfo(3)             UNIX Programmer's Manual             getnameinfo(3)
2
3
4

NAME

6       getnameinfo  - address-to-name translation in protocol-independent man‐
7       ner
8

SYNOPSIS

10       #include <sys/socket.h>
11       #include <netdb.h>
12
13       int getnameinfo(const struct sockaddr *sa, socklen_t salen,
14                       char *host, size_t hostlen,
15                       char *serv, size_t servlen, int flags);
16

DESCRIPTION

18       The  getnameinfo(3)  function  is  defined   for   protocol-independent
19       address-to-nodename  translation.   It  combines  the  functionality of
20       gethostbyaddr(3) and getservbyport(3) and  is  the  inverse  of  getad‐
21       drinfo(3).   The  sa  argument is a pointer to a generic socket address
22       structure (of type sockaddr_in or  sockaddr_in6)  of  size  salen  that
23       holds  the  input  IP  address and port number.  The arguments host and
24       serv are pointers to buffers (of size hostlen and servlen respectively)
25       to hold the return values.
26
27       The  caller  can  specify  that  no  hostname  (or  no service name) is
28       required by providing a NULL host (or serv) argument or a zero  hostlen
29       (or  servlen)  parameter.  However, at least one of hostname or service
30       name must be requested.
31
32       The flags argument modifies the behaviour of getnameinfo(3) as follows:
33
34       NI_NOFQDN
35              If set, return only the hostname part  of  the  FQDN  for  local
36              hosts.
37
38       NI_NUMERICHOST
39              If  set,  then  the  numeric  form  of the hostname is returned.
40              (When not set, this will still happen in case  the  node's  name
41              cannot be looked up.)
42
43       NI_NAMEREQD
44              If  set,  then  a  error  is  returned if the hostname cannot be
45              looked up.
46
47       NI_NUMERICSERV
48              If set, then the service address is returned  in  numeric  form,
49              for example by its port number.
50
51       NI_DGRAM
52              If  set,  then  the  service is datagram (UDP) based rather than
53              stream (TCP) based. This is required for the few ports (512-514)
54              that have different services for UDP and TCP.
55
56   Extensions to getaddrinfo() for Internationalized Domain Names
57       Starting  with  glibc  2.3.4, getnameinfo() has been extended to selec‐
58       tively allow host names to be transparently converted to and  from  the
59       Internationalized  Domain Name (IDN) format (see RFC 3490, Internation‐
60       alizing Domain Names in Applications  (IDNA)).   Three  new  flags  are
61       defined:
62
63       NI_IDN If  this flag is used, then the name found in the lookup process
64              is converted from IDN format to the locale's encoding if  neces‐
65              sary.   ASCII-only  names  are  not  affected by the conversion,
66              which makes this flag usable in existing programs  and  environ‐
67              ments.
68
69       NI_IDN_ALLOW_UNASSIGNED, NI_IDN_USE_STD3_ASCII_RULES
70              Setting these flags will enable the IDNA_ALLOW_UNASSIGNED (allow
71              unassigned Unicode code  points)  and  IDNA_USE_STD3_ASCII_RULES
72              (check  output  to  make sure it is a STD3 conforming host name)
73              flags respectively to be used in the IDNA handling.
74

RETURN VALUE

76       On success 0 is returned, and node and service names, if requested, are
77       filled  with  null-terminated  strings,  possibly  truncated to fit the
78       specified buffer lengths.  On error one of the following non-zero error
79       codes is returned:
80
81       EAI_AGAIN
82              The name could not be resolved at this time. Try again later.
83
84       EAI_BADFLAGS
85              The flags parameter has an invalid value.
86
87       EAI_FAIL
88              A non-recoverable error occurred.
89
90       EAI_FAMILY
91              The address family was not recognized, or the address length was
92              invalid for the specified family.
93
94       EAI_MEMORY
95              Out of memory.
96
97       EAI_NONAME
98              The  name  does  not  resolve  for  the   supplied   parameters.
99              NI_NAMEREQD  is  set  and  the host's name cannot be located, or
100              neither hostname nor service name were requested.
101
102       EAI_OVERFLOW
103              The buffer pointed to by host or serv was too small.
104
105       EAI_SYSTEM
106              A system error occurred. The error code can be found in errno.
107
108       The gai_strerror(3) function translates these error codes  to  a  human
109       readable string, suitable for error reporting.
110

FILES

112       /etc/hosts
113       /etc/nsswitch.conf
114       /etc/resolv.conf
115

NOTE

117       In  order to assist the programmer in choosing reasonable sizes for the
118       supplied buffers, <netdb.h> defines the constants
119              # define NI_MAXHOST      1025
120              # define NI_MAXSERV      32
121       The former is the  constant  MAXDNAME  in  recent  versions  of  BIND's
122       <arpa/nameser.h>  header  file. The latter is a guess based on the ser‐
123       vices listed in the current Assigned Numbers RFC.
124

EXAMPLE

126       The following code tries to get the numeric hostname and service  name,
127       for  a  given socket address. Note that there is no hardcoded reference
128       to a particular address family.
129
130                struct sockaddr *sa;    /* input */
131                char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
132
133                if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf,
134                    sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0)
135                        printf("host=%s, serv=%s\n", hbuf, sbuf);
136
137       The following version checks  if  the  socket  address  has  a  reverse
138       address mapping.
139
140                struct sockaddr *sa;    /* input */
141                char hbuf[NI_MAXHOST];
142
143                if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf),
144                    NULL, 0, NI_NAMEREQD))
145                       printf("could not resolve hostname");
146                else
147                       printf("host=%s\n", hbuf);
148

CONFORMING TO

150       RFC 2553, POSIX.1-2001.
151