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