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 BSD 4.2 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.Fd #include <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 70The 71.Fn gethostbyname , 72.Fn gethostbyname2 73and 74.Fn gethostbyaddr 75functions 76each return a pointer to an object with the 77following structure describing an internet host 78referenced by name or by address, respectively. 79This structure contains either the information obtained from the name server, 80.Xr named 8 , 81broken-out fields from a line in 82.Pa /etc/hosts , 83or database entries supplied by the 84.Xr yp 4 85system. 86The order of the lookups is controlled by the 87.Sq hosts 88entry in 89.Xr nsswitch.conf 5 . 90.Bd -literal 91struct hostent { 92 char *h_name; /* official name of host */ 93 char **h_aliases; /* alias list */ 94 int h_addrtype; /* host address type */ 95 int h_length; /* length of address */ 96 char **h_addr_list; /* list of addresses from name server */ 97}; 98#define h_addr h_addr_list[0] /* address, for backward compatibility */ 99.Ed 100.Pp 101The members of this structure are: 102.Bl -tag -width h_addr_list 103.It Fa h_name 104Official name of the host. 105.It Fa h_aliases 106A NULL-terminated array of alternate names for the host. 107.It Fa h_addrtype 108The type of address being returned; usually 109.Dv AF_INET . 110.It Fa h_length 111The length, in bytes, of the address. 112.It Fa h_addr_list 113A NULL-terminated array of network addresses for the host. 114Host addresses are returned in network byte order. 115.It Fa h_addr 116The first address in 117.Fa h_addr_list ; 118this is for backward compatibility. 119.El 120.Pp 121When using the nameserver, 122.Fn gethostbyname 123and 124.Fn gethostbyname2 125will search for the named host in the current domain and its parents 126unless the name ends in a dot. 127If the name contains no dot, and if the environment variable 128.Dq Ev HOSTALIASES 129contains the name of an alias file, the alias file will first be searched 130for an alias matching the input name. 131See 132.Xr hostname 7 133for the domain search procedure and the alias file format. 134.Pp 135The 136.Fn gethostbyname2 137function is an evolution of 138.Fn gethostbyname 139which is intended to allow lookups in address families other than 140.Dv AF_INET , 141for example 142.Dv AF_INET6 . 143Currently the 144.Fa af 145argument must be specified as 146.Dv AF_INET 147else the function will return 148.Dv NULL 149after having set 150.Va h_errno 151to 152.Dv NETDB_INTERNAL 153.Pp 154The 155.Fn sethostent 156function 157may be used to request the use of a connected 158.Tn TCP 159socket for queries. 160If the 161.Fa stayopen 162flag is non-zero, 163this sets the option to send all queries to the name server using 164.Tn TCP 165and to retain the connection after each call to 166.Fn gethostbyname , 167.Fn gethostbyname2 168or 169.Fn gethostbyaddr . 170Otherwise, queries are performed using 171.Tn UDP 172datagrams. 173.Pp 174The 175.Fn endhostent 176function 177closes the 178.Tn TCP 179connection. 180.Pp 181The 182.Fn herror 183function writes a message to the diagnostic output consisting of the 184string parameter 185.Fa s , 186the constant string ": ", and a message corresponding to the value of 187.Va h_errno . 188.Pp 189The 190.Fn hstrerror 191function returns a string which is the message text corresponding to the 192value of the 193.Fa err 194parameter. 195.Sh FILES 196.Bl -tag -width /etc/nsswitch.conf -compact 197.It Pa /etc/hosts 198.It Pa /etc/nsswitch.conf 199.It Pa /etc/resolv.conf 200.El 201.Sh DIAGNOSTICS 202Error return status from 203.Fn gethostbyname , 204.Fn gethostbyname2 205and 206.Fn gethostbyaddr 207is indicated by return of a null pointer. 208The external integer 209.Va h_errno 210may then be checked to see whether this is a temporary failure 211or an invalid or unknown host. 212The routine 213.Fn herror 214can be used to print an error message describing the failure. 215If its argument 216.Fa string 217is 218.Pf non Dv -NULL , 219it is printed, followed by a colon and a space. 220The error message is printed with a trailing newline. 221.Pp 222The variable 223.Va h_errno 224can have the following values: 225.Bl -tag -width HOST_NOT_FOUND 226.It Dv HOST_NOT_FOUND 227No such host is known. 228.It Dv TRY_AGAIN 229This is usually a temporary error 230and means that the local server did not receive 231a response from an authoritative server. 232A retry at some later time may succeed. 233.It Dv NO_RECOVERY 234Some unexpected server failure was encountered. 235This is a non-recoverable error. 236.It Dv NO_DATA 237The requested name is valid but does not have an IP address; 238this is not a temporary error. 239This means that the name is known to the name server but there is no address 240associated with this name. 241Another type of request to the name server using this domain name 242will result in an answer; 243for example, a mail-forwarder may be registered for this domain. 244.El 245.Sh SEE ALSO 246.Xr resolver 3 , 247.Xr hosts 5 , 248.Xr hostname 7 , 249.Xr named 8 250.Sh CAVEAT 251The 252.Fn gethostent 253function 254is defined, and 255.Fn sethostent 256and 257.Fn endhostent 258are redefined, 259when 260.Xr libc 3 261is built to use only the routines to lookup in 262.Pa /etc/hosts 263and not the name server. 264.Pp 265The 266.Fn gethostent 267function 268reads the next line of 269.Pa /etc/hosts , 270opening the file if necessary. 271.Pp 272The 273.Fn sethostent 274function 275opens and/or rewinds the file 276.Pa /etc/hosts . 277If the 278.Fa stayopen 279argument is non-zero, 280the file will not be closed after each call to 281.Fn gethostbyname , 282.Fn gethostbyname2 283or 284.Fn gethostbyaddr . 285.Pp 286The 287.Fn endhostent 288function 289closes the file. 290.Sh HISTORY 291The 292.Fn herror 293function appeared in 294.Bx 4.3 . 295The 296.Fn endhostent , 297.Fn gethostbyaddr , 298.Fn gethostbyname , 299.Fn gethostent , 300and 301.Fn sethostent 302functions appeared in 303.Bx 4.2 . 304The 305.Fn gethostbyname2 306function first appeared in bind-4.9.4. 307.Sh BUGS 308These functions use static data storage; 309if the data is needed for future use, it should be 310copied before any subsequent calls overwrite it. 311Only the Internet 312address format is currently understood. 313