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