ares_getnameinfo.3

   1 .\" $Id$\r
   2 .\"\r
   3 .\" Copyright 2005 by Dominick Meglio.\r
   4 .\"\r
   5 .\" Permission to use, copy, modify, and distribute this\r
   6 .\" software and its documentation for any purpose and without\r
   7 .\" fee is hereby granted, provided that the above copyright\r
   8 .\" notice appear in all copies and that both that copyright\r
   9 .\" notice and this permission notice appear in supporting\r
  10 .\" documentation, and that the name of M.I.T. not be used in\r
  11 .\" advertising or publicity pertaining to distribution of the\r
  12 .\" software without specific, written prior permission.\r
  13 .\" M.I.T. makes no representations about the suitability of\r
  14 .\" this software for any purpose.  It is provided "as is"\r
  15 .\" without express or implied warranty.\r
  16 .\"\r
  17 .TH ARES_GETNAMEINFO 3 "16 May 2005"\r
  18 .SH NAME\r
  19 ares_getnameinfo \- Address-to-nodename translation in protocol-independent manner\r
  20 .SH SYNOPSIS\r
  21 .nf\r
  22 .B #include <ares.h>\r
  23 .PP\r
  24 .B typedef void (*ares_nameinfo_callback)(void *\fIarg\fP, int \fIstatus\fP,\r
  25 .B      int \fItimeouts\fP, char *\fInode\fP, char *\fIservice\fP)\r
  26 .PP\r
  27 .B void ares_getnameinfo(ares_channel \fIchannel\fP, const struct sockaddr *\fIsa\fP,\r
  28 .B      socklen_t \fIsalen\fP, int \fIflags\fP, ares_nameinfo_callback \fIcallback\fP,\r
  29 .B      void *\fIarg\fP)\r
  30 .fi\r
  31 .SH DESCRIPTION\r
  32 The\r
  33 .B ares_getnameinfo\r
  34 function is defined for protocol-independent address translation. The function\r
  35 is a combination of \fIares_gethostbyaddr(3)\fP and \fIgetservbyport(3)\fP. The function will\r
  36 translate the address either by executing a host query on the name service channel\r
  37 identified by\r
  38 .IR channel \r
  39 or it will attempt to resolve it locally if possible.\r
  40 The parameters\r
  41 .I sa\r
  42 and\r
  43 .I len\r
  44 give the address as a sockaddr structure, and\r
  45 .I flags\r
  46 gives the options that the function will use.  Valid flags are listed below:\r
  47 .TP 19\r
  48 .B ARES_NI_NOFQDN\r
  49 Only the nodename portion of the FQDN is returned for local hosts.\r
  50 .TP 19\r
  51 .B ARES_NI_NUMERICHOST\r
  52 The numeric form of the hostname is returned rather than the name.\r
  53 .TP 19\r
  54 .B ARES_NI_NAMEREQD\r
  55 An error is returned if the hostname cannot be found in the DNS.\r
  56 .TP 19\r
  57 .B ARES_NI_NUMERICSERV\r
  58 The numeric form of the service is returned rather than the name.\r
  59 .TP 19\r
  60 .B ARES_NI_TCP\r
  61 The service name is to be looked up for the TCP protocol.\r
  62 .TP 19\r
  63 .B ARES_NI_UDP\r
  64 The service name is to be looked up for the UDP protocol.\r
  65 .TP 19\r
  66 .B ARES_NI_SCTP\r
  67 The service name is to be looked up for the SCTP protocol.\r
  68 .TP 19\r
  69 .B ARES_NI_DCCP\r
  70 The service name is to be looked up for the DCCP protocol.\r
  71 .TP 19\r
  72 .B ARES_NI_NUMERICSCOPE\r
  73 The numeric form of the scope ID is returned rather than the name.\r
  74 .TP 19\r
  75 .B ARES_NI_LOOKUPHOST\r
  76 A hostname lookup is being requested.\r
  77 .TP 19\r
  78 .B ARES_NI_LOOKUPSERVICE\r
  79 A service name lookup is being requested.\r
  80 .PP\r
  81 When the query\r
  82 is complete or has \r
  83 failed, the ares library will invoke \fIcallback\fP.  Completion or failure of \r
  84 the query may happen immediately, or may happen during a later call to\r
  85 \fIares_process(3)\fP, \fIares_destroy(3)\fP or \fIares_cancel(3)\fP.\r
  86 .PP\r
  87 The callback argument\r
  88 .I arg\r
  89 is copied from the\r
  90 .B ares_getnameinfo\r
  91 argument\r
  92 .IR arg .\r
  93 The callback argument\r
  94 .I status\r
  95 indicates whether the query succeeded and, if not, how it failed.  It\r
  96 may have any of the following values:\r
  97 .TP 19\r
  98 .B ARES_SUCCESS\r
  99 The host lookup completed successfully.\r
 100 .TP 19\r
 101 .B ARES_ENOTIMP\r
 102 The ares library does not know how to look up addresses of type\r
 103 .IR family .\r
 104 .TP 19\r
 105 .B ARES_ENOTFOUND\r
 106 The address\r
 107 .I addr\r
 108 was not found.\r
 109 .TP 19\r
 110 .B ARES_ENOMEM\r
 111 Memory was exhausted.\r
 112 .TP 19\r
 113 .B ARES_EDESTRUCTION\r
 114 The name service channel\r
 115 .I channel\r
 116 is being destroyed; the query will not be completed.\r
 117 .TP 19\r
 118 .B ARES_EBADFLAGS\r
 119 The\r
 120 .I flags\r
 121 parameter contains an illegal value.\r
 122 .PP\r
 123 The callback argument\r
 124 .I timeouts\r
 125 reports how many times a query timed out during the execution of the\r
 126 given request.\r
 127 .PP\r
 128 On successful completion of the query, the callback argument\r
 129 .I node\r
 130 contains a string representing the hostname (assuming \r
 131 .B ARES_NI_LOOKUPHOST\r
 132 was specified). Additionally, \r
 133 .I service\r
 134 contains a string representing the service name (assuming\r
 135 .B ARES_NI_LOOKUPSERVICE\r
 136 was specified).\r
 137 If the query did not complete successfully, or one of the values\r
 138 was not requested, \r
 139 .I node\r
 140 or\r
 141 .I service\r
 142 will be \r
 143 .BR NULL .\r
 144 .SH SEE ALSO\r
 145 .BR ares_process (3),\r
 146 .BR ares_getaddrinfo (3)\r
 147 .SH AUTHOR\r
 148 Dominick Meglio\r
 149 .br\r
 150 Copyright 2005 by Dominick Meglio.\r