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