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