Penguin
Recent Changes
Blame: getnameinfo(3)
EditPageHistoryDiffInfoLikePages
Annotated edit history of getnameinfo(3) version 4, including all changes. View license author blame.
Rev Author # Line
1 perry 1 getnameinfo
2 !!!getnameinfo
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 RETURN VALUE
7 ERRORS
8 FILES
9 NOTE
10 EXAMPLES
11 CONFORMING TO
12 SEE ALSO
13 ----
14 !!NAME
15
16
17 getnameinfo - address-to-name translation in protocol-independent manner
18 !!SYNOPSIS
19
20
21 __#include
22 __''sa''__, socklen_t__ ''salen''__,
23 char *__''host''__, size_t__ ''hostlen''__,
24 char *__''serv''__, size_t__ ''servlen''__, int__ ''flags''__);
25 __
26 !!DESCRIPTION
27
28
29 The getnameinfo(3) function is defined for
30 protocol-independent address-to-nodename translation. It
31 combines the functionality of gethostbyaddr(3) and
32 getservbyport(3) and is the inverse of
33 getaddrinfo(3). The ''sa'' argument is a pointer
34 to a generic socket address structure (of type
35 ''sockaddr_in'' or ''sockaddr_in6'') of size
36 ''salen'' that holds the input IP address and port
37 number. The arguments ''host'' and ''serv'' are
38 pointers to buffers (of size ''hostlen'' and
39 ''servlen'' repectively) to hold the return
40 values.
41
42
43 The caller can specify that no hostname (or no service name)
44 is required by providing a NULL ''host'' (or ''serv'')
45 argument or a zero ''hostlen'' (or ''servlen'')
46 parameter. However, at least one of hostname or service name
47 must be requested.
48
49
50 The ''flags'' argument modifies the behaviour of
51 getnameinfo(3) as follows:
52
53
54 __NI_NOFQDN__
55
56
57 If set, return only the hostname part of the FQDN for local
58 hosts.
59
60
61 __NI_NUMERICHOST__
62
63
64 If set, then the numeric form of the hostname is returned.
65 (When not set, this will still happen in case the node's
66 name cannot be looked up.)
67
68
69 __NI_NAMEREQD__
70
71
72 If set, then a error is returned if the hostname cannot be
73 looked up.
74
75
76 __NI_NUMERICSERV__
77
78
79 If set, then the service address is returned in numeric
80 form, for example by its port number.
81
82
83 __NI_DGRAM__
84
85
86 If set, then the service is datagram (UDP) based rather than
87 stream (TCP) based. This is required for the few ports
88 (512-514) that have different services for UDP and
89 TCP.
90 !!RETURN VALUE
91
92
93 On success 0 is returned, and node and service names, if
94 requested, are filled with NUL-terminated strings, possibly
95 truncated to fit the specified buffer lengths. On error a
96 nonzero value is returned, and ''errno'' is set
97 appropriately.
98 !!ERRORS
99
100
101 __EAI_AGAIN__
102
103
104 The name could not be resolved at this time. Try again
105 later.
106
107
108 __EAI_BADFLAGS__
109
110
111 The ''flags'' parameter has an invalid
112 value.
113
114
115 __EAI_FAIL__
116
117
118 A non-recoverable error occurred.
119
120
121 __EAI_FAMILY__
122
123
124 The address family was not recognized, or the address length
125 was invalid for the specified family.
126
127
128 __EAI_MEMORY__
129
130
131 Out of memory.
132
133
134 __EAI_NONAME__
135
136
137 The name does not resolve for the supplied parameters.
138 NI_NAMEREQD is set and the host's name cannot be located, or
139 neither hostname nor service name were
140 requested.
141
142
143 __EAI_SYSTEM__
144
145
146 A system error occurred. The error code can be found in
147 ''errno''.
148 !!FILES
149
150
151 /etc/hosts
152 /etc/nsswitch.conf
153 /etc/resolv.conf
154 !!NOTE
155
156
157 In order to assist the programmer in choosing reasonable
158 sizes for the supplied buffers, ''''
159 defines the constants
160
161
162 # define NI_MAXHOST 1025
163 # define NI_MAXSERV 32
164
165
166 The former is the constant MAXDNAME in recent versions of
167 BIND's '''' header file. The latter
168 is a guess based on the services listed in the current
169 Assigned Numbers RFC.
170 !!EXAMPLES
171
172
173 The following code tries to get the numeric hostname and
174 service name, for a given socket address. Note that there is
175 no hardcoded reference to a particular address
176 family.
177
178
179 struct sockaddr *sa; /* input */
180 char hbuf[[NI_MAXHOST], sbuf[[NI_MAXSERV];
181 if (getnameinfo(sa, sa-
182
183
184 The following version checks if the socket address has a
185 reverse address mapping.
186
187
188 struct sockaddr *sa; /* input */ char
189 hbuf[[NI_MAXHOST];
190
191
192 if (getnameinfo(sa, sa-
193 !!CONFORMING TO
194
195
196 RFC 2553. (See also XNS, issue 5.2.)
197 !!SEE ALSO
198
199
200 getaddrinfo(3), gethostbyaddr(3),
201 getservbyname(3), getservbyport(3),
4 perry 202 inet_ntop(3), socket(3), hosts(5),
1 perry 203 services(5), hostname(7),
204 named(8)
205
206
207 R. Gilligan, S. Thomson, J. Bound and W. Stevens, ''Basic
208 Socket Interface Extensions for IPv6'', RFC 2553, March
209 1999.
210
211
212 Tatsuya Jinmei and Atsushi Onoe, ''An Extension of Format
213 for IPv6 Scoped Addresses'', internet draft, work in
214 progress.
215 ftp://ftp.ietf.org/internet-drafts/draft-ietf-ipngwg-scopedaddr-format-02.txt
216
217
218 Craig Metz, ''Protocol Independence Using the Sockets
219 API'', Proceedings of the freenix track: 2000 USENIX
220 annual technical conference, June 2000.
221 http://www.usenix.org/publications/library/proceedings/usenix2000/freenix/metzprotocol.html
222 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.