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 2021-03-22 "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 .PP
  36 .BI "struct hostent *getipnodebyname(const char *" name ", int " af ,
  37 .BI "                                int " flags ", int *" error_num );
  38 .BI "struct hostent *getipnodebyaddr(const void *" addr ", size_t " len ,
  39 .BI "                                int " af ", int *" "error_num" );
  40 .BI "void freehostent(struct hostent *" "ip" );
  41 .fi
  42 .SH DESCRIPTION
  43 These functions are deprecated (and unavailable in glibc).
  44 Use
  45 .BR getaddrinfo (3)
  46 and
  47 .BR getnameinfo (3)
  48 instead.
  49 .PP
  50 The
  51 .BR getipnodebyname ()
  52 and
  53 .BR getipnodebyaddr ()
  54 functions return the names and addresses of a network host.
  55 These functions return a pointer to the
  56 following structure:
  57 .PP
  58 .in +4n
  59 .EX
  60 struct hostent {
  61     char  *h_name;
  62     char **h_aliases;
  63     int    h_addrtype;
  64     int    h_length;
  65     char **h_addr_list;
  66 };
  67 .EE
  68 .in
  69 .PP
  70 These functions replace the
  71 .BR gethostbyname (3)
  72 and
  73 .BR gethostbyaddr (3)
  74 functions, which could access only the IPv4 network address family.
  75 The
  76 .BR getipnodebyname ()
  77 and
  78 .BR getipnodebyaddr ()
  79 functions can access multiple network address families.
  80 .PP
  81 Unlike the
  82 .B gethostby
  83 functions,
  84 these functions return pointers to dynamically allocated memory.
  85 The
  86 .BR freehostent ()
  87 function is used to release the dynamically allocated memory
  88 after the caller no longer needs the
  89 .I hostent
  90 structure.
  91 .SS getipnodebyname() arguments
  92 The
  93 .BR getipnodebyname ()
  94 function
  95 looks up network addresses for the host
  96 specified by the
  97 .I name
  98 argument.
  99 The
 100 .I af
 101 argument specifies one of the following values:
 102 .TP
 103 .B AF_INET
 104 The
 105 .I name
 106 argument points to a dotted-quad IPv4 address or a name
 107 of an IPv4 network host.
 108 .TP
 109 .B AF_INET6
 110 The
 111 .I name
 112 argument points to a hexadecimal IPv6 address or a name
 113 of an IPv6 network host.
 114 .PP
 115 The
 116 .I flags
 117 argument specifies additional options.
 118 More than one option can be specified by bitwise OR-ing
 119 them together.
 120 .I flags
 121 should be set to 0
 122 if no options are desired.
 123 .TP
 124 .B AI_V4MAPPED
 125 This flag is used with
 126 .B AF_INET6
 127 to request a query for IPv4 addresses instead of
 128 IPv6 addresses; the IPv4 addresses will
 129 be mapped to IPv6 addresses.
 130 .TP
 131 .B AI_ALL
 132 This flag is used with
 133 .B AI_V4MAPPED
 134 to request a query for both IPv4 and IPv6 addresses.
 135 Any IPv4 address found will be mapped to an IPv6 address.
 136 .TP
 137 .B AI_ADDRCONFIG
 138 This flag is used with
 139 .B AF_INET6
 140 to
 141 further request that queries for IPv6 addresses should not be made unless
 142 the system has at least one IPv6 address assigned to a network interface,
 143 and that queries for IPv4 addresses should not be made unless the
 144 system has at least one IPv4 address assigned to a network interface.
 145 This flag may be used by itself or with the
 146 .B AI_V4MAPPED
 147 flag.
 148 .TP
 149 .B AI_DEFAULT
 150 This flag is equivalent to
 151 .BR "(AI_ADDRCONFIG | AI_V4MAPPED)" .
 152 .SS getipnodebyaddr() arguments
 153 The
 154 .BR getipnodebyaddr ()
 155 function
 156 looks up the name of the host whose
 157 network address is
 158 specified by the
 159 .I addr
 160 argument.
 161 The
 162 .I af
 163 argument specifies one of the following values:
 164 .TP
 165 .B AF_INET
 166 The
 167 .I addr
 168 argument points to a
 169 .I struct in_addr
 170 and
 171 .I len
 172 must be set to
 173 .IR "sizeof(struct in_addr)" .
 174 .TP
 175 .B AF_INET6
 176 The
 177 .I addr
 178 argument points to a
 179 .I struct in6_addr
 180 and
 181 .I len
 182 must be set to
 183 .IR "sizeof(struct in6_addr)" .
 184 .SH RETURN VALUE
 185 NULL is returned if an error occurred, and
 186 .I error_num
 187 will contain an error code from the following list:
 188 .TP
 189 .B HOST_NOT_FOUND
 190 The hostname or network address was not found.
 191 .TP
 192 .B NO_ADDRESS
 193 The domain name server recognized the network address or name,
 194 but no answer was returned.
 195 This can happen if the network host has only IPv4 addresses and
 196 a request has been made for IPv6 information only, or vice versa.
 197 .TP
 198 .B NO_RECOVERY
 199 The domain name server returned a permanent failure response.
 200 .TP
 201 .B TRY_AGAIN
 202 The domain name server returned a temporary failure response.
 203 You might have better luck next time.
 204 .PP
 205 A successful query returns a pointer to a
 206 .I hostent
 207 structure that contains the following fields:
 208 .TP
 209 .I h_name
 210 This is the official name of this network host.
 211 .TP
 212 .I h_aliases
 213 This is an array of pointers to unofficial aliases for the same host.
 214 The array is terminated by a null pointer.
 215 .TP
 216 .I h_addrtype
 217 This is a copy of the
 218 .I af
 219 argument to
 220 .BR getipnodebyname ()
 221 or
 222 .BR getipnodebyaddr ().
 223 .I h_addrtype
 224 will always be
 225 .B AF_INET
 226 if the
 227 .I af
 228 argument was
 229 .BR AF_INET .
 230 .I h_addrtype
 231 will always be
 232 .B AF_INET6
 233 if the
 234 .I af
 235 argument was
 236 .BR AF_INET6 .
 237 .TP
 238 .I h_length
 239 This field will be set to
 240 .I sizeof(struct in_addr)
 241 if
 242 .I h_addrtype
 243 is
 244 .BR AF_INET ,
 245 and to
 246 .I sizeof(struct in6_addr)
 247 if
 248 .I h_addrtype
 249 is
 250 .BR AF_INET6 .
 251 .TP
 252 .I h_addr_list
 253 This is an array of one or more pointers to network address structures for the
 254 network host.
 255 The array is terminated by a null pointer.
 256 .SH CONFORMING TO
 257 RFC\ 2553.
 258 .\" Not in POSIX.1-2001.
 259 .SH NOTES
 260 These functions were present in glibc 2.1.91-95, but were
 261 removed again.
 262 Several UNIX-like systems support them, but all
 263 call them deprecated.
 264 .SH SEE ALSO
 265 .BR getaddrinfo (3),
 266 .BR getnameinfo (3),
 267 .BR inet_ntop (3),
 268 .BR inet_pton (3)