/contrib/bind9/lib/lwres/man/lwres_gethostent.3
Unknown | 315 lines | 315 code | 0 blank | 0 comment | 0 complexity | e97d2b592b94b8d37f40bf85021c9189 MD5 | raw file
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