1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: curl_multi_remove_handle
5Section: 3
6Source: libcurl
7See-also:
8  - curl_multi_add_handle (3)
9  - curl_multi_cleanup (3)
10  - curl_multi_init (3)
11Protocol:
12  - All
13Added-in: 7.9.6
14---
15
16# NAME
17
18curl_multi_remove_handle - remove an easy handle from a multi session
19
20# SYNOPSIS
21
22~~~c
23#include <curl/curl.h>
24
25CURLMcode curl_multi_remove_handle(CURLM *multi_handle, CURL *easy_handle);
26~~~
27
28# DESCRIPTION
29
30Removes a given *easy_handle* from the *multi_handle*. This makes the
31specified easy handle be removed from this multi handle's control.
32
33When the easy handle has been removed from a multi stack, it is again
34perfectly legal to invoke curl_easy_perform(3) on this easy handle.
35
36Removing an easy handle while being in use is perfectly legal and effectively
37halts the transfer in progress involving that easy handle. All other easy
38handles and transfers remain unaffected.
39
40It is fine to remove a handle at any time during a transfer, just not from
41within any libcurl callback function.
42
43Removing an easy handle from the multi handle before the corresponding
44transfer is complete might cause libcurl to close the connection - if the
45state of it and the internal protocol handler deem it necessary. Otherwise
46libcurl keeps the connection alive in the connection pool associated with the
47multi handle, ready to get reused for a future transfer using this multi
48handle.
49
50# %PROTOCOLS%
51
52# EXAMPLE
53
54~~~c
55int main(void)
56{
57  CURLM *multi = curl_multi_init();
58  int queued = 0;
59
60  /* when an easy handle has completed, remove it */
61  CURLMsg *msg = curl_multi_info_read(multi, &queued);
62  if(msg) {
63    if(msg->msg == CURLMSG_DONE) {
64      /* a transfer ended */
65      fprintf(stderr, "Transfer completed\n");
66      curl_multi_remove_handle(multi, msg->easy_handle);
67    }
68  }
69}
70~~~
71
72# %AVAILABILITY%
73
74# RETURN VALUE
75
76CURLMcode type, general libcurl multi interface error code.
77