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. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 33.\" $FreeBSD$ 34.\" 35.Dd May 25, 1995 36.Dt GETHOSTBYNAME 3 37.Os 38.Sh NAME 39.Nm gethostbyname , 40.Nm gethostbyname2 , 41.Nm gethostbyaddr , 42.Nm gethostent , 43.Nm sethostent , 44.Nm endhostent , 45.Nm herror , 46.Nm hstrerror 47.Nd get network host entry 48.Sh LIBRARY 49.Lb libc 50.Sh SYNOPSIS 51.In netdb.h 52.Vt extern int h_errno ; 53.Ft struct hostent * 54.Fn gethostbyname "const char *name" 55.Ft struct hostent * 56.Fn gethostbyname2 "const char *name" "int af" 57.Ft struct hostent * 58.Fn gethostbyaddr "const char *addr" "int len" "int type" 59.Ft struct hostent * 60.Fn gethostent void 61.Ft void 62.Fn sethostent "int stayopen" 63.Ft void 64.Fn endhostent void 65.Ft void 66.Fn herror "const char *string" 67.Ft const char * 68.Fn hstrerror "int err" 69.Sh DESCRIPTION 70.Bf -symbolic 71The 72.Xr getaddrinfo 3 73and 74.Xr getnameinfo 3 75functions are preferred over the 76.Fn gethostbyname , 77.Fn gethostbyname2 , 78and 79.Fn gethostbyaddr 80functions. 81.Ef 82.Pp 83The 84.Fn gethostbyname , 85.Fn gethostbyname2 86and 87.Fn gethostbyaddr 88functions 89each return a pointer to an object with the 90following structure describing an internet host 91referenced by name or by address, respectively. 92.Pp 93The 94.Fa name 95parameter passed to 96.Fn gethostbyname 97or 98.Fn gethostbyname2 99should point to a 100.Dv NUL Ns -terminated 101hostname. 102The 103.Fa addr 104parameter passed to 105.Fn gethostbyaddr 106should point to an address which is 107.Fa len 108bytes long, 109in binary form 110(i.e. not an IP address in human readable 111.Tn ASCII 112form). 113The 114.Fa type 115parameter specifies the address family 116(e.g.\& 117.Dv AF_INET , AF_INET6 , 118etc.) of this address. 119.Pp 120The structure returned contains either the information obtained from the name 121server, 122.Xr named 8 , 123broken-out fields from a line in 124.Pa /etc/hosts , 125or database entries supplied by the 126.Xr yp 4 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. 196If the 197.Fa stayopen 198flag is non-zero, 199this sets the option to send all queries to the name server using 200.Tn TCP 201and to retain the connection after each call to 202.Fn gethostbyname , 203.Fn gethostbyname2 204or 205.Fn gethostbyaddr . 206Otherwise, queries are performed using 207.Tn UDP 208datagrams. 209.Pp 210The 211.Fn endhostent 212function 213closes the 214.Tn TCP 215connection. 216.Pp 217The 218.Fn herror 219function writes a message to the diagnostic output consisting of the 220string parameter 221.Fa s , 222the constant string 223.Qq Li ":\ " , 224and a message corresponding to the value of 225.Va h_errno . 226.Pp 227The 228.Fn hstrerror 229function returns a string which is the message text corresponding to the 230value of the 231.Fa err 232parameter. 233.Sh FILES 234.Bl -tag -width /etc/nsswitch.conf -compact 235.It Pa /etc/hosts 236.It Pa /etc/nsswitch.conf 237.It Pa /etc/resolv.conf 238.El 239.Sh EXAMPLES 240Print out the hostname associated with a specific IP address: 241.Bd -literal -offset indent 242const char *ipstr = "127.0.0.1"; 243struct in_addr ip; 244struct hostent *hp; 245 246if (!inet_aton(ipstr, &ip)) 247 errx(1, "can't parse IP address %s", ipstr); 248 249if ((hp = gethostbyaddr((const char *)&ip, 250 sizeof ip, AF_INET)) == NULL) 251 errx(1, "no name associated with %s", ipstr); 252 253printf("name associated with %s is %s\en", ipstr, hp->h_name); 254.Ed 255.Sh DIAGNOSTICS 256Error return status from 257.Fn gethostbyname , 258.Fn gethostbyname2 259and 260.Fn gethostbyaddr 261is indicated by return of a 262.Dv NULL 263pointer. 264The external integer 265.Va h_errno 266may then be checked to see whether this is a temporary failure 267or an invalid or unknown host. 268The routine 269.Fn herror 270can be used to print an error message describing the failure. 271If its argument 272.Fa string 273is 274.Pf non- Dv NULL , 275it is printed, followed by a colon and a space. 276The error message is printed with a trailing newline. 277.Pp 278The variable 279.Va h_errno 280can have the following values: 281.Bl -tag -width HOST_NOT_FOUND 282.It Dv HOST_NOT_FOUND 283No such host is known. 284.It Dv TRY_AGAIN 285This is usually a temporary error 286and means that the local server did not receive 287a response from an authoritative server. 288A retry at some later time may succeed. 289.It Dv NO_RECOVERY 290Some unexpected server failure was encountered. 291This is a non-recoverable error. 292.It Dv NO_DATA 293The requested name is valid but does not have an IP address; 294this is not a temporary error. 295This means that the name is known to the name server but there is no address 296associated with this name. 297Another type of request to the name server using this domain name 298will result in an answer; 299for example, a mail-forwarder may be registered for this domain. 300.El 301.Sh SEE ALSO 302.Xr getaddrinfo 3 , 303.Xr getnameinfo 3 , 304.Xr inet_aton 3 , 305.Xr resolver 3 , 306.Xr hosts 5 , 307.Xr hostname 7 , 308.Xr named 8 309.Sh CAVEAT 310The 311.Fn gethostent 312function 313is defined, and 314.Fn sethostent 315and 316.Fn endhostent 317are redefined, 318when 319.Xr libc 3 320is built to use only the routines to lookup in 321.Pa /etc/hosts 322and not the name server. 323.Pp 324The 325.Fn gethostent 326function 327reads the next line of 328.Pa /etc/hosts , 329opening the file if necessary. 330.Pp 331The 332.Fn sethostent 333function 334opens and/or rewinds the file 335.Pa /etc/hosts . 336If the 337.Fa stayopen 338argument is non-zero, 339the file will not be closed after each call to 340.Fn gethostbyname , 341.Fn gethostbyname2 342or 343.Fn gethostbyaddr . 344.Pp 345The 346.Fn endhostent 347function 348closes the file. 349.Sh HISTORY 350The 351.Fn herror 352function appeared in 353.Bx 4.3 . 354The 355.Fn endhostent , 356.Fn gethostbyaddr , 357.Fn gethostbyname , 358.Fn gethostent , 359and 360.Fn sethostent 361functions appeared in 362.Bx 4.2 . 363The 364.Fn gethostbyname2 365function first appeared in 366.Tn BIND 367version 4.9.4. 368.Sh BUGS 369These functions use static data storage; 370if the data is needed for future use, it should be 371copied before any subsequent calls overwrite it. 372Only the Internet 373address format is currently understood. 374.Pp 375.Fn gethostbyname2 376cannot perform 377.Dv AF_INET6 378lookups over NIS. 379.Xr getaddrinfo 3 380must be used instead. 381