/contrib/bind9/lib/lwres/man/lwres_gethostent.3

  1.\" Copyright (C) 2004, 2005, 2007, 2012 Internet Systems Consortium, Inc. ("ISC")
  2.\" Copyright (C) 2001 Internet Software Consortium.
  3.\" 
  4.\" Permission to use, copy, modify, and/or distribute this software for any
  5.\" purpose with or without fee is hereby granted, provided that the above
  6.\" copyright notice and this permission notice appear in all copies.
  7.\" 
  8.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  9.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 10.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 11.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 12.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 13.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 14.\" PERFORMANCE OF THIS SOFTWARE.
 15.\"
 16.\" $Id$
 17.\"
 18.hy 0
 19.ad l
 20.\"     Title: lwres_gethostent
 21.\"    Author: 
 22.\" Generator: DocBook XSL Stylesheets v1.71.1 <http://docbook.sf.net/>
 23.\"      Date: Jun 30, 2000
 24.\"    Manual: BIND9
 25.\"    Source: BIND9
 26.\"
 27.TH "LWRES_GETHOSTENT" "3" "Jun 30, 2000" "BIND9" "BIND9"
 28.\" disable hyphenation
 29.nh
 30.\" disable justification (adjust text to left margin only)
 31.ad l
 32.SH "NAME"
 33lwres_gethostbyname, lwres_gethostbyname2, lwres_gethostbyaddr, lwres_gethostent, lwres_sethostent, lwres_endhostent, lwres_gethostbyname_r, lwres_gethostbyaddr_r, lwres_gethostent_r, lwres_sethostent_r, lwres_endhostent_r \- lightweight resolver get network host entry
 34.SH "SYNOPSIS"
 35.nf
 36#include <lwres/netdb.h>
 37.fi
 38.HP 37
 39.BI "struct hostent * lwres_gethostbyname(const\ char\ *" "name" ");"
 40.HP 38
 41.BI "struct hostent * lwres_gethostbyname2(const\ char\ *" "name" ", int\ " "af" ");"
 42.HP 37
 43.BI "struct hostent * lwres_gethostbyaddr(const\ char\ *" "addr" ", int\ " "len" ", int\ " "type" ");"
 44.HP 34
 45.BI "struct hostent * lwres_gethostent(void);"
 46.HP 22
 47.BI "void lwres_sethostent(int\ " "stayopen" ");"
 48.HP 22
 49.BI "void lwres_endhostent(void);"
 50.HP 39
 51.BI "struct hostent * lwres_gethostbyname_r(const\ char\ *" "name" ", struct\ hostent\ *" "resbuf" ", char\ *" "buf" ", int\ " "buflen" ", int\ *" "error" ");"
 52.HP 39
 53.BI "struct hostent * lwres_gethostbyaddr_r(const\ char\ *" "addr" ", int\ " "len" ", int\ " "type" ", struct\ hostent\ *" "resbuf" ", char\ *" "buf" ", int\ " "buflen" ", int\ *" "error" ");"
 54.HP 36
 55.BI "struct hostent * lwres_gethostent_r(struct\ hostent\ *" "resbuf" ", char\ *" "buf" ", int\ " "buflen" ", int\ *" "error" ");"
 56.HP 24
 57.BI "void lwres_sethostent_r(int\ " "stayopen" ");"
 58.HP 24
 59.BI "void lwres_endhostent_r(void);"
 60.SH "DESCRIPTION"
 61.PP
 62These functions provide hostname\-to\-address and address\-to\-hostname lookups by means of the lightweight resolver. They are similar to the standard
 63\fBgethostent\fR(3)
 64functions provided by most operating systems. They use a
 65\fBstruct hostent\fR
 66which is usually defined in
 67\fI<namedb.h>\fR.
 68.PP
 69.RS 4
 70.nf
 71struct  hostent {
 72        char    *h_name;        /* official name of host */
 73        char    **h_aliases;    /* alias list */
 74        int     h_addrtype;     /* host address type */
 75        int     h_length;       /* length of address */
 76        char    **h_addr_list;  /* list of addresses from name server */
 77};
 78#define h_addr  h_addr_list[0]  /* address, for backward compatibility */
 79.fi
 80.RE
 81.sp
 82.PP
 83The members of this structure are:
 84.PP
 85\fBh_name\fR
 86.RS 4
 87The official (canonical) name of the host.
 88.RE
 89.PP
 90\fBh_aliases\fR
 91.RS 4
 92A NULL\-terminated array of alternate names (nicknames) for the host.
 93.RE
 94.PP
 95\fBh_addrtype\fR
 96.RS 4
 97The type of address being returned \(em
 98\fBPF_INET\fR
 99or
100\fBPF_INET6\fR.
101.RE
102.PP
103\fBh_length\fR
104.RS 4
105The length of the address in bytes.
106.RE
107.PP
108\fBh_addr_list\fR
109.RS 4
110A
111\fBNULL\fR
112terminated array of network addresses for the host. Host addresses are returned in network byte order.
113.RE
114.PP
115For backward compatibility with very old software,
116\fBh_addr\fR
117is the first address in
118\fBh_addr_list.\fR
119.PP
120\fBlwres_gethostent()\fR,
121\fBlwres_sethostent()\fR,
122\fBlwres_endhostent()\fR,
123\fBlwres_gethostent_r()\fR,
124\fBlwres_sethostent_r()\fR
125and
126\fBlwres_endhostent_r()\fR
127provide iteration over the known host entries on systems that provide such functionality through facilities like
128\fI/etc/hosts\fR
129or NIS. The lightweight resolver does not currently implement these functions; it only provides them as stub functions that always return failure.
130.PP
131\fBlwres_gethostbyname()\fR
132and
133\fBlwres_gethostbyname2()\fR
134look up the hostname
135\fIname\fR.
136\fBlwres_gethostbyname()\fR
137always looks for an IPv4 address while
138\fBlwres_gethostbyname2()\fR
139looks for an address of protocol family
140\fIaf\fR: either
141\fBPF_INET\fR
142or
143\fBPF_INET6\fR
144\(em IPv4 or IPV6 addresses respectively. Successful calls of the functions return a
145\fBstruct hostent\fRfor the name that was looked up.
146\fBNULL\fR
147is returned if the lookups by
148\fBlwres_gethostbyname()\fR
149or
150\fBlwres_gethostbyname2()\fR
151fail.
152.PP
153Reverse lookups of addresses are performed by
154\fBlwres_gethostbyaddr()\fR.
155\fIaddr\fR
156is an address of length
157\fIlen\fR
158bytes and protocol family
159\fItype\fR
160\(em
161\fBPF_INET\fR
162or
163\fBPF_INET6\fR.
164\fBlwres_gethostbyname_r()\fR
165is a thread\-safe function for forward lookups. If an error occurs, an error code is returned in
166\fI*error\fR.
167\fIresbuf\fR
168is a pointer to a
169\fBstruct hostent\fR
170which is initialised by a successful call to
171\fBlwres_gethostbyname_r()\fR.
172\fIbuf\fR
173is a buffer of length
174\fIlen\fR
175bytes which is used to store the
176\fBh_name\fR,
177\fBh_aliases\fR, and
178\fBh_addr_list\fR
179elements of the
180\fBstruct hostent\fR
181returned in
182\fIresbuf\fR. Successful calls to
183\fBlwres_gethostbyname_r()\fR
184return
185\fIresbuf\fR, which is a pointer to the
186\fBstruct hostent\fR
187it created.
188.PP
189\fBlwres_gethostbyaddr_r()\fR
190is a thread\-safe function that performs a reverse lookup of address
191\fIaddr\fR
192which is
193\fIlen\fR
194bytes long and is of protocol family
195\fItype\fR
196\(em
197\fBPF_INET\fR
198or
199\fBPF_INET6\fR. If an error occurs, the error code is returned in
200\fI*error\fR. The other function parameters are identical to those in
201\fBlwres_gethostbyname_r()\fR.
202\fIresbuf\fR
203is a pointer to a
204\fBstruct hostent\fR
205which is initialised by a successful call to
206\fBlwres_gethostbyaddr_r()\fR.
207\fIbuf\fR
208is a buffer of length
209\fIlen\fR
210bytes which is used to store the
211\fBh_name\fR,
212\fBh_aliases\fR, and
213\fBh_addr_list\fR
214elements of the
215\fBstruct hostent\fR
216returned in
217\fIresbuf\fR. Successful calls to
218\fBlwres_gethostbyaddr_r()\fR
219return
220\fIresbuf\fR, which is a pointer to the
221\fBstruct hostent()\fR
222it created.
223.SH "RETURN VALUES"
224.PP
225The functions
226\fBlwres_gethostbyname()\fR,
227\fBlwres_gethostbyname2()\fR,
228\fBlwres_gethostbyaddr()\fR, and
229\fBlwres_gethostent()\fR
230return NULL to indicate an error. In this case the global variable
231\fBlwres_h_errno\fR
232will contain one of the following error codes defined in
233\fI<lwres/netdb.h>\fR:
234.PP
235\fBHOST_NOT_FOUND\fR
236.RS 4
237The host or address was not found.
238.RE
239.PP
240\fBTRY_AGAIN\fR
241.RS 4
242A recoverable error occurred, e.g., a timeout. Retrying the lookup may succeed.
243.RE
244.PP
245\fBNO_RECOVERY\fR
246.RS 4
247A non\-recoverable error occurred.
248.RE
249.PP
250\fBNO_DATA\fR
251.RS 4
252The name exists, but has no address information associated with it (or vice versa in the case of a reverse lookup). The code NO_ADDRESS is accepted as a synonym for NO_DATA for backwards compatibility.
253.RE
254.PP
255\fBlwres_hstrerror\fR(3)
256translates these error codes to suitable error messages.
257.PP
258\fBlwres_gethostent()\fR
259and
260\fBlwres_gethostent_r()\fR
261always return
262\fBNULL\fR.
263.PP
264Successful calls to
265\fBlwres_gethostbyname_r()\fR
266and
267\fBlwres_gethostbyaddr_r()\fR
268return
269\fIresbuf\fR, a pointer to the
270\fBstruct hostent\fR
271that was initialised by these functions. They return
272\fBNULL\fR
273if the lookups fail or if
274\fIbuf\fR
275was too small to hold the list of addresses and names referenced by the
276\fBh_name\fR,
277\fBh_aliases\fR, and
278\fBh_addr_list\fR
279elements of the
280\fBstruct hostent\fR. If
281\fIbuf\fR
282was too small, both
283\fBlwres_gethostbyname_r()\fR
284and
285\fBlwres_gethostbyaddr_r()\fR
286set the global variable
287\fBerrno\fR
288to
289\fBERANGE\fR.
290.SH "SEE ALSO"
291.PP
292\fBgethostent\fR(3),
293\fBlwres_getipnode\fR(3),
294\fBlwres_hstrerror\fR(3)
295.SH "BUGS"
296.PP
297\fBlwres_gethostbyname()\fR,
298\fBlwres_gethostbyname2()\fR,
299\fBlwres_gethostbyaddr()\fR
300and
301\fBlwres_endhostent()\fR
302are not thread safe; they return pointers to static data and provide error codes through a global variable. Thread\-safe versions for name and address lookup are provided by
303\fBlwres_gethostbyname_r()\fR, and
304\fBlwres_gethostbyaddr_r()\fR
305respectively.
306.PP
307The resolver daemon does not currently support any non\-DNS name services such as
308\fI/etc/hosts\fR
309or
310\fBNIS\fR, consequently the above functions don't, either.
311.SH "COPYRIGHT"
312Copyright \(co 2004, 2005, 2007, 2012 Internet Systems Consortium, Inc. ("ISC")
313.br
314Copyright \(co 2001 Internet Software Consortium.
315.br