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      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 On successful completion of the query, the callback argument\r
 124 .I node\r
 125 contains a string representing the hostname (assuming \r
 126 .B ARES_NI_LOOKUPHOST\r
 127 was specified). Additionally, \r
 128 .I service\r
 129 contains a string representing the service name (assuming\r
 130 .B ARES_NI_LOOKUPSERVICE\r
 131 was specified).\r
 132 If the query did not complete successfully, or one of the values\r
 133 was not requested, \r
 134 .I node\r
 135 or\r
 136 .I service\r
 137 will be \r
 138 .BR NULL .\r
 139 .SH SEE ALSO\r
 140 .BR ares_process (3),\r
 141 .BR ares_getaddrinfo (3)\r
 142 .SH AUTHOR\r
 143 Dominick Meglio\r
 144 .br\r
 145 Copyright 2005 by Dominick Meglio.\r