1gethostbyname(3NSL) Networking Services Library Functions gethostbyname(3NSL)
2
6 gethostbyname, gethostbyname_r, gethostbyaddr, gethostbyaddr_r, gethos‐
7 tent, gethostent_r, sethostent, endhostent - get network host entry
8
10 cc [ flag... ] file... -lnsl [ library... ]
11 #include <netdb.h>
12 struct hostent *gethostbyname(const char *name);
14 struct hostent *gethostbyname_r(const char *name,
17 struct hostent *result, char *buffer, int buflen,
18 int *h_errnop);
19 struct hostent *gethostbyaddr(const char *addr, int len,
22 int type);
23 struct hostent *gethostbyaddr_r(const char *addr, int length,
26 int type, struct hostent *result, char *buffer,
27 int buflen, int *h_errnop);
28 struct hostent *gethostent(void);
31 struct hostent *gethostent_r(struct hostent *result,
34 char *buffer, int buflen, int *h_errnop);
35 int sethostent(int stayopen);
38 int endhostent(void);
41
44 These functions are used to obtain entries describing hosts. An entry
45 can come from any of the sources for hosts specified in the /etc/nss‐
46 witch.conf file. See nsswitch.conf(4). These functions have been super‐
47 seded by getipnodebyname(3SOCKET), getipnodebyaddr(3SOCKET), and getad‐
48 drinfo(3SOCKET), which provide greater portability to applications when
49 multithreading is performed or technologies such as IPv6 are used. For
50 example, the functions described in the following cannot be used with
51 applications targeted to work with IPv6.
52 The gethostbyname() function searches for information for a host with
55 the hostname specified by the character-string parameter name.
56 The gethostbyaddr() function searches for information for a host with a
59 given host address. The parameter type specifies the family of the
60 address. This should be one of the address families defined in
61 <sys/socket.h>. See the NOTES section for more information. Also see
62 the EXAMPLES section for information on how to convert an Internet IP
63 address notation that is separated by periods (.) into an addr parame‐
64 ter. The parameter len specifies the length of the buffer indicated by
65 addr.
66 All addresses are returned in network order. In order to interpret the
69 addresses, byteorder(3SOCKET) must be used for byte order conversion.
70 The sethostent(), gethostent(), and endhostent() functions are used to
73 enumerate host entries from the database.
74 The sethostent() function sets or resets the enumeration to the begin‐
77 ning of the set of host entries. This function should be called before
78 the first call to gethostent(). Calls to gethostbyname() and gethost‐
79 byaddr() leave the enumeration position in an indeterminate state. If
80 the stayopen flag is non-zero, the system can keep allocated resources
81 such as open file descriptors until a subsequent call to endhostent().
82 Successive calls to the gethostent() function return either successive
85 entries or NULL, indicating the end of the enumeration.
86 The endhostent() function can be called to indicate that the caller
89 expects to do no further host entry retrieval operations; the system
90 can then deallocate resources it was using. It is still allowed, but
91 possibly less efficient, for the process to call more host retrieval
92 functions after calling endhostent().
93 Reentrant Interfaces
95 The gethostbyname(), gethostbyaddr(), and gethostent() functions use
96 static storage that is reused in each call, making these functions
97 unsafe for use in multithreaded applications.
98 The gethostbyname_r(), gethostbyaddr_r(), and gethostent_r() functions
101 provide reentrant interfaces for these operations.
102 Each reentrant interface performs the same operation as its non-reen‐
105 trant counterpart, named by removing the _r suffix. The reentrant
106 interfaces, however, use buffers supplied by the caller to store
107 returned results and the interfaces are safe for use in both single-
108 threaded and multithreaded applications.
109 Each reentrant interface takes the same parameters as its non-reentrant
112 counterpart, as well as the following additional parameters. The param‐
113 eter result must be a pointer to a struct hostent structure allocated
114 by the caller. On successful completion, the function returns the host
115 entry in this structure. The parameter buffer must be a pointer to a
116 buffer supplied by the caller. This buffer is used as storage space for
117 the host data. All of the pointers within the returned struct hostent
118 result point to data stored within this buffer. See the RETURN VALUES
119 section for more information. The buffer must be large enough to hold
120 all of the data associated with the host entry. The parameter buflen
121 should give the size in bytes of the buffer indicated by buffer. The
122 parameter h_errnop should be a pointer to an integer. An integer error
123 status value is stored there on certain error conditions. See the
124 ERRORS section for more information.
125 For enumeration in multithreaded applications, the position within the
128 enumeration is a process-wide property shared by all threads. The
129 sethostent() function can be used in a multithreaded application but
130 resets the enumeration position for all threads. If multiple threads
131 interleave calls to gethostent_r(), the threads will enumerate disjoint
132 subsets of the host database.
133 Like their non-reentrant counterparts, gethostbyname_r() and gethost‐
136 byaddr_r() leave the enumeration position in an indeterminate state.
137
139 Host entries are represented by the struct hostent structure defined in
140 <netdb.h>:
141 struct hostent {
143 char *h_name; /* canonical name of host */
144 char **h_aliases; /* alias list */
145 int h_addrtype; /* host address type */
146 int h_length; /* length of address */
147 char **h_addr_list; /* list of addresses */
148 };
149 See the EXAMPLES section for information about how to retrieve a ``.''
153 separated Internet IP address string from the h_addr_list field of
154 struct hostent.
155 The gethostbyname(), gethostbyname_r(), gethostbyaddr(), and gethost‐
158 byaddr_r() functions each return a pointer to a struct hostent if they
159 successfully locate the requested entry; otherwise they return NULL.
160 The gethostent() and gethostent_r() functions each return a pointer to
163 a struct hostent if they successfully enumerate an entry; otherwise
164 they return NULL, indicating the end of the enumeration.
165 The gethostbyname(), gethostbyaddr(), and gethostent() functions use
168 static storage, so returned data must be copied before a subsequent
169 call to any of these functions if the data is to be saved.
170 When the pointer returned by the reentrant functions gethostbyname_r(),
173 gethostbyaddr_r(), and gethostent_r() is not NULL, it is always equal
174 to the result pointer that was supplied by the caller.
175 The sethostent() and endhostent() functions return 0 on success.
178
180 The reentrant functions gethostbyname_r(), gethostbyaddr_r(), and geth‐
181 ostent_r() will return NULL and set errno to ERANGE if the length of
182 the buffer supplied by caller is not large enough to store the result.
183 See Intro(2) for the proper usage and interpretation of errno in multi‐
184 threaded applications.
185 The reentrant functions gethostbyname_r() and gethostbyaddr_r() set the
188 integer pointed to by h_errnop to one of these values in case of error.
189 On failures, the non-reentrant functions gethostbyname() and gethost‐
192 byaddr() set a global integer h_errno to indicate one of these error
193 codes (defined in <netdb.h>): HOST_NOT_FOUND, TRY_AGAIN, NO_RECOVERY,
194 NO_DATA, and NO_ADDRESS.
195 If a resolver is provided with a malformed address, or if any other
198 error occurs before gethostbyname() is resolved, then gethostbyname()
199 returns an internal error with a value of −1.
200 The gethostbyname() function will set h_errno to NETDB_INTERNAL when it
203 returns a NULL value.
204
206 Example 1 Using gethostbyaddr()
207 Here is a sample program that gets the canonical name, aliases, and
210 ``.'' separated Internet IP addresses for a given ``.'' separated IP
211 address:
212 #include <stdio.h>
215 #include <stdlib.h
216 #include <string.h>
217 #include <sys/types.h>
218 #include <sys/socket.h>
219 #include <netinet/in.h>
220 #include <arpa/inet.h>
221 #include <netdb.h>
222 int main(int argc, const char **argv)
223 {
224 in_addr_t addr;
225 struct hostent *hp;
226 char **p;
227 if (argc != 2) {
228 (void) printf("usage: %s IP-address\n", argv[0]);
229 exit (1);
230 }
231 if ((int)(addr = inet_addr(argv[1])) == -1) {
232 (void) printf("IP-address must be of the form a.b.c.d\n");
233 exit (2);
234 }
235 hp = gethostbyaddr((char *)&addr, 4, AF_INET);
236 if (hp == NULL) {
237 (void) printf("host information for %s not found\n", argv[1]);
238 exit (3);
239 }
240 for (p = hp->h_addr_list; *p != 0; p++) {
241 struct in_addr in;
242 char **q;
243 (void) memcpy(&in.s_addr, *p, sizeof (in.s_addr));
244 (void) printf("%s%s", inet_ntoa(in), hp−>h_name);
245 for (q = hp->h_aliases; *q != 0; q++)
246 (void) printf(" %s", *q);
247 (void) putchar('0);
248 }
249 exit (0);
250 }
251 Note that the preceding sample program is unsafe for use in multi‐
255 threaded applications.
256
259 /etc/hosts hosts file that associates the names of hosts
260 with their Internet Protocol (IP) addresses
261 /etc/netconfig network configuration database
264 /etc/nsswitch.conf configuration file for the name service switch
267
270 See attributes(5) for descriptions of the following attributes:
271 ┌─────────────────────────────┬─────────────────────────────┐
276 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
277 ├─────────────────────────────┼─────────────────────────────┤
278 │MT-Level │See Reentrant Interfaces in │
279 │ │the DESCRIPTION section. │
280 └─────────────────────────────┴─────────────────────────────┘
281
283 Intro(2), Intro(3), byteorder(3SOCKET), inet(3SOCKET), netdb.h(3HEAD),
284 netdir(3NSL), hosts(4), netconfig(4), nss(4), nsswitch.conf(4),
285 attributes(5)
286
288 The reentrant interfaces gethostbyname_r(), gethostbyaddr_r(), and
289 gethostent_r() are included in this release on an uncommitted basis
290 only and are subject to change or removal in future minor releases.
291
293 To ensure that they all return consistent results, gethostbyname(),
294 gethostbyname_r(), and netdir_getbyname() are implemented in terms of
295 the same internal library function. This function obtains the system-
296 wide source lookup policy based on the inet family entries in netcon‐
297 fig(4) and the hosts: entry in nsswitch.conf(4). Similarly, gethost‐
298 byaddr(), gethostbyaddr_r(), and netdir_getbyaddr() are implemented in
299 terms of the same internal library function. If the inet family entries
300 in netconfig(4) have a ``-'' in the last column for nametoaddr
301 libraries, then the entry for hosts in nsswitch.conf will be used;
302 nametoaddr libraries in that column will be used, and nsswitch.conf
303 will not be consulted.
304 There is no analogue of gethostent() and gethostent_r() in the netdir
307 functions, so these enumeration functions go straight to the hosts
308 entry in nsswitch.conf. Thus enumeration can return results from a dif‐
309 ferent source than that used by gethostbyname(), gethostbyname_r(),
310 gethostbyaddr(), and gethostbyaddr_r().
311 All the functions that return a struct hostent must always return the
314 canonical name in the h_name field. This name, by definition, is the
315 well-known and official hostname shared between all aliases and all
316 addresses. The underlying source that satisfies the request determines
317 the mapping of the input name or address into the set of names and
318 addresses in hostent. Different sources might do that in different
319 ways. If there is more than one alias and more than one address in hos‐
320 tent, no pairing is implied between them.
321 The system attempts to put those addresses that are on the same subnet
324 as the caller before addresses that are on different subnets. However,
325 if address sorting is disabled by setting SORT_ADDRS to FALSE in the
326 /etc/default/nss file, the system does not put the local subnet
327 addresses first. See nss(4) for more information.
328 When compiling multithreaded applications, see Intro(3), MULTITHREADED
331 APPLICATIONS, for information about the use of the _REENTRANT flag.
332 Use of the enumeration interfaces gethostent() and gethostent_r() is
335 discouraged; enumeration might not be supported for all database
336 sources. The semantics of enumeration are discussed further in nss‐
337 witch.conf(4).
338 The current implementations of these functions only return or accept
341 addresses for the Internet address family (type AF_INET).
342 The form for an address of type AF_INET is a struct in_addr defined in
345 <netinet/in.h>. The functions described in inet(3SOCKET), and illus‐
346 trated in the EXAMPLES section, are helpful in constructing and manipu‐
347 lating addresses in this form.
348SunOS 5.11 24 Aug 2007 gethostbyname(3NSL)