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