1.\" $OpenBSD: gethostbyname.3,v 1.25 2007/05/31 19:19:30 jmc 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.Dd $Mdocdate: May 31 2007 $ 31.Dt GETHOSTBYNAME 3 32.Os 33.Sh NAME 34.Nm gethostbyname , 35.Nm gethostbyname2 , 36.Nm gethostbyaddr , 37.Nm gethostent , 38.Nm sethostent , 39.Nm endhostent , 40.Nm hstrerror , 41.Nm herror 42.Nd get network host entry 43.Sh SYNOPSIS 44.Fd #include <netdb.h> 45.Vt extern int h_errno ; 46.Ft struct hostent * 47.Fn gethostbyname "const char *name" 48.Ft struct hostent * 49.Fn gethostbyname2 "const char *name" "int af" 50.Ft struct hostent * 51.Fn gethostbyaddr "const void *addr" "socklen_t len" "int af" 52.Ft struct hostent * 53.Fn gethostent void 54.Ft void 55.Fn sethostent "int stayopen" 56.Ft void 57.Fn endhostent void 58.Ft void 59.Fn herror "const char *string" 60.Ft const char * 61.Fn hstrerror "int err" 62.Sh DESCRIPTION 63The 64.Fn gethostbyname , 65.Fn gethostbyname2 , 66and 67.Fn gethostbyaddr 68functions each return a pointer to an object with the following structure 69describing an Internet host referenced by name or by address, respectively. 70This structure contains either information obtained from the name server (i.e., 71.Xr resolver 3 72and 73.Xr named 8 ) , 74broken-out fields from a line in 75.Pa /etc/hosts , 76or database entries supplied by the 77.Xr yp 8 78system. 79.Xr resolv.conf 5 80describes how the particular database is chosen. 81.Bd -literal -offset indent 82struct hostent { 83 char *h_name; /* official name of host */ 84 char **h_aliases; /* alias list */ 85 int h_addrtype; /* host address type */ 86 int h_length; /* length of address */ 87 char **h_addr_list; /* list of returned addresses */ 88}; 89#define h_addr h_addr_list[0] /* address, for backward compat */ 90.Ed 91.Pp 92The members of this structure are: 93.Bl -tag -width h_addr_list 94.It Fa h_name 95Official name of the host. 96.It Fa h_aliases 97A null-terminated array of alternate names for the host. 98.It Fa h_addrtype 99The type of address being returned. 100.It Fa h_length 101The length, in bytes, of the address. 102.It Fa h_addr_list 103A null-terminated array of network addresses for the host. 104Host addresses are returned in network byte order. 105.It Fa h_addr 106The first address in 107.Fa h_addr_list ; 108this is for backward compatibility. 109.El 110.Pp 111The function 112.Fn gethostbyname 113will search for the named host in the current domain and its parents 114using the search lookup semantics detailed in 115.Xr resolv.conf 5 116and 117.Xr hostname 7 . 118.Pp 119.Fn gethostbyname2 120is an advanced form of 121.Fn gethostbyname 122which allows lookups in address families other than 123.Dv AF_INET . 124Currently, the only supported address family besides 125.Dv AF_INET 126is 127.Dv AF_INET6 . 128.Pp 129The 130.Fn gethostbyaddr 131function will search for the specified address of length 132.Fa len 133in the address family 134.Fa af . 135The only address family currently supported is 136.Dv AF_INET . 137.Pp 138The 139.Fn sethostent 140function may be used to request the use of a connected 141.Tn TCP 142socket for queries. 143If the 144.Fa stayopen 145flag is non-zero, 146this sets the option to send all queries to the name server using 147.Tn TCP 148and to retain the connection after each call to 149.Fn gethostbyname 150or 151.Fn gethostbyaddr . 152Otherwise, queries are performed using 153.Tn UDP 154datagrams. 155.Pp 156The 157.Fn endhostent 158function closes the 159.Tn TCP 160connection. 161.Pp 162The 163.Fn herror 164function prints an error message describing the failure. 165If its argument 166.Fa string 167is non-null, 168it is prepended to the message string and separated from it by a colon 169.Pq Ql \&: 170and a space. 171The error message is printed with a trailing newline. 172The contents of the error message is the same as that returned by 173.Fn hstrerror 174with argument 175.Fa h_errno . 176.Sh ENVIRONMENT 177.Bl -tag -width HOSTALIASES 178.It HOSTALIASES 179A file containing local host aliases. 180See 181.Xr hostname 7 182for more information. 183.It RES_OPTIONS 184A list of options to override the resolver's internal defaults. 185See 186.Xr resolver 3 187for more information. 188.El 189.Sh FILES 190.Bl -tag -width /etc/resolv.conf -compact 191.It Pa /etc/hosts 192.It Pa /etc/resolv.conf 193.El 194.Sh DIAGNOSTICS 195Error return status from 196.Fn gethostbyname , 197.Fn gethostbyname2 , 198and 199.Fn gethostbyaddr 200is indicated by return of a null pointer. 201The external integer 202.Va h_errno 203may then be checked to see whether this is a temporary failure 204or an invalid or unknown host. 205.Pp 206The variable 207.Va h_errno 208can have the following values: 209.Bl -tag -width HOST_NOT_FOUND 210.It Dv HOST_NOT_FOUND 211No such host is known. 212.It Dv TRY_AGAIN 213This is usually a temporary error 214and means that the local server did not receive 215a response from an authoritative server. 216A retry at some later time may succeed. 217.It Dv NO_RECOVERY 218Some unexpected server failure was encountered. 219This is a non-recoverable error. 220.It Dv NO_DATA 221The requested name is valid but does not have an IP address; 222this is not a temporary error. 223This means that the name is known to the name server but there is no address 224associated with this name. 225Another type of request to the name server using this domain name 226will result in an answer; 227for example, a mail-forwarder may be registered for this domain. 228.It Dv NETDB_INTERNAL 229An internal error occurred. 230This may occur when an address family other than 231.Dv AF_INET 232or 233.Dv AF_INET6 234is specified or when a resource is unable to be allocated. 235.It Dv NETDB_SUCCESS 236The function completed successfully. 237.El 238.Sh SEE ALSO 239.Xr getaddrinfo 3 , 240.Xr getnameinfo 3 , 241.Xr resolver 3 , 242.Xr hosts 5 , 243.Xr resolv.conf 5 , 244.Xr hostname 7 , 245.Xr named 8 246.Sh HISTORY 247The 248.Fn herror 249function appeared in 250.Bx 4.3 . 251The 252.Fn endhostent , 253.Fn gethostbyaddr , 254.Fn gethostbyname , 255.Fn gethostent , 256and 257.Fn sethostent 258functions appeared in 259.Bx 4.2 . 260.Sh CAVEATS 261If the search routines in 262.Xr resolv.conf 5 263decide to read the 264.Pa /etc/hosts 265file, 266.Fn gethostent 267and other functions will 268read the next line of the file, 269re-opening the file if necessary. 270.Pp 271The 272.Fn sethostent 273function opens and/or rewinds the file 274.Pa /etc/hosts . 275If the 276.Fa stayopen 277argument is non-zero, the file will not be closed after each call to 278.Fn gethostbyname , 279.Fn gethostbyname2 , 280or 281.Fn gethostbyaddr . 282.Pp 283The 284.Fn endhostent 285function closes the file. 286.Sh BUGS 287These functions use static data storage; 288if the data is needed for future use, it should be 289copied before any subsequent calls overwrite it. 290.Pp 291Only the Internet 292address formats are currently understood. 293.Pp 294YP does not support any address families other than 295.Dv AF_INET 296and uses 297the traditional database format. 298