Revert "Update to 7.40.1"

[platform/upstream/curl.git] / docs / libcurl / curl_multi_add_handle.3

diff --git a/docs/libcurl/curl_multi_add_handle.3 b/docs/libcurl/curl_multi_add_handle.3
index 1553b4e..31c422e 100644 (file)
--- a/docs/libcurl/curl_multi_add_handle.3
+++ b/docs/libcurl/curl_multi_add_handle.3
@@ -1,5 +1,24 @@
-.\" $Id$
-.\"
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" *
+.\" * This software is licensed as described in the file COPYING, which
+.\" * you should have received as part of this distribution. The terms
+.\" * are also available at http://curl.haxx.se/docs/copyright.html.
+.\" *
+.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+.\" * copies of the Software, and permit persons to whom the Software is
+.\" * furnished to do so, under the terms of the COPYING file.
+.\" *
+.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+.\" * KIND, either express or implied.
+.\" *
+.\" **************************************************************************
 .TH curl_multi_add_handle 3 "4 March 2002" "libcurl 7.9.5" "libcurl Manual"
 .SH NAME
 curl_multi_add_handle - add an easy handle to a multi session
@@ -10,17 +29,25 @@ CURLMcode curl_multi_add_handle(CURLM *multi_handle, CURL *easy_handle);
 .ad
 .SH DESCRIPTION
 Adds a standard easy handle to the multi stack. This function call will make
-this \fImulti_handle\fP control the specified \fIeasy_handle\fP.
-Furthermore, libcurl now initiates the connection associated with the
-specified \fIeasy_handle\fP.
+this \fImulti_handle\fP control the specified \fIeasy_handle\fP.  Furthermore,
+libcurl now initiates the connection associated with the specified
+\fIeasy_handle\fP.
 
-When an easy handle has been added to a multi stack, you can not and you must
-not use \fIcurl_easy_perform(3)\fP on that handle!
+While an easy handle is added to a multi stack, you can not and you must not
+use \fIcurl_easy_perform(3)\fP on that handle. After having removed the handle
+from the multi stack again, it is perfectly fine to use it with the easy
+interface again.
 
-If the easy handle is not set to use a shared (CURLOPT_SHARE) or global DNS
-cache (CURLOPT_DNS_USE_GLOBAL_CACHE), it will be made to use the DNS cache
-that is shared between all easy handles within the multi handle when
-\fIcurl_multi_add_handle(3)\fP is called.
+If the easy handle is not set to use a shared (\fICURLOPT_SHARE(3)\fP) or
+global DNS cache (\fICURLOPT_DNS_USE_GLOBAL_CACHE(3)\fP), it will be made to
+use the DNS cache that is shared between all easy handles within the multi
+handle when \fIcurl_multi_add_handle(3)\fP is called.
+
+If you have CURLMOPT_TIMERFUNCTION set in the multi handle (and you really
+should if you're working event-based with \fIcurl_multi_socket_action(3)\fP
+and friends), that callback will be called from within this function to ask
+for an updated timer so that your main event loop will get the activity on
+this handle to get started.
 
 The easy handle will remain added until you remove it again with
 \fIcurl_multi_remove_handle(3)\fP. You should remove the easy handle from the