mirror of
https://github.com/curl/curl.git
synced 2026-05-13 17:26:20 +03:00
c78044c07e
- Make curl_multi_waitfds consistent with the documentation. Issue Addressed: - The documentation of curl_multi_waitfds indicates that users should be able to call curl_multi_waitfds with a NULL ufds. However, before this change, the function would return CURLM_BAD_FUNCTION_ARGUMENT. - Additionally, the documentation suggests that users can use this function to determine the number of file descriptors (fds) needed. However, the function would stop counting fds if the supplied fds were exhausted. Changes Made: - NULL ufds Handling: curl_multi_waitfds can now accept a NULL ufds if size is also zero. - Counting File Descriptors: If curl_multi_waitfds is passed a NULL ufds, or the size of ufds is insufficient, the output parameter fd_count will return the number of fds needed. This value may be higher than actually needed but never lower. Testing: - Test 2405 has been updated to cover the usage scenarios described above. Fixes https://github.com/curl/curl/issues/15146 Closes https://github.com/curl/curl/pull/15155
113 lines
2.9 KiB
Markdown
113 lines
2.9 KiB
Markdown
---
|
|
c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
|
|
SPDX-License-Identifier: curl
|
|
Title: curl_multi_waitfds
|
|
Section: 3
|
|
Source: libcurl
|
|
See-also:
|
|
- curl_multi_perform (3)
|
|
- curl_multi_poll (3)
|
|
- curl_multi_wait (3)
|
|
- curl_multi_fdset (3)
|
|
Protocol:
|
|
- All
|
|
Added-in: 8.8.0
|
|
---
|
|
|
|
# NAME
|
|
|
|
curl_multi_waitfds - extract file descriptor information from a multi handle
|
|
|
|
# SYNOPSIS
|
|
|
|
~~~c
|
|
#include <curl/curl.h>
|
|
#include <stdlib.h>
|
|
|
|
CURLMcode curl_multi_waitfds(CURLM *multi,
|
|
struct curl_waitfd *ufds,
|
|
unsigned int size,
|
|
unsigned int *fd_count);
|
|
~~~
|
|
|
|
# DESCRIPTION
|
|
|
|
This function extracts *curl_waitfd* structures which are similar to
|
|
*poll(2)*'s *pollfd* structure from a given multi_handle.
|
|
|
|
These structures can be used for polling on multi_handle file descriptors in a
|
|
fashion similar to curl_multi_poll(3). The curl_multi_perform(3)
|
|
function should be called as soon as one of them is ready to be read from or
|
|
written to.
|
|
|
|
libcurl fills provided *ufds* array up to the *size*.
|
|
If a number of descriptors used by the multi_handle is greater than the
|
|
*size* parameter then libcurl returns CURLM_OUT_OF_MEMORY error.
|
|
|
|
If the *fd_count* argument is not a null pointer, it points to a variable
|
|
that on return specifies the number of descriptors used by the multi_handle to
|
|
be checked for being ready to read or write.
|
|
|
|
The client code can pass *size* equal to zero just to get the number of the
|
|
descriptors and allocate appropriate storage for them to be used in a
|
|
subsequent function call. In this case, *fd_count* receives a number greater
|
|
than or equal to the number of descriptors.
|
|
|
|
# %PROTOCOLS%
|
|
|
|
# EXAMPLE
|
|
|
|
~~~c
|
|
#include <stdlib.h>
|
|
|
|
int main(void)
|
|
{
|
|
CURLMcode mc;
|
|
struct curl_waitfd *ufds;
|
|
|
|
CURLM *multi = curl_multi_init();
|
|
|
|
do {
|
|
/* call curl_multi_perform() */
|
|
|
|
/* get the count of file descriptors from the transfers */
|
|
unsigned int fd_count = 0;
|
|
|
|
mc = curl_multi_waitfds(multi, NULL, 0, &fd_count);
|
|
|
|
if(mc != CURLM_OK) {
|
|
fprintf(stderr, "curl_multi_waitfds() failed, code %d.\n", mc);
|
|
break;
|
|
}
|
|
|
|
if(!fd_count)
|
|
continue; /* no descriptors yet */
|
|
|
|
/* Allocate storage for our descriptors.
|
|
* Note that a better approach can be used to minimize allocations and
|
|
* deallocations, if needed, like pre-allocated or grow-only array.
|
|
*/
|
|
ufds = (struct curl_waitfd*)malloc(fd_count * sizeof(struct curl_waitfd));
|
|
|
|
/* get wait descriptors from the transfers and put them into array. */
|
|
mc = curl_multi_waitfds(multi, ufds, fd_count, &fd_count);
|
|
|
|
if(mc != CURLM_OK) {
|
|
fprintf(stderr, "curl_multi_waitfds() failed, code %d.\n", mc);
|
|
free(ufds);
|
|
break;
|
|
}
|
|
|
|
/* Do polling on descriptors in ufds */
|
|
|
|
free(ufds);
|
|
} while(!mc);
|
|
}
|
|
~~~
|
|
|
|
# %AVAILABILITY%
|
|
|
|
# RETURN VALUE
|
|
|
|
**CURLMcode** type, general libcurl multi interface error code. See
|
|
libcurl-errors(3)
|