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 default use 193.Tn UDP 194datagrams. 195If the 196.Fa stayopen 197flag is non-zero, a 198.Tn TCP 199connection to the name server will be used. 200It will remain open after calls to 201.Fn gethostbyname , 202.Fn gethostbyname2 203or 204.Fn gethostbyaddr 205have completed. 206.Pp 207The 208.Fn endhostent 209function 210closes the 211.Tn TCP 212connection. 213.Pp 214The 215.Fn herror 216function writes a message to the diagnostic output consisting of the 217string argument 218.Fa string , 219the constant string 220.Qq Li ":\ " , 221and a message corresponding to the value of 222.Va h_errno . 223.Pp 224The 225.Fn hstrerror 226function returns a string which is the message text corresponding to the 227value of the 228.Fa err 229argument. 230.Sh FILES 231.Bl -tag -width /etc/nsswitch.conf -compact 232.It Pa /etc/hosts 233.It Pa /etc/nsswitch.conf 234.It Pa /etc/resolv.conf 235.El 236.Sh EXAMPLES 237Print out the hostname associated with a specific IP address: 238.Bd -literal -offset indent 239const char *ipstr = "127.0.0.1"; 240struct in_addr ip; 241struct hostent *hp; 242 243if (!inet_aton(ipstr, &ip)) 244 errx(1, "can't parse IP address %s", ipstr); 245 246if ((hp = gethostbyaddr((const void *)&ip, 247 sizeof ip, AF_INET)) == NULL) 248 errx(1, "no name associated with %s", ipstr); 249 250printf("name associated with %s is %s\en", ipstr, hp->h_name); 251.Ed 252.Sh DIAGNOSTICS 253Error return status from 254.Fn gethostbyname , 255.Fn gethostbyname2 256and 257.Fn gethostbyaddr 258is indicated by return of a 259.Dv NULL 260pointer. 261The integer 262.Va h_errno 263may then be checked to see whether this is a temporary failure 264or an invalid or unknown host. 265The routine 266.Fn herror 267can be used to print an error message describing the failure. 268If its argument 269.Fa string 270is 271.Pf non- Dv NULL , 272it is printed, followed by a colon and a space. 273The error message is printed with a trailing newline. 274.Pp 275The variable 276.Va h_errno 277can have the following values: 278.Bl -tag -width HOST_NOT_FOUND 279.It Dv HOST_NOT_FOUND 280No such host is known. 281.It Dv TRY_AGAIN 282This is usually a temporary error 283and means that the local server did not receive 284a response from an authoritative server. 285A retry at some later time may succeed. 286.It Dv NO_RECOVERY 287Some unexpected server failure was encountered. 288This is a non-recoverable error. 289.It Dv NO_DATA 290The requested name is valid but does not have an IP address; 291this is not a temporary error. 292This means that the name is known to the name server but there is no address 293associated with this name. 294Another type of request to the name server using this domain name 295will result in an answer; 296for example, a mail-forwarder may be registered for this domain. 297.El 298.Sh SEE ALSO 299.Xr getaddrinfo 3 , 300.Xr getnameinfo 3 , 301.Xr inet_aton 3 , 302.Xr resolver 3 , 303.Xr hosts 5 , 304.Xr hostname 7 , 305.Xr named 8 306.Sh CAVEAT 307The 308.Fn gethostent 309function 310is defined, and 311.Fn sethostent 312and 313.Fn endhostent 314are redefined, 315when 316.Lb libc 317is built to use only the routines to lookup in 318.Pa /etc/hosts 319and not the name server. 320.Pp 321The 322.Fn gethostent 323function 324reads the next line of 325.Pa /etc/hosts , 326opening the file if necessary. 327.Pp 328The 329.Fn sethostent 330function 331opens and/or rewinds the file 332.Pa /etc/hosts . 333If the 334.Fa stayopen 335argument is non-zero, 336the file will not be closed after each call to 337.Fn gethostbyname , 338.Fn gethostbyname2 339or 340.Fn gethostbyaddr . 341.Pp 342The 343.Fn endhostent 344function 345closes the file. 346.Sh HISTORY 347The 348.Fn herror 349function appeared in 350.Bx 4.3 . 351The 352.Fn endhostent , 353.Fn gethostbyaddr , 354.Fn gethostbyname , 355.Fn gethostent , 356and 357.Fn sethostent 358functions appeared in 359.Bx 4.2 . 360The 361.Fn gethostbyname2 362function first appeared in 363.Tn BIND 364version 4.9.4. 365.Sh BUGS 366These functions use a thread-specific data storage; 367if the data is needed for future use, it should be 368copied before any subsequent calls overwrite it. 369.Pp 370Though these functions are thread-safe, 371still it is recommended to use the 372.Xr getaddrinfo 3 373family of functions, instead. 374.Pp 375Only the Internet 376address format is currently understood. 377