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