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.\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 33.\" $Id: gethostbyname.3,v 1.9 1998/03/23 13:05:07 bde Exp $ 34.\" 35.Dd May 25, 1995 36.Dt GETHOSTBYNAME 3 37.Os BSD 4.2 38.Sh NAME 39.Nm gethostbyname , 40.Nm gethostbyname2 , 41.Nm gethostbyaddr , 42.Nm gethostent , 43.Nm sethostent , 44.Nm endhostent , 45.Nm herror , 46.Nm hstrerror 47.Nd get network host entry 48.Sh SYNOPSIS 49.Fd #include <netdb.h> 50.Vt extern int h_errno; 51.Ft struct hostent * 52.Fn gethostbyname "const char *name" 53.Ft struct hostent * 54.Fn gethostbyname2 "const char *name" "int af" 55.Ft struct hostent * 56.Fn gethostbyaddr "const char *addr" "int len" "int type" 57.Ft struct hostent * 58.Fn gethostent void 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 , 79or broken-out fields from a line in 80.Pa /etc/hosts . 81If the local name server is not running these routines do a lookup in 82.Pa /etc/hosts . 83.Bd -literal 84struct hostent { 85 char *h_name; /* official name of host */ 86 char **h_aliases; /* alias list */ 87 int h_addrtype; /* host address type */ 88 int h_length; /* length of address */ 89 char **h_addr_list; /* list of addresses from name server */ 90}; 91#define h_addr h_addr_list[0] /* address, for backward compatibility */ 92.Ed 93.Pp 94The members of this structure are: 95.Bl -tag -width h_addr_list 96.It Fa h_name 97Official name of the host. 98.It Fa h_aliases 99A NULL-terminated array of alternate names for the host. 100.It Fa h_addrtype 101The type of address being returned; usually 102.Dv AF_INET . 103.It Fa h_length 104The length, in bytes, of the address. 105.It Fa h_addr_list 106A NULL-terminated array of network addresses for the host. 107Host addresses are returned in network byte order. 108.It Fa h_addr 109The first address in 110.Fa h_addr_list ; 111this is for backward compatibility. 112.El 113.Pp 114When using the nameserver, 115.Fn gethostbyname 116and 117.Fn gethostbyname 118will search for the named host in the current domain and its parents 119unless the name ends in a dot. 120If the name contains no dot, and if the environment variable 121.Dq Ev HOSTALIASES 122contains the name of an alias file, the alias file will first be searched 123for an alias matching the input name. 124See 125.Xr hostname 7 126for the domain search procedure and the alias file format. 127.Pp 128The 129.Fn gethostbyname2 130function is an evolution of 131.Fn gethostbyname 132which is intended to allow lookups in address families other than 133.Dv AF_INET , 134for example 135.Dv AF_INET6 . 136Currently the 137.Fa af 138argument must be specified as 139.Dv AF_INET 140else the function will return 141.Dv NULL 142after having set 143.Va h_errno 144to 145.Dv NETDB_INTERNAL 146.Pp 147The 148.Fn sethostent 149function 150may be used to request the use of a connected 151.Tn TCP 152socket for queries. 153If the 154.Fa stayopen 155flag is non-zero, 156this sets the option to send all queries to the name server using 157.Tn TCP 158and to retain the connection after each call to 159.Fn gethostbyname , 160.Fn gethostbyname2 161or 162.Fn gethostbyaddr . 163Otherwise, queries are performed using 164.Tn UDP 165datagrams. 166.Pp 167The 168.Fn endhostent 169function 170closes the 171.Tn TCP 172connection. 173.Pp 174The 175.Fn herror 176function writes a message to the diagnostic output consisting of the 177string parameter 178.Fa s , 179the constant string ": ", and a message corresponding to the value of 180.Va h_errno . 181.Pp 182The 183.Fn hstrerror 184function returns a string which is the message text corresponding to the 185value of the 186.Fa err 187parameter. 188.Sh FILES 189.Bl -tag -width /etc/resolv.conf -compact 190.It Pa /etc/hosts 191.It Pa /etc/host.conf 192.It Pa /etc/resolv.conf 193.El 194.Sh DIAGNOSTICS 195Error return status from 196.Fn gethostbyname , 197.Fn gethostbyname2 198and 199.Fn gethostbyaddr 200is indicated by return of a null pointer. 201The external integer 202.Va h_errno 203may then be checked to see whether this is a temporary failure 204or an invalid or unknown host. 205The routine 206.Fn herror 207can be used to print an error message describing the failure. 208If its argument 209.Fa string 210is 211.Pf non Dv -NULL , 212it is printed, followed by a colon and a space. 213The error message is printed with a trailing newline. 214.Pp 215The variable 216.Va h_errno 217can have the following values: 218.Bl -tag -width HOST_NOT_FOUND 219.It Dv HOST_NOT_FOUND 220No such host is known. 221.It Dv TRY_AGAIN 222This is usually a temporary error 223and means that the local server did not receive 224a response from an authoritative server. 225A retry at some later time may succeed. 226.It Dv NO_RECOVERY 227Some unexpected server failure was encountered. 228This is a non-recoverable error. 229.It Dv NO_DATA 230The requested name is valid but does not have an IP address; 231this is not a temporary error. 232This means that the name is known to the name server but there is no address 233associated with this name. 234Another type of request to the name server using this domain name 235will result in an answer; 236for example, a mail-forwarder may be registered for this domain. 237.El 238.Sh SEE ALSO 239.Xr resolver 3 , 240.Xr hosts 5 , 241.Xr hostname 7 , 242.Xr named 8 243.Sh CAVEAT 244The 245.Fn gethostent 246function 247is defined, and 248.Fn sethostent 249and 250.Fn endhostent 251are redefined, 252when 253.Xr libc 3 254is built to use only the routines to lookup in 255.Pa /etc/hosts 256and not the name server. 257.Pp 258The 259.Fn gethostent 260function 261reads the next line of 262.Pa /etc/hosts , 263opening the file if necessary. 264.Pp 265The 266.Fn sethostent 267function 268opens and/or rewinds the file 269.Pa /etc/hosts . 270If the 271.Fa stayopen 272argument is non-zero, 273the file will not be closed after each call to 274.Fn gethostbyname , 275.Fn gethostbyname2 276or 277.Fn gethostbyaddr . 278.Pp 279The 280.Fn endhostent 281function 282closes the file. 283.Sh HISTORY 284The 285.Fn herror 286function appeared in 287.Bx 4.3 . 288The 289.Fn endhostent , 290.Fn gethostbyaddr , 291.Fn gethostbyname , 292.Fn gethostent , 293and 294.Fn sethostent 295functions appeared in 296.Bx 4.2 . 297The 298.Fn gethostbyname2 299function first appeared in bind-4.9.4. 300.Sh BUGS 301These functions use static data storage; 302if the data is needed for future use, it should be 303copied before any subsequent calls overwrite it. 304Only the Internet 305address format is currently understood. 306