From 3730a986649e377b2b7557bd2b7d2429d0a03b84 Mon Sep 17 00:00:00 2001 From: jayvenn21 Date: Sat, 7 Feb 2026 18:43:00 -0500 Subject: [PATCH] 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