1.\" Copyright (c) 1983, 1987, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)gethostbyname.3 8.3 (Berkeley) 02/27/95 7.\" 8.Dd 9.Dt GETHOSTBYNAME 3 10.Os BSD 4.2 11.Sh NAME 12.Nm gethostbyname , 13.Nm gethostbyaddr , 14.Nm gethostent , 15.Nm sethostent , 16.Nm endhostent , 17.Nm herror 18.Nd get network host entry 19.Sh SYNOPSIS 20.Fd #include <netdb.h> 21.Fd extern int h_errno; 22.Ft struct hostent * 23.Fn gethostbyname "char *name" 24.Ft struct hostent * 25.Fn gethostbyaddr "char *addr" "int len" "int type" 26.Ft struct hostent * 27.Fn gethostent void 28.Fn sethostent "int stayopen" 29.Fn endhostent void 30.Fn herror "char *string" 31.Sh DESCRIPTION 32The 33.Fn gethostbyname 34and 35.Fn gethostbyaddr 36functions 37each return a pointer to an object with the 38following structure describing an internet host 39referenced by name or by address, respectively. 40This structure contains either the information obtained from the name server, 41.Xr named 8 , 42or broken-out fields from a line in 43.Pa /etc/hosts . 44If the local name server is not running these routines do a lookup in 45.Pa /etc/hosts . 46.Bd -literal 47struct hostent { 48 char *h_name; /* official name of host */ 49 char **h_aliases; /* alias list */ 50 int h_addrtype; /* host address type */ 51 int h_length; /* length of address */ 52 char **h_addr_list; /* list of addresses from name server */ 53}; 54#define h_addr h_addr_list[0] /* address, for backward compatibility */ 55.Ed 56.Pp 57The members of this structure are: 58.Bl -tag -width h_addr_list 59.It Fa h_name 60Official name of the host. 61.It Fa h_aliases 62A zero terminated array of alternate names for the host. 63.It Fa h_addrtype 64The type of address being returned; currently always 65.Dv AF_INET . 66.It Fa h_length 67The length, in bytes, of the address. 68.It Fa h_addr_list 69A zero terminated array of network addresses for the host. 70Host addresses are returned in network byte order. 71.It Fa h_addr 72The first address in 73.Fa h_addr_list ; 74this is for backward compatibility. 75.Pp 76When using the nameserver, 77.Fn gethostbyname 78will search for the named host in the current domain and its parents 79unless the name ends in a dot. 80If the name contains no dot, and if the environment variable 81.Dq Ev HOSTALIASES 82contains the name of an alias file, the alias file will first be searched 83for an alias matching the input name. 84See 85.Xr hostname 7 86for the domain search procedure and the alias file format. 87.Pp 88The 89.Fn sethostent 90function 91may be used to request the use of a connected 92.Tn TCP 93socket for queries. 94If the 95.Fa stayopen 96flag is non-zero, 97this sets the option to send all queries to the name server using 98.Tn TCP 99and to retain the connection after each call to 100.Fn gethostbyname 101or 102.Fn gethostbyaddr . 103Otherwise, queries are performed using 104.Tn UDP 105datagrams. 106.Pp 107The 108.Fn endhostent 109function 110closes the 111.Tn TCP 112connection. 113.Sh FILES 114.Bl -tag -width /etc/hosts -compact 115.It Pa /etc/hosts 116.El 117.Sh DIAGNOSTICS 118Error return status from 119.Fn gethostbyname 120and 121.Fn gethostbyaddr 122is indicated by return of a null pointer. 123The external integer 124.Va h_errno 125may then be checked to see whether this is a temporary failure 126or an invalid or unknown host. 127The routine 128.Fn herror 129can be used to print an error message describing the failure. 130If its argument 131.Fa string 132is 133.Pf non Dv -NULL , 134it is printed, followed by a colon and a space. 135The error message is printed with a trailing newline. 136.Pp 137The variable 138.Va h_errno 139can have the following values: 140.Bl -tag -width HOST_NOT_FOUND 141.It Dv HOST_NOT_FOUND 142No such host is known. 143.It Dv TRY_AGAIN 144This is usually a temporary error 145and means that the local server did not receive 146a response from an authoritative server. 147A retry at some later time may succeed. 148.It Dv NO_RECOVERY 149Some unexpected server failure was encountered. 150This is a non-recoverable error. 151.It Dv NO_DATA 152The requested name is valid but does not have an IP address; 153this is not a temporary error. 154This means that the name is known to the name server but there is no address 155associated with this name. 156Another type of request to the name server using this domain name 157will result in an answer; 158for example, a mail-forwarder may be registered for this domain. 159.El 160.Sh SEE ALSO 161.Xr resolver 3 , 162.Xr hosts 5 , 163.Xr hostname 7 , 164.Xr named 8 165.Sh CAVEAT 166The 167.Fn gethostent 168function 169is defined, and 170.Fn sethostent 171and 172.Fn endhostent 173are redefined, 174when 175.Xr libc 3 176is built to use only the routines to lookup in 177.Pa /etc/hosts 178and not the name server. 179.Pp 180The 181.Fn gethostent 182function 183reads the next line of 184.Pa /etc/hosts , 185opening the file if necessary. 186.Pp 187The 188.Fn sethostent 189function 190opens and/or rewinds the file 191.Pa /etc/hosts . 192If the 193.Fa stayopen 194argument is non-zero, 195the file will not be closed after each call to 196.Fn gethostbyname 197or 198.Fn gethostbyaddr . 199.Pp 200The 201.Fn endhostent 202function 203closes the file. 204.Sh HISTORY 205The 206.Fn herror 207function appeared in 208.Bx 4.3 . 209The 210.Fn endhostent , 211.Fn gethostbyaddr , 212.Fn gethostbyname , 213.Fn gethostent , 214and 215.Fn sethostent 216functions appeared in 217.Bx 4.2 . 218.Sh BUGS 219These functions use static data storage; 220if the data is needed for future use, it should be 221copied before any subsequent calls overwrite it. 222Only the Internet 223address format is currently understood. 224