1.\" $NetBSD: gethostbyname.3,v 1.29 2013/08/19 07:18:42 christos Exp $ 2.\" 3.\" Copyright (c) 1983, 1987, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 31.\" 32.Dd August 19, 2013 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.Fd extern 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 67The 68.Fn gethostbyname , 69.Fn gethostbyname2 70and 71.Fn gethostbyaddr 72functions 73each return a pointer to an object with the 74following structure describing an internet host. 75.Bd -literal 76struct hostent { 77 char *h_name; /* official name of host */ 78 char **h_aliases; /* alias list */ 79 int h_addrtype; /* host address type */ 80 int h_length; /* length of address */ 81 char **h_addr_list; /* list of addresses from name server */ 82}; 83#define h_addr h_addr_list[0] /* address, for backward compatibility */ 84.Ed 85.Pp 86The members of this structure are: 87.Bl -tag -width h_addr_list 88.It Fa h_name 89Official name of the host. 90.It Fa h_aliases 91A NULL-terminated array of alternative names for the host. 92.It Fa h_addrtype 93The type of address being returned; currently always 94.Dv AF_INET . 95.It Fa h_length 96The length, in bytes, of the address. 97.It Fa h_addr_list 98A NULL-terminated array of network addresses for the host. 99Host addresses are returned in network byte order. 100.It Fa h_addr 101The first address in 102.Fa h_addr_list ; 103this is for backward compatibility. 104.El 105.Pp 106In the case of 107.Fn gethostbyname 108and 109.Fn gethostbyname2 , 110the host is specified by name, 111or using a string representation of a numeric address. 112In the case of 113.Fn gethostbyaddr , 114the host is specified using a binary representation of an address. 115.Pp 116The returned 117.Ft "struct hostent" 118structure may contain 119the result of a simple string to binary conversion, 120information obtained from the domain name resolver (see 121.Xr resolver 3 ) , 122broken-out fields from a line in 123.Pa /etc/hosts , 124or database entries supplied by the 125.Xr yp 8 126system. 127The order of the lookups is controlled by the 128.Sq hosts 129entry in 130.Xr nsswitch.conf 5 . 131.Pp 132When using the domain name resolver, 133.Fn gethostbyname 134and 135.Fn gethostbyname2 136will search for the named host in the current domain and its parents 137unless the name ends in a dot. 138If the name contains no dot, and if the environment variable 139.Dq Ev HOSTALIASES 140contains the name of an alias file, the alias file will first be searched 141for an alias matching the input name. 142See 143.Xr hostname 7 144for the domain search procedure and the alias file format. 145.Pp 146The 147.Fn gethostbyname2 148function is an evolution of 149.Fn gethostbyname 150which is intended to allow lookups in address families other than 151.Dv AF_INET , 152for example 153.Dv AF_INET6 . 154Currently the 155.Fa af 156argument must be specified as 157.Dv AF_INET 158or 159.Dv AF_INET6 , 160else the function will return 161.Dv NULL 162after having set 163.Va h_errno 164to 165.Dv NETDB_INTERNAL . 166.Pp 167The 168.Fn gethostent 169function 170reads the next line of the 171.Pa /etc/hosts 172file, opening the file if necessary. 173.Pp 174The 175.Fn sethostent 176function 177may be used to request the use of a connected 178.Tn TCP 179socket for queries. 180If the 181.Fa stayopen 182flag is non-zero, 183this sets the option to send all queries to the name server using 184.Tn TCP 185and to retain the connection after each call to 186.Fn gethostbyname , 187.Fn gethostbyname2 , 188or 189.Fn gethostbyaddr . 190Otherwise, queries are performed using 191.Tn UDP 192datagrams. 193.Pp 194The 195.Fn endhostent 196function 197closes the 198.Tn TCP 199connection. 200.Pp 201The 202.Fn herror 203function writes a message to the diagnostic output consisting of the 204string parameter 205.Fa s , 206the constant string ": ", and a message corresponding to the value of 207.Va h_errno . 208.Pp 209The 210.Fn hstrerror 211function returns a string which is the message text corresponding to the 212value of the 213.Fa err 214parameter. 215.Sh FILES 216.Bl -tag -width /etc/hosts -compact 217.It Pa /etc/hosts 218.El 219.Sh DIAGNOSTICS 220Error return status from 221.Fn gethostbyent , 222.Fn gethostbyname , 223.Fn gethostbyname2 , 224and 225.Fn gethostbyaddr 226is indicated by return of a null pointer. 227The external integer 228.Va h_errno 229may then be checked to see whether this is a temporary failure 230or an invalid or unknown host. 231The routine 232.Fn herror 233can be used to print an error message describing the failure. 234If its argument 235.Fa string 236is 237.Pf non Dv -NULL , 238it is printed, followed by a colon and a space. 239The error message is printed with a trailing newline. 240.Pp 241The variable 242.Va h_errno 243can have the following values: 244.Bl -tag -width HOST_NOT_FOUND 245.It Dv HOST_NOT_FOUND 246No such host is known. 247.It Dv TRY_AGAIN 248This is usually a temporary error 249and means that the local server did not receive 250a response from an authoritative server. 251A retry at some later time may succeed. 252.It Dv NO_RECOVERY 253Some unexpected server failure was encountered. 254This is a non-recoverable error. 255.It Dv NO_DATA 256The requested name is valid but does not have an IP address; 257this is not a temporary error. 258This means that the name is known to the name server but there is no address 259associated with this name. 260Another type of request to the name server using this domain name 261will result in an answer; 262for example, a mail-forwarder may be registered for this domain. 263.El 264.Sh SEE ALSO 265.Xr resolver 3 , 266.Xr hosts 5 , 267.Xr nsswitch.conf 5 , 268.Xr hostname 7 , 269.Xr named 8 270.Sh HISTORY 271The 272.Fn herror 273function appeared in 274.Bx 4.3 . 275The 276.Fn endhostent , 277.Fn gethostbyaddr , 278.Fn gethostbyname , 279.Fn gethostent , 280and 281.Fn sethostent 282functions appeared in 283.Bx 4.2 . 284The 285.Fn gethostbyname2 286function first appeared in bind-4.9.4. 287IPv6 support was implemented in WIDE Hydrangea IPv6 protocol stack kit. 288.Sh CAVEATS 289If the search routines specified in 290.Xr nsswitch.conf 5 291decide to read the 292.Pa /etc/hosts 293file, 294.Fn gethostbyname , 295.Fn gethostbyname2 , 296and 297.Fn gethostbyaddr 298will 299read the next line of the file, 300re-opening the file if necessary. 301.Pp 302The 303.Fn sethostent 304function 305opens and/or rewinds the file 306.Pa /etc/hosts . 307If the 308.Fa stayopen 309argument is non-zero, 310the file will not be closed after each call to 311.Fn gethostbyname , 312.Fn gethostbyname2 , 313.Fn gethostbyaddr , 314or 315.Fn gethostent . 316.Pp 317The 318.Fn endhostent 319function closes the file. 320.Sh BUGS 321These functions use static data storage; 322if the data is needed for future use, it should be 323copied before any subsequent calls overwrite it. 324Only the Internet 325address format is currently understood. 326.Pp 327The 328.Fn gethostent 329does not currently follow the search order specified in 330.Xr nsswitch.conf 5 331and only reads the 332.Pa /etc/hosts 333file. 334