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: src/lib/libc/net/gethostbyname.3,v 1.38 2007/01/09 00:28:02 imp Exp $ 30.\" 31.Dd May 6, 2019 32.Dt GETHOSTBYNAME 3 33.Os 34.Sh NAME 35.Nm gethostbyname , 36.Nm gethostbyname_r , 37.Nm gethostbyname2 , 38.Nm gethostbyname2_r , 39.Nm gethostbyaddr , 40.Nm gethostbyaddr_r , 41.Nm gethostent , 42.Nm gethostent_r , 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.In netdb.h 52.Vt int h_errno ; 53.Ft struct hostent * 54.Fn gethostbyname "const char *name" 55.Ft int 56.Fn gethostbyname_r "const char *name" "struct hostent *he" "char *buffer" "size_t buflen" "struct hostent **result" "int *h_errnop" 57.Ft struct hostent * 58.Fn gethostbyname2 "const char *name" "int af" 59.Ft int 60.Fn gethostbyname2_r "const char *name" "int af" "struct hostent *he" "char *buffer" "size_t buflen" "struct hostent **result" "int *h_errnop" 61.Ft struct hostent * 62.Fn gethostbyaddr "const void *addr" "socklen_t len" "int type" 63.Ft int 64.Fn gethostbyaddr_r "const void *addr" "socklen_t len" "int af" "struct hostent *he" "char *buffer" "size_t buflen" "struct hostent **result" "int *h_errnop" 65.Ft struct hostent * 66.Fn gethostent void 67.Ft int 68.Fn gethostent_r "struct hostent *he" "char *buffer" "size_t buflen" "struct hostent **result" "int *h_errnop" 69.Ft void 70.Fn sethostent "int stayopen" 71.Ft void 72.Fn endhostent void 73.Ft void 74.Fn herror "const char *string" 75.Ft const char * 76.Fn hstrerror "int err" 77.Sh DESCRIPTION 78.Bf -symbolic 79The 80.Xr getaddrinfo 3 81and 82.Xr getnameinfo 3 83functions are preferred over the 84.Fn gethostbyname , 85.Fn gethostbyname2 , 86and 87.Fn gethostbyaddr 88functions. 89.Ef 90.Pp 91The 92.Fn gethostbyname , 93.Fn gethostbyname2 94and 95.Fn gethostbyaddr 96functions 97each return a pointer to an object with the 98following structure describing an internet host 99referenced by name or by address, respectively. 100.Pp 101The 102.Fa name 103argument passed to 104.Fn gethostbyname 105or 106.Fn gethostbyname2 107should point to a 108.Dv NUL Ns -terminated 109hostname. 110The 111.Fa addr 112argument passed to 113.Fn gethostbyaddr 114should point to an address which is 115.Fa len 116bytes long, 117in binary form 118(i.e., not an IP address in human readable 119.Tn ASCII 120form). 121The 122.Fa type 123argument specifies the address family 124(e.g.\& 125.Dv AF_INET , AF_INET6 , 126etc.) of this address. 127.Pp 128The structure returned contains either the information obtained from the name 129server, 130.Xr named 8 , 131broken-out fields from a line in 132.Pa /etc/hosts , 133or database entries supplied by the 134.Xr yp 8 135system. 136The order of the lookups is controlled by the 137.Sq hosts 138entry in 139.Xr nsswitch.conf 5 . 140.Bd -literal 141struct hostent { 142 char *h_name; /* official name of host */ 143 char **h_aliases; /* alias list */ 144 int h_addrtype; /* host address type */ 145 int h_length; /* length of address */ 146 char **h_addr_list; /* list of addresses from name server */ 147}; 148#define h_addr h_addr_list[0] /* address, for backward compatibility */ 149.Ed 150.Pp 151The members of this structure are: 152.Bl -tag -width ".Fa h_addr_list" 153.It Fa h_name 154Official name of the host. 155.It Fa h_aliases 156A 157.Dv NULL Ns -terminated 158array of alternate names for the host. 159.It Fa h_addrtype 160The type of address being returned; usually 161.Dv AF_INET . 162.It Fa h_length 163The length, in bytes, of the address. 164.It Fa h_addr_list 165A 166.Dv NULL Ns -terminated 167array of network addresses for the host. 168Host addresses are returned in network byte order. 169.It Fa h_addr 170The first address in 171.Fa h_addr_list ; 172this is for backward compatibility. 173.El 174.Pp 175When using the nameserver, 176.Fn gethostbyname 177and 178.Fn gethostbyname2 179will search for the named host in the current domain and its parents 180unless the name ends in a dot. 181If the name contains no dot, and if the environment variable 182.Dq Ev HOSTALIASES 183contains the name of an alias file, the alias file will first be searched 184for an alias matching the input name. 185See 186.Xr hostname 7 187for the domain search procedure and the alias file format. 188.Pp 189The 190.Fn gethostbyname2 191function is an evolution of 192.Fn gethostbyname 193which is intended to allow lookups in address families other than 194.Dv AF_INET , 195for example 196.Dv AF_INET6 . 197.Pp 198The 199.Fn sethostent 200function 201may be used to request the use of a connected 202.Tn TCP 203socket for queries. 204If the 205.Fa stayopen 206flag is non-zero, 207this sets the option to send all queries to the name server using 208.Tn TCP 209and to retain the connection after each call to 210.Fn gethostbyname , 211.Fn gethostbyname2 212or 213.Fn gethostbyaddr . 214Otherwise, queries are performed using 215.Tn UDP 216datagrams. 217.Pp 218The 219.Fn endhostent 220function 221closes the 222.Tn TCP 223connection. 224.Pp 225The 226.Fn herror 227function writes a message to the diagnostic output consisting of the 228string argument 229.Fa string , 230the constant string 231.Qq Li ":\ " , 232and a message corresponding to the value of 233.Va h_errno . 234.Pp 235The 236.Fn hstrerror 237function returns a string which is the message text corresponding to the 238value of the 239.Fa err 240argument. 241.Pp 242The 243.Fn gethostent_r , 244.Fn gethostbyaddr_r , 245.Fn gethostbyname_r , 246and 247.Fn gethostbyname_r 248functions are reentrant versions of the above functions that take a 249pointer to a 250.Vt hostent 251structure which is used to store state information. 252The structure must be zero-filled before it is used 253and should be considered opaque for the sake of portability. 254These functions also take a pointer to another 255.Vt hostent 256structure which is used to store the results of the database lookup. 257.Sh RETURN VALUES 258Error return status from 259.Fn gethostbyname , 260.Fn gethostbyname2 261and 262.Fn gethostbyaddr 263is indicated by return of a 264.Dv NULL 265pointer. 266The integer 267.Va h_errno 268may then be checked to see whether this is a temporary failure 269or an invalid or unknown host. 270The routine 271.Fn herror 272can be used to print an error message describing the failure. 273If its argument 274.Fa string 275is 276.Pf non- Dv NULL , 277it is printed, followed by a colon and a space. 278The error message is printed with a trailing newline. 279.Pp 280The 281.Fn gethostent_r , 282.Fn gethostbyaddr_r , 283.Fn gethostbyname_r , 284and 285.Fn gethostbyname2_r 286functions return 0 on success or \-1 if end-of-file 287is reached or an error occurs. 288.Sh FILES 289.Bl -tag -width ".Pa /etc/nsswitch.conf" -compact 290.It Pa /etc/hosts 291.It Pa /etc/nsswitch.conf 292.It Pa /etc/resolv.conf 293.El 294.Sh EXAMPLES 295Print out the hostname associated with a specific IP address: 296.Bd -literal -offset indent 297const char *ipstr = "127.0.0.1"; 298struct in_addr ip; 299struct hostent *hp; 300 301if (!inet_aton(ipstr, &ip)) 302 errx(1, "can't parse IP address %s", ipstr); 303 304if ((hp = gethostbyaddr((const void *)&ip, 305 sizeof ip, AF_INET)) == NULL) 306 errx(1, "no name associated with %s", ipstr); 307 308printf("name associated with %s is %s\en", ipstr, hp->h_name); 309.Ed 310.Sh ERRORS 311The variable 312.Va h_errno 313can have the following values: 314.Bl -tag -width ".Dv HOST_NOT_FOUND" 315.It Dv HOST_NOT_FOUND 316No such host is known. 317.It Dv TRY_AGAIN 318This is usually a temporary error 319and means that the local server did not receive 320a response from an authoritative server. 321A retry at some later time may succeed. 322.It Dv NO_RECOVERY 323Some unexpected server failure was encountered. 324This is a non-recoverable error. 325.It Dv NO_DATA 326The requested name is valid but does not have an IP address; 327this is not a temporary error. 328This means that the name is known to the name server but there is no address 329associated with this name. 330Another type of request to the name server using this domain name 331will result in an answer; 332for example, a mail-forwarder may be registered for this domain. 333.El 334.Sh SEE ALSO 335.Xr getaddrinfo 3 , 336.Xr getnameinfo 3 , 337.Xr inet_aton 3 , 338.Xr resolver 3 , 339.Xr hosts 5 , 340.Xr hostname 7 , 341.Xr named 8 342.Sh STANDARDS 343The 344.Fn gethostent , 345.Fn sethostent , 346and 347.Fn endhostent 348functions conform to 349.St -p1003.1-2004 . 350.Pp 351The 352.Fn gethostbyaddr , 353.Fn gethostbyaddr_r , 354.Fn gethostbyname , 355.Fn gethostbyname_r , 356.Fn gethostbyname2 , 357.Fn gethostbyname2_r , 358and 359.Fn gethostent_r 360functions are not currently standardized. 361.Sh CAVEATS 362The 363.Fn gethostent 364function 365is defined, and 366.Fn sethostent 367and 368.Fn endhostent 369are redefined, 370when 371.Lb libc 372is built to use only the routines to lookup in 373.Pa /etc/hosts 374and not the name server. 375.Pp 376The 377.Fn gethostent 378function 379reads the next line of 380.Pa /etc/hosts , 381opening the file if necessary. 382.Pp 383The 384.Fn sethostent 385function 386opens and/or rewinds the file 387.Pa /etc/hosts . 388If the 389.Fa stayopen 390argument is non-zero, 391the file will not be closed after each call to 392.Fn gethostbyname , 393.Fn gethostbyname2 394or 395.Fn gethostbyaddr . 396.Pp 397The 398.Fn endhostent 399function 400closes the file. 401.Sh HISTORY 402The 403.Fn herror 404function appeared in 405.Bx 4.3 . 406The 407.Fn endhostent , 408.Fn gethostbyaddr , 409.Fn gethostbyname , 410.Fn gethostent , 411and 412.Fn sethostent 413functions appeared in 414.Bx 4.2 . 415The 416.Fn gethostbyname2 417function first appeared in 418.Tn BIND 419version 4.9.4. 420.Pp 421The 422.Fn gethostent_r , 423.Fn gethostbyaddr_r , 424.Fn getnetbyname_r , 425and 426.Fn gethostbyname2_r , 427functions appeared in 428.Dx 2.1 . 429.Sh BUGS 430These functions use a thread-specific data storage; 431if the data is needed for future use, it should be 432copied before any subsequent calls overwrite it. 433.Pp 434Though these functions are thread-safe, 435still it is recommended to use the 436.Xr getaddrinfo 3 437family of functions, instead. 438.Pp 439Only the Internet 440address format is currently understood. 441