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