1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_SEEKFUNCTION
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_DEBUGFUNCTION (3)
9  - CURLOPT_IOCTLFUNCTION (3)
10  - CURLOPT_SEEKDATA (3)
11  - CURLOPT_STDERR (3)
12Protocol:
13  - All
14Added-in: 7.18.0
15---
16
17# NAME
18
19CURLOPT_SEEKFUNCTION - user callback for seeking in input stream
20
21# SYNOPSIS
22
23~~~c
24#include <curl/curl.h>
25
26/* These are the return codes for the seek callbacks */
27#define CURL_SEEKFUNC_OK       0
28#define CURL_SEEKFUNC_FAIL     1 /* fail the entire transfer */
29#define CURL_SEEKFUNC_CANTSEEK 2 /* tell libcurl seeking cannot be done, so
30                                    libcurl might try other means instead */
31
32int seek_callback(void *clientp, curl_off_t offset, int origin);
33
34CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SEEKFUNCTION, seek_callback);
35~~~
36
37# DESCRIPTION
38
39Pass a pointer to your callback function, which should match the prototype
40shown above.
41
42This function gets called by libcurl to seek to a certain position in the
43input stream and can be used to fast forward a file in a resumed upload
44(instead of reading all uploaded bytes with the normal read
45function/callback). It is also called to rewind a stream when data has already
46been sent to the server and needs to be sent again. This may happen when doing
47an HTTP PUT or POST with a multi-pass authentication method, or when an
48existing HTTP connection is reused too late and the server closes the
49connection. The function shall work like fseek(3) or lseek(3) and it gets
50SEEK_SET, SEEK_CUR or SEEK_END as argument for *origin*, although libcurl
51currently only passes SEEK_SET.
52
53*clientp* is the pointer you set with CURLOPT_SEEKDATA(3).
54
55The callback function must return *CURL_SEEKFUNC_OK* on success,
56*CURL_SEEKFUNC_FAIL* to cause the upload operation to fail or
57*CURL_SEEKFUNC_CANTSEEK* to indicate that while the seek failed, libcurl
58is free to work around the problem if possible. The latter can sometimes be
59done by instead reading from the input or similar.
60
61If you forward the input arguments directly to fseek(3) or lseek(3), note that
62the data type for *offset* is not the same as defined for curl_off_t on
63many systems.
64
65# DEFAULT
66
67NULL
68
69# %PROTOCOLS%
70
71# EXAMPLE
72
73~~~c
74#include <unistd.h> /* for lseek */
75
76struct data {
77  int our_fd;
78};
79static int seek_cb(void *clientp, curl_off_t offset, int origin)
80{
81  struct data *d = (struct data *)clientp;
82  lseek(d->our_fd, offset, origin);
83  return CURL_SEEKFUNC_OK;
84}
85
86int main(void)
87{
88  struct data seek_data;
89  CURL *curl = curl_easy_init();
90  if(curl) {
91    curl_easy_setopt(curl, CURLOPT_SEEKFUNCTION, seek_cb);
92    curl_easy_setopt(curl, CURLOPT_SEEKDATA, &seek_data);
93  }
94}
95~~~
96
97# %AVAILABILITY%
98
99# RETURN VALUE
100
101Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
102