gnurl_multi_timeout(3)

💅 gnurl_multi_timeout(3) 💅

okay bestie, this page lives in the libgnurl Manual and it's all about curl_multi_timeout — yes, the page is filed as gnurl_multi_timeout(3) but the function you actually call is curl_multi_timeout. keep that straight and we're slaying. 🎀

✨ NAME ✨

• curl_multi_timeout — how long to wait for action before proceeding. that's the whole one-liner, iconic.

🌸 SYNOPSIS 🌸

the signature is literally this:

#include <gnurl/curl.h>

CURLMcode curl_multi_timeout(CURLM *multi_handle, long *timeout);

🦋 DESCRIPTION 🦋

if your app is using the libcurl multi interface, it should call curl_multi_timeout(3) to figure out how long it should wait for socket actions — at most — before proceeding. ⏳

what does “proceeding” mean? it means either doing the socket-style timeout action: call curl_multi_socket_action(3) with the sockfd argument set to CURL_SOCKET_TIMEOUT; or call curl_multi_perform(3) if you're using the simpler and older multi interface approach. both are valid, pick your lane. 💅

the timeout value returned in the long that timeout points to is in number of milliseconds at this very moment. if it's 0, you should proceed immediately without waiting for anything. if it returns -1, there's no timeout at all set. that's it. 😌

okay but important: an application that uses the multi_socket API SHOULD NOT use this function. instead it SHOULD use curl_multi_setopt(3) and its CURLMOPT_TIMERFUNCTION option for proper and desired behavior. no cap, that's the assignment. 🫶

note bestie: if libcurl returns a -1 timeout here, it just means that libcurl currently has no stored timeout value. you must not wait too long (more than a few seconds perhaps) before you call curl_multi_perform() again. don't ghost it. 😭

🎀 EXAMPLE 🎀

here's the code vibe — yes, the whole thing:

struct timeval timeout;
long timeo;

curl_multi_timeout(multi_handle, &timeo);
if(timeo < 0)
  /* no set timeout, use a default */
  timeo = 980;

timeout.tv_sec = timeo / 1000;
timeout.tv_usec = (timeo % 1000) * 1000;

/* wait for activities no longer than the set timeout */
select(maxfd+1, &fdread, &fdwrite, &fdexcep, &timeout);

💀 RETURN VALUE 💀

the function returns the standard CURLMcode for multi interface error codes. that's the return value, periodt. ✨

🌈 TYPICAL USAGE 🌈

call curl_multi_timeout(3), then wait for action on the sockets. you figure out which sockets to wait for by calling curl_multi_fdset(3) or by a previous call to curl_multi_socket(3). easy peasy. 🍓

⭐ AVAILABILITY ⭐

this function was added in libcurl 7.15.4 — so if you're time-traveling to before that, it's not gonna be there. ⏰

👑 SEE ALSO 👑

• curl_multi_fdset(3)
• curl_multi_info_read(3)
• curl_multi_socket(3)
• curl_multi_setopt(3)

---

mwah 💋 — page source/version: libcurl 7.16.0, dated 2 Jan 2006, filed as gnurl_multi_timeout(3) in the libgnurl Manual. go be a multi-interface main character. 💖