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.\" $DragonFly: src/lib/libc/net/gethostbyname.3,v 1.3 2006/11/17 23:01:21 swildner Exp $ 35.\" 36.Dd May 25, 1995 37.Dt GETHOSTBYNAME 3 38.Os 39.Sh NAME 40.Nm gethostbyname , 41.Nm gethostbyname2 , 42.Nm gethostbyaddr , 43.Nm gethostent , 44.Nm sethostent , 45.Nm endhostent , 46.Nm herror , 47.Nm hstrerror 48.Nd get network host entry 49.Sh LIBRARY 50.Lb libc 51.Sh SYNOPSIS 52.In netdb.h 53.Vt extern int h_errno ; 54.Ft struct hostent * 55.Fn gethostbyname "const char *name" 56.Ft struct hostent * 57.Fn gethostbyname2 "const char *name" "int af" 58.Ft struct hostent * 59.Fn gethostbyaddr "const char *addr" "int len" "int type" 60.Ft struct hostent * 61.Fn gethostent void 62.Ft void 63.Fn sethostent "int stayopen" 64.Ft void 65.Fn endhostent void 66.Ft void 67.Fn herror "const char *string" 68.Ft const char * 69.Fn hstrerror "int err" 70.Sh DESCRIPTION 71The 72.Fn gethostbyname , 73.Fn gethostbyname2 74and 75.Fn gethostbyaddr 76functions 77each return a pointer to an object with the 78following structure describing an internet host 79referenced by name or by address, respectively. 80This structure contains either the information obtained from the name server, 81.Xr named 8 , 82or broken-out fields from a line in 83.Pa /etc/hosts . 84If the local name server is not running these routines do a lookup in 85.Pa /etc/hosts . 86.Bd -literal 87struct hostent { 88 char *h_name; /* official name of host */ 89 char **h_aliases; /* alias list */ 90 int h_addrtype; /* host address type */ 91 int h_length; /* length of address */ 92 char **h_addr_list; /* list of addresses from name server */ 93}; 94#define h_addr h_addr_list[0] /* address, for backward compatibility */ 95.Ed 96.Pp 97The members of this structure are: 98.Bl -tag -width h_addr_list 99.It Va h_name 100Official name of the host. 101.It Va h_aliases 102A 103.Dv NULL Ns -terminated 104array of alternate names for the host. 105.It Va h_addrtype 106The type of address being returned; usually 107.Dv AF_INET . 108.It Va h_length 109The length, in bytes, of the address. 110.It Va h_addr_list 111A 112.Dv NULL Ns -terminated 113array of network addresses for the host. 114Host addresses are returned in network byte order. 115.It Va h_addr 116The first address in 117.Va 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 187.Qq Li ":\ " , 188and a message corresponding to the value of 189.Va h_errno . 190.Pp 191The 192.Fn hstrerror 193function returns a string which is the message text corresponding to the 194value of the 195.Fa err 196parameter. 197.Sh FILES 198.Bl -tag -width /etc/resolv.conf -compact 199.It Pa /etc/hosts 200.It Pa /etc/host.conf 201.It Pa /etc/resolv.conf 202.El 203.Sh DIAGNOSTICS 204Error return status from 205.Fn gethostbyname , 206.Fn gethostbyname2 207and 208.Fn gethostbyaddr 209is indicated by return of a 210.Dv NULL 211pointer. 212The external integer 213.Va h_errno 214may then be checked to see whether this is a temporary failure 215or an invalid or unknown host. 216The routine 217.Fn herror 218can be used to print an error message describing the failure. 219If its argument 220.Fa string 221is 222.Pf non- Dv NULL , 223it is printed, followed by a colon and a space. 224The error message is printed with a trailing newline. 225.Pp 226The variable 227.Va h_errno 228can have the following values: 229.Bl -tag -width HOST_NOT_FOUND 230.It Dv HOST_NOT_FOUND 231No such host is known. 232.It Dv TRY_AGAIN 233This is usually a temporary error 234and means that the local server did not receive 235a response from an authoritative server. 236A retry at some later time may succeed. 237.It Dv NO_RECOVERY 238Some unexpected server failure was encountered. 239This is a non-recoverable error. 240.It Dv NO_DATA 241The requested name is valid but does not have an IP address; 242this is not a temporary error. 243This means that the name is known to the name server but there is no address 244associated with this name. 245Another type of request to the name server using this domain name 246will result in an answer; 247for example, a mail-forwarder may be registered for this domain. 248.El 249.Sh SEE ALSO 250.Xr getaddrinfo 3 , 251.Xr resolver 3 , 252.Xr hosts 5 , 253.Xr hostname 7 , 254.Xr named 8 255.Sh CAVEAT 256The 257.Fn gethostent 258function 259is defined, and 260.Fn sethostent 261and 262.Fn endhostent 263are redefined, 264when 265.Em libc 266is built to use only the routines to lookup in 267.Pa /etc/hosts 268and not the name server. 269.Pp 270The 271.Fn gethostent 272function 273reads the next line of 274.Pa /etc/hosts , 275opening the file if necessary. 276.Pp 277The 278.Fn sethostent 279function 280opens and/or rewinds the file 281.Pa /etc/hosts . 282If the 283.Fa stayopen 284argument is non-zero, 285the file will not be closed after each call to 286.Fn gethostbyname , 287.Fn gethostbyname2 288or 289.Fn gethostbyaddr . 290.Pp 291The 292.Fn endhostent 293function 294closes the file. 295.Sh HISTORY 296The 297.Fn herror 298function appeared in 299.Bx 4.3 . 300The 301.Fn endhostent , 302.Fn gethostbyaddr , 303.Fn gethostbyname , 304.Fn gethostent , 305and 306.Fn sethostent 307functions appeared in 308.Bx 4.2 . 309The 310.Fn gethostbyname2 311function first appeared in 312.Tn BIND 313version 4.9.4. 314.Sh BUGS 315These functions use static data storage; 316if the data is needed for future use, it should be 317copied before any subsequent calls overwrite it. 318Only the Internet 319address format is currently understood. 320