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