man/man3/g_h_b_n.3

   1 .\" Copyright (c) 1983, 1987 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms are permitted provided
   5 .\" that: (1) source distributions retain this entire copyright notice and
   6 .\" comment, and (2) distributions including binaries display the following
   7 .\" acknowledgement:  ``This product includes software developed by the
   8 .\" University of California, Berkeley and its contributors'' in the
   9 .\" documentation or other materials provided with the distribution and in
  10 .\" all advertising materials mentioning features or use of this software.
  11 .\" Neither the name of the University nor the names of its contributors may
  12 .\" be used to endorse or promote products derived from this software without
  13 .\" specific prior written permission.
  14 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
  15 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  16 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  17 .\"
  18 .\"     @(#)gethostbyname.3     6.12 (Berkeley) 6/23/90
  19 .\"
  20 .TH GETHOSTBYNAME 3 "June 23, 1990"
  21 .UC 5
  22 .SH NAME
  23 g_h_b_n, gethostbyname, gethostbyaddr, gethostent, sethostent, endhostent, herror \- get network host entry
  24 .SH SYNOPSIS
  25 .B "#include <net/gen/netdb.h>
  26 .PP
  27 .B "extern int h_errno;
  28 .PP
  29 .B "struct hostent *gethostbyname(name)
  30 .br
  31 .B "char *name;
  32 .PP
  33 .B "struct hostent *gethostbyaddr(addr, len, type)
  34 .br
  35 .B "char *addr; int len, type;
  36 .PP
  37 .B "struct hostent *gethostent()
  38 .PP
  39 .B "sethostent(stayopen)
  40 .br
  41 .B "int stayopen;
  42 .PP
  43 .B "endhostent()
  44 .PP
  45 .B "herror(string)
  46 .br
  47 .B "char *string;
  48 .PP
  49 .SH DESCRIPTION
  50 .I Gethostbyname
  51 and
  52 .I gethostbyaddr
  53 each return a pointer to an object with the
  54 following structure describing an internet host
  55 referenced by name or by address, respectively.
  56 This structure contains the information obtained from the name server.
  57 .PP
  58 .nf
  59 struct  hostent {
  60         char    *h_name;        /* official name of host */
  61         char    **h_aliases;    /* alias list */
  62         int     h_addrtype;     /* host address type */
  63         int     h_length;       /* length of address */
  64         char    **h_addr_list;  /* list of addresses from name server */
  65 };
  66 #define h_addr  h_addr_list[0]  /* address, for backward compatibility */
  67 .ft R
  68 .ad
  69 .fi
  70 .PP
  71 The members of this structure are:
  72 .TP \w'h_addr_list'u+2n
  73 h_name
  74 Official name of the host.
  75 .TP \w'h_addr_list'u+2n
  76 h_aliases
  77 A zero terminated array of alternate names for the host.
  78 .TP \w'h_addr_list'u+2n
  79 h_addrtype
  80 The type of address being returned; currently always AF_INET.
  81 .TP \w'h_addr_list'u+2n
  82 h_length
  83 The length, in bytes, of the address.
  84 .TP \w'h_addr_list'u+2n
  85 h_addr_list
  86 A zero terminated array of network addresses for the host.
  87 Host addresses are returned in network byte order.
  88 .TP \w'h_addr_list'u+2n
  89 h_addr
  90 The first address in h_addr_list; this is for backward compatiblity.
  91 .PP
  92 When using the nameserver,
  93 .I gethostbyname
  94 will search for the named host in the current domain and its parents
  95 unless the name ends in a dot.
  96 If the name contains no dot, and if the environment variable ``HOSTALAIASES''
  97 contains the name of an alias file, the alias file will first be searched
  98 for an alias matching the input name.
  99 See
 100 .IR hostname (7)
 101 for the domain search procedure and the alias file format.
 102 .PP
 103 .I Sethostent
 104 may be used to request the use of a connected TCP socket for queries.
 105 If the
 106 .I stayopen
 107 flag is non-zero,
 108 this sets the option to send all queries to the name server using TCP
 109 and to retain the connection after each call to
 110 .I gethostbyname
 111 or
 112 .IR gethostbyaddr .
 113 Otherwise, queries are performed using UDP datagrams.
 114 .PP
 115 .I Endhostent
 116 closes the TCP connection.
 117 .SH DIAGNOSTICS
 118 .PP
 119 Error return status from
 120 .I gethostbyname
 121 and
 122 .I gethostbyaddr
 123 is indicated by return of a null pointer.
 124 The external integer
 125 .IR h_errno
 126 may then be checked to see whether this is a temporary failure
 127 or an invalid or unknown host.
 128 The routine
 129 .I herror
 130 can be used to print an error message describing the failure.
 131 If its argument
 132 .I string
 133 is non-NULL, it is printed, followed by a colon and a space.
 134 The error message is printed with a trailing newline.
 135 .PP
 136 .IR h_errno
 137 can have the following values:
 138 .RS
 139 .IP HOST_NOT_FOUND \w'HOST_NOT_FOUND'u+2n
 140 No such host is known.
 141 .IP TRY_AGAIN \w'HOST_NOT_FOUND'u+2n
 142 This is usually a temporary error
 143 and means that the local server did not receive
 144 a response from an authoritative server.
 145 A retry at some later time may succeed.
 146 .IP NO_RECOVERY \w'HOST_NOT_FOUND'u+2n
 147 Some unexpected server failure was encountered.
 148 This is a non-recoverable error.
 149 .IP NO_DATA \w'HOST_NOT_FOUND'u+2n
 150 The requested name is valid but does not have an IP address;
 151 this is not a temporary error.
 152 This means that the name is known to the name server but there is no address
 153 associated with this name.
 154 Another type of request to the name server using this domain name
 155 will result in an answer;
 156 for example, a mail-forwarder may be registered for this domain.
 157 .RE
 158 .SH "SEE ALSO"
 159 resolver(3), hostname(7), nonamed(8), named(8)
 160 .SH BUGS
 161 All information
 162 is contained in a static area
 163 so it must be copied if it is
 164 to be saved.  Only the Internet
 165 address format is currently understood.