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. 79.Pp 80The 81.Fa name 82parameter passed to 83.Fn gethostbyname 84or 85.Fn gethostbyname2 86should point to a 87.Dv NUL Ns -terminated 88hostname. 89The 90.Fa addr 91parameter passed to 92.Fn gethostbyaddr 93should point to an address which is 94.Fa len 95bytes long, 96in binary form 97(i.e. not an IP address in human readable 98.Tn ASCII 99form). 100The 101.Fa type 102parameter specifies the address family 103(e.g.\& 104.Dv AF_INET , AF_INET6 , 105etc.) of this address. 106.Pp 107The structure returned contains either the information obtained from the name 108server, 109.Xr named 8 , 110broken-out fields from a line in 111.Pa /etc/hosts , 112or database entries supplied by the 113.Xr yp 4 114system. 115The order of the lookups is controlled by the 116.Sq hosts 117entry in 118.Xr nsswitch.conf 5 . 119.Bd -literal 120struct hostent { 121 char *h_name; /* official name of host */ 122 char **h_aliases; /* alias list */ 123 int h_addrtype; /* host address type */ 124 int h_length; /* length of address */ 125 char **h_addr_list; /* list of addresses from name server */ 126}; 127#define h_addr h_addr_list[0] /* address, for backward compatibility */ 128.Ed 129.Pp 130The members of this structure are: 131.Bl -tag -width h_addr_list 132.It Va h_name 133Official name of the host. 134.It Va h_aliases 135A 136.Dv NULL Ns -terminated 137array of alternate names for the host. 138.It Va h_addrtype 139The type of address being returned; usually 140.Dv AF_INET . 141.It Va h_length 142The length, in bytes, of the address. 143.It Va h_addr_list 144A 145.Dv NULL Ns -terminated 146array of network addresses for the host. 147Host addresses are returned in network byte order. 148.It Va h_addr 149The first address in 150.Va h_addr_list ; 151this is for backward compatibility. 152.El 153.Pp 154When using the nameserver, 155.Fn gethostbyname 156and 157.Fn gethostbyname2 158will search for the named host in the current domain and its parents 159unless the name ends in a dot. 160If the name contains no dot, and if the environment variable 161.Dq Ev HOSTALIASES 162contains the name of an alias file, the alias file will first be searched 163for an alias matching the input name. 164See 165.Xr hostname 7 166for the domain search procedure and the alias file format. 167.Pp 168The 169.Fn gethostbyname2 170function is an evolution of 171.Fn gethostbyname 172which is intended to allow lookups in address families other than 173.Dv AF_INET , 174for example 175.Dv AF_INET6 . 176.Pp 177The 178.Fn sethostent 179function 180may be used to request the use of a connected 181.Tn TCP 182socket for queries. 183If the 184.Fa stayopen 185flag is non-zero, 186this sets the option to send all queries to the name server using 187.Tn TCP 188and to retain the connection after each call to 189.Fn gethostbyname , 190.Fn gethostbyname2 191or 192.Fn gethostbyaddr . 193Otherwise, queries are performed using 194.Tn UDP 195datagrams. 196.Pp 197The 198.Fn endhostent 199function 200closes the 201.Tn TCP 202connection. 203.Pp 204The 205.Fn herror 206function writes a message to the diagnostic output consisting of the 207string parameter 208.Fa s , 209the constant string 210.Qq Li ":\ " , 211and a message corresponding to the value of 212.Va h_errno . 213.Pp 214The 215.Fn hstrerror 216function returns a string which is the message text corresponding to the 217value of the 218.Fa err 219parameter. 220.Sh FILES 221.Bl -tag -width /etc/nsswitch.conf -compact 222.It Pa /etc/hosts 223.It Pa /etc/nsswitch.conf 224.It Pa /etc/resolv.conf 225.El 226.Sh EXAMPLES 227Print out the hostname associated with a specific IP address: 228.Bd -literal -offset indent 229const char *ipstr = "127.0.0.1"; 230struct in_addr ip; 231struct hostent *hp; 232 233if (!inet_aton(ipstr, &ip)) 234 errx(1, "can't parse IP address %s", ipstr); 235 236if ((hp = gethostbyaddr((const char *)&ip, 237 sizeof ip, AF_INET)) == NULL) 238 errx(1, "no name associated with %s", ipstr); 239 240printf("name associated with %s is %s\en", ipstr, hp->h_name); 241.Ed 242.Sh DIAGNOSTICS 243Error return status from 244.Fn gethostbyname , 245.Fn gethostbyname2 246and 247.Fn gethostbyaddr 248is indicated by return of a 249.Dv NULL 250pointer. 251The external integer 252.Va h_errno 253may then be checked to see whether this is a temporary failure 254or an invalid or unknown host. 255The routine 256.Fn herror 257can be used to print an error message describing the failure. 258If its argument 259.Fa string 260is 261.Pf non- Dv NULL , 262it is printed, followed by a colon and a space. 263The error message is printed with a trailing newline. 264.Pp 265The variable 266.Va h_errno 267can have the following values: 268.Bl -tag -width HOST_NOT_FOUND 269.It Dv HOST_NOT_FOUND 270No such host is known. 271.It Dv TRY_AGAIN 272This is usually a temporary error 273and means that the local server did not receive 274a response from an authoritative server. 275A retry at some later time may succeed. 276.It Dv NO_RECOVERY 277Some unexpected server failure was encountered. 278This is a non-recoverable error. 279.It Dv NO_DATA 280The requested name is valid but does not have an IP address; 281this is not a temporary error. 282This means that the name is known to the name server but there is no address 283associated with this name. 284Another type of request to the name server using this domain name 285will result in an answer; 286for example, a mail-forwarder may be registered for this domain. 287.El 288.Sh SEE ALSO 289.Xr getaddrinfo 3 , 290.Xr inet_aton 3 , 291.Xr resolver 3 , 292.Xr hosts 5 , 293.Xr hostname 7 , 294.Xr named 8 295.Sh CAVEAT 296The 297.Fn gethostent 298function 299is defined, and 300.Fn sethostent 301and 302.Fn endhostent 303are redefined, 304when 305.Xr libc 3 306is built to use only the routines to lookup in 307.Pa /etc/hosts 308and not the name server. 309.Pp 310The 311.Fn gethostent 312function 313reads the next line of 314.Pa /etc/hosts , 315opening the file if necessary. 316.Pp 317The 318.Fn sethostent 319function 320opens and/or rewinds the file 321.Pa /etc/hosts . 322If the 323.Fa stayopen 324argument is non-zero, 325the file will not be closed after each call to 326.Fn gethostbyname , 327.Fn gethostbyname2 328or 329.Fn gethostbyaddr . 330.Pp 331The 332.Fn endhostent 333function 334closes the file. 335.Sh HISTORY 336The 337.Fn herror 338function appeared in 339.Bx 4.3 . 340The 341.Fn endhostent , 342.Fn gethostbyaddr , 343.Fn gethostbyname , 344.Fn gethostent , 345and 346.Fn sethostent 347functions appeared in 348.Bx 4.2 . 349The 350.Fn gethostbyname2 351function first appeared in 352.Tn BIND 353version 4.9.4. 354.Sh BUGS 355These functions use static data storage; 356if the data is needed for future use, it should be 357copied before any subsequent calls overwrite it. 358Only the Internet 359address format is currently understood. 360.Pp 361.Fn gethostbyname2 362cannot perform 363.Dv AF_INET6 364lookups over NIS. 365.Xr getaddrinfo 3 366must be used instead. 367