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