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