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