aboutsummaryrefslogtreecommitdiff
path: root/docs/libcurl
diff options
context:
space:
mode:
authorDaniel Stenberg <daniel@haxx.se>2008-01-10 10:30:19 +0000
committerDaniel Stenberg <daniel@haxx.se>2008-01-10 10:30:19 +0000
commit18faa509403c39b4914114cfe2966241b62b2959 (patch)
treebb5e0bf7ac66a313e62263348449afbe4ad924c6 /docs/libcurl
parent0ce484eed901f73cae89e25d9939a249729f15d3 (diff)
Georg Lippitsch brought CURLOPT_SEEKFUNCTION and CURLOPT_SEEKDATA to allow
libcurl to seek in a given input stream. This is particularly important when doing upload resumes when there's already a huge part of the file present remotely. Before, and still if this callback isn't used, libcurl will read and through away the entire file up to the point to where the resuming begins (which of course can be a slow opereration depending on file size, I/O bandwidth and more). This new function will also be preferred to get used instead of the CURLOPT_IOCTLFUNCTION for seeking back in a stream when doing multi-stage HTTP auth with POST/PUT.
Diffstat (limited to 'docs/libcurl')
-rw-r--r--docs/libcurl/curl_easy_setopt.323
1 files changed, 22 insertions, 1 deletions
diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3
index 96f2d2b2c..56b763fe7 100644
--- a/docs/libcurl/curl_easy_setopt.3
+++ b/docs/libcurl/curl_easy_setopt.3
@@ -171,11 +171,32 @@ something special I/O-related needs to be done that the library can't do by
itself. For now, rewinding the read data stream is the only action it can
request. The rewinding of the read data stream may be necessary when doing a
HTTP PUT or POST with a multi-pass authentication method. (Option added in
-7.12.3)
+7.12.3).
+
+Use \fICURLOPT_SEEKFUNCTION\fP instead to provide seeking!
.IP CURLOPT_IOCTLDATA
Pass a pointer that will be untouched by libcurl and passed as the 3rd
argument in the ioctl callback set with \fICURLOPT_IOCTLFUNCTION\fP. (Option
added in 7.12.3)
+.IP CURLOPT_SEEKFUNCTION
+Function pointer that should match the following prototype: \fIint
+function(void *instream, curl_off_t offset, int origin);\fP This function gets
+called by libcurl to seek to a certain position in the input stream and can be
+used to fast forward a file in a resumed upload (instead of reading all
+uploaded bytes with the normal read function/callback). It is also called to
+rewind a stream when doing a HTTP PUT or POST with a multi-pass authentication
+method. The function shall work like "fseek" or "lseek" and accepted SEEK_SET,
+SEEK_CUR and SEEK_END as argument for origin, although (in 7.18.0) libcurl
+only passes SEEK_SET. The callback must return 0 on success as returning
+non-zero will cause the upload operation to fail.
+
+If you forward the input arguments directly to "fseek" or "lseek", note that
+the data type for \fIoffset\fP is not the same as defined for curl_off_t on
+many systems! (Option added in 7.18.0)
+.IP CURLOPT_SEEKDATA
+Data pointer to pass to the file read function. If you use the
+\fICURLOPT_SEEKFUNCTION\fP option, this is the pointer you'll get as input. If
+you don't specify a seek callback, NULL is passed. (Option added in 7.18.0)
.IP CURLOPT_SOCKOPTFUNCTION
Function pointer that should match the \fIcurl_sockopt_callback\fP prototype
found in \fI<curl/curl.h>\fP. This function gets called by libcurl after the