ares_getnameinfo.3

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