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_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 If the query completed, the callback argument
  87 .I abuf
  88 points to a result buffer of length
  89 .IR alen .
  90 If the query did not complete,
  91 .I abuf
  92 will be NULL and
  93 .I alen
  94 will be 0.
  95 .PP
  96 Unless the flag
  97 .B ARES_FLAG_NOCHECKRESP
  98 was set at channel initialization time,
  99 .B ares_send
 100 will normally ignore responses whose questions do not match the
 101 questions in
 102 .IR qbuf ,
 103 as well as responses with reply codes of
 104 .BR SERVFAIL ,
 105 .BR NOTIMP ,
 106 and
 107 .BR REFUSED .
 108 Unlike other query functions in the ares library, however,
 109 .B ares_send
 110 does not inspect the header of the reply packet to determine the error
 111 status, so a callback status of
 112 .B ARES_SUCCESS
 113 does not reflect as much about the response as for other query
 114 functions.
 115 .SH SEE ALSO
 116 .BR ares_process (3)
 117 .SH AUTHOR
 118 Greg Hudson, MIT Information Systems
 119 .br
 120 Copyright 1998 by the Massachusetts Institute of Technology.