getnameinfo(3)

1getnameinfo(3)             Library Functions Manual             getnameinfo(3)
2
3
4

NAME

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

LIBRARY

10       Standard C library (libc, -lc)
11

SYNOPSIS

13       #include <sys/socket.h>
14       #include <netdb.h>
15
16       int getnameinfo(const struct sockaddr *restrict addr, socklen_t addrlen,
17                       char host[_Nullable restrict .hostlen],
18                       socklen_t hostlen,
19                       char serv[_Nullable restrict .servlen],
20                       socklen_t servlen,
21                       int flags);
22
23   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
24
25       getnameinfo():
26           Since glibc 2.22:
27               _POSIX_C_SOURCE >= 200112L
28           glibc 2.21 and earlier:
29               _POSIX_C_SOURCE
30

DESCRIPTION

32       The getnameinfo() function is the inverse of  getaddrinfo(3):  it  con‐
33       verts a socket address to a corresponding host and service, in a proto‐
34       col-independent manner.  It  combines  the  functionality  of  gethost‐
35       byaddr(3)  and  getservbyport(3),  but unlike those functions, getname‐
36       info() is reentrant and allows programs to  eliminate  IPv4-versus-IPv6
37       dependencies.
38
39       The  addr  argument  is a pointer to a generic socket address structure
40       (of type sockaddr_in or sockaddr_in6) of size addrlen  that  holds  the
41       input  IP  address  and  port  number.  The arguments host and serv are
42       pointers to caller-allocated buffers (of size hostlen and  servlen  re‐
43       spectively)  into  which  getnameinfo()  places null-terminated strings
44       containing the host and service names respectively.
45
46       The caller can specify that no hostname (or no  service  name)  is  re‐
47       quired  by  providing  a NULL host (or serv) argument or a zero hostlen
48       (or servlen) argument.  However, at least one of  hostname  or  service
49       name must be requested.
50
51       The flags argument modifies the behavior of getnameinfo() as follows:
52
53       NI_NAMEREQD
54              If  set, then an error is returned if the hostname cannot be de‐
55              termined.
56
57       NI_DGRAM
58              If set, then the service is datagram  (UDP)  based  rather  than
59              stream  (TCP)  based.   This  is  required  for  the  few  ports
60              (512–514) that have different services for UDP and TCP.
61
62       NI_NOFQDN
63              If set, return only the hostname part of the fully qualified do‐
64              main name for local hosts.
65
66       NI_NUMERICHOST
67              If  set,  then  the  numeric  form  of the hostname is returned.
68              (When not set, this will still happen in case  the  node's  name
69              cannot be determined.)
70
71       NI_NUMERICSERV
72              If  set,  then  the  numeric  form of the service address is re‐
73              turned.  (When not set, this will still happen in case the  ser‐
74              vice's name cannot be determined.)
75
76   Extensions to getnameinfo() for Internationalized Domain Names
77       Starting  with  glibc  2.3.4, getnameinfo() has been extended to selec‐
78       tively allow hostnames to be transparently converted to  and  from  the
79       Internationalized  Domain Name (IDN) format (see RFC 3490, Internation‐
80       alizing Domain Names in Applications (IDNA)).  Three new flags are  de‐
81       fined:
82
83       NI_IDN If  this flag is used, then the name found in the lookup process
84              is converted from IDN format to the locale's encoding if  neces‐
85              sary.   ASCII-only  names  are  not  affected by the conversion,
86              which makes this flag usable in existing programs  and  environ‐
87              ments.
88
89       NI_IDN_ALLOW_UNASSIGNED, NI_IDN_USE_STD3_ASCII_RULES
90              Setting these flags will enable the IDNA_ALLOW_UNASSIGNED (allow
91              unassigned Unicode code  points)  and  IDNA_USE_STD3_ASCII_RULES
92              (check  output  to  make  sure it is a STD3 conforming hostname)
93              flags respectively to be used in the IDNA handling.
94

RETURN VALUE

96       On success, 0 is returned, and node and service  names,  if  requested,
97       are  filled with null-terminated strings, possibly truncated to fit the
98       specified buffer lengths.  On error, one of the following nonzero error
99       codes is returned:
100
101       EAI_AGAIN
102              The name could not be resolved at this time.  Try again later.
103
104       EAI_BADFLAGS
105              The flags argument has an invalid value.
106
107       EAI_FAIL
108              A nonrecoverable error occurred.
109
110       EAI_FAMILY
111              The address family was not recognized, or the address length was
112              invalid for the specified family.
113
114       EAI_MEMORY
115              Out of memory.
116
117       EAI_NONAME
118              The  name  does  not  resolve  for   the   supplied   arguments.
119              NI_NAMEREQD  is  set  and  the host's name cannot be located, or
120              neither hostname nor service name were requested.
121
122       EAI_OVERFLOW
123              The buffer pointed to by host or serv was too small.
124
125       EAI_SYSTEM
126              A system error occurred.  The error code can be found in errno.
127
128       The gai_strerror(3) function translates these error codes  to  a  human
129       readable string, suitable for error reporting.
130

FILES

132       /etc/hosts
133       /etc/nsswitch.conf
134       /etc/resolv.conf
135

ATTRIBUTES

137       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
138       tributes(7).
139
140       ┌─────────────────────────────────┬───────────────┬────────────────────┐
141       │Interface                        │ Attribute     │ Value              │
142       ├─────────────────────────────────┼───────────────┼────────────────────┤
143       │getnameinfo()                    │ Thread safety │ MT-Safe env locale │
144       └─────────────────────────────────┴───────────────┴────────────────────┘
145

STANDARDS

147       POSIX.1-2008.  RFC 2553.
148

HISTORY

150       glibc 2.1.  POSIX.1-2001.
151
152       Before glibc 2.2, the hostlen  and  servlen  arguments  were  typed  as
153       size_t.
154

NOTES

156       In  order to assist the programmer in choosing reasonable sizes for the
157       supplied buffers, <netdb.h> defines the constants
158
159           #define NI_MAXHOST      1025
160           #define NI_MAXSERV      32
161
162       Since glibc 2.8, these definitions are exposed only if suitable feature
163       test  macros  are  defined, namely: _GNU_SOURCE, _DEFAULT_SOURCE (since
164       glibc  2.19),  or  (in  glibc  versions  up  to  and  including   2.19)
165       _BSD_SOURCE or _SVID_SOURCE.
166
167       The  former  is  the  constant  MAXDNAME  in  recent versions of BIND's
168       <arpa/nameser.h> header file.  The latter is a guess based on the  ser‐
169       vices listed in the current Assigned Numbers RFC.
170

EXAMPLES

172       The  following code tries to get the numeric hostname and service name,
173       for a given socket address.  Note that there is no hardcoded  reference
174       to a particular address family.
175
176           struct sockaddr *addr;     /* input */
177           socklen_t addrlen;         /* input */
178           char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
179
180           if (getnameinfo(addr, addrlen, hbuf, sizeof(hbuf), sbuf,
181                       sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0)
182               printf("host=%s, serv=%s\n", hbuf, sbuf);
183
184       The  following  version  checks if the socket address has a reverse ad‐
185       dress mapping.
186
187           struct sockaddr *addr;     /* input */
188           socklen_t addrlen;         /* input */
189           char hbuf[NI_MAXHOST];
190
191           if (getnameinfo(addr, addrlen, hbuf, sizeof(hbuf),
192                       NULL, 0, NI_NAMEREQD))
193               printf("could not resolve hostname");
194           else
195               printf("host=%s\n", hbuf);
196
197       An example program using getnameinfo() can be found in getaddrinfo(3).
198