external/bsd/libbind/dist/doc/gethostbyname.man3

   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 ,
  64 and
  65 .Fn gethostbyaddr
  66 each return a pointer to a
  67 .Ft hostent
  68 structure (see below) describing an internet host
  69 referenced by name or by address, as the function names indicate.
  70 This structure contains either the information obtained from the name server,
  71 or broken-out fields from a line in
  72 .Pa /etc/hosts .
  73 If the local name server is not running, these routines do a lookup in
  74 .Pa /etc/hosts .
  75 .Bd -literal -offset indent
  76 struct  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
  87 The members of this structure are:
  88 .Bl -tag -width "h_addr_list"
  89 .It h_name
  90 Official name of the host.
  91 .It h_aliases
  92 A zero-terminated array of alternate names for the host.
  93 .It h_addrtype
  94 The type of address being returned; usually
  95 .Dv AF_INET .
  96 .It h_length
  97 The length, in bytes, of the address.
  98 .It h_addr_list
  99 A zero-terminated array of network addresses for the host.
 100 Host addresses are returned in network byte order.
 101 .It h_addr
 102 The first address in
 103 .Li h_addr_list ;
 104 this is for backward compatibility.
 105 .El
 106 .Pp
 107 When using the nameserver,
 108 .Fn gethostbyname
 109 will search for the named host in each parent domain given in the
 110 .Dq Li search
 111 directive of
 112 .Xr resolv.conf 5
 113 unless the name contains a dot
 114 .Pq Dq \&. .
 115 If the name contains no dot, and if the environment variable
 116 .Ev HOSTALIASES
 117 contains the name of an alias file, the alias file will first be searched
 118 for an alias matching the input name.
 119 See
 120 .Xr hostname 7
 121 for the domain search procedure and the alias file format.
 122 .Pp
 123 .Fn Gethostbyname2
 124 is an evolution of
 125 .Fn gethostbyname
 126 intended to allow lookups in address families other than
 127 .Dv AF_INET ,
 128 for example,
 129 .Dv AF_INET6 .
 130 Currently, the
 131 .Fa af
 132 argument must be specified as
 133 .Dv AF_INET
 134 else the function will return
 135 .Dv NULL
 136 after having set
 137 .Ft h_errno
 138 to
 139 .Dv NETDB_INTERNAL .
 140 .Pp
 141 .Fn Sethostent
 142 may be used to request the use of a connected TCP socket for queries.
 143 If the
 144 .Fa stayopen
 145 flag is non-zero,
 146 this sets the option to send all queries to the name server using TCP
 147 and to retain the connection after each call to
 148 .Fn gethostbyname
 149 or
 150 .Fn gethostbyaddr .
 151 Otherwise, queries are performed using UDP datagrams.
 152 .Pp
 153 .Fn Endhostent
 154 closes the TCP connection.
 155 .Sh ENVIRONMENT
 156 .Bl -tag -width "HOSTALIASES  " -compact
 157 .It Ev HOSTALIASES
 158 Name of file containing
 159 .Pq Ar host alias , full hostname
 160 pairs.
 161 .El
 162 .Sh FILES
 163 .Bl -tag -width "HOSTALIASES  " -compact
 164 .It Pa /etc/hosts
 165 See
 166 .Xr hosts 5 .
 167 .El
 168 .Sh DIAGNOSTICS
 169 .Pp
 170 Error return status from
 171 .Fn gethostbyname
 172 and
 173 .Fn gethostbyaddr
 174 is indicated by return of a null pointer.
 175 The external integer
 176 .Ft h_errno
 177 may then be checked to see whether this is a temporary failure
 178 or an invalid or unknown host.
 179 The routine
 180 .Fn herror
 181 can be used to print an error message describing the failure.
 182 If its argument
 183 .Fa string
 184 is non-NULL, it is printed, followed by a colon and a space.
 185 The error message is printed with a trailing newline.
 186 .Pp
 187 .Ft h_errno
 188 can have the following values:
 189 .Bl -tag -width "HOST_NOT_FOUND  " -offset indent
 190 .It Dv NETDB_INTERNAL
 191 This indicates an internal error in the library, unrelated to the network
 192 or name service.
 193 .Ft errno
 194 will be valid in this case; see
 195 .Xr perror  .
 196 .It Dv HOST_NOT_FOUND
 197 No such host is known.
 198 .It Dv TRY_AGAIN
 199 This is usually a temporary error
 200 and means that the local server did not receive
 201 a response from an authoritative server.
 202 A retry at some later time may succeed.
 203 .It Dv NO_RECOVERY
 204 Some unexpected server failure was encountered.
 205 This is a non-recoverable error, as one might expect.
 206 .It Dv NO_DATA
 207 The requested name is valid but does not have an IP address;
 208 this is not a temporary error.
 209 This means that the name is known to the name server but there is no address
 210 associated with this name.
 211 Another type of request to the name server using this domain name
 212 will result in an answer;
 213 for 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
 223 is defined, and
 224 .Fn sethostent
 225 and
 226 .Fn endhostent
 227 are redefined,
 228 when
 229 .Pa libc
 230 is built to use only the routines to lookup in
 231 .Pa /etc/hosts
 232 and not the name server:
 233 .Bd -ragged -offset indent
 234 .Pp
 235 .Fn Gethostent
 236 reads the next line of
 237 .Pa /etc/hosts ,
 238 opening the file if necessary.
 239 .Pp
 240 .Fn Sethostent
 241 is redefined to open and rewind the file.  If the
 242 .Fa stayopen
 243 argument is non-zero,
 244 the hosts data base will not be closed after each call to
 245 .Fn gethostbyname
 246 or
 247 .Fn gethostbyaddr .
 248 .Pp
 249 .Fn Endhostent
 250 is redefined to close the file.
 251 .Ed
 252 .Sh BUGS
 253 All information is contained in a static area so it must be copied if it is
 254 to be saved.  Only the Internet address format is currently understood.