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

   1 .\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")
   2 .\" Copyright (c) 1996,1999 by Internet Software Consortium
   3 .\"
   4 .\" Permission to use, copy, modify, and distribute this software for any
   5 .\" purpose with or without fee is hereby granted, provided that the above
   6 .\" copyright notice and this permission notice appear in all copies.
   7 .\"
   8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
   9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  10 .\" MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR
  11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
  14 .\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  15 .\"
  16 .\" Copyright (c) 1983, 1987 The Regents of the University of California.
  17 .\" All rights reserved.
  18 .\"
  19 .\" Redistribution and use in source and binary forms are permitted provided
  20 .\" that: (1) source distributions retain this entire copyright notice and
  21 .\" comment, and (2) distributions including binaries display the following
  22 .\" acknowledgement:  ``This product includes software developed by the
  23 .\" University of California, Berkeley and its contributors'' in the
  24 .\" documentation or other materials provided with the distribution and in
  25 .\" all advertising materials mentioning features or use of this software.
  26 .\" Neither the name of the University nor the names of its contributors may
  27 .\" be used to endorse or promote products derived from this software without
  28 .\" specific prior written permission.
  29 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
  30 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  31 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  32 .\"
  33 .Dd September 17, 1999
  34 .Dt GETIPNODEBYNAME 3
  35 .Os BSD 4
  36 .Sh NAME
  37 .Nm getipnodebyname ,
  38 .Nm getipnodebyaddr
  39 .Nd get network host entry
  40 .br
  41 .Nm freehostent
  42 .Nd free network host entry
  43 .Sh SYNOPSIS
  44 .Fd #include <netdb.h>
  45 .Pp
  46 .Ft struct hostent *
  47 .Fn getipnodebyname "const char *name" "int af" "int flags" "int *error"
  48 .Ft struct hostent *
  49 .Fn getipnodebyaddr "const void *addr" "size_t len" "int af" "int *error"
  50 .Ft void
  51 .Fn freehostent "struct hostent *he"
  52 .Sh DESCRIPTION
  53 .Fn Getipnodebyname ,
  54 and
  55 .Fn getipnodebyaddr
  56 each return a pointer to a
  57 .Ft hostent
  58 structure (see below) describing an internet host
  59 referenced by name or by address, as the function names indicate.
  60 This structure contains either the information obtained from the name server,
  61 or broken-out fields from a line in
  62 .Pa /etc/hosts .
  63 If the local name server is not running, these routines do a lookup in
  64 .Pa /etc/hosts .
  65 .Bd -literal -offset indent
  66 struct  hostent {
  67         char    *h_name;        /* official name of host */
  68         char    **h_aliases;    /* alias list */
  69         int     h_addrtype;     /* host address type */
  70         int     h_length;       /* length of address */
  71         char    **h_addr_list;  /* list of addresses from name server */
  72 };
  73
  74 #define h_addr  h_addr_list[0]  /* address, for backward compatibility */
  75 .Ed
  76 .Pp
  77 The members of this structure are:
  78 .Bl -tag -width "h_addr_list"
  79 .It h_name
  80 Official name of the host.
  81 .It h_aliases
  82 A zero-terminated array of alternate names for the host.
  83 .It h_addrtype
  84 The type of address being returned.
  85 .It h_length
  86 The length, in bytes, of the address.
  87 .It h_addr_list
  88 A zero-terminated array of network addresses for the host.
  89 Host addresses are returned in network byte order.
  90 .It h_addr
  91 The first address in
  92 .Li h_addr_list ;
  93 this is for backward compatibility.
  94 .El
  95 .Pp
  96 This structure should be freed after use by calling
  97 .Fn freehostent .
  98 .Pp
  99 When using the nameserver,
 100 .Fn getiphostbyaddr
 101 will search for the named host in each parent domain given in the
 102 .Dq Li search
 103 directive of
 104 .Xr resolv.conf 5
 105 unless the name contains a dot
 106 .Pq Dq \&. .
 107 If the name contains no dot, and if the environment variable
 108 .Ev HOSTALIASES
 109 contains the name of an alias file, the alias file will first be searched
 110 for an alias matching the input name.
 111 See
 112 .Xr hostname 7
 113 for the domain search procedure and the alias file format.
 114 .Pp
 115 .Fn Getiphostbyaddr
 116 can be told to look for IPv4 addresses, IPv6 addresses or both IPv4 and IPv6.
 117 If IPv4 addresses only are to be looked up then
 118 .Fa af
 119 should be set to
 120 .Dv AF_INET ,
 121 otherwise it should be set to
 122 .Dv AF_INET6 .
 123 .Pp
 124 There are three flags that can be set
 125 .Bl -tag -width "AI_ADDRCONFIG"
 126 .It Dv AI_V4MAPPED
 127 Return IPv4 addresses if no IPv6 addresses are found.
 128 This flag is ignored unless
 129 .Fa af
 130 is
 131 .Dv AF_INET6 .
 132 .It Dv AI_ALL
 133 Return IPv4 addresses as well IPv6 addresses if
 134 .Dv AI_V4MAPPED
 135 is set.
 136 This flag is ignored unless
 137 .Fa af
 138 is
 139 .Dv AF_INET6 .
 140 .It Dv AI_ADDRCONFIG
 141 Only return addresses of a given type if the system has an active interface
 142 with that type.
 143 .El
 144 .Pp
 145 Also
 146 .Dv AI_DEFAULT
 147 is defined to be
 148 .Dv (AI_V4MAPPED|AI_ADDRCONFIG) .
 149 .Pp
 150 .Fn Getipnodebyaddr
 151 will lookup IPv4 mapped and compatible addresses in the IPv4 name
 152 space and IPv6 name space
 153 .Pp
 154 .Fn Freehostent
 155 frees the hostent structure allocated be
 156 .Fn getipnodebyname
 157 and
 158 .Fn getipnodebyaddr .
 159 The structures returned by
 160 .Fn gethostbyname ,
 161 .Fn gethostbyname2 ,
 162 .Fn gethostbyaddr
 163 and
 164 .Fn gethostent
 165 should not be passed to
 166 .Fn freehostent
 167 as they are pointers to static areas.
 168 .Sh ENVIRONMENT
 169 .Bl -tag -width "HOSTALIASES  " -compact
 170 .It Ev HOSTALIASES
 171 Name of file containing
 172 .Pq Ar host alias , full hostname
 173 pairs.
 174 .El
 175 .Sh FILES
 176 .Bl -tag -width "HOSTALIASES  " -compact
 177 .It Pa /etc/hosts
 178 See
 179 .Xr hosts 5 .
 180 .El
 181 .Sh DIAGNOSTICS
 182 .Pp
 183 Error return status from
 184 .Fn getipnodebyname
 185 and
 186 .Fn getipnodebyaddr
 187 is indicated by return of a null pointer.
 188 In this case
 189 .Ft error
 190 may then be checked to see whether this is a temporary failure
 191 or an invalid or unknown host.
 192 .Ft errno
 193 can have the following values:
 194 .Bl -tag -width "HOST_NOT_FOUND  " -offset indent
 195 .It Dv NETDB_INTERNAL
 196 This indicates an internal error in the library, unrelated to the network
 197 or name service.
 198 .Ft errno
 199 will be valid in this case; see
 200 .Xr perror  .
 201 .It Dv HOST_NOT_FOUND
 202 No such host is known.
 203 .It Dv TRY_AGAIN
 204 This is usually a temporary error
 205 and means that the local server did not receive
 206 a response from an authoritative server.
 207 A retry at some later time may succeed.
 208 .It Dv NO_RECOVERY
 209 Some unexpected server failure was encountered.
 210 This is a non-recoverable error, as one might expect.
 211 .It Dv NO_ADDRESS
 212 The requested name is valid but does not have an IP address;
 213 this is not a temporary error.
 214 This means that the name is known to the name server but there is no address
 215 associated with this name.
 216 Another type of request to the name server using this domain name
 217 will result in an answer;
 218 for example, a mail-forwarder may be registered for this domain.
 219 .El
 220 .Sh SEE ALSO
 221 .Xr hosts 5 ,
 222 .Xr hostname 7 ,
 223 .Xr resolver 3 ,
 224 .Xr resolver 5 ,
 225 .Xr gethostbyname 3 ,
 226 .Xr RFC2553 .