.\" generated by cd2nroff 0.1 from curl_multi_timeout.md
.TH curl_multi_timeout 3 "2026-05-13" libcurl
.SH NAME
curl_multi_timeout \- how long to wait for action before proceeding
.SH SYNOPSIS
.nf
#include <curl/curl.h>

CURLMcode curl_multi_timeout(CURLM *multi_handle, long *timeout);
.fi
.SH DESCRIPTION
An application using the libcurl multi interface should call
\fIcurl_multi_timeout(3)\fP to figure out how long it should wait for socket
actions \- at most \- before proceeding.

Proceeding means either doing the socket\-style timeout action: call the
\fIcurl_multi_socket_action(3)\fP function with the \fBsockfd\fP argument set
to CURL_SOCKET_TIMEOUT, or call \fIcurl_multi_perform(3)\fP if you are using
the simpler and older multi interface approach.

The timeout value returned in the long \fBtimeout_ms\fP points to, is in number
of milliseconds at this moment. If 0, it means you should proceed immediately
without waiting for anything. If it returns \-1, there is no timeout at all set.

An application that uses the \fImulti_socket\fP API should not use this function.
It should instead use the \fICURLMOPT_TIMERFUNCTION(3)\fP option for proper and
desired behavior.

Note: if libcurl returns a \-1 timeout here, it means that libcurl currently
has no stored timeout value. You must not wait too long (more than a few
seconds perhaps) before you call \fIcurl_multi_perform(3)\fP again.
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
  struct timeval timeout;
  long timeo;
  fd_set fdread;
  fd_set fdwrite;
  fd_set fdexcep;
  int maxfd = 2;
  CURLM *multi = curl_multi_init();

  curl_multi_timeout(multi, &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);
}
.fi
.SH TYPICAL USAGE
Call \fIcurl_multi_timeout(3)\fP, then wait for action on the sockets. Figure
out which sockets to wait for by calling \fIcurl_multi_fdset(3)\fP.

When there is activity or timeout, call \fIcurl_multi_perform(3)\fP and then
loop \- until all transfers are complete.
.SH AVAILABILITY
Added in curl 7.15.4
.SH RETURN VALUE
This function returns a CURLMcode indicating success or error.

CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see
\fIlibcurl\-errors(3)\fP.
.SH SEE ALSO
.BR curl_multi_fdset (3),
.BR curl_multi_info_read (3),
.BR curl_multi_setopt (3),
.BR curl_multi_socket (3)