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