contrib/bind-9.2.4rc7/lib/lwres/man/lwres_gethostent.3

   1 .\" Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   2 .\" Copyright (C) 2001  Internet Software Consortium.
   3 .\"
   4 .\" Permission to use, copy, modify, and 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: lwres_gethostent.3,v 1.16.2.2 2004/03/15 04:45:02 marka Exp $
  17 .\"
  18 .TH "LWRES_GETHOSTENT" "3" "Jun 30, 2000" "BIND9" ""
  19 .SH NAME
  20 lwres_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
  21 .SH SYNOPSIS
  22 \fB#include <lwres/netdb.h>
  23 .sp
  24 .na
  25 struct hostent *
  26 lwres_gethostbyname(const char *name);
  27 .ad
  28 .sp
  29 .na
  30 struct hostent *
  31 lwres_gethostbyname2(const char *name, int af);
  32 .ad
  33 .sp
  34 .na
  35 struct hostent *
  36 lwres_gethostbyaddr(const char *addr, int len, int type);
  37 .ad
  38 .sp
  39 .na
  40 struct hostent *
  41 lwres_gethostent(void);
  42 .ad
  43 .sp
  44 .na
  45 void
  46 lwres_sethostent(int stayopen);
  47 .ad
  48 .sp
  49 .na
  50 void
  51 lwres_endhostent(void);
  52 .ad
  53 .sp
  54 .na
  55 struct hostent *
  56 lwres_gethostbyname_r(const char *name, struct hostent *resbuf, char *buf, int buflen, int *error);
  57 .ad
  58 .sp
  59 .na
  60 struct hostent *
  61 lwres_gethostbyaddr_r(const char *addr, int len, int type, struct hostent *resbuf, char *buf, int buflen, int *error);
  62 .ad
  63 .sp
  64 .na
  65 struct hostent *
  66 lwres_gethostent_r(struct hostent *resbuf, char *buf, int buflen, int *error);
  67 .ad
  68 .sp
  69 .na
  70 void
  71 lwres_sethostent_r(int stayopen);
  72 .ad
  73 .sp
  74 .na
  75 void
  76 lwres_endhostent_r(void);
  77 .ad
  78 \fR
  79 .SH "DESCRIPTION"
  80 .PP
  81 These functions provide hostname-to-address and
  82 address-to-hostname lookups by means of the lightweight resolver.
  83 They are similar to the standard
  84 \fBgethostent\fR(3)
  85 functions provided by most operating systems.
  86 They use a
  87 \fBstruct hostent\fR
  88 which is usually defined in
  89 \fI<namedb.h>\fR.
  90 .sp
  91 .nf
  92 struct  hostent {
  93         char    *h_name;        /* official name of host */
  94         char    **h_aliases;    /* alias list */
  95         int     h_addrtype;     /* host address type */
  96         int     h_length;       /* length of address */
  97         char    **h_addr_list;  /* list of addresses from name server */
  98 };
  99 #define h_addr  h_addr_list[0]  /* address, for backward compatibility */
 100 .sp
 101 .fi
 102 .PP
 103 The members of this structure are:
 104 .TP
 105 \fBh_name\fR
 106 The official (canonical) name of the host.
 107 .TP
 108 \fBh_aliases\fR
 109 A NULL-terminated array of alternate names (nicknames) for the host.
 110 .TP
 111 \fBh_addrtype\fR
 112 The type of address being returned \(em
 113 \fBPF_INET\fR
 114 or
 115 \fBPF_INET6\fR.
 116 .TP
 117 \fBh_length\fR
 118 The length of the address in bytes.
 119 .TP
 120 \fBh_addr_list\fR
 121 A \fBNULL\fR
 122 terminated array of network addresses for the host.
 123 Host addresses are returned in network byte order.
 124 .PP
 125 For backward compatibility with very old software,
 126 h_addr
 127 is the first address in
 128 h_addr_list.
 129 .PP
 130 \fBlwres_gethostent()\fR,
 131 \fBlwres_sethostent()\fR,
 132 \fBlwres_endhostent()\fR,
 133 \fBlwres_gethostent_r()\fR,
 134 \fBlwres_sethostent_r()\fR
 135 and
 136 \fBlwres_endhostent_r()\fR
 137 provide iteration over the known host entries on systems that
 138 provide such functionality through facilities like
 139 \fI/etc/hosts\fR
 140 or NIS. The lightweight resolver does not currently implement
 141 these functions; it only provides them as stub functions that always
 142 return failure.
 143 .PP
 144 \fBlwres_gethostbyname()\fR and
 145 \fBlwres_gethostbyname2()\fR look up the hostname
 146 \fIname\fR.
 147 \fBlwres_gethostbyname()\fR always looks for an IPv4
 148 address while \fBlwres_gethostbyname2()\fR looks for an
 149 address of protocol family \fIaf\fR: either
 150 \fBPF_INET\fR or \fBPF_INET6\fR \(em IPv4 or IPV6
 151 addresses respectively. Successful calls of the functions return a
 152 \fBstruct hostent\fRfor the name that was looked up.
 153 \fBNULL\fR is returned if the lookups by
 154 \fBlwres_gethostbyname()\fR or
 155 \fBlwres_gethostbyname2()\fR fail.
 156 .PP
 157 Reverse lookups of addresses are performed by
 158 \fBlwres_gethostbyaddr()\fR.
 159 \fIaddr\fR is an address of length
 160 \fIlen\fR bytes and protocol family
 161 \fItype\fR \(em \fBPF_INET\fR or
 162 \fBPF_INET6\fR.
 163 \fBlwres_gethostbyname_r()\fR is a thread-safe function
 164 for forward lookups. If an error occurs, an error code is returned in
 165 \fI*error\fR.
 166 \fIresbuf\fR is a pointer to a \fBstruct
 167 hostent\fR which is initialised by a successful call to
 168 \fBlwres_gethostbyname_r()\fR .
 169 \fIbuf\fR is a buffer of length
 170 \fIlen\fR bytes which is used to store the
 171 h_name, h_aliases, and
 172 h_addr_list elements of the \fBstruct
 173 hostent\fR returned in \fIresbuf\fR.
 174 Successful calls to \fBlwres_gethostbyname_r()\fR
 175 return \fIresbuf\fR,
 176 which is a pointer to the \fBstruct hostent\fR it created.
 177 .PP
 178 \fBlwres_gethostbyaddr_r()\fR is a thread-safe function
 179 that performs a reverse lookup of address \fIaddr\fR
 180 which is \fIlen\fR bytes long and is of protocol
 181 family \fItype\fR \(em \fBPF_INET\fR or
 182 \fBPF_INET6\fR. If an error occurs, the error code is returned
 183 in \fI*error\fR. The other function parameters are
 184 identical to those in \fBlwres_gethostbyname_r()\fR.
 185 \fIresbuf\fR is a pointer to a \fBstruct
 186 hostent\fR which is initialised by a successful call to
 187 \fBlwres_gethostbyaddr_r()\fR.
 188 \fIbuf\fR is a buffer of length
 189 \fIlen\fR bytes which is used to store the
 190 h_name, h_aliases, and
 191 h_addr_list elements of the \fBstruct
 192 hostent\fR returned in \fIresbuf\fR. Successful
 193 calls to \fBlwres_gethostbyaddr_r()\fR return
 194 \fIresbuf\fR, which is a pointer to the
 195 \fBstruct hostent()\fR it created.
 196 .SH "RETURN VALUES"
 197 .PP
 198 The functions
 199 \fBlwres_gethostbyname()\fR,
 200 \fBlwres_gethostbyname2()\fR,
 201 \fBlwres_gethostbyaddr()\fR,
 202 and
 203 \fBlwres_gethostent()\fR
 204 return NULL to indicate an error. In this case the global variable
 205 \fBlwres_h_errno\fR
 206 will contain one of the following error codes defined in
 207 \fI<lwres/netdb.h>\fR:
 208 .TP
 209 \fBHOST_NOT_FOUND\fR
 210 The host or address was not found.
 211 .TP
 212 \fBTRY_AGAIN\fR
 213 A recoverable error occurred, e.g., a timeout.
 214 Retrying the lookup may succeed.
 215 .TP
 216 \fBNO_RECOVERY\fR
 217 A non-recoverable error occurred.
 218 .TP
 219 \fBNO_DATA\fR
 220 The name exists, but has no address information
 221 associated with it (or vice versa in the case
 222 of a reverse lookup). The code NO_ADDRESS
 223 is accepted as a synonym for NO_DATA for backwards
 224 compatibility.
 225 .PP
 226 \fBlwres_hstrerror\fR(3)
 227 translates these error codes to suitable error messages.
 228 .PP
 229 \fBlwres_gethostent()\fR
 230 and
 231 \fBlwres_gethostent_r()\fR
 232 always return
 233 \fBNULL\fR.
 234 .PP
 235 Successful calls to \fBlwres_gethostbyname_r()\fR and
 236 \fBlwres_gethostbyaddr_r()\fR return
 237 \fIresbuf\fR, a pointer to the \fBstruct
 238 hostent\fR that was initialised by these functions. They return
 239 \fBNULL\fR if the lookups fail or if \fIbuf\fR
 240 was too small to hold the list of addresses and names referenced by
 241 the h_name, h_aliases, and
 242 h_addr_list elements of the \fBstruct
 243 hostent\fR. If \fIbuf\fR was too small, both
 244 \fBlwres_gethostbyname_r()\fR and
 245 \fBlwres_gethostbyaddr_r()\fR set the global variable
 246 \fBerrno\fR to ERANGE.
 247 .SH "SEE ALSO"
 248 .PP
 249 \fBgethostent\fR(3),
 250 \fBlwres_getipnode\fR(3),
 251 \fBlwres_hstrerror\fR(3)
 252 .SH "BUGS"
 253 .PP
 254 \fBlwres_gethostbyname()\fR,
 255 \fBlwres_gethostbyname2()\fR,
 256 \fBlwres_gethostbyaddr()\fR
 257 and
 258 \fBlwres_endhostent()\fR
 259 are not thread safe; they return pointers to static data and
 260 provide error codes through a global variable.
 261 Thread-safe versions for name and address lookup are provided by
 262 \fBlwres_gethostbyname_r()\fR,
 263 and
 264 \fBlwres_gethostbyaddr_r()\fR
 265 respectively.
 266 .PP
 267 The resolver daemon does not currently support any non-DNS
 268 name services such as
 269 \fI/etc/hosts\fR
 270 or
 271 \fBNIS\fR,
 272 consequently the above functions don't, either.