From 91526273544ffbcafc0c20fa46f31659d45fb3b5 Mon Sep 17 00:00:00 2001 From: jayvenn21 Date: Wed, 4 Feb 2026 15:59:16 -0500 Subject: [PATCH 01/13] docs: document idle connection behavior for socket callbacks Document observed behavior around idle connections and socket callbacks: - When CURLOPT_CLOSESOCKETFUNCTION is copied and when it is invoked - How idle connections interact with CURLMOPT_SOCKETFUNCTION - Why read/error events may still occur on sockets removed from polling No functional changes. --- docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md | 7 +++- .../opts/CURLOPT_CLOSESOCKETFUNCTION.md | 35 +++++++++++++++++++ 2 files changed, 41 insertions(+), 1 deletion(-) diff --git a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md index 2774ccbfc7..4fd81d7a57 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 @@ -98,7 +99,11 @@ 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. +active transfer. It might soon be added again. When a connection enters +the idle pool, libcurl invokes the callback with CURL_POLL_REMOVE. +Subsequent callbacks for that socket may have *socketp* set to NULL; do +not rely on *socketp* to track idle connections. For more on idle +connection behavior, see CURLOPT_CLOSESOCKETFUNCTION(3). 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 diff --git a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md index 0dc9bb4c61..50621c22c3 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,40 @@ 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 IDLE CONNECTIONS + +When using the multi interface with a connection cache, the following +observed behavior applies. It is relevant for applications that manage +large numbers of sockets and custom polling loops (e.g. kqueue or epoll). + +**CURLOPT_CLOSESOCKETFUNCTION lifecycle** + +The callback and CURLOPT_CLOSESOCKETDATA(3) are copied from the *first* easy +handle that creates the connection. Changing this option on a subsequent +easy handle that reuses the same connection has no effect for that +connection. The callback is not invoked when an idle connection is +closed after CURL_CSELECT_ERR (e.g. when the socket has already been +reported as in error state). Applications should not rely on the close +callback to be called for every socket that leaves use. + +**Idle connection polling** + +Connections in the idle pool may still receive read (or error) events +from the kernel. Polling backends (kqueue, epoll, etc.) can deliver +events even after libcurl has removed read/write interest for that +socket. This can surface as zero-length reads or spurious data when +the connection is later closed or reused. Applications using +CURLMOPT_SOCKETFUNCTION(3) should handle such events without assuming +the socket is still actively used by libcurl. + +**CURLMOPT_SOCKETFUNCTION and idle sockets** + +When a connection enters the idle pool, libcurl invokes the socket +callback with CURL_POLL_REMOVE. Subsequent callbacks for that socket +may have *socketp* set to NULL. Do not rely on *socketp* to track idle +connections; use the socket descriptor and *easy* (or your own mapping) +instead. + # DEFAULT Use the standard socket close function. From 45bc09e7869e6bbd9bc94b21dd3ecdb41426c744 Mon Sep 17 00:00:00 2001 From: jayvenn21 Date: Wed, 4 Feb 2026 16:21:42 -0500 Subject: [PATCH 02/13] docs: fix man page formatting for idle connection behavior --- docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md | 2 +- docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md index 4fd81d7a57..558c98306e 100644 --- a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md +++ b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md @@ -98,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 connection enters the idle pool, libcurl invokes the callback with CURL_POLL_REMOVE. Subsequent callbacks for that socket may have *socketp* set to NULL; do diff --git a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md index 50621c22c3..a69aab89d4 100644 --- a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md @@ -54,7 +54,7 @@ When using the multi interface with a connection cache, the following observed behavior applies. It is relevant for applications that manage large numbers of sockets and custom polling loops (e.g. kqueue or epoll). -**CURLOPT_CLOSESOCKETFUNCTION lifecycle** +## Callback lifecycle The callback and CURLOPT_CLOSESOCKETDATA(3) are copied from the *first* easy handle that creates the connection. Changing this option on a subsequent @@ -64,17 +64,17 @@ closed after CURL_CSELECT_ERR (e.g. when the socket has already been reported as in error state). Applications should not rely on the close callback to be called for every socket that leaves use. -**Idle connection polling** +## Idle connection polling -Connections in the idle pool may still receive read (or error) events +Connections in the idle pool may still receive read or error events from the kernel. Polling backends (kqueue, epoll, etc.) can deliver -events even after libcurl has removed read/write interest for that +events even after libcurl has removed read or write interest for that socket. This can surface as zero-length reads or spurious data when the connection is later closed or reused. Applications using CURLMOPT_SOCKETFUNCTION(3) should handle such events without assuming the socket is still actively used by libcurl. -**CURLMOPT_SOCKETFUNCTION and idle sockets** +## Socket callback and idle sockets When a connection enters the idle pool, libcurl invokes the socket callback with CURL_POLL_REMOVE. Subsequent callbacks for that socket From 03bbd8b9e0021bb564bbe5398ea11db2a15f30b3 Mon Sep 17 00:00:00 2001 From: jayvenn21 Date: Wed, 4 Feb 2026 16:25:55 -0500 Subject: [PATCH 03/13] docs: fix spelling in CURLOPT_CLOSESOCKETFUNCTION --- docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md index a69aab89d4..37dc13fec9 100644 --- a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md @@ -54,7 +54,7 @@ When using the multi interface with a connection cache, the following observed behavior applies. It is relevant for applications that manage large numbers of sockets and custom polling loops (e.g. kqueue or epoll). -## Callback lifecycle +## Callback life cycle The callback and CURLOPT_CLOSESOCKETDATA(3) are copied from the *first* easy handle that creates the connection. Changing this option on a subsequent From 1b1ad3a6014d5f69d920f952a6b038356ea18262 Mon Sep 17 00:00:00 2001 From: jayvenn21 Date: Thu, 5 Feb 2026 08:25:33 -0500 Subject: [PATCH 04/13] docs: clarify idle connection polling behavior per review --- docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md index 37dc13fec9..657a80969b 100644 --- a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md @@ -66,13 +66,15 @@ callback to be called for every socket that leaves use. ## Idle connection polling -Connections in the idle pool may still receive read or error events -from the kernel. Polling backends (kqueue, epoll, etc.) can deliver -events even after libcurl has removed read or write interest for that -socket. This can surface as zero-length reads or spurious data when -the connection is later closed or reused. Applications using -CURLMOPT_SOCKETFUNCTION(3) should handle such events without assuming -the socket is still actively used by libcurl. +Idle connections are not expected to receive application data. Read or +error events may still occur when the peer closes the connection, or as +zero-length reads, or for HTTPS when encrypted data decrypts to +zero-length. libcurl cannot safely interpret or act on such events +once the socket has been removed from polling (CURL_POLL_REMOVE), and +applications cannot forward them to libcurl for idle connections. +Applications must handle fd reuse and spurious readiness events +defensively; the underlying risk is the kernel closing or reusing the +fd after libcurl has stopped monitoring it. ## Socket callback and idle sockets From 7d65e271c51c26b0491bd7d6f142f317472b178e Mon Sep 17 00:00:00 2001 From: jayvenn21 Date: Thu, 5 Feb 2026 08:29:53 -0500 Subject: [PATCH 05/13] docs: fix pyspelling by marking technical terms --- docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md index 657a80969b..413ad0f70d 100644 --- a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md @@ -68,13 +68,13 @@ callback to be called for every socket that leaves use. Idle connections are not expected to receive application data. Read or error events may still occur when the peer closes the connection, or as -zero-length reads, or for HTTPS when encrypted data decrypts to +zero-length reads, or for HTTPS when encrypted data `decrypts` to zero-length. libcurl cannot safely interpret or act on such events once the socket has been removed from polling (CURL_POLL_REMOVE), and applications cannot forward them to libcurl for idle connections. -Applications must handle fd reuse and spurious readiness events +Applications must handle `fd` reuse and spurious readiness events defensively; the underlying risk is the kernel closing or reusing the -fd after libcurl has stopped monitoring it. +`fd` after libcurl has stopped monitoring it. ## Socket callback and idle sockets From 9426e140c0e8b4b3b5be90de42a5737ba12fefb2 Mon Sep 17 00:00:00 2001 From: jayvenn21 Date: Sat, 7 Feb 2026 17:33:17 -0500 Subject: [PATCH 06/13] docs: reframe idle connection notes as API guarantees per review --- docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md | 11 +++--- .../opts/CURLOPT_CLOSESOCKETFUNCTION.md | 38 +++++++++---------- 2 files changed, 24 insertions(+), 25 deletions(-) diff --git a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md index 558c98306e..a2dc71b933 100644 --- a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md +++ b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md @@ -99,11 +99,12 @@ writable. ## CURL_POLL_REMOVE The specified socket or file descriptor is no longer used by libcurl for any -active transfer. It might soon be added again. When a connection enters -the idle pool, libcurl invokes the callback with CURL_POLL_REMOVE. -Subsequent callbacks for that socket may have *socketp* set to NULL; do -not rely on *socketp* to track idle connections. For more on idle -connection behavior, see CURLOPT_CLOSESOCKETFUNCTION(3). +active transfer. It might soon be added again. After libcurl signals +CURL_POLL_REMOVE, the application must stop monitoring that socket for +read and write events on libcurl's behalf. The pointer previously assigned +to the socket with curl_multi_assign(3) is forgotten by libcurl. +Applications must not rely on *socketp* to track idle connections. For +more on idle connection behavior, see CURLOPT_CLOSESOCKETFUNCTION(3). 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 diff --git a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md index 413ad0f70d..52d8d0aaba 100644 --- a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md @@ -50,9 +50,9 @@ than the transfer itself in the multi/share handle's connection cache. # NOTES ON IDLE CONNECTIONS -When using the multi interface with a connection cache, the following -observed behavior applies. It is relevant for applications that manage -large numbers of sockets and custom polling loops (e.g. kqueue or epoll). +When using the multi interface with a connection cache, applications must +not assume that sockets associated with idle connections behave the same +as active connections. ## Callback life cycle @@ -60,29 +60,27 @@ The callback and CURLOPT_CLOSESOCKETDATA(3) are copied from the *first* easy handle that creates the connection. Changing this option on a subsequent easy handle that reuses the same connection has no effect for that connection. The callback is not invoked when an idle connection is -closed after CURL_CSELECT_ERR (e.g. when the socket has already been -reported as in error state). Applications should not rely on the close +closed after CURL_CSELECT_ERR. Applications should not rely on the close callback to be called for every socket that leaves use. -## Idle connection polling +## Readiness events after CURL_POLL_REMOVE -Idle connections are not expected to receive application data. Read or -error events may still occur when the peer closes the connection, or as -zero-length reads, or for HTTPS when encrypted data `decrypts` to -zero-length. libcurl cannot safely interpret or act on such events -once the socket has been removed from polling (CURL_POLL_REMOVE), and -applications cannot forward them to libcurl for idle connections. -Applications must handle `fd` reuse and spurious readiness events -defensively; the underlying risk is the kernel closing or reusing the -`fd` after libcurl has stopped monitoring it. +Applications must not assume that receiving readiness events for a socket +implies that libcurl still expects the socket to be reported back via +curl_multi_socket_action(3). Readiness events may occur for reasons +outside libcurl's control, but libcurl provides no API for reporting such +events once a socket has been removed from polling. Applications +integrating with external polling systems must defensively handle +unexpected readiness events. ## Socket callback and idle sockets -When a connection enters the idle pool, libcurl invokes the socket -callback with CURL_POLL_REMOVE. Subsequent callbacks for that socket -may have *socketp* set to NULL. Do not rely on *socketp* to track idle -connections; use the socket descriptor and *easy* (or your own mapping) -instead. +After libcurl signals CURL_POLL_REMOVE for a socket, the application must +stop monitoring that socket for read and write events on libcurl's behalf. +libcurl may still retain the connection internally for reuse. When the +socket has been removed, the pointer previously assigned to it with +curl_multi_assign(3) is forgotten by libcurl. Applications must not rely +on *socketp* to track idle connections. # DEFAULT From db82a8f110a58444c1e7632a5a793f94dea93327 Mon Sep 17 00:00:00 2001 From: Jayanth Vennamreddy <53269831+jayvenn21@users.noreply.github.com> Date: Sat, 7 Feb 2026 18:39:41 -0500 Subject: [PATCH 07/13] Update docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md Co-authored-by: Daniel Stenberg --- docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md index 52d8d0aaba..cbb30be296 100644 --- a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md @@ -76,7 +76,7 @@ unexpected readiness events. ## Socket callback and idle sockets After libcurl signals CURL_POLL_REMOVE for a socket, the application must -stop monitoring that socket for read and write events on libcurl's behalf. +stop monitoring that socket on libcurl's behalf. libcurl may still retain the connection internally for reuse. When the socket has been removed, the pointer previously assigned to it with curl_multi_assign(3) is forgotten by libcurl. Applications must not rely From 386e35cda66ec79e03f029125fc7c1ac2e5ad7f6 Mon Sep 17 00:00:00 2001 From: Jayanth Vennamreddy <53269831+jayvenn21@users.noreply.github.com> Date: Sat, 7 Feb 2026 18:39:51 -0500 Subject: [PATCH 08/13] Update docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md Co-authored-by: Daniel Stenberg --- docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md index cbb30be296..e390695600 100644 --- a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md @@ -79,8 +79,7 @@ After libcurl signals CURL_POLL_REMOVE for a socket, the application must stop monitoring that socket on libcurl's behalf. libcurl may still retain the connection internally for reuse. When the socket has been removed, the pointer previously assigned to it with -curl_multi_assign(3) is forgotten by libcurl. Applications must not rely -on *socketp* to track idle connections. +curl_multi_assign(3) is forgotten by libcurl. libcurl does not track idle connections. # DEFAULT From 3730a986649e377b2b7557bd2b7d2429d0a03b84 Mon Sep 17 00:00:00 2001 From: jayvenn21 Date: Sat, 7 Feb 2026 18:43:00 -0500 Subject: [PATCH 09/13] docs: limit close socket callback documentation to defined behavior Remove socket function and polling details from the close socket callback man page and clarify only the documented lifecycle guarantees. --- docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md | 9 +++-- .../opts/CURLOPT_CLOSESOCKETFUNCTION.md | 34 ++++--------------- 2 files changed, 10 insertions(+), 33 deletions(-) diff --git a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md index a2dc71b933..c6d74036ca 100644 --- a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md +++ b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md @@ -100,11 +100,10 @@ writable. 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 for -read and write events on libcurl's behalf. The pointer previously assigned -to the socket with curl_multi_assign(3) is forgotten by libcurl. -Applications must not rely on *socketp* to track idle connections. For -more on idle connection behavior, see CURLOPT_CLOSESOCKETFUNCTION(3). +CURL_POLL_REMOVE, the application must stop monitoring that socket on +libcurl's behalf. libcurl does not track idle connections. The pointer +previously assigned to the socket with curl_multi_assign(3) is forgotten by +libcurl. Applications must not rely on *socketp* to 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 diff --git a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md index e390695600..66a66e6f28 100644 --- a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md @@ -50,36 +50,14 @@ than the transfer itself in the multi/share handle's connection cache. # NOTES ON IDLE CONNECTIONS -When using the multi interface with a connection cache, applications must -not assume that sockets associated with idle connections behave the same -as active connections. - -## Callback life cycle - +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 connection. Changing this option on a subsequent +handle that creates the connection; changing this option on a subsequent easy handle that reuses the same connection has no effect for that -connection. The callback is not invoked when an idle connection is -closed after CURL_CSELECT_ERR. Applications should not rely on the close -callback to be called for every socket that leaves use. - -## Readiness events after CURL_POLL_REMOVE - -Applications must not assume that receiving readiness events for a socket -implies that libcurl still expects the socket to be reported back via -curl_multi_socket_action(3). Readiness events may occur for reasons -outside libcurl's control, but libcurl provides no API for reporting such -events once a socket has been removed from polling. Applications -integrating with external polling systems must defensively handle -unexpected readiness events. - -## Socket callback and idle sockets - -After libcurl signals CURL_POLL_REMOVE for a socket, the application must -stop monitoring that socket on libcurl's behalf. -libcurl may still retain the connection internally for reuse. When the -socket has been removed, the pointer previously assigned to it with -curl_multi_assign(3) is forgotten by libcurl. libcurl does not track idle connections. +connection. The callback is not guaranteed to be called for every socket +that leaves use, for example when connections are kept alive in the +connection cache and reused. Applications must not assume the callback is +called for every socket lifecycle. # DEFAULT From ba041b04a15cfb1aa29be2407b475f68d8c2e2dc Mon Sep 17 00:00:00 2001 From: jayvenn21 Date: Mon, 9 Feb 2026 10:33:25 -0500 Subject: [PATCH 10/13] docs: narrow CURLOPT_CLOSESOCKETFUNCTION to defined guarantees --- docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md index 66a66e6f28..6ad9a5050f 100644 --- a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md @@ -50,14 +50,11 @@ than the transfer itself in the multi/share handle's connection cache. # NOTES ON IDLE CONNECTIONS -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 connection; changing this option on a subsequent -easy handle that reuses the same connection has no effect for that -connection. The callback is not guaranteed to be called for every socket -that leaves use, for example when connections are kept alive in the -connection cache and reused. Applications must not assume the callback is -called for every socket lifecycle. +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 connection; +changing this option on a subsequent easy handle that reuses the same +connection has no effect for that connection. # DEFAULT From 8158f622a6f56cd2b0d171d225cb18788e1c5a46 Mon Sep 17 00:00:00 2001 From: jayvenn21 Date: Mon, 9 Feb 2026 19:37:20 -0500 Subject: [PATCH 11/13] docs: remove redundant socketp sentence per review --- docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md index c6d74036ca..ad71f413f8 100644 --- a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md +++ b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md @@ -103,7 +103,7 @@ 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. The pointer previously assigned to the socket with curl_multi_assign(3) is forgotten by -libcurl. Applications must not rely on *socketp* to track idle connections. +libcurl. 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 From 21e2e5479521fec8bf421fd715267c9ab12404e7 Mon Sep 17 00:00:00 2001 From: jayvenn21 Date: Tue, 10 Feb 2026 11:14:37 -0500 Subject: [PATCH 12/13] docs: add reason callback is stored with connection per review --- docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md index 6ad9a5050f..3de339e49b 100644 --- a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md @@ -54,7 +54,10 @@ 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 connection; changing this option on a subsequent easy handle that reuses the same -connection has no effect for that connection. +connection has no effect for that connection. The callback is stored with +the connection because the connection may outlive the easy handle that +created it, so that libcurl can still invoke it when the connection is +closed even after that handle has been cleaned up. # DEFAULT From 9c58ed92c26ad897cc22e0dbba8a4c45b5da39e8 Mon Sep 17 00:00:00 2001 From: jayvenn21 Date: Fri, 19 Jun 2026 11:37:17 -0400 Subject: [PATCH 13/13] docs: address socket callback review feedback --- docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md | 4 +--- docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md | 14 +++++++------- 2 files changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md index ad71f413f8..a40967a449 100644 --- a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md +++ b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md @@ -101,9 +101,7 @@ writable. 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. The pointer -previously assigned to the socket with curl_multi_assign(3) is forgotten by -libcurl. +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 diff --git a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md index 3de339e49b..f141da2536 100644 --- a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md @@ -48,16 +48,16 @@ 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 IDLE CONNECTIONS +# 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 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 may outlive the easy handle that -created it, so that libcurl can still invoke it when the connection is -closed even after that handle has been cleaned up. +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