doc/html/ref/net-common-tcpip-manpages-getnameinfo.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >getnameinfo</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE="TCP/IP Library Reference"
  23 HREF="tcpip-library-reference.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="getifaddrs"
  26 HREF="net-common-tcpip-manpages-getifaddrs.html"><LINK
  27 REL="NEXT"
  28 TITLE="getnetent"
  29 HREF="net-common-tcpip-manpages-getnetent.html"></HEAD
  30 ><BODY
  31 CLASS="SECT1"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="net-common-tcpip-manpages-getifaddrs.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 >Chapter 38. TCP/IP Library Reference</TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="net-common-tcpip-manpages-getnetent.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><DIV
  81 CLASS="SECT1"
  82 ><H1
  83 CLASS="SECT1"
  84 ><A
  85 NAME="NET-COMMON-TCPIP-MANPAGES-GETNAMEINFO">getnameinfo</H1
  86 ><TABLE
  87 BORDER="5"
  88 BGCOLOR="#E0E0F0"
  89 WIDTH="70%"
  90 ><TR
  91 ><TD
  92 ><PRE
  93 CLASS="SCREEN"
  94 >GETNAMEINFO(3)          System Library Functions Manual         GETNAMEINFO(3)
  95
  96 NAME
  97      getnameinfo - address-to-nodename translation in protocol-independent
  98      manner
  99
 100 SYNOPSIS
 101      #include &lt;sys/types.h&#62;
 102      #include &lt;sys/socket.h&#62;
 103      #include &lt;netdb.h&#62;
 104
 105      int
 106      getnameinfo(const struct sockaddr *sa, socklen_t salen, char *host,
 107              size_t hostlen, char *serv, size_t servlen, int flags);
 108
 109 DESCRIPTION
 110      The getnameinfo() function is defined for protocol-independent address-
 111      to-nodename translation.  Its functionality is a reverse conversion of
 112      getaddrinfo(3), and implements similar functionality with
 113      gethostbyaddr(3) and getservbyport(3) in more sophisticated manner.
 114
 115      This function looks up an IP address and port number provided by the
 116      caller in the DNS and system-specific database, and returns text strings
 117      for both in buffers provided by the caller.  The function indicates suc-
 118      cessful completion by a zero return value; a non-zero return value indi-
 119      cates failure.
 120
 121      The first argument, sa, points to either a sockaddr_in structure (for
 122      IPv4) or a sockaddr_in6 structure (for IPv6) that holds the IP address
 123      and port number.  The salen argument gives the length of the sockaddr_in
 124      or sockaddr_in6 structure.
 125
 126      The function returns the nodename associated with the IP address in the
 127      buffer pointed to by the host argument.  The caller provides the size of
 128      this buffer via the hostlen argument.  The service name associated with
 129      the port number is returned in the buffer pointed to by serv, and the
 130      servlen argument gives the length of this buffer.  The caller specifies
 131      not to return either string by providing a zero value for the hostlen or
 132      servlen arguments.  Otherwise, the caller must provide buffers large
 133      enough to hold the nodename and the service name, including the terminat-
 134      ing null characters.
 135
 136      Unfortunately most systems do not provide constants that specify the max-
 137      imum size of either a fully-qualified domain name or a service name.
 138      Therefore to aid the application in allocating buffers for these two
 139      returned strings the following constants are defined in &lt;netdb.h&#62;:
 140
 141      #define NI_MAXHOST    MAXHOSTNAMELEN
 142      #define NI_MAXSERV    32
 143
 144      The first value is actually defined as the constant MAXDNAME in recent
 145      versions of BIND's &lt;arpa/nameser.h&#62; header (older versions of BIND define
 146      this constant to be 256) and the second is a guess based on the services
 147      listed in the current Assigned Numbers RFC.
 148
 149      The final argument is a flag that changes the default actions of this
 150      function.  By default the fully-qualified domain name (FQDN) for the host
 151      is looked up in the DNS and returned.  If the flag bit NI_NOFQDN is set,
 152      only the nodename portion of the FQDN is returned for local hosts.
 153
 154      If the flag bit NI_NUMERICHOST is set, or if the host's name cannot be
 155      located in the DNS, the numeric form of the host's address is returned
 156      instead of its name (e.g., by calling inet_ntop() instead of
 157      gethostbyaddr()).  If the flag bit NI_NAMEREQD is set, an error is
 158      returned if the host's name cannot be located in the DNS.
 159
 160      If the flag bit NI_NUMERICSERV is set, the numeric form of the service
 161      address is returned (e.g., its port number) instead of its name.  The two
 162      NI_NUMERICxxx flags are required to support the -n flag that many com-
 163      mands provide.
 164
 165      A fifth flag bit, NI_DGRAM, specifies that the service is a datagram ser-
 166      vice, and causes getservbyport() to be called with a second argument of
 167      "udp" instead of its default of "tcp".  This is required for the few
 168      ports (512-514) that have different services for UDP and TCP.
 169
 170      These NI_xxx flags are defined in &lt;netdb.h&#62;.
 171
 172    Extension for scoped IPv6 address
 173      The implementation allows experimental numeric IPv6 address notation with
 174      scope identifier.  IPv6 link-local address will appear as string like
 175      ``fe80::1%ne0'', if NI_WITHSCOPEID bit is enabled in flags argument.
 176      Refer to getaddrinfo(3) for the notation.
 177
 178 EXAMPLES
 179      The following code tries to get numeric hostname, and service name, for
 180      given socket address.  Observe that there is no hardcoded reference to
 181      particular address family.
 182
 183            struct sockaddr *sa;    /* input */
 184            char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
 185
 186            if (getnameinfo(sa, sa-&#62;sa_len, hbuf, sizeof(hbuf), sbuf,
 187                sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) {
 188                    errx(1, "could not get numeric hostname");
 189                    /*NOTREACHED*/
 190            }
 191            printf("host=%s, serv=%s\n", hbuf, sbuf);
 192
 193      The following version checks if the socket address has reverse address
 194      mapping.
 195
 196            struct sockaddr *sa;    /* input */
 197            char hbuf[NI_MAXHOST];
 198
 199            if (getnameinfo(sa, sa-&#62;sa_len, hbuf, sizeof(hbuf), NULL, 0,
 200                NI_NAMEREQD)) {
 201                    errx(1, "could not resolve hostname");
 202                    /*NOTREACHED*/
 203            }
 204            printf("host=%s\n", hbuf);
 205
 206 DIAGNOSTICS
 207      The function indicates successful completion by a zero return value; a
 208      non-zero return value indicates failure.  Error codes are as below:
 209
 210      EAI_AGAIN          The name could not be resolved at this time.  Future
 211                         attempts may succeed.
 212
 213      EAI_BADFLAGS       The flags had an invalid value.
 214
 215      EAI_FAIL           A non-recoverable error occurred.
 216
 217      EAI_FAMILY         The address family was not recognized or the address
 218                         length was invalid for the specified family.
 219
 220      EAI_MEMORY         There was a memory allocation failure.
 221
 222      EAI_NONAME         The name does not resolve for the supplied parameters.
 223                         NI_NAMEREQD is set and the host's name cannot be
 224                         located, or both nodename and servname were null.
 225
 226      EAI_SYSTEM         A system error occurred.  The error code can be found
 227                         in errno.
 228
 229 SEE ALSO
 230      getaddrinfo(3), gethostbyaddr(3), getservbyport(3), hosts(5),
 231      resolv.conf(5), services(5), hostname(7), named(8)
 232
 233      R. Gilligan, S. Thomson, J. Bound, and W. Stevens, Basic Socket Interface
 234      Extensions for IPv6, RFC2553, March 1999.
 235
 236      Tatsuya Jinmei and Atsushi Onoe, An Extension of Format for IPv6 Scoped
 237      Addresses, internet draft, draft-ietf-ipngwg-scopedaddr-format-02.txt,
 238      work in progress material.
 239
 240      Craig Metz, "Protocol Independence Using the Sockets API", Proceedings of
 241      the freenix track: 2000 USENIX annual technical conference, June 2000.
 242
 243 HISTORY
 244      The implementation first appeared in WIDE Hydrangea IPv6 protocol stack
 245      kit.
 246
 247 STANDARDS
 248      The getaddrinfo() function is defined IEEE POSIX 1003.1g draft specifica-
 249      tion, and documented in ``Basic Socket Interface Extensions for IPv6''
 250      (RFC2553).
 251
 252 BUGS
 253      The current implementation is not thread-safe.
 254
 255      The text was shamelessly copied from RFC2553.
 256
 257      OpenBSD intentionally uses different NI_MAXHOST value from what RFC2553
 258      suggests, to avoid buffer length handling mistakes.
 259
 260 BSD                              May 25, 1995                              BSD
 261     </PRE
 262 ></TD
 263 ></TR
 264 ></TABLE
 265 ></DIV
 266 ><DIV
 267 CLASS="NAVFOOTER"
 268 ><HR
 269 ALIGN="LEFT"
 270 WIDTH="100%"><TABLE
 271 SUMMARY="Footer navigation table"
 272 WIDTH="100%"
 273 BORDER="0"
 274 CELLPADDING="0"
 275 CELLSPACING="0"
 276 ><TR
 277 ><TD
 278 WIDTH="33%"
 279 ALIGN="left"
 280 VALIGN="top"
 281 ><A
 282 HREF="net-common-tcpip-manpages-getifaddrs.html"
 283 ACCESSKEY="P"
 284 >Prev</A
 285 ></TD
 286 ><TD
 287 WIDTH="34%"
 288 ALIGN="center"
 289 VALIGN="top"
 290 ><A
 291 HREF="ecos-ref.html"
 292 ACCESSKEY="H"
 293 >Home</A
 294 ></TD
 295 ><TD
 296 WIDTH="33%"
 297 ALIGN="right"
 298 VALIGN="top"
 299 ><A
 300 HREF="net-common-tcpip-manpages-getnetent.html"
 301 ACCESSKEY="N"
 302 >Next</A
 303 ></TD
 304 ></TR
 305 ><TR
 306 ><TD
 307 WIDTH="33%"
 308 ALIGN="left"
 309 VALIGN="top"
 310 >getifaddrs</TD
 311 ><TD
 312 WIDTH="34%"
 313 ALIGN="center"
 314 VALIGN="top"
 315 ><A
 316 HREF="tcpip-library-reference.html"
 317 ACCESSKEY="U"
 318 >Up</A
 319 ></TD
 320 ><TD
 321 WIDTH="33%"
 322 ALIGN="right"
 323 VALIGN="top"
 324 >getnetent</TD
 325 ></TR
 326 ></TABLE
 327 ></DIV
 328 ></BODY
 329 ></HTML
 330 >