curl_multi_timeout

Syntax

#include <curl/curl.h>

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

Parameters

multi_handle Pointer to a multi handle.
timeout Pointer to a timeout value in milliseconds.

Return Values

If the operation was successful, CURLM_OK is returned. Otherwise, a specific CURLM libcurl Error Code is returned.

Description

An application using the libcurl multi interface should call curl_multi_timeout to decide how long it should wait for socket actions, at most, before proceeding.

Proceeding requires either performing the socket-style timeout action: call the curl_multi_socket_action function with the sockfd argument set to CURL_SOCKET_TIMEOUT, or calling curl_multi_perform if using the simpler and older multi interface approach.

The timeout value returned in the long that timeout points to, is in number of milliseconds at the exact moment. If 0, proceed immediately without waiting. If it returns -1, there is no timeout set.

An application that uses the multi_socket API should not use this function, but should instead use curl_multi_setopt and its CURLMOPT_TIMERFUNCTION option for correct and desired behavior.

NOTE:
If libcurl returns a -1 timeout, it indicates that libcurl currently has no stored timeout value. Do not wait too long (more than a few seconds) before calling curl_multi_perform again.

Typical Usage

Call curl_multi_timeout, then wait for action on the sockets. Decide which sockets to wait for by calling curl_multi_fdset or by a previous call to curl_multi_socket.

Availability

This function was added in libcurl 7.15.4.

Do Not Call From

None.

See Also

HTTP Client Library (libcurl)
libcurl API Functions
libcurl Error Codes
curl_multi_fdset
curl_multi_info_read
curl_multi_socket
curl_multi_setopt

Revision History

2013/09/18 Conversion
2013/05/08 Automated cleanup pass.
2012/05/04 Initial version.


CONFIDENTIAL