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