original/man3/getipnodebyname.3

   1 .\" Copyright 2000 Sam Varshavchik <mrsam@courier-mta.com>
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" References: RFC 2553
  26 .TH GETIPNODEBYNAME 3 2010-09-04 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 getipnodebyname, getipnodebyaddr, freehostent \- get network
  29 hostnames and addresses
  30 .SH SYNOPSIS
  31 .nf
  32 .B #include <sys/types.h>
  33 .B #include <sys/socket.h>
  34 .B #include <netdb.h>
  35 .sp
  36 .BI "struct hostent *getipnodebyname(const char *" name ", int " af ,
  37 .BI "                                int " flags ", int *" error_num );
  38 .sp
  39 .BI "struct hostent *getipnodebyaddr(const void *" addr ", size_t " len ,
  40 .BI "                                int " af ", int *" "error_num" );
  41 .sp
  42 .BI "void freehostent(struct hostent *" "ip" );
  43 .fi
  44 .SH DESCRIPTION
  45 These functions are deprecated (and unavailable in glibc).
  46 Use
  47 .BR getaddrinfo (3)
  48 and
  49 .BR getnameinfo (3)
  50 instead.
  51 .LP
  52 The
  53 .BR getipnodebyname ()
  54 and
  55 .BR getipnodebyaddr ()
  56 functions return the names and addresses of a network host.
  57 These functions return a pointer to the
  58 following structure:
  59 .sp
  60 .in +4n
  61 .nf
  62 struct hostent {
  63     char  *h_name;
  64     char **h_aliases;
  65     int    h_addrtype;
  66     int    h_length;
  67     char **h_addr_list;
  68 };
  69 .in
  70 .fi
  71 .PP
  72 These functions replace the
  73 .BR gethostbyname (3)
  74 and
  75 .BR gethostbyaddr (3)
  76 functions, which could access only the IPv4 network address family.
  77 The
  78 .BR getipnodebyname ()
  79 and
  80 .BR getipnodebyaddr ()
  81 functions can access multiple network address families.
  82 .PP
  83 Unlike the
  84 .B gethostby
  85 functions,
  86 these functions return pointers to dynamically allocated memory.
  87 The
  88 .BR freehostent ()
  89 function is used to release the dynamically allocated memory
  90 after the caller no longer needs the
  91 .I hostent
  92 structure.
  93 .SS getipnodebyname() arguments
  94 The
  95 .BR getipnodebyname ()
  96 function
  97 looks up network addresses for the host
  98 specified by the
  99 .I name
 100 argument.
 101 The
 102 .I af
 103 argument specifies one of the following values:
 104 .TP
 105 .B AF_INET
 106 The
 107 .I name
 108 argument points to a dotted-quad IPv4 address or a name
 109 of an IPv4 network host.
 110 .TP
 111 .B AF_INET6
 112 The
 113 .I name
 114 argument points to a hexadecimal IPv6 address or a name
 115 of an IPv6 network host.
 116 .PP
 117 The
 118 .I flags
 119 argument specifies additional options.
 120 More than one option can be specified by bitwise OR-ing
 121 them together.
 122 .I flags
 123 should be set to 0
 124 if no options are desired.
 125 .TP
 126 .B AI_V4MAPPED
 127 This flag is used with
 128 .B AF_INET6
 129 to request a query for IPv4 addresses instead of
 130 IPv6 addresses; the IPv4 addresses will
 131 be mapped to IPv6 addresses.
 132 .TP
 133 .B AI_ALL
 134 This flag is used with
 135 .B AI_V4MAPPED
 136 to request a query for both IPv4 and IPv6 addresses.
 137 Any IPv4 address found will be mapped to an IPv6 address.
 138 .TP
 139 .B AI_ADDRCONFIG
 140 This flag is used with
 141 .B AF_INET6
 142 to
 143 further request that queries for IPv6 addresses should not be made unless
 144 the system has at least one IPv6 address assigned to a network interface,
 145 and that queries for IPv4 addresses should not be made unless the
 146 system has at least one IPv4 address assigned to a network interface.
 147 This flag may be used by itself or with the
 148 .B AI_V4MAPPED
 149 flag.
 150 .TP
 151 .B AI_DEFAULT
 152 This flag is equivalent to
 153 .BR "(AI_ADDRCONFIG | AI_V4MAPPED)" .
 154 .SS getipnodebyaddr() arguments
 155 The
 156 .BR getipnodebyaddr ()
 157 function
 158 looks up the name of the host whose
 159 network address is
 160 specified by the
 161 .I addr
 162 argument.
 163 The
 164 .I af
 165 argument specifies one of the following values:
 166 .TP
 167 .B AF_INET
 168 The
 169 .I addr
 170 argument points to a
 171 .I struct in_addr
 172 and
 173 .I len
 174 must be set to
 175 .IR "sizeof(struct in_addr)" .
 176 .TP
 177 .B AF_INET6
 178 The
 179 .I addr
 180 argument points to a
 181 .I struct in6_addr
 182 and
 183 .I len
 184 must be set to
 185 .IR "sizeof(struct in6_addr)" .
 186 .SH RETURN VALUE
 187 NULL is returned if an error occurred, and
 188 .I error_num
 189 will contain an error code from the following list:
 190 .TP
 191 .B HOST_NOT_FOUND
 192 The hostname or network address was not found.
 193 .TP
 194 .B NO_ADDRESS
 195 The domain name server recognized the network address or name,
 196 but no answer was returned.
 197 This can happen if the network host has only IPv4 addresses and
 198 a request has been made for IPv6 information only, or vice versa.
 199 .TP
 200 .B NO_RECOVERY
 201 The domain name server returned a permanent failure response.
 202 .TP
 203 .B TRY_AGAIN
 204 The domain name server returned a temporary failure response.
 205 You might have better luck next time.
 206 .PP
 207 A successful query returns a pointer to a
 208 .I hostent
 209 structure that contains the following fields:
 210 .TP
 211 .I h_name
 212 This is the official name of this network host.
 213 .TP
 214 .I h_aliases
 215 This is an array of pointers to unofficial aliases for the same host.
 216 The array is terminated by a null pointer.
 217 .TP
 218 .I h_addrtype
 219 This is a copy of the
 220 .I af
 221 argument to
 222 .BR getipnodebyname ()
 223 or
 224 .BR getipnodebyaddr ().
 225 .I h_addrtype
 226 will always be
 227 .B AF_INET
 228 if the
 229 .I af
 230 argument was
 231 .BR AF_INET .
 232 .I h_addrtype
 233 will always be
 234 .B AF_INET6
 235 if the
 236 .I af
 237 argument was
 238 .BR AF_INET6 .
 239 .TP
 240 .I h_length
 241 This field will be set to
 242 .I sizeof(struct in_addr)
 243 if
 244 .I h_addrtype
 245 is
 246 .BR AF_INET ,
 247 and to
 248 .I sizeof(struct in6_addr)
 249 if
 250 .I h_addrtype
 251 is
 252 .BR AF_INET6 .
 253 .TP
 254 .I h_addr_list
 255 This is an array of one or more pointers to network address structures for the
 256 network host.
 257 The array is terminated by a null pointer.
 258 .SH CONFORMING TO
 259 RFC\ 2553.
 260 .\" Not in POSIX.1-2001.
 261 .SH NOTES
 262 These functions were present in glibc 2.1.91-95, but were
 263 removed again.
 264 Several UNIX-like systems support them, but all
 265 call them deprecated.
 266 .SH SEE ALSO
 267 .BR getaddrinfo (3),
 268 .BR getnameinfo (3),
 269 .BR inet_ntop (3),
 270 .BR inet_pton (3)
 271 .SH COLOPHON
 272 This page is part of release 3.77 of the Linux
 273 .I man-pages
 274 project.
 275 A description of the project,
 276 information about reporting bugs,
 277 and the latest version of this page,
 278 can be found at
 279 \%http://www.kernel.org/doc/man\-pages/.