101 lines
4.2 KiB
Groff
101 lines
4.2 KiB
Groff
|
.\" **************************************************************************
|
||
|
|
.\" * _ _ ____ _
|
||
|
|
.\" * 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_perform 3 "August 22, 2023" "libcurl 8.3.0" "libcurl"
|
||
|
|
|
||
|
|
.SH NAME
|
||
|
|
curl_multi_perform - reads/writes available data from easy handles
|
||
|
|
.SH SYNOPSIS
|
||
|
|
.nf
|
||
|
|
#include <curl/curl.h>
|
||
|
|
|
||
|
|
CURLMcode curl_multi_perform(CURLM *multi_handle, int *running_handles);
|
||
|
|
.fi
|
||
|
|
.SH DESCRIPTION
|
||
|
|
This function performs transfers on all the added handles that need attention
|
||
|
|
in a non-blocking fashion. The easy handles have previously been added to the
|
||
|
|
multi handle with \fIcurl_multi_add_handle(3)\fP.
|
||
|
|
|
||
|
|
When an application has found out there is data available for the multi_handle
|
||
|
|
or a timeout has elapsed, the application should call this function to
|
||
|
|
read/write whatever there is to read or write right now etc.
|
||
|
|
\fIcurl_multi_perform(3)\fP returns as soon as the reads/writes are done. This
|
||
|
|
function does not require that there actually is any data available for
|
||
|
|
reading or that data can be written, it can be called just in case. It stores
|
||
|
|
the number of handles that still transfer data in the second argument's
|
||
|
|
integer-pointer.
|
||
|
|
|
||
|
|
If the amount of \fIrunning_handles\fP is changed from the previous call (or
|
||
|
|
is less than the amount of easy handles you have added to the multi handle),
|
||
|
|
you know that there is one or more transfers less "running". You can then call
|
||
|
|
\fIcurl_multi_info_read(3)\fP to get information about each individual
|
||
|
|
completed transfer, and that returned info includes CURLcode and more. If an
|
||
|
|
added handle fails quickly, it may never be counted as a running_handle. You
|
||
|
|
could use \fIcurl_multi_info_read(3)\fP to track actual status of the added
|
||
|
|
handles in that case.
|
||
|
|
|
||
|
|
When \fIrunning_handles\fP is set to zero (0) on the return of this function,
|
||
|
|
there is no longer any transfers in progress.
|
||
|
|
|
||
|
|
When this function returns error, the state of all transfers are uncertain and
|
||
|
|
they cannot be continued. \fIcurl_multi_perform(3)\fP should not be called
|
||
|
|
again on the same multi handle after an error has been returned, unless first
|
||
|
|
removing all the handles and adding new ones.
|
||
|
|
.SH EXAMPLE
|
||
|
|
.nf
|
||
|
|
int still_running;
|
||
|
|
do {
|
||
|
|
CURLMcode mc = curl_multi_perform(multi_handle, &still_running);
|
||
|
|
|
||
|
|
if(!mc && still_running)
|
||
|
|
/* wait for activity, timeout or "nothing" */
|
||
|
|
mc = curl_multi_poll(multi_handle, NULL, 0, 1000, NULL);
|
||
|
|
|
||
|
|
if(mc) {
|
||
|
|
fprintf(stderr, "curl_multi_poll() failed, code %d.\\n", (int)mc);
|
||
|
|
break;
|
||
|
|
}
|
||
|
|
|
||
|
|
/* if there are still transfers, loop! */
|
||
|
|
} while(still_running);
|
||
|
|
.fi
|
||
|
|
.SH AVAILABILITY
|
||
|
|
Added in 7.9.6
|
||
|
|
.SH RETURN VALUE
|
||
|
|
CURLMcode type, general libcurl multi interface error code.
|
||
|
|
|
||
|
|
This function returns errors regarding the whole multi stack. Problems on
|
||
|
|
individual transfers may have occurred even when this function returns
|
||
|
|
\fICURLM_OK\fP. Use \fIcurl_multi_info_read(3)\fP to figure out how individual
|
||
|
|
transfers did.
|
||
|
|
.SH "TYPICAL USAGE"
|
||
|
|
Most applications use \fIcurl_multi_poll(3)\fP to make libcurl wait for
|
||
|
|
activity on any of the ongoing transfers. As soon as one or more file
|
||
|
|
descriptor has activity or the function times out, the application calls
|
||
|
|
\fIcurl_multi_perform(3)\fP.
|
||
|
|
.SH "SEE ALSO"
|
||
|
|
.BR curl_multi_cleanup "(3), " curl_multi_init "(3), "
|
||
|
|
.BR curl_multi_wait "(3), " curl_multi_add_handle "(3), "
|
||
|
|
.BR curl_multi_fdset "(3), " curl_multi_info_read "(3), "
|
||
|
|
.BR libcurl-errors "(3)"
|