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 c0dbfbc1608a038d5e5ee87c189e0dc319f20bf8..4e276a83aed55ee2d024b01b5b9c96c6bbe2f31c 100644 (file)
--- 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