1.\" $NetBSD: gethostbyname.3,v 1.27 2004/08/17 13:45:14 wiz Exp $ 2.\" 3.\" Copyright (c) 1983, 1987, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 31.\" 32.Dd August 17, 2004 33.Dt GETHOSTBYNAME 3 34.Os 35.Sh NAME 36.Nm gethostbyname , 37.Nm gethostbyname2 , 38.Nm gethostbyaddr , 39.Nm gethostent , 40.Nm sethostent , 41.Nm endhostent , 42.Nm herror , 43.Nm hstrerror 44.Nd get network host entry 45.Sh LIBRARY 46.Lb libc 47.Sh SYNOPSIS 48.In netdb.h 49.Fd extern int h_errno; 50.Ft struct hostent * 51.Fn gethostbyname "const char *name" 52.Ft struct hostent * 53.Fn gethostbyname2 "const char *name" "int af" 54.Ft struct hostent * 55.Fn gethostbyaddr "const char *addr" "socklen_t len" "int type" 56.Ft struct hostent * 57.Fn gethostent void 58.Ft void 59.Fn sethostent "int stayopen" 60.Ft void 61.Fn endhostent void 62.Ft void 63.Fn herror "const char *string" 64.Ft const char * 65.Fn hstrerror "int err" 66.Sh DESCRIPTION 67The 68.Fn gethostbyname , 69.Fn gethostbyname2 70and 71.Fn gethostbyaddr 72functions 73each return a pointer to an object with the 74following structure describing an internet host 75referenced by name or by address, respectively. 76This structure contains either the information obtained from the name server, 77.Xr named 8 , 78broken-out fields from a line in 79.Pa /etc/hosts , 80or database entries supplied by the 81.Xr yp 8 82system. 83The order of the lookups is controlled by the 84.Sq hosts 85entry in 86.Xr nsswitch.conf 5 . 87.Bd -literal 88struct hostent { 89 char *h_name; /* official name of host */ 90 char **h_aliases; /* alias list */ 91 int h_addrtype; /* host address type */ 92 int h_length; /* length of address */ 93 char **h_addr_list; /* list of addresses from name server */ 94}; 95#define h_addr h_addr_list[0] /* address, for backward compatibility */ 96.Ed 97.Pp 98The members of this structure are: 99.Bl -tag -width h_addr_list 100.It Fa h_name 101Official name of the host. 102.It Fa h_aliases 103A NULL-terminated array of alternative names for the host. 104.It Fa h_addrtype 105The type of address being returned; currently always 106.Dv AF_INET . 107.It Fa h_length 108The length, in bytes, of the address. 109.It Fa h_addr_list 110A NULL-terminated array of network addresses for the host. 111Host addresses are returned in network byte order. 112.It Fa h_addr 113The first address in 114.Fa h_addr_list ; 115this is for backward compatibility. 116.El 117.Pp 118When using the nameserver, 119.Fn gethostbyname 120and 121.Fn gethostbyname2 122will search for the named host in the current domain and its parents 123unless the name ends in a dot. 124If the name contains no dot, and if the environment variable 125.Dq Ev HOSTALIASES 126contains the name of an alias file, the alias file will first be searched 127for an alias matching the input name. 128See 129.Xr hostname 7 130for the domain search procedure and the alias file format. 131.Pp 132The 133.Fn gethostbyname2 134function is an evolution of 135.Fn gethostbyname 136which is intended to allow lookups in address families other than 137.Dv AF_INET , 138for example 139.Dv AF_INET6 . 140Currently the 141.Fa af 142argument must be specified as 143.Dv AF_INET 144or 145.Dv AF_INET6 , 146else the function will return 147.Dv NULL 148after having set 149.Va h_errno 150to 151.Dv NETDB_INTERNAL . 152.Pp 153The 154.Fn gethostent 155function 156reads the next line of the 157.Pa /etc/hosts 158file, opening the file if necessary. 159.Pp 160The 161.Fn sethostent 162function 163may be used to request the use of a connected 164.Tn TCP 165socket for queries. 166If the 167.Fa stayopen 168flag is non-zero, 169this sets the option to send all queries to the name server using 170.Tn TCP 171and to retain the connection after each call to 172.Fn gethostbyname , 173.Fn gethostbyname2 , 174or 175.Fn gethostbyaddr . 176Otherwise, queries are performed using 177.Tn UDP 178datagrams. 179.Pp 180The 181.Fn endhostent 182function 183closes the 184.Tn TCP 185connection. 186.Pp 187The 188.Fn herror 189function writes a message to the diagnostic output consisting of the 190string parameter 191.Fa s , 192the constant string ": ", and a message corresponding to the value of 193.Va h_errno . 194.Pp 195The 196.Fn hstrerror 197function returns a string which is the message text corresponding to the 198value of the 199.Fa err 200parameter. 201.Sh FILES 202.Bl -tag -width /etc/hosts -compact 203.It Pa /etc/hosts 204.El 205.Sh DIAGNOSTICS 206Error return status from 207.Fn gethostbyent , 208.Fn gethostbyname , 209.Fn gethostbyname2 , 210and 211.Fn gethostbyaddr 212is indicated by return of a null pointer. 213The external integer 214.Va h_errno 215may then be checked to see whether this is a temporary failure 216or an invalid or unknown host. 217The routine 218.Fn herror 219can be used to print an error message describing the failure. 220If its argument 221.Fa string 222is 223.Pf non Dv -NULL , 224it is printed, followed by a colon and a space. 225The error message is printed with a trailing newline. 226.Pp 227The variable 228.Va h_errno 229can have the following values: 230.Bl -tag -width HOST_NOT_FOUND 231.It Dv HOST_NOT_FOUND 232No such host is known. 233.It Dv TRY_AGAIN 234This is usually a temporary error 235and means that the local server did not receive 236a response from an authoritative server. 237A retry at some later time may succeed. 238.It Dv NO_RECOVERY 239Some unexpected server failure was encountered. 240This is a non-recoverable error. 241.It Dv NO_DATA 242The requested name is valid but does not have an IP address; 243this is not a temporary error. 244This means that the name is known to the name server but there is no address 245associated with this name. 246Another type of request to the name server using this domain name 247will result in an answer; 248for example, a mail-forwarder may be registered for this domain. 249.El 250.Sh SEE ALSO 251.Xr resolver 3 , 252.Xr hosts 5 , 253.Xr nsswitch.conf 5 , 254.Xr hostname 7 , 255.Xr named 8 256.Sh HISTORY 257The 258.Fn herror 259function appeared in 260.Bx 4.3 . 261The 262.Fn endhostent , 263.Fn gethostbyaddr , 264.Fn gethostbyname , 265.Fn gethostent , 266and 267.Fn sethostent 268functions appeared in 269.Bx 4.2 . 270The 271.Fn gethostbyname2 272function first appeared in bind-4.9.4. 273IPv6 support was implemented in WIDE Hydrangea IPv6 protocol stack kit. 274.Sh CAVEATS 275If the search routines specified in 276.Xr nsswitch.conf 5 277decide to read the 278.Pa /etc/hosts 279file, 280.Fn gethostbyname , 281.Fn gethostbyname2 , 282and 283.Fn gethostbyaddr 284will 285read the next line of the file, 286re-opening the file if necessary. 287.Pp 288The 289.Fn sethostent 290function 291opens and/or rewinds the file 292.Pa /etc/hosts . 293If the 294.Fa stayopen 295argument is non-zero, 296the file will not be closed after each call to 297.Fn gethostbyname , 298.Fn gethostbyname2 , 299.Fn gethostbyaddr , 300or 301.Fn gethostent . 302.Pp 303The 304.Fn endhostent 305function closes the file. 306.Sh BUGS 307These functions use static data storage; 308if the data is needed for future use, it should be 309copied before any subsequent calls overwrite it. 310Only the Internet 311address format is currently understood. 312.Pp 313The 314.Fn gethostent 315does not currently follow the search order specified in 316.Xr nsswitch.conf 5 317and only reads the 318.Pa /etc/hosts 319file. 320