lib/libc/net/gethostbyname.3

   1 .\" Copyright (c) 1983, 1987, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .Dd June 27, 2022
  29 .Dt GETHOSTBYNAME 3
  30 .Os
  31 .Sh NAME
  32 .Nm gethostbyname ,
  33 .Nm gethostbyname2 ,
  34 .Nm gethostbyaddr ,
  35 .Nm gethostent ,
  36 .Nm sethostent ,
  37 .Nm endhostent ,
  38 .Nm herror ,
  39 .Nm hstrerror ,
  40 .Nm gethostbyname_r ,
  41 .Nm gethostbyname2_r ,
  42 .Nm gethostbyaddr_r
  43 .Nd get network host entry
  44 .Sh LIBRARY
  45 .Lb libc
  46 .Sh SYNOPSIS
  47 .In netdb.h
  48 .Vt int h_errno ;
  49 .Ft struct hostent *
  50 .Fn gethostbyname "const char *name"
  51 .Ft struct hostent *
  52 .Fn gethostbyname2 "const char *name" "int af"
  53 .Ft struct hostent *
  54 .Fn gethostbyaddr "const void *addr" "socklen_t len" "int af"
  55 .Ft struct hostent *
  56 .Fn gethostent void
  57 .Ft void
  58 .Fn sethostent "int stayopen"
  59 .Ft void
  60 .Fn endhostent void
  61 .Ft void
  62 .Fn herror "const char *string"
  63 .Ft const char *
  64 .Fn hstrerror "int err"
  65 .Ft int
  66 .Fn gethostbyname_r "const char *name" "struct hostent *he" "char *buffer" "size_t buflen" "struct hostent **result" "int *h_errnop"
  67 .Ft int
  68 .Fn gethostbyname2_r "const char *name" "int af" "struct hostent *he" "char *buffer" "size_t buflen" "struct hostent **result" "int *h_errnop"
  69 .Ft int
  70 .Fn gethostbyaddr_r "const void *addr" "socklen_t len" "int af" "struct hostent *hp" "char *buf" "size_t buflen" "struct hostent **result" "int *h_errno"p
  71 .Sh DESCRIPTION
  72 .Bf -symbolic
  73 The
  74 .Xr getaddrinfo 3
  75 and
  76 .Xr getnameinfo 3
  77 functions are preferred over the
  78 .Fn gethostbyname ,
  79 .Fn gethostbyname2 ,
  80 and
  81 .Fn gethostbyaddr
  82 functions.
  83 .Ef
  84 .Pp
  85 The
  86 .Fn gethostbyname ,
  87 .Fn gethostbyname2
  88 and
  89 .Fn gethostbyaddr
  90 functions
  91 each return a pointer to an object with the
  92 following structure describing an internet host
  93 referenced by name or by address, respectively.
  94 .Pp
  95 The
  96 .Fa name
  97 argument passed to
  98 .Fn gethostbyname
  99 or
 100 .Fn gethostbyname2
 101 should point to a
 102 .Dv NUL Ns -terminated
 103 hostname.
 104 The
 105 .Fa addr
 106 argument passed to
 107 .Fn gethostbyaddr
 108 should point to an address which is
 109 .Fa len
 110 bytes long,
 111 in binary form
 112 (i.e., not an IP address in human readable
 113 .Tn ASCII
 114 form).
 115 The
 116 .Fa af
 117 argument specifies the address family
 118 (e.g.\&
 119 .Dv AF_INET , AF_INET6 ,
 120 etc.) of this address.
 121 .Pp
 122 The structure returned contains either the information obtained from the name
 123 server, broken-out fields from a line in
 124 .Pa /etc/hosts ,
 125 or database entries supplied by the
 126 .Xr yp 8
 127 system.
 128 The order of the lookups is controlled by the
 129 .Sq hosts
 130 entry in
 131 .Xr nsswitch.conf 5 .
 132 .Bd -literal
 133 struct  hostent {
 134         char    *h_name;        /* official name of host */
 135         char    **h_aliases;    /* alias list */
 136         int     h_addrtype;     /* host address type */
 137         int     h_length;       /* length of address */
 138         char    **h_addr_list;  /* list of addresses from name server */
 139 };
 140 #define h_addr  h_addr_list[0]  /* address, for backward compatibility */
 141 .Ed
 142 .Pp
 143 The members of this structure are:
 144 .Bl -tag -width h_addr_list
 145 .It Va h_name
 146 Official name of the host.
 147 .It Va h_aliases
 148 A
 149 .Dv NULL Ns -terminated
 150 array of alternate names for the host.
 151 .It Va h_addrtype
 152 The type of address being returned; usually
 153 .Dv AF_INET .
 154 .It Va h_length
 155 The length, in bytes, of the address.
 156 .It Va h_addr_list
 157 A
 158 .Dv NULL Ns -terminated
 159 array of network addresses for the host.
 160 Host addresses are returned in network byte order.
 161 .It Va h_addr
 162 The first address in
 163 .Va h_addr_list ;
 164 this is for backward compatibility.
 165 .El
 166 .Pp
 167 When using the nameserver,
 168 .Fn gethostbyname
 169 and
 170 .Fn gethostbyname2
 171 will search for the named host in the current domain and its parents
 172 unless the name ends in a dot.
 173 If the name contains no dot, and if the environment variable
 174 .Dq Ev HOSTALIASES
 175 contains the name of an alias file, the alias file will first be searched
 176 for an alias matching the input name.
 177 See
 178 .Xr hostname 7
 179 for the domain search procedure and the alias file format.
 180 .Pp
 181 The
 182 .Fn gethostbyname2
 183 function is an evolution of
 184 .Fn gethostbyname
 185 which is intended to allow lookups in address families other than
 186 .Dv AF_INET ,
 187 for example
 188 .Dv AF_INET6 .
 189 .Pp
 190 The
 191 .Fn sethostent
 192 function
 193 may be used to request the use of a connected
 194 .Tn TCP
 195 socket for queries.
 196 Queries will by default use
 197 .Tn UDP
 198 datagrams.
 199 If the
 200 .Fa stayopen
 201 flag is non-zero, a
 202 .Tn TCP
 203 connection to the name server will be used.
 204 It will remain open after calls to
 205 .Fn gethostbyname ,
 206 .Fn gethostbyname2
 207 or
 208 .Fn gethostbyaddr
 209 have completed.
 210 .Pp
 211 The
 212 .Fn endhostent
 213 function
 214 closes the
 215 .Tn TCP
 216 connection.
 217 .Pp
 218 The
 219 .Fn herror
 220 function writes a message to the diagnostic output consisting of the
 221 string argument
 222 .Fa string ,
 223 the constant string
 224 .Qq Li ":\ " ,
 225 and a message corresponding to the value of
 226 .Va h_errno .
 227 .Pp
 228 The
 229 .Fn hstrerror
 230 function returns a string which is the message text corresponding to the
 231 value of the
 232 .Fa err
 233 argument.
 234 .Pp
 235 Functions with the
 236 .Em _r
 237 suffix provide reentrant versions of their respective counterparts.
 238 The caller must supply five additional parameters: a
 239 .Vt struct hostent
 240 variable to be filled on success, a
 241 .Va buffer
 242 of
 243 .Va buflen
 244 bytes in size, a
 245 .Vt struct hostent
 246 .Va result
 247 variable that will point to the result on success or be set to
 248 .Dv NULL
 249 on failure or if the name is not found.
 250 The
 251 .Va h_errnop
 252 variable will be filled with the error code if any.
 253 All these functions return 0 on success.
 254 .Sh FILES
 255 .Bl -tag -width /etc/nsswitch.conf -compact
 256 .It Pa /etc/hosts
 257 .It Pa /etc/nsswitch.conf
 258 .It Pa /etc/resolv.conf
 259 .El
 260 .Sh EXAMPLES
 261 Print out the hostname associated with a specific IP address:
 262 .Bd -literal -offset indent
 263 const char *ipstr = "127.0.0.1";
 264 struct in_addr ip;
 265 struct hostent *hp;
 266
 267 if (!inet_aton(ipstr, &ip))
 268         errx(1, "can't parse IP address %s", ipstr);
 269
 270 if ((hp = gethostbyaddr((const void *)&ip,
 271     sizeof ip, AF_INET)) == NULL)
 272         errx(1, "no name associated with %s", ipstr);
 273
 274 printf("name associated with %s is %s\en", ipstr, hp->h_name);
 275 .Ed
 276 .Sh DIAGNOSTICS
 277 Error return status from
 278 .Fn gethostbyname ,
 279 .Fn gethostbyname2
 280 and
 281 .Fn gethostbyaddr
 282 is indicated by return of a
 283 .Dv NULL
 284 pointer.
 285 The integer
 286 .Va h_errno
 287 may then be checked to see whether this is a temporary failure
 288 or an invalid or unknown host.
 289 The routine
 290 .Fn herror
 291 can be used to print an error message describing the failure.
 292 If its argument
 293 .Fa string
 294 is
 295 .Pf non- Dv NULL ,
 296 it is printed, followed by a colon and a space.
 297 The error message is printed with a trailing newline.
 298 .Pp
 299 The variable
 300 .Va h_errno
 301 can have the following values:
 302 .Bl -tag -width HOST_NOT_FOUND
 303 .It Dv HOST_NOT_FOUND
 304 No such host is known.
 305 .It Dv TRY_AGAIN
 306 This is usually a temporary error
 307 and means that the local server did not receive
 308 a response from an authoritative server.
 309 A retry at some later time may succeed.
 310 .It Dv NO_RECOVERY
 311 Some unexpected server failure was encountered.
 312 This is a non-recoverable error.
 313 .It Dv NO_DATA
 314 The requested name is valid but does not have an IP address;
 315 this is not a temporary error.
 316 This means that the name is known to the name server but there is no address
 317 associated with this name.
 318 Another type of request to the name server using this domain name
 319 will result in an answer;
 320 for example, a mail-forwarder may be registered for this domain.
 321 .El
 322 .Sh SEE ALSO
 323 .Xr getaddrinfo 3 ,
 324 .Xr getnameinfo 3 ,
 325 .Xr inet_aton 3 ,
 326 .Xr resolver 3 ,
 327 .Xr hosts 5 ,
 328 .Xr hostname 7
 329 .Sh HISTORY
 330 The
 331 .Fn herror
 332 function appeared in
 333 .Bx 4.3 .
 334 The
 335 .Fn endhostent ,
 336 .Fn gethostbyaddr ,
 337 .Fn gethostbyname ,
 338 .Fn gethostent ,
 339 and
 340 .Fn sethostent
 341 functions appeared in
 342 .Bx 4.2 .
 343 The
 344 .Fn gethostbyname2
 345 function first appeared in
 346 .Tn BIND
 347 version 4.9.4.
 348 The
 349 .Fn gethostbyname_r
 350 function first appeared in
 351 .Fx 6.2 .
 352 .Sh CAVEATS
 353 The
 354 .Fn gethostent
 355 function
 356 is defined, and
 357 .Fn sethostent
 358 and
 359 .Fn endhostent
 360 are redefined,
 361 when
 362 .Lb libc
 363 is built to use only the routines to lookup in
 364 .Pa /etc/hosts
 365 and not the name server.
 366 .Pp
 367 The
 368 .Fn gethostent
 369 function
 370 reads the next line of
 371 .Pa /etc/hosts ,
 372 opening the file if necessary.
 373 .Pp
 374 The
 375 .Fn sethostent
 376 function
 377 opens and/or rewinds the file
 378 .Pa /etc/hosts .
 379 If the
 380 .Fa stayopen
 381 argument is non-zero,
 382 the file will not be closed after each call to
 383 .Fn gethostbyname ,
 384 .Fn gethostbyname2
 385 or
 386 .Fn gethostbyaddr .
 387 .Pp
 388 The
 389 .Fn endhostent
 390 function
 391 closes the file.
 392 .Sh BUGS
 393 These functions use a thread-specific data storage;
 394 if the data is needed for future use, it should be
 395 copied before any subsequent calls overwrite it.
 396 .Pp
 397 Though these functions are thread-safe,
 398 still it is recommended to use the
 399 .Xr getaddrinfo 3
 400 family of functions, instead.
 401 .Pp
 402 Only the Internet
 403 address format is currently understood.