From: Daniel Stenberg <daniel@haxx.se>
Date: Tue, 25 Oct 2022 22:35:07 +0000 (+0200)
Subject: CURLMOPT_SOCKETFUNCTION.3: clarify CURL_POLL_REMOVE
X-Git-Tag: curl-7_87_0~237
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=716ad5ea4976f095751a5522118e186b8b6ec31f;p=thirdparty%2Fcurl.git

CURLMOPT_SOCKETFUNCTION.3: clarify CURL_POLL_REMOVE

The removal is brief or long, don't assume.

Reported-by: Luca Niccoli

Fixes #9799
Closes #9800
---

diff --git a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.3 b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.3
index c0dbfbc160..4e276a83ae 100644
--- a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.3
+++ b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.3
@@ -40,12 +40,16 @@ CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_SOCKETFUNCTION, socket_callb
 Pass a pointer to your callback function, which should match the prototype
 shown above.
 
-When the \fIcurl_multi_socket_action(3)\fP function is called, it informs the
-application about updates in the socket (file descriptor) status by doing
-none, one, or multiple calls to the \fBsocket_callback\fP. The callback
-function gets status updates with changes since the previous time the callback
-was called. If the given callback pointer is set to NULL, no callback will be
-called.
+When the \fIcurl_multi_socket_action(3)\fP function is called, it uses this
+callback to inform the application about updates in the socket (file
+descriptor) status by doing none, one, or multiple calls to the
+\fBsocket_callback\fP. The callback function gets status updates with changes
+since the previous time the callback was called. If the given callback pointer
+is set to NULL, no callback will be called.
+
+libcurl then expects the application to monitor the sockets for the specific
+activities and tell libcurl again when something happens on one of them. Tell
+libcurl by calling \fIcurl_multi_socket_action(3)\fP.
 .SH "CALLBACK ARGUMENTS"
 \fIeasy\fP identifies the specific transfer for which this update is related.
 
@@ -73,7 +77,8 @@ Wait for outgoing data. For the socket to become writable.
 Wait for incoming and outgoing data. For the socket to become readable or
 writable.
 .IP CURL_POLL_REMOVE
-The specified socket/file descriptor is no longer used by libcurl.
+The specified socket/file descriptor is no longer used by libcurl for any
+active transfer. It might soon be added again.
 .SH DEFAULT
 NULL (no callback)
 .SH PROTOCOLS