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