1LWRES_GETHOSTENT(3)                  BIND9                 LWRES_GETHOSTENT(3)
2
3
4

NAME

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

SYNOPSIS

13       #include <lwres/netdb.h>
14
15       struct hostent * lwres_gethostbyname(const char *name);
16
17       struct hostent * lwres_gethostbyname2(const char *name, int af);
18
19       struct hostent * lwres_gethostbyaddr(const char *addr, int len,
20                                            int type);
21
22       struct hostent * lwres_gethostent(void);
23
24       void lwres_sethostent(int stayopen);
25
26       void lwres_endhostent(void);
27
28       struct hostent * lwres_gethostbyname_r(const char *name,
29                                              struct hostent *resbuf,
30                                              char *buf, int buflen,
31                                              int *error);
32
33       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
39       struct hostent * lwres_gethostent_r(struct hostent *resbuf, char *buf,
40                                           int buflen, int *error);
41
42       void lwres_sethostent_r(int stayopen);
43
44       void lwres_endhostent_r(void);
45

DESCRIPTION

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
52           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
61       The members of this structure are:
62
63       h_name
64           The official (canonical) name of the host.
65
66       h_aliases
67           A NULL-terminated array of alternate names (nicknames) for the
68           host.
69
70       h_addrtype
71           The type of address being returned — PF_INET or PF_INET6.
72
73       h_length
74           The length of the address in bytes.
75
76       h_addr_list
77           A NULL terminated array of network addresses for the host. Host
78           addresses are returned in network byte order.
79
80       For backward compatibility with very old software, h_addr is the first
81       address in h_addr_list.
82
83       lwres_gethostent(), lwres_sethostent(), lwres_endhostent(),
84       lwres_gethostent_r(), lwres_sethostent_r() and lwres_endhostent_r()
85       provide iteration over the known host entries on systems that provide
86       such functionality through facilities like /etc/hosts or NIS. The
87       lightweight resolver does not currently implement these functions; it
88       only provides them as stub functions that always return failure.
89
90       lwres_gethostbyname() and lwres_gethostbyname2() look up the hostname
91       name.  lwres_gethostbyname() always looks for an IPv4 address while
92       lwres_gethostbyname2() looks for an address of protocol family af:
93       either PF_INET or PF_INET6 — IPv4 or IPV6 addresses respectively.
94       Successful calls of the functions return a struct hostentfor the name
95       that was looked up.  NULL is returned if the lookups by
96       lwres_gethostbyname() or lwres_gethostbyname2() fail.
97
98       Reverse lookups of addresses are performed by lwres_gethostbyaddr().
99       addr is an address of length len bytes and protocol family type
100       PF_INET or PF_INET6.  lwres_gethostbyname_r() is a thread-safe function
101       for forward lookups. If an error occurs, an error code is returned in
102       *error.  resbuf is a pointer to a struct hostent which is initialised
103       by a successful call to lwres_gethostbyname_r().  buf is a buffer of
104       length len bytes which is used to store the h_name, h_aliases, and
105       h_addr_list elements of the struct hostent returned in resbuf.
106       Successful calls to lwres_gethostbyname_r() return resbuf, which is a
107       pointer to the struct hostent it created.
108
109       lwres_gethostbyaddr_r() is a thread-safe function that performs a
110       reverse lookup of address addr which is len bytes long and is of
111       protocol family typePF_INET or PF_INET6. If an error occurs, the
112       error code is returned in *error. The other function parameters are
113       identical to those in lwres_gethostbyname_r().  resbuf is a pointer to
114       a struct hostent which is initialised by a successful call to
115       lwres_gethostbyaddr_r().  buf is a buffer of length len bytes which is
116       used to store the h_name, h_aliases, and h_addr_list elements of the
117       struct hostent returned in resbuf. Successful calls to
118       lwres_gethostbyaddr_r() return resbuf, which is a pointer to the struct
119       hostent() it created.
120

RETURN VALUES

122       The functions lwres_gethostbyname(), lwres_gethostbyname2(),
123       lwres_gethostbyaddr(), and lwres_gethostent() return NULL to indicate
124       an error. In this case the global variable lwres_h_errno will contain
125       one of the following error codes defined in <lwres/netdb.h>:
126
127       HOST_NOT_FOUND
128           The host or address was not found.
129
130       TRY_AGAIN
131           A recoverable error occurred, e.g., a timeout. Retrying the lookup
132           may succeed.
133
134       NO_RECOVERY
135           A non-recoverable error occurred.
136
137       NO_DATA
138           The name exists, but has no address information associated with it
139           (or vice versa in the case of a reverse lookup). The code
140           NO_ADDRESS is accepted as a synonym for NO_DATA for backwards
141           compatibility.
142
143       lwres_hstrerror(3) translates these error codes to suitable error
144       messages.
145
146       lwres_gethostent() and lwres_gethostent_r() always return NULL.
147
148       Successful calls to lwres_gethostbyname_r() and lwres_gethostbyaddr_r()
149       return resbuf, a pointer to the struct hostent that was initialised by
150       these functions. They return NULL if the lookups fail or if buf was too
151       small to hold the list of addresses and names referenced by the h_name,
152       h_aliases, and h_addr_list elements of the struct hostent. If buf was
153       too small, both lwres_gethostbyname_r() and lwres_gethostbyaddr_r() set
154       the global variable errno to ERANGE.
155

SEE ALSO

157       gethostent(3), lwres_getipnode(3), lwres_hstrerror(3)
158

BUGS

160       lwres_gethostbyname(), lwres_gethostbyname2(), lwres_gethostbyaddr()
161       and lwres_endhostent() are not thread safe; they return pointers to
162       static data and provide error codes through a global variable.
163       Thread-safe versions for name and address lookup are provided by
164       lwres_gethostbyname_r(), and lwres_gethostbyaddr_r() respectively.
165
166       The resolver daemon does not currently support any non-DNS name
167       services such as /etc/hosts or NIS, consequently the above functions
168       don't, either.
169

AUTHOR

171       Internet Systems Consortium, Inc.
172
174       Copyright © 2001, 2004, 2005, 2007, 2014-2016, 2018 Internet Systems
175       Consortium, Inc. ("ISC")
176
177
178
179ISC                               2007-06-18               LWRES_GETHOSTENT(3)
Impressum