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