ares_gethostbyaddr.3

   1 .\"
   2 .\" Copyright 1998 by the Massachusetts Institute of Technology.
   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_GETHOSTBYADDR 3 "24 July 1998"
  17 .SH NAME
  18 ares_gethostbyaddr \- Initiate a host query by address
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <ares.h>
  22 .PP
  23 .B typedef void (*ares_host_callback)(void *\fIarg\fP, int \fIstatus\fP,
  24 .B      int \fItimeouts\fP, struct hostent *\fIhostent\fP)
  25 .PP
  26 .B void ares_gethostbyaddr(ares_channel \fIchannel\fP, const void *\fIaddr\fP,
  27 .B      int \fIaddrlen\fP, int \fIfamily\fP, ares_host_callback \fIcallback\fP,
  28 .B      void *\fIarg\fP)
  29 .fi
  30 .SH DESCRIPTION
  31 The
  32 .B ares_gethostbyaddr
  33 function initiates a host query by address on the name service channel
  34 identified by
  35 .IR channel .
  36 The parameters
  37 .I addr
  38 and
  39 .I addrlen
  40 give the address as a series of bytes, and
  41 .I family
  42 gives the type of address.  When the query is complete or has failed, the ares
  43 library will invoke \fIcallback\fP.  Completion or failure of the query may
  44 happen immediately, or may happen during a later call to
  45 \fIares_process(3)\fP, \fIares_destroy(3)\fP or \fIares_cancel(3)\fP.
  46 .PP
  47 The callback argument
  48 .I arg
  49 is copied from the
  50 .B ares_gethostbyaddr
  51 argument
  52 .IR arg .
  53 The callback argument
  54 .I status
  55 indicates whether the query succeeded and, if not, how it failed.  It
  56 may have any of the following values:
  57 .TP 19
  58 .B ARES_SUCCESS
  59 The host lookup completed successfully.
  60 .TP 19
  61 .B ARES_ENOTIMP
  62 The ares library does not know how to look up addresses of type
  63 .IR family .
  64 .TP 19
  65 .B ARES_ENOTFOUND
  66 The address
  67 .I addr
  68 was not found.
  69 .TP 19
  70 .B ARES_ENOMEM
  71 Memory was exhausted.
  72 .TP 19
  73 .B ARES_ECANCELLED
  74 The query was cancelled.
  75 .TP 19
  76 .B ARES_EDESTRUCTION
  77 The name service channel
  78 .I channel
  79 is being destroyed; the query will not be completed.
  80 .PP
  81 The callback argument
  82 .I timeouts
  83 reports how many times a query timed out during the execution of the
  84 given request.
  85 .PP
  86 On successful completion of the query, the callback argument
  87 .I hostent
  88 points to a
  89 .B struct hostent
  90 containing the name of the host returned by the query.  The callback
  91 need not and should not attempt to free the memory pointed to by
  92 .IR hostent ;
  93 the ares library will free it when the callback returns.  If the query
  94 did not complete successfully,
  95 .I hostent
  96 will be
  97 .BR NULL .
  98 .SH SEE ALSO
  99 .BR ares_process (3),
 100 .BR ares_gethostbyname (3)
 101 .SH AUTHOR
 102 Greg Hudson, MIT Information Systems
 103 .br
 104 Copyright 1998 by the Massachusetts Institute of Technology.