curl_multi_get_handles: get easy handles from a multi handle

Closes #11750

diff --git a/docs/libcurl/Makefile.inc b/docs/libcurl/Makefile.inc
index e7e8280124c8327828049ced4a0eaaa96e2f5dd7..1f3b1e2ff884e31a157cca6ce7de2c20c1748991 100644 (file)
--- a/docs/libcurl/Makefile.inc
+++ b/docs/libcurl/Makefile.inc
@@ -73,6 +73,7 @@ man_MANS = \
  curl_multi_assign.3 \
  curl_multi_cleanup.3 \
  curl_multi_fdset.3 \
+ curl_multi_get_handles.3 \
  curl_multi_info_read.3 \
  curl_multi_init.3 \
  curl_multi_perform.3 \

diff --git a/docs/libcurl/curl_multi_get_handles.3 b/docs/libcurl/curl_multi_get_handles.3
new file mode 100644 (file)
index 0000000..3999bbe
--- /dev/null
+++ b/docs/libcurl/curl_multi_get_handles.3
@@ -0,0 +1,73 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 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 https://curl.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.
+.\" *
+.\" * SPDX-License-Identifier: curl
+.\" *
+.\" **************************************************************************
+.TH curl_multi_get_handles 3 "28 August 2023" "libcurl" "libcurl"
+.SH NAME
+curl_multi_get_handles - returns all added easy handles
+.SH SYNOPSIS
+.nf
+#include <curl/curl.h>
+
+CURL **curl_multi_get_handles(CURLM *multi_handle);
+.fi
+.SH DESCRIPTION
+Returns an array with pointers to all added easy handles. The end of the list
+is marked with a NULL pointer.
+
+Even if there is not a single easy handle added, this still returns an array
+but with only a single NULL pointer entry.
+
+The returned array contains all the handles that are present at the time of
+the call. As soon as a handle has been removed from or a handle has been added
+to the multi handle after the handle array was returned, the two data points
+are out of sync.
+
+The order of the easy handles within the array is not guaranteed.
+
+The returned array must be freed with a call to \fIcurl_free(3)\fP after use.
+.SH EXAMPLE
+.nf
+  /* init a multi stack */
+  multi_handle = curl_multi_init();
+
+  /* add a transfer */
+  curl_multi_add_handle(multi_handle, http_handle);
+
+  /* extract all added handles */
+  CURL **list = curl_multi_get_handles(multi_handle);
+
+  if(list) {
+    /* remove all added handles */
+    for(i = 0; list[i]; i++) {
+      curl_multi_remove_handle(multi_handle, list[i]);
+    }
+    curl_free(list);
+  }
+.fi
+.SH AVAILABILITY
+Added in 8.4.0
+.SH RETURN VALUE
+Returns NULL on failure. Otherwise it returns a pointer to an allocated array.
+.SH "SEE ALSO"
+.BR curl_multi_cleanup "(3)," curl_multi_init "(3), "
+.BR curl_multi_add_handle "(3), " curl_multi_remove_handle "(3) "

diff --git a/include/curl/multi.h b/include/curl/multi.h
index 13b55b780792cf871932735db8175e4f9b893769..e79b48ff32ac73c30ffafdcfa8dc5dfc36d57e39 100644 (file)
--- a/include/curl/multi.h
+++ b/include/curl/multi.h
@@ -426,6 +426,17 @@ CURL_EXTERN CURLMcode curl_multi_setopt(CURLM *multi_handle,
 CURL_EXTERN CURLMcode curl_multi_assign(CURLM *multi_handle,
                                         curl_socket_t sockfd, void *sockp);
 
+/*
+ * Name:    curl_multi_get_handles()
+ *
+ * Desc:    Returns an allocated array holding all handles currently added to
+ *          the multi handle. Marks the final entry with a NULL pointer. If
+ *          there is no easy handle added to the multi handle, this function
+ *          returns an array with the first entry as a NULL pointer.
+ *
+ * Returns: NULL on failure, otherwise a CURL **array pointer
+ */
+CURL_EXTERN CURL **curl_multi_get_handles(CURLM *multi_handle);
 
 /*
  * Name: curl_push_callback

diff --git a/lib/conncache.c b/lib/conncache.c
index a21409c13f1f220d82e3bd1ce31da882351e2525..93d87686c8e212466be541ffaef1a20ae1d317b3 100644 (file)
--- a/lib/conncache.c
+++ b/lib/conncache.c
@@ -107,6 +107,7 @@ int Curl_conncache_init(struct conncache *connc, int size)
   connc->closure_handle = curl_easy_init();
   if(!connc->closure_handle)
     return 1; /* bad */
+  connc->closure_handle->internal = true;
 
   Curl_hash_init(&connc->hash, size, Curl_hash_str,
                  Curl_str_key_compare, free_bundle_hash_entry);

diff --git a/lib/doh.c b/lib/doh.c
index 6f99a061c33b486eba75594cc068abe231454b6c..bb0c89ec6d8657a22fc905bc5caf73618630449c 100644 (file)
--- a/lib/doh.c
+++ b/lib/doh.c
@@ -242,6 +242,7 @@ static CURLcode dohprobe(struct Curl_easy *data,
     /* pass in the struct pointer via a local variable to please coverity and
        the gcc typecheck helpers */
     struct dynbuf *resp = &p->serverdoh;
+    doh->internal = true;
     ERROR_CHECK_SETOPT(CURLOPT_URL, url);
     ERROR_CHECK_SETOPT(CURLOPT_DEFAULT_PROTOCOL, "https");
     ERROR_CHECK_SETOPT(CURLOPT_WRITEFUNCTION, doh_write_cb);

diff --git a/lib/multi.c b/lib/multi.c
index 19a950a8020576756c1a6b9a0288e2646f3fa93d..15b998865e27f8f143a4946fa4633cc9f5b9eddd 100644 (file)
--- a/lib/multi.c
+++ b/lib/multi.c
@@ -3788,3 +3788,21 @@ unsigned int Curl_multi_max_concurrent_streams(struct Curl_multi *multi)
   DEBUGASSERT(multi);
   return multi->max_concurrent_streams;
 }
+
+struct Curl_easy **curl_multi_get_handles(struct Curl_multi *multi)
+{
+  struct Curl_easy **a = malloc(sizeof(struct Curl_easy *) *
+                                (multi->num_easy + 1));
+  if(a) {
+    int i = 0;
+    struct Curl_easy *e = multi->easyp;
+    while(e) {
+      DEBUGASSERT(i < multi->num_easy);
+      if(!e->internal)
+        a[i++] = e;
+      e = e->next;
+    }
+    a[i] = NULL; /* last entry is a NULL */
+  }
+  return a;
+}

diff --git a/lib/urldata.h b/lib/urldata.h
index 82f0f18b1b928fab8300e30eca6a91378c4fd898..989caeeb8dfc631fa7cf0d0bc2642df775beed90 100644 (file)
--- a/lib/urldata.h
+++ b/lib/urldata.h
@@ -1950,7 +1950,7 @@ struct Curl_easy {
      other using the same cache. For easier tracking
      in log output.
      This may wrap around after LONG_MAX to 0 again, so it
-     has no uniqueness guarantuee for very large processings. */
+     has no uniqueness guarantee for very large processings. */
   curl_off_t id;
 
   /* first, two fields for the linked list of these */
@@ -2013,6 +2013,10 @@ struct Curl_easy {
 #ifdef USE_HYPER
   struct hyptransfer hyp;
 #endif
+
+  /* internal: true if this easy handle was created for internal use and the
+     user does not have ownership of the handle. */
+  bool internal;
 };
 
 #define LIBCURL_NAME "libcurl"

diff --git a/libcurl.def b/libcurl.def
index 1de609e80dfd4e89c713d100bf85a932e52793d4..c6c96063a11bb18a00285bb1bc202322ba455c02 100644 (file)
--- a/libcurl.def
+++ b/libcurl.def
@@ -51,6 +51,7 @@ curl_multi_add_handle
 curl_multi_assign
 curl_multi_cleanup
 curl_multi_fdset
+curl_multi_get_handles
 curl_multi_info_read
 curl_multi_init
 curl_multi_perform

diff --git a/scripts/singleuse.pl b/scripts/singleuse.pl
index 7b0b099647037593c545594b1dabf89d804ec1db..b8a57f8d8d851d4b08c49355b48a1b1f1bd90f60 100755 (executable)
--- a/scripts/singleuse.pl
+++ b/scripts/singleuse.pl
@@ -96,6 +96,7 @@ my %api = (
     'curl_multi_assign' => 'API',
     'curl_multi_cleanup' => 'API',
     'curl_multi_fdset' => 'API',
+    'curl_multi_get_handles' => 'API',
     'curl_multi_info_read' => 'API',
     'curl_multi_init' => 'API',
     'curl_multi_perform' => 'API',

diff --git a/tests/data/test1135 b/tests/data/test1135
index 0f055e9bc17b657d7f2504656977ee678a3ef580..17191feba3a0387ec8a636f54a9622986ce79d3c 100644 (file)
--- a/tests/data/test1135
+++ b/tests/data/test1135
@@ -106,6 +106,7 @@ curl_multi_socket_all
 curl_multi_timeout
 curl_multi_setopt
 curl_multi_assign
+curl_multi_get_handles
 curl_pushheader_bynum
 curl_pushheader_byname
 curl_easy_option_by_name