From 3bc93643cbc0e805d5de23af959d9159671a89de Mon Sep 17 00:00:00 2001 From: Jayanth Vennamreddy Date: Wed, 4 Feb 2026 15:59:16 -0500 Subject: [PATCH] docs: connection reuse behavior for socket callbacks Document observed behavior around connections reuse and socket callbacks. When CURLOPT_CLOSESOCKETFUNCTION is copied and when it is invoked. Closes #20521 --- docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md | 3 ++- docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md | 13 +++++++++++++ 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md index 2774ccbfc7..fb67c01a60 100644 --- a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md +++ b/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,7 +98,7 @@ writable. ## CURL_POLL_REMOVE -The specified socket/file descriptor is no longer used by libcurl for any +The specified socket or file descriptor is no longer used by libcurl for any active transfer. It might soon be added again. When a socket is given a CURL_POLL_REMOVE value, it might be because libcurl diff --git a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md index 0dc9bb4c61..42a58e25a5 100644 --- a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md +++ b/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,18 @@ 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 + +The close socket callback is invoked when libcurl closes a socket it owns. +When using the multi interface, 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.