1.\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC") 2.\" 3.\" Permission to use, copy, modify, and distribute this software for any 4.\" purpose with or without fee is hereby granted, provided that the above 5.\" copyright notice and this permission notice appear in all copies. 6.\" 7.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES 8.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 9.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR 10.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 11.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 12.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT 13.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 14.\" 15.\" Copyright (c) 1983, 1987 The Regents of the University of California. 16.\" All rights reserved. 17.\" 18.\" Redistribution and use in source and binary forms are permitted provided 19.\" that: (1) source distributions retain this entire copyright notice and 20.\" comment, and (2) distributions including binaries display the following 21.\" acknowledgement: ``This product includes software developed by the 22.\" University of California, Berkeley and its contributors'' in the 23.\" documentation or other materials provided with the distribution and in 24.\" all advertising materials mentioning features or use of this software. 25.\" Neither the name of the University nor the names of its contributors may 26.\" be used to endorse or promote products derived from this software without 27.\" specific prior written permission. 28.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED 29.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF 30.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. 31.\" 32.\" @(#)gethostbyname.3 6.12 (Berkeley) 6/23/90 33.\" 34.Dd June 23, 1990 35.Dt GETHOSTBYNAME 3 36.Os BSD 4 37.Sh NAME 38.Nm gethostbyname , 39.Nm gethostbyaddr , 40.Nm gethostent , 41.Nm sethostent , 42.Nm endhostent , 43.Nm herror 44.Nd get network host entry 45.Sh SYNOPSIS 46.Fd #include <netdb.h> 47.Ft extern int 48.Fa h_errno ; 49.Pp 50.Ft struct hostent * 51.Fn gethostbyname "char *name" 52.Ft struct hostent * 53.Fn gethostbyname2 "char *name" "int af" 54.Ft struct hostent * 55.Fn gethostbyaddr "char *addr" "int len, type" 56.Ft struct hostent * 57.Fn gethostent 58.Fn sethostent "int stayopen" 59.Fn endhostent 60.Fn herror "char *string" 61.Sh DESCRIPTION 62.Fn Gethostbyname , 63.Fn gethostbyname2 , 64and 65.Fn gethostbyaddr 66each return a pointer to a 67.Ft hostent 68structure (see below) describing an internet host 69referenced by name or by address, as the function names indicate. 70This structure contains either the information obtained from the name server, 71or broken-out fields from a line in 72.Pa /etc/hosts . 73If the local name server is not running, these routines do a lookup in 74.Pa /etc/hosts . 75.Bd -literal -offset indent 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 84#define h_addr h_addr_list[0] /* address, for backward compatibility */ 85.Ed 86.Pp 87The members of this structure are: 88.Bl -tag -width "h_addr_list" 89.It h_name 90Official name of the host. 91.It h_aliases 92A zero-terminated array of alternate names for the host. 93.It h_addrtype 94The type of address being returned; usually 95.Dv AF_INET . 96.It h_length 97The length, in bytes, of the address. 98.It h_addr_list 99A zero-terminated array of network addresses for the host. 100Host addresses are returned in network byte order. 101.It h_addr 102The first address in 103.Li h_addr_list ; 104this is for backward compatibility. 105.El 106.Pp 107When using the nameserver, 108.Fn gethostbyname 109will search for the named host in each parent domain given in the 110.Dq Li search 111directive of 112.Xr resolv.conf 5 113unless the name contains a dot 114.Pq Dq \&. . 115If the name contains no dot, and if the environment variable 116.Ev HOSTALIASES 117contains the name of an alias file, the alias file will first be searched 118for an alias matching the input name. 119See 120.Xr hostname 7 121for the domain search procedure and the alias file format. 122.Pp 123.Fn Gethostbyname2 124is an evolution of 125.Fn gethostbyname 126intended to allow lookups in address families other than 127.Dv AF_INET , 128for example, 129.Dv AF_INET6 . 130Currently, the 131.Fa af 132argument must be specified as 133.Dv AF_INET 134else the function will return 135.Dv NULL 136after having set 137.Ft h_errno 138to 139.Dv NETDB_INTERNAL . 140.Pp 141.Fn Sethostent 142may be used to request the use of a connected TCP socket for queries. 143If the 144.Fa stayopen 145flag is non-zero, 146this sets the option to send all queries to the name server using TCP 147and to retain the connection after each call to 148.Fn gethostbyname 149or 150.Fn gethostbyaddr . 151Otherwise, queries are performed using UDP datagrams. 152.Pp 153.Fn Endhostent 154closes the TCP connection. 155.Sh ENVIRONMENT 156.Bl -tag -width "HOSTALIASES " -compact 157.It Ev HOSTALIASES 158Name of file containing 159.Pq Ar host alias , full hostname 160pairs. 161.El 162.Sh FILES 163.Bl -tag -width "HOSTALIASES " -compact 164.It Pa /etc/hosts 165See 166.Xr hosts 5 . 167.El 168.Sh DIAGNOSTICS 169.Pp 170Error return status from 171.Fn gethostbyname 172and 173.Fn gethostbyaddr 174is indicated by return of a null pointer. 175The external integer 176.Ft h_errno 177may then be checked to see whether this is a temporary failure 178or an invalid or unknown host. 179The routine 180.Fn herror 181can be used to print an error message describing the failure. 182If its argument 183.Fa string 184is non-NULL, it is printed, followed by a colon and a space. 185The error message is printed with a trailing newline. 186.Pp 187.Ft h_errno 188can have the following values: 189.Bl -tag -width "HOST_NOT_FOUND " -offset indent 190.It Dv NETDB_INTERNAL 191This indicates an internal error in the library, unrelated to the network 192or name service. 193.Ft errno 194will be valid in this case; see 195.Xr perror . 196.It Dv HOST_NOT_FOUND 197No such host is known. 198.It Dv TRY_AGAIN 199This is usually a temporary error 200and means that the local server did not receive 201a response from an authoritative server. 202A retry at some later time may succeed. 203.It Dv NO_RECOVERY 204Some unexpected server failure was encountered. 205This is a non-recoverable error, as one might expect. 206.It Dv NO_DATA 207The requested name is valid but does not have an IP address; 208this is not a temporary error. 209This means that the name is known to the name server but there is no address 210associated with this name. 211Another type of request to the name server using this domain name 212will result in an answer; 213for example, a mail-forwarder may be registered for this domain. 214.El 215.Sh SEE ALSO 216.Xr hosts 5 , 217.Xr hostname 7 , 218.Xr resolver 3 , 219.Xr resolver 5 . 220.Sh CAVEAT 221.Pp 222.Fn Gethostent 223is defined, and 224.Fn sethostent 225and 226.Fn endhostent 227are redefined, 228when 229.Pa libc 230is built to use only the routines to lookup in 231.Pa /etc/hosts 232and not the name server: 233.Bd -ragged -offset indent 234.Pp 235.Fn Gethostent 236reads the next line of 237.Pa /etc/hosts , 238opening the file if necessary. 239.Pp 240.Fn Sethostent 241is redefined to open and rewind the file. If the 242.Fa stayopen 243argument is non-zero, 244the hosts data base will not be closed after each call to 245.Fn gethostbyname 246or 247.Fn gethostbyaddr . 248.Pp 249.Fn Endhostent 250is redefined to close the file. 251.Ed 252.Sh BUGS 253All information is contained in a static area so it must be copied if it is 254to be saved. Only the Internet address format is currently understood. 255