Merge 9c58ed92c2 into 1d7b8e6c29

docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md

@@ -7,6 +7,7 @@ Source: libcurl
 See-also:
   - CURLMOPT_SOCKETDATA (3)
   - CURLMOPT_TIMERFUNCTION (3)
+  - CURLOPT_CLOSESOCKETFUNCTION (3)
   - curl_multi_socket_action (3)
 Protocol:
   - All
@@ -97,8 +98,10 @@ writable.
 
 ## CURL_POLL_REMOVE
 
-The specified socket/file descriptor is no longer used by libcurl for any
-active transfer. It might soon be added again.
+The specified socket or file descriptor is no longer used by libcurl for any
+active transfer. It might soon be added again. After libcurl signals
+CURL_POLL_REMOVE, the application must stop monitoring that socket on
+libcurl's behalf. libcurl does not track idle connections.
 
 When a socket is given a CURL_POLL_REMOVE value, it might be because libcurl
 is going to close it, but it might also mean that it does not need any more

docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md

@@ -7,6 +7,7 @@ Source: libcurl
 See-also:
   - CURLOPT_CLOSESOCKETDATA (3)
   - CURLOPT_OPENSOCKETFUNCTION (3)
+  - CURLMOPT_SOCKETFUNCTION (3)
 Protocol:
   - All
 Added-in: 7.21.7
@@ -47,6 +48,17 @@ after the easy handle has been cleaned up. The callback and data is
 inherited by a new connection and that connection may live longer
 than the transfer itself in the multi/share handle's connection cache.
 
+# NOTES ON CONNECTION REUSE
+
+When using the multi interface, the close socket callback is invoked when
+libcurl closes a socket it owns. The callback and CURLOPT_CLOSESOCKETDATA(3)
+are copied from the *first* easy handle that creates the socket used for a
+connection; changing this option on a subsequent easy handle that reuses the
+same connection has no effect for that connection. The callback is stored with
+the connection because the connection and its associated socket may outlive the
+easy handle that created it, so that libcurl can still invoke it when the
+socket is closed even after that handle has been cleaned up.
+
 # DEFAULT
 
 Use the standard socket close function.