ares_send.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_SEND 3 "25 July 1998"
  17 .SH NAME
  18 ares_send \- Initiate a DNS query
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <ares.h>
  22 .PP
  23 .B typedef void (*ares_callback)(void *\fIarg\fP, int \fIstatus\fP,
  24 .B      int \fItimeouts\fP, unsigned char *\fIabuf\fP, int \fIalen\fP)
  25 .PP
  26 .B void ares_send(ares_channel \fIchannel\fP, const unsigned char *\fIqbuf\fP,
  27 .B      int \fIqlen\fP, ares_callback \fIcallback\fP, void *\fIarg\fP)
  28 .fi
  29 .SH DESCRIPTION
  30 The
  31 .B ares_send
  32 function initiates a DNS query on the name service channel identified
  33 by
  34 .IR channel .
  35 The parameters
  36 .I qbuf
  37 and
  38 .I qlen
  39 give the DNS query, which should already have been formatted according
  40 to the DNS protocol.  When the query is complete or has failed, the
  41 ares library will invoke
  42 .IR callback .
  43 Completion or failure of the query may happen immediately, or may
  44 happen during a later call to
  45 .BR ares_process (3)
  46 or
  47 .BR ares_destroy (3).
  48 .PP
  49 The callback argument
  50 .I arg
  51 is copied from the
  52 .B ares_send
  53 argument
  54 .IR arg .
  55 The callback argument
  56 .I status
  57 indicates whether the query succeeded and, if not, how it failed.  It
  58 may have any of the following values:
  59 .TP 19
  60 .B ARES_SUCCESS
  61 The query completed.
  62 .TP 19
  63 .B ARES_EBADQUERY
  64 The query buffer was poorly formed (was not long enough for a DNS
  65 header or was too long for TCP transmission).
  66 .TP 19
  67 .B ARES_ETIMEOUT
  68 No name servers responded within the timeout period.
  69 .TP 19
  70 .B ARES_ECONNREFUSED
  71 No name servers could be contacted.
  72 .TP 19
  73 .B ARES_ENOMEM
  74 Memory was exhausted.
  75 .TP 19
  76 .B ARES_ECANCELLED
  77 The query was cancelled.
  78 .TP 19
  79 .B ARES_EDESTRUCTION
  80 The name service channel
  81 .I channel
  82 is being destroyed; the query will not be completed.
  83 .PP
  84 The callback argument
  85 .I timeouts
  86 reports how many times a query timed out during the execution of the
  87 given request.
  88 .PP
  89 If the query completed, the callback argument
  90 .I abuf
  91 points to a result buffer of length
  92 .IR alen .
  93 If the query did not complete,
  94 .I abuf
  95 will be NULL and
  96 .I alen
  97 will be 0.
  98 .PP
  99 Unless the flag
 100 .B ARES_FLAG_NOCHECKRESP
 101 was set at channel initialization time,
 102 .B ares_send
 103 will normally ignore responses whose questions do not match the
 104 questions in
 105 .IR qbuf ,
 106 as well as responses with reply codes of
 107 .BR SERVFAIL ,
 108 .BR NOTIMP ,
 109 and
 110 .BR REFUSED .
 111 Unlike other query functions in the ares library, however,
 112 .B ares_send
 113 does not inspect the header of the reply packet to determine the error
 114 status, so a callback status of
 115 .B ARES_SUCCESS
 116 does not reflect as much about the response as for other query
 117 functions.
 118 .SH SEE ALSO
 119 .BR ares_process (3)
 120 .SH AUTHOR
 121 Greg Hudson, MIT Information Systems
 122 .br
 123 Copyright 1998 by the Massachusetts Institute of Technology.