From 436cdf820412fd2ba77e1770d61c1150f0d7523a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 8 Dec 2021 15:37:37 +0100 Subject: [PATCH] curl_multi_perform/socket_action.3: clarify what errors mean An error returned from one of these funtions mean that ALL still ongoing transfers are to be considered failed. Ref: #8114 Closes #8120 --- docs/libcurl/curl_multi_perform.3 | 9 +++++++-- docs/libcurl/curl_multi_socket_action.3 | 5 +++++ 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/libcurl/curl_multi_perform.3 b/docs/libcurl/curl_multi_perform.3 index 324edb470c..327e452104 100644 --- a/docs/libcurl/curl_multi_perform.3 +++ b/docs/libcurl/curl_multi_perform.3 @@ -43,8 +43,8 @@ store 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 +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 @@ -53,6 +53,11 @@ 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. \fBcurl_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; diff --git a/docs/libcurl/curl_multi_socket_action.3 b/docs/libcurl/curl_multi_socket_action.3 index 5308ff33af..c30ce9990b 100644 --- a/docs/libcurl/curl_multi_socket_action.3 +++ b/docs/libcurl/curl_multi_socket_action.3 @@ -65,6 +65,11 @@ timeout action: call the \fIcurl_multi_socket_action(3)\fP function with the \fIcurl_multi_timeout(3)\fP function to poll the value at any given time, but for an event-based system using the callback is far better than relying on polling the timeout value. + +When this function returns error, the state of all transfers are uncertain and +they cannot be continued. \fBcurl_multi_socket_action(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 "TYPICAL USAGE" 1. Create a multi handle -- 2.47.3