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. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 29.\" $FreeBSD$ 30.\" 31.Dd October 4, 2017 32.Dt GETHOSTBYNAME 3 33.Os 34.Sh NAME 35.Nm gethostbyname , 36.Nm gethostbyname2 , 37.Nm gethostbyaddr , 38.Nm gethostent , 39.Nm sethostent , 40.Nm endhostent , 41.Nm herror , 42.Nm hstrerror 43.Nd get network host entry 44.Sh LIBRARY 45.Lb libc 46.Sh SYNOPSIS 47.In netdb.h 48.Vt int h_errno ; 49.Ft struct hostent * 50.Fn gethostbyname "const char *name" 51.Ft struct hostent * 52.Fn gethostbyname2 "const char *name" "int af" 53.Ft struct hostent * 54.Fn gethostbyaddr "const void *addr" "socklen_t len" "int af" 55.Ft struct hostent * 56.Fn gethostent void 57.Ft void 58.Fn sethostent "int stayopen" 59.Ft void 60.Fn endhostent void 61.Ft void 62.Fn herror "const char *string" 63.Ft const char * 64.Fn hstrerror "int err" 65.Sh DESCRIPTION 66.Bf -symbolic 67The 68.Xr getaddrinfo 3 69and 70.Xr getnameinfo 3 71functions are preferred over the 72.Fn gethostbyname , 73.Fn gethostbyname2 , 74and 75.Fn gethostbyaddr 76functions. 77.Ef 78.Pp 79The 80.Fn gethostbyname , 81.Fn gethostbyname2 82and 83.Fn gethostbyaddr 84functions 85each return a pointer to an object with the 86following structure describing an internet host 87referenced by name or by address, respectively. 88.Pp 89The 90.Fa name 91argument passed to 92.Fn gethostbyname 93or 94.Fn gethostbyname2 95should point to a 96.Dv NUL Ns -terminated 97hostname. 98The 99.Fa addr 100argument passed to 101.Fn gethostbyaddr 102should point to an address which is 103.Fa len 104bytes long, 105in binary form 106(i.e., not an IP address in human readable 107.Tn ASCII 108form). 109The 110.Fa af 111argument specifies the address family 112(e.g.\& 113.Dv AF_INET , AF_INET6 , 114etc.) of this address. 115.Pp 116The structure returned contains either the information obtained from the name 117server, 118.Xr named 8 , 119broken-out fields from a line in 120.Pa /etc/hosts , 121or database entries supplied by the 122.Xr yp 8 123system. 124The order of the lookups is controlled by the 125.Sq hosts 126entry in 127.Xr nsswitch.conf 5 . 128.Bd -literal 129struct hostent { 130 char *h_name; /* official name of host */ 131 char **h_aliases; /* alias list */ 132 int h_addrtype; /* host address type */ 133 int h_length; /* length of address */ 134 char **h_addr_list; /* list of addresses from name server */ 135}; 136#define h_addr h_addr_list[0] /* address, for backward compatibility */ 137.Ed 138.Pp 139The members of this structure are: 140.Bl -tag -width h_addr_list 141.It Va h_name 142Official name of the host. 143.It Va h_aliases 144A 145.Dv NULL Ns -terminated 146array of alternate names for the host. 147.It Va h_addrtype 148The type of address being returned; usually 149.Dv AF_INET . 150.It Va h_length 151The length, in bytes, of the address. 152.It Va h_addr_list 153A 154.Dv NULL Ns -terminated 155array of network addresses for the host. 156Host addresses are returned in network byte order. 157.It Va h_addr 158The first address in 159.Va h_addr_list ; 160this is for backward compatibility. 161.El 162.Pp 163When using the nameserver, 164.Fn gethostbyname 165and 166.Fn gethostbyname2 167will search for the named host in the current domain and its parents 168unless the name ends in a dot. 169If the name contains no dot, and if the environment variable 170.Dq Ev HOSTALIASES 171contains the name of an alias file, the alias file will first be searched 172for an alias matching the input name. 173See 174.Xr hostname 7 175for the domain search procedure and the alias file format. 176.Pp 177The 178.Fn gethostbyname2 179function is an evolution of 180.Fn gethostbyname 181which is intended to allow lookups in address families other than 182.Dv AF_INET , 183for example 184.Dv AF_INET6 . 185.Pp 186The 187.Fn sethostent 188function 189may be used to request the use of a connected 190.Tn TCP 191socket for queries. 192Queries will by defaulat use 193.Tn UDP 194datagrams. If the 195.Fa stayopen 196flag is non-zero, a 197.Tn TCP 198connection to the name server will be used. It will remain open after calls to 199.Fn gethostbyname , 200.Fn gethostbyname2 201or 202.Fn gethostbyaddr 203have completed. 204.Pp 205The 206.Fn endhostent 207function 208closes the 209.Tn TCP 210connection. 211.Pp 212The 213.Fn herror 214function writes a message to the diagnostic output consisting of the 215string argument 216.Fa string , 217the constant string 218.Qq Li ":\ " , 219and a message corresponding to the value of 220.Va h_errno . 221.Pp 222The 223.Fn hstrerror 224function returns a string which is the message text corresponding to the 225value of the 226.Fa err 227argument. 228.Sh FILES 229.Bl -tag -width /etc/nsswitch.conf -compact 230.It Pa /etc/hosts 231.It Pa /etc/nsswitch.conf 232.It Pa /etc/resolv.conf 233.El 234.Sh EXAMPLES 235Print out the hostname associated with a specific IP address: 236.Bd -literal -offset indent 237const char *ipstr = "127.0.0.1"; 238struct in_addr ip; 239struct hostent *hp; 240 241if (!inet_aton(ipstr, &ip)) 242 errx(1, "can't parse IP address %s", ipstr); 243 244if ((hp = gethostbyaddr((const void *)&ip, 245 sizeof ip, AF_INET)) == NULL) 246 errx(1, "no name associated with %s", ipstr); 247 248printf("name associated with %s is %s\en", ipstr, hp->h_name); 249.Ed 250.Sh DIAGNOSTICS 251Error return status from 252.Fn gethostbyname , 253.Fn gethostbyname2 254and 255.Fn gethostbyaddr 256is indicated by return of a 257.Dv NULL 258pointer. 259The integer 260.Va h_errno 261may then be checked to see whether this is a temporary failure 262or an invalid or unknown host. 263The routine 264.Fn herror 265can be used to print an error message describing the failure. 266If its argument 267.Fa string 268is 269.Pf non- Dv NULL , 270it is printed, followed by a colon and a space. 271The error message is printed with a trailing newline. 272.Pp 273The variable 274.Va h_errno 275can have the following values: 276.Bl -tag -width HOST_NOT_FOUND 277.It Dv HOST_NOT_FOUND 278No such host is known. 279.It Dv TRY_AGAIN 280This is usually a temporary error 281and means that the local server did not receive 282a response from an authoritative server. 283A retry at some later time may succeed. 284.It Dv NO_RECOVERY 285Some unexpected server failure was encountered. 286This is a non-recoverable error. 287.It Dv NO_DATA 288The requested name is valid but does not have an IP address; 289this is not a temporary error. 290This means that the name is known to the name server but there is no address 291associated with this name. 292Another type of request to the name server using this domain name 293will result in an answer; 294for example, a mail-forwarder may be registered for this domain. 295.El 296.Sh SEE ALSO 297.Xr getaddrinfo 3 , 298.Xr getnameinfo 3 , 299.Xr inet_aton 3 , 300.Xr resolver 3 , 301.Xr hosts 5 , 302.Xr hostname 7 , 303.Xr named 8 304.Sh CAVEAT 305The 306.Fn gethostent 307function 308is defined, and 309.Fn sethostent 310and 311.Fn endhostent 312are redefined, 313when 314.Lb libc 315is built to use only the routines to lookup in 316.Pa /etc/hosts 317and not the name server. 318.Pp 319The 320.Fn gethostent 321function 322reads the next line of 323.Pa /etc/hosts , 324opening the file if necessary. 325.Pp 326The 327.Fn sethostent 328function 329opens and/or rewinds the file 330.Pa /etc/hosts . 331If the 332.Fa stayopen 333argument is non-zero, 334the file will not be closed after each call to 335.Fn gethostbyname , 336.Fn gethostbyname2 337or 338.Fn gethostbyaddr . 339.Pp 340The 341.Fn endhostent 342function 343closes the file. 344.Sh HISTORY 345The 346.Fn herror 347function appeared in 348.Bx 4.3 . 349The 350.Fn endhostent , 351.Fn gethostbyaddr , 352.Fn gethostbyname , 353.Fn gethostent , 354and 355.Fn sethostent 356functions appeared in 357.Bx 4.2 . 358The 359.Fn gethostbyname2 360function first appeared in 361.Tn BIND 362version 4.9.4. 363.Sh BUGS 364These functions use a thread-specific data storage; 365if the data is needed for future use, it should be 366copied before any subsequent calls overwrite it. 367.Pp 368Though these functions are thread-safe, 369still it is recommended to use the 370.Xr getaddrinfo 3 371family of functions, instead. 372.Pp 373Only the Internet 374address format is currently understood. 375