1LWRES_GETHOSTENT(3) BIND9 LWRES_GETHOSTENT(3)
2
6 lwres_gethostbyname, lwres_gethostbyname2, lwres_gethostbyaddr,
7 lwres_gethostent, lwres_sethostent, lwres_endhostent,
8 lwres_gethostbyname_r, lwres_gethostbyaddr_r, lwres_gethostent_r,
9 lwres_sethostent_r, lwres_endhostent_r - lightweight resolver get
10 network host entry
11
13 #include <lwres/netdb.h>
14 struct hostent * lwres_gethostbyname(const char *name);
16 struct hostent * lwres_gethostbyname2(const char *name, int af);
18 struct hostent * lwres_gethostbyaddr(const char *addr, int len,
20 int type);
21 struct hostent * lwres_gethostent(void);
23 void lwres_sethostent(int stayopen);
25 void lwres_endhostent(void);
27 struct hostent * lwres_gethostbyname_r(const char *name,
29 struct hostent *resbuf,
30 char *buf, int buflen,
31 int *error);
32 struct hostent * lwres_gethostbyaddr_r(const char *addr, int len,
34 int type,
35 struct hostent *resbuf,
36 char *buf, int buflen,
37 int *error);
38 struct hostent * lwres_gethostent_r(struct hostent *resbuf, char *buf,
40 int buflen, int *error);
41 void lwres_sethostent_r(int stayopen);
43 void lwres_endhostent_r(void);
45
47 These functions provide hostname-to-address and address-to-hostname
48 lookups by means of the lightweight resolver. They are similar to the
49 standard gethostent(3) functions provided by most operating systems.
50 They use a struct hostent which is usually defined in <namedb.h>.
51 struct hostent {
53 char *h_name; /* official name of host */
54 char **h_aliases; /* alias list */
55 int h_addrtype; /* host address type */
56 int h_length; /* length of address */
57 char **h_addr_list; /* list of addresses from name server */
58 };
59 #define h_addr h_addr_list[0] /* address, for backward compatibility */
60 The members of this structure are:
63 h_name
65 The official (canonical) name of the host.
66 h_aliases
68 A NULL-terminated array of alternate names (nicknames) for the
69 host.
70 h_addrtype
72 The type of address being returned — PF_INET or PF_INET6.
73 h_length
75 The length of the address in bytes.
76 h_addr_list
78 A NULL terminated array of network addresses for the host. Host
79 addresses are returned in network byte order.
80 For backward compatibility with very old software, h_addr is the first
82 address in h_addr_list.
83 lwres_gethostent(), lwres_sethostent(), lwres_endhostent(),
85 lwres_gethostent_r(), lwres_sethostent_r() and lwres_endhostent_r()
86 provide iteration over the known host entries on systems that provide
87 such functionality through facilities like /etc/hosts or NIS. The
88 lightweight resolver does not currently implement these functions; it
89 only provides them as stub functions that always return failure.
90 lwres_gethostbyname() and lwres_gethostbyname2() look up the hostname
92 name. lwres_gethostbyname() always looks for an IPv4 address while
93 lwres_gethostbyname2() looks for an address of protocol family af:
94 either PF_INET or PF_INET6 — IPv4 or IPV6 addresses respectively.
95 Successful calls of the functions return a struct hostentfor the name
96 that was looked up. NULL is returned if the lookups by
97 lwres_gethostbyname() or lwres_gethostbyname2() fail.
98 Reverse lookups of addresses are performed by lwres_gethostbyaddr().
100 addr is an address of length len bytes and protocol family type —
101 PF_INET or PF_INET6. lwres_gethostbyname_r() is a thread-safe function
102 for forward lookups. If an error occurs, an error code is returned in
103 *error. resbuf is a pointer to a struct hostent which is initialised
104 by a successful call to lwres_gethostbyname_r(). buf is a buffer of
105 length len bytes which is used to store the h_name, h_aliases, and
106 h_addr_list elements of the struct hostent returned in resbuf.
107 Successful calls to lwres_gethostbyname_r() return resbuf, which is a
108 pointer to the struct hostent it created.
109 lwres_gethostbyaddr_r() is a thread-safe function that performs a
111 reverse lookup of address addr which is len bytes long and is of
112 protocol family type — PF_INET or PF_INET6. If an error occurs, the
113 error code is returned in *error. The other function parameters are
114 identical to those in lwres_gethostbyname_r(). resbuf is a pointer to
115 a struct hostent which is initialised by a successful call to
116 lwres_gethostbyaddr_r(). buf is a buffer of length len bytes which is
117 used to store the h_name, h_aliases, and h_addr_list elements of the
118 struct hostent returned in resbuf. Successful calls to
119 lwres_gethostbyaddr_r() return resbuf, which is a pointer to the struct
120 hostent() it created.
121
123 The functions lwres_gethostbyname(), lwres_gethostbyname2(),
124 lwres_gethostbyaddr(), and lwres_gethostent() return NULL to indicate
125 an error. In this case the global variable lwres_h_errno will contain
126 one of the following error codes defined in <lwres/netdb.h>:
127 HOST_NOT_FOUND
129 The host or address was not found.
130 TRY_AGAIN
132 A recoverable error occurred, e.g., a timeout. Retrying the lookup
133 may succeed.
134 NO_RECOVERY
136 A non-recoverable error occurred.
137 NO_DATA
139 The name exists, but has no address information associated with it
140 (or vice versa in the case of a reverse lookup). The code
141 NO_ADDRESS is accepted as a synonym for NO_DATA for backwards
142 compatibility.
143 lwres_hstrerror(3) translates these error codes to suitable error
145 messages.
146 lwres_gethostent() and lwres_gethostent_r() always return NULL.
148 Successful calls to lwres_gethostbyname_r() and lwres_gethostbyaddr_r()
150 return resbuf, a pointer to the struct hostent that was initialised by
151 these functions. They return NULL if the lookups fail or if buf was too
152 small to hold the list of addresses and names referenced by the h_name,
153 h_aliases, and h_addr_list elements of the struct hostent. If buf was
154 too small, both lwres_gethostbyname_r() and lwres_gethostbyaddr_r() set
155 the global variable errno to ERANGE.
156
158 gethostent(3), lwres_getipnode(3), lwres_hstrerror(3)
159
161 lwres_gethostbyname(), lwres_gethostbyname2(), lwres_gethostbyaddr()
162 and lwres_endhostent() are not thread safe; they return pointers to
163 static data and provide error codes through a global variable.
164 Thread-safe versions for name and address lookup are provided by
165 lwres_gethostbyname_r(), and lwres_gethostbyaddr_r() respectively.
166 The resolver daemon does not currently support any non-DNS name
168 services such as /etc/hosts or NIS, consequently the above functions
169 don't, either.
170
172 Copyright © 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC")
173 Copyright © 2001 Internet Software Consortium.
174BIND9 Jun 30, 2000 LWRES_GETHOSTENT(3)