Return to curl_multi_add_handle.3 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs / libcurl

Annotation of embedaddon/curl/docs/libcurl/curl_multi_add_handle.3, revision 1.1.1.1

1.1       misho       1: .\" **************************************************************************
                      2: .\" *                                  _   _ ____  _
                      3: .\" *  Project                     ___| | | |  _ \| |
                      4: .\" *                             / __| | | | |_) | |
                      5: .\" *                            | (__| |_| |  _ <| |___
                      6: .\" *                             \___|\___/|_| \_\_____|
                      7: .\" *
                      8: .\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al.
                      9: .\" *
                     10: .\" * This software is licensed as described in the file COPYING, which
                     11: .\" * you should have received as part of this distribution. The terms
                     12: .\" * are also available at https://curl.haxx.se/docs/copyright.html.
                     13: .\" *
                     14: .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
                     15: .\" * copies of the Software, and permit persons to whom the Software is
                     16: .\" * furnished to do so, under the terms of the COPYING file.
                     17: .\" *
                     18: .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
                     19: .\" * KIND, either express or implied.
                     20: .\" *
                     21: .\" **************************************************************************
                     22: .TH curl_multi_add_handle 3 "June 30, 2018" "libcurl 7.70.0" "libcurl Manual"
                     23: 
                     24: .SH NAME
                     25: curl_multi_add_handle - add an easy handle to a multi session
                     26: .SH SYNOPSIS
                     27: #include <curl/curl.h>
                     28: 
                     29: CURLMcode curl_multi_add_handle(CURLM *multi_handle, CURL *easy_handle);
                     30: .ad
                     31: .SH DESCRIPTION
                     32: Adds a standard easy handle to the multi stack. This function call will make
                     33: this \fImulti_handle\fP control the specified \fIeasy_handle\fP.
                     34: 
                     35: While an easy handle is added to a multi stack, you cannot and you must not
                     36: use \fIcurl_easy_perform(3)\fP on that handle. After having removed the easy
                     37: handle from the multi stack again, it is perfectly fine to use it with the
                     38: easy interface again.
                     39: 
                     40: If the easy handle is not set to use a shared (\fICURLOPT_SHARE(3)\fP) or
                     41: global DNS cache (\fICURLOPT_DNS_USE_GLOBAL_CACHE(3)\fP), it will be made to
                     42: use the DNS cache that is shared between all easy handles within the multi
                     43: handle when \fIcurl_multi_add_handle(3)\fP is called.
                     44: 
                     45: When an easy interface is added to a multi handle, it will use a shared
                     46: connection cache owned by the multi handle. Removing and adding new easy
                     47: handles will not affect the pool of connections or the ability to do
                     48: connection re-use.
                     49: 
                     50: If you have \fICURLMOPT_TIMERFUNCTION(3)\fP set in the multi handle (and you
                     51: really should if you're working event-based with
                     52: \fIcurl_multi_socket_action(3)\fP and friends), that callback will be called
                     53: from within this function to ask for an updated timer so that your main event
                     54: loop will get the activity on this handle to get started.
                     55: 
                     56: The easy handle will remain added to the multi handle until you remove it
                     57: again with \fIcurl_multi_remove_handle(3)\fP - even when a transfer with that
                     58: specific easy handle is completed.
                     59: 
                     60: You should remove the easy handle from the multi stack before you terminate
                     61: first the easy handle and then the multi handle:
                     62: 
                     63: 1 - \fIcurl_multi_remove_handle(3)\fP
                     64: 
                     65: 2 - \fIcurl_easy_cleanup(3)\fP
                     66: 
                     67: 3 - \fIcurl_multi_cleanup(3)\fP
                     68: .SH RETURN VALUE
                     69: CURLMcode type, general libcurl multi interface error code.
                     70: .SH "SEE ALSO"
                     71: .BR curl_multi_cleanup "(3)," curl_multi_init "(3), "
                     72: .BR curl_multi_setopt "(3), " curl_multi_socket_action "(3) "