b71d3d9aea
Daniel Stenberg
2026-06-18
Subject
CURLMOPT_SOCKETFUNCTION.md: this sends *all* file descriptors
Binary
No binary (build failed)
Architecture & Compiler Flags
—
Build Log
(log yok)
Commit Diff GitHub →
docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md+35 -21
| @@ -22,13 +22,14 @@ CURLMOPT_SOCKETFUNCTION - callback informed about what to wait for | |
| ~~~c | |
| #include <curl/curl.h> | |
| - | int socket_callback(CURL *easy, /* easy handle */ |
| - | curl_socket_t s, /* socket */ |
| - | int what, /* describes the socket */ |
| - | void *clientp, /* private callback pointer */ |
| - | void *socketp); /* private socket pointer */ |
| - | |
| - | CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_SOCKETFUNCTION, socket_callback); |
| + | int socket_callback(CURL *easy, |
| + | curl_socket_t socket, |
| + | int what, |
| + | void *clientp, |
| + | void *socketp); |
| + | |
| + | CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_SOCKETFUNCTION, |
| + | socket_callback); |
| ~~~ | |
| # DESCRIPTION | |
| @@ -36,12 +37,12 @@ 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 curl_multi_socket_action(3) 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 |
| - | **socket_callback**. 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 is called. |
| + | When the curl_multi_socket_action(3) 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 **socket_callback**. 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 is |
| + | 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 | |
| @@ -52,18 +53,23 @@ This may even happen after all transfers are done and is *likely* to | |
| happen *during* a call to curl_multi_cleanup(3) when cached connections | |
| are shut down. | |
| + | libcurl may use a number of internal file descriptors for name resolving, |
| + | Happy Eyeballs racing, internal communication and more, in addition to the |
| + | main sockets used for network transfers. All of those file descriptors might |
| + | get passed to this callback as "sockets". |
| + | |
| # CALLBACK ARGUMENTS | |
| - | *easy* identifies the specific transfer for which this update is related. |
| + | **easy** identifies the specific transfer for which this update is related. |
| Since this callback manages a whole multi handle, an application should not | |
| make assumptions about which particular handle that is passed here. It might | |
| even be an internal easy handle that the application did not add itself. | |
| - | *s* is the specific socket this function invocation concerns. If the |
| - | **what** argument is not CURL_POLL_REMOVE then it holds information about |
| - | what activity on this socket the application is supposed to |
| - | monitor. Subsequent calls to this callback might update the **what** bits |
| - | for a socket that is already monitored. |
| + | **socket** is the specific socket this function invocation concerns. If the |
| + | **what** argument is not CURL_POLL_REMOVE then it holds information about what |
| + | activity on this socket the application is supposed to monitor. Subsequent |
| + | calls to this callback might update the **what** bits for a socket that is |
| + | already monitored. |
| The socket callback should return 0 on success, and -1 on error. If this | |
| callback returns error, **all** transfers currently in progress in this | |
| @@ -73,8 +79,8 @@ multi handle are aborted and made to fail. | |
| **socketp** is set with curl_multi_assign(3) or NULL. | |
| - | The **what** parameter informs the callback on the status of the given |
| - | socket. It can hold one of these values: |
| + | The **what** parameter informs the callback on the status of the given socket. |
| + | It can hold one of these values: |
| ## CURL_POLL_IN | |
| @@ -94,6 +100,14 @@ writable. | |
| The specified socket/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 |
| + | is going to close it, but it might also mean that it does not need any more |
| + | monitoring for the moment. An application cannot assume either. The same |
| + | socket might appear soon in a call asking for monitoring again. |
| + | |
| + | A socket that is removed like this loses its assigned pointer as set with |
| + | curl_multi_assign(3). |
| + | |
| # DEFAULT | |
| NULL (no callback) | |