Subject: [PATCH 2/4] Documentation: properly document ARES_ECANCELLED

[PATCH 2/4] Documentation: properly document ARES_ECANCELLED

From: Alexander Klauer <Alexander.Klauer_at_itwm.fraunhofer.de>
Date: Thu, 21 Mar 2013 10:20:13 +0100

This commit clarifies the behaviour of ares_cancel() with respect to
callbacks and adds missing documentation of ARES_ECANCELLED to the man
pages of the affected functions.

---
 ares_cancel.3        |    4 +++-
 ares_gethostbyaddr.3 |    3 +++
 ares_gethostbyname.3 |    3 +++
 ares_getnameinfo.3   |    3 +++
 ares_query.3         |    3 +++
 ares_search.3        |    3 +++
 ares_send.3          |    3 +++
 7 files changed, 21 insertions(+), 1 deletion(-)
diff --git a/ares_cancel.3 b/ares_cancel.3
index ef10ec5..c34d8c5 100644
--- a/ares_cancel.3
+++ b/ares_cancel.3
@@ -28,7 +28,9 @@ name service channel identified by \fIchannel\fP.  \fBares_cancel\fP invokes
 the callbacks for each pending query on the channel, passing a status of
 .BR ARES_ECANCELLED .
 These calls give the callbacks a chance to clean up any state which
-might have been stored in their arguments.
+might have been stored in their arguments. If a callback adds a new request
+to the channel, that request will be cancelled as well, so that upon return
+of \fBares_cancel\fP, no requests remain.
 .SH SEE ALSO
 .BR ares_init (3)
 .BR ares_destroy (3)
diff --git a/ares_gethostbyaddr.3 b/ares_gethostbyaddr.3
index f589868..7727307 100644
--- a/ares_gethostbyaddr.3
+++ b/ares_gethostbyaddr.3
@@ -70,6 +70,9 @@ was not found.
 .B ARES_ENOMEM
 Memory was exhausted.
 .TP 19
+.B ARES_ECANCELLED
+The query was cancelled.
+.TP 19
 .B ARES_EDESTRUCTION
 The name service channel
 .I channel
diff --git a/ares_gethostbyname.3 b/ares_gethostbyname.3
index a578a53..6b24ea4 100644
--- a/ares_gethostbyname.3
+++ b/ares_gethostbyname.3
@@ -74,6 +74,9 @@ was not found.
 .B ARES_ENOMEM
 Memory was exhausted.
 .TP 19
+.B ARES_ECANCELLED
+The query was cancelled.
+.TP 19
 .B ARES_EDESTRUCTION
 The name service channel
 .I channel
diff --git a/ares_getnameinfo.3 b/ares_getnameinfo.3
index 7e4990c..d227606 100644
--- a/ares_getnameinfo.3
+++ b/ares_getnameinfo.3
@@ -109,6 +109,9 @@ was not found.
 .B ARES_ENOMEM
 Memory was exhausted.
 .TP 19
+.B ARES_ECANCELLED
+The query was cancelled.
+.TP 19
 .B ARES_EDESTRUCTION
 The name service channel
 .I channel
diff --git a/ares_query.3 b/ares_query.3
index 0c5df84..733fbc9 100644
--- a/ares_query.3
+++ b/ares_query.3
@@ -118,6 +118,9 @@ No name servers could be contacted.
 .B ARES_ENOMEM
 Memory was exhausted.
 .TP 19
+.B ARES_ECANCELLED
+The query was cancelled.
+.TP 19
 .B ARES_EDESTRUCTION
 The name service channel
 .I channel
diff --git a/ares_search.3 b/ares_search.3
index 4184b00..2c85d20 100644
--- a/ares_search.3
+++ b/ares_search.3
@@ -119,6 +119,9 @@ No name servers could be contacted.
 .B ARES_ENOMEM
 Memory was exhausted.
 .TP 19
+.B ARES_ECANCELLED
+The query was cancelled.
+.TP 19
 .B ARES_EDESTRUCTION
 The name service channel
 .I channel
diff --git a/ares_send.3 b/ares_send.3
index 48d90ab..b89abfe 100644
--- a/ares_send.3
+++ b/ares_send.3
@@ -73,6 +73,9 @@ No name servers could be contacted.
 .B ARES_ENOMEM
 Memory was exhausted.
 .TP 19
+.B ARES_ECANCELLED
+The query was cancelled.
+.TP 19
 .B ARES_EDESTRUCTION
 The name service channel
 .I channel
-- 
1.7.9.5
Received on 2013-03-21