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