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.4 (Berkeley) 05/25/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 NULL-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 NULL-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.El 76.Pp 77When using the nameserver, 78.Fn gethostbyname 79will search for the named host in the current domain and its parents 80unless the name ends in a dot. 81If the name contains no dot, and if the environment variable 82.Dq Ev HOSTALIASES 83contains the name of an alias file, the alias file will first be searched 84for an alias matching the input name. 85See 86.Xr hostname 7 87for the domain search procedure and the alias file format. 88.Pp 89The 90.Fn sethostent 91function 92may be used to request the use of a connected 93.Tn TCP 94socket for queries. 95If the 96.Fa stayopen 97flag is non-zero, 98this sets the option to send all queries to the name server using 99.Tn TCP 100and to retain the connection after each call to 101.Fn gethostbyname 102or 103.Fn gethostbyaddr . 104Otherwise, queries are performed using 105.Tn UDP 106datagrams. 107.Pp 108The 109.Fn endhostent 110function 111closes the 112.Tn TCP 113connection. 114.Sh FILES 115.Bl -tag -width /etc/hosts -compact 116.It Pa /etc/hosts 117.El 118.Sh DIAGNOSTICS 119Error return status from 120.Fn gethostbyname 121and 122.Fn gethostbyaddr 123is indicated by return of a null pointer. 124The external integer 125.Va h_errno 126may then be checked to see whether this is a temporary failure 127or an invalid or unknown host. 128The routine 129.Fn herror 130can be used to print an error message describing the failure. 131If its argument 132.Fa string 133is 134.Pf non Dv -NULL , 135it is printed, followed by a colon and a space. 136The error message is printed with a trailing newline. 137.Pp 138The variable 139.Va h_errno 140can have the following values: 141.Bl -tag -width HOST_NOT_FOUND 142.It Dv HOST_NOT_FOUND 143No such host is known. 144.It Dv TRY_AGAIN 145This is usually a temporary error 146and means that the local server did not receive 147a response from an authoritative server. 148A retry at some later time may succeed. 149.It Dv NO_RECOVERY 150Some unexpected server failure was encountered. 151This is a non-recoverable error. 152.It Dv NO_DATA 153The requested name is valid but does not have an IP address; 154this is not a temporary error. 155This means that the name is known to the name server but there is no address 156associated with this name. 157Another type of request to the name server using this domain name 158will result in an answer; 159for example, a mail-forwarder may be registered for this domain. 160.El 161.Sh SEE ALSO 162.Xr resolver 3 , 163.Xr hosts 5 , 164.Xr hostname 7 , 165.Xr named 8 166.Sh CAVEAT 167The 168.Fn gethostent 169function 170is defined, and 171.Fn sethostent 172and 173.Fn endhostent 174are redefined, 175when 176.Xr libc 3 177is built to use only the routines to lookup in 178.Pa /etc/hosts 179and not the name server. 180.Pp 181The 182.Fn gethostent 183function 184reads the next line of 185.Pa /etc/hosts , 186opening the file if necessary. 187.Pp 188The 189.Fn sethostent 190function 191opens and/or rewinds the file 192.Pa /etc/hosts . 193If the 194.Fa stayopen 195argument is non-zero, 196the file will not be closed after each call to 197.Fn gethostbyname 198or 199.Fn gethostbyaddr . 200.Pp 201The 202.Fn endhostent 203function 204closes the file. 205.Sh HISTORY 206The 207.Fn herror 208function appeared in 209.Bx 4.3 . 210The 211.Fn endhostent , 212.Fn gethostbyaddr , 213.Fn gethostbyname , 214.Fn gethostent , 215and 216.Fn sethostent 217functions appeared in 218.Bx 4.2 . 219.Sh BUGS 220These functions use static data storage; 221if the data is needed for future use, it should be 222copied before any subsequent calls overwrite it. 223Only the Internet 224address format is currently understood. 225