1---
2c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLMOPT_TIMERFUNCTION
5Section: 3
6Source: libcurl
7See-also:
8  - CURLMOPT_SOCKETFUNCTION (3)
9  - CURLMOPT_TIMERDATA (3)
10---
11
12# NAME
13
14CURLMOPT_TIMERFUNCTION - callback to receive timeout values
15
16# SYNOPSIS
17
18~~~c
19#include <curl/curl.h>
20
21int timer_callback(CURLM *multi,    /* multi handle */
22                   long timeout_ms, /* timeout in number of ms */
23                   void *clientp);    /* private callback pointer */
24
25CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_TIMERFUNCTION, timer_callback);
26~~~
27
28# DESCRIPTION
29
30Pass a pointer to your callback function, which should match the prototype
31shown above.
32
33Certain features, such as timeouts and retries, require you to call libcurl
34even when there is no activity on the file descriptors.
35
36Your callback function **timer_callback** should install a non-repeating
37timer with an expire time of **timeout_ms** milliseconds. When that timer
38fires, call either curl_multi_socket_action(3) or
39curl_multi_perform(3), depending on which interface you use.
40
41A **timeout_ms** value of -1 passed to this callback means you should delete
42the timer. All other values are valid expire times in number of milliseconds.
43
44The **timer_callback** is called when the timeout expire time is changed.
45
46The **clientp** pointer is set with CURLMOPT_TIMERDATA(3).
47
48The timer callback should return 0 on success, and -1 on error. If this
49callback returns error, **all** transfers currently in progress in this
50multi handle are aborted and made to fail.
51
52This callback can be used instead of, or in addition to,
53curl_multi_timeout(3).
54
55**WARNING:** do not call libcurl directly from within the callback itself
56when the **timeout_ms** value is zero, since it risks triggering an
57unpleasant recursive behavior that immediately calls another call to the
58callback with a zero timeout...
59
60# DEFAULT
61
62NULL
63
64# PROTOCOLS
65
66All
67
68# EXAMPLE
69
70~~~c
71struct priv {
72  void *custom;
73};
74
75static int timerfunc(CURLM *multi, long timeout_ms, void *clientp)
76{
77 struct priv *mydata = clientp;
78 printf("our ptr: %p\n", mydata->custom);
79
80 if(timeout_ms) {
81   /* this is the new single timeout to wait for */
82 }
83 else {
84   /* delete the timeout, nothing to wait for now */
85 }
86}
87
88int main(void)
89{
90  struct priv mydata;
91  CURLM *multi = curl_multi_init();
92  curl_multi_setopt(multi, CURLMOPT_TIMERFUNCTION, timerfunc);
93  curl_multi_setopt(multi, CURLMOPT_TIMERDATA, &mydata);
94}
95~~~
96
97# AVAILABILITY
98
99Added in 7.16.0
100
101# RETURN VALUE
102
103Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
104