Artifactspublic-v0

curl

master
ply4 git calls306 ms288 KiB2 cachedprotocol v2
106 lines2.9 KiBRaw

NAME

CURLOPT_SEEKFUNCTION - user callback for seeking in input stream

SYNOPSIS

c
#include <curl/curl.h>

/* These are the return codes for the seek callbacks */
#define CURL_SEEKFUNC_OK       0
#define CURL_SEEKFUNC_FAIL     1 /* fail the entire transfer */
#define CURL_SEEKFUNC_CANTSEEK 2 /* tell libcurl seeking cannot be done, so
                                    libcurl might try other means instead */

int seek_callback(void *clientp, curl_off_t offset, int origin);

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SEEKFUNCTION, seek_callback);

DESCRIPTION

Pass a pointer to your callback function, which should match the prototype shown above.

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 data has already been sent to the server and needs to be sent again. This may happen when doing an HTTP PUT or POST with a multi-pass authentication method, or when an existing HTTP connection is reused too late and the server closes the connection. The function shall work like fseek(3) or lseek(3) and it gets SEEK_SET, SEEK_CUR or SEEK_END as argument for origin, although libcurl currently only passes SEEK_SET.

clientp is the pointer you set with CURLOPT_SEEKDATA(3).

The callback function must return CURL_SEEKFUNC_OK on success, CURL_SEEKFUNC_FAIL to cause the upload operation to fail or CURL_SEEKFUNC_CANTSEEK to indicate that while the seek failed, libcurl is free to work around the problem if possible. The latter can sometimes be done by instead reading from the input or similar.

If you forward the input arguments directly to fseek(3) or lseek(3), note that the data type for offset is not the same as defined for curl_off_t on many systems.

DEFAULT

NULL

%PROTOCOLS%

EXAMPLE

c
#include <unistd.h> /* for lseek */

struct data {
  int our_fd;
};
static int seek_cb(void *clientp, curl_off_t offset, int origin)
{
  struct data *d = (struct data *)clientp;
  lseek(d->our_fd, offset, origin);
  return CURL_SEEKFUNC_OK;
}

int main(void)
{
  struct data seek_data;
  CURL *curl = curl_easy_init();
  if(curl) {
    curl_easy_setopt(curl, CURLOPT_SEEKFUNCTION, seek_cb);
    curl_easy_setopt(curl, CURLOPT_SEEKDATA, &seek_data);
  }
}

%AVAILABILITY%

RETURN VALUE

curl_easy_setopt(3) returns a CURLcode indicating success or error.

CURLE_OK (0) means everything was OK, non-zero means an error occurred, see libcurl-errors(3).

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---
19# NAME
21CURLOPT_SEEKFUNCTION - user callback for seeking in input stream
23# SYNOPSIS
25~~~c
26#include <curl/curl.h>
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 */
34int seek_callback(void *clientp, curl_off_t offset, int origin);
36CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SEEKFUNCTION, seek_callback);
37~~~
39# DESCRIPTION
41Pass a pointer to your callback function, which should match the prototype
42shown above.
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.
55*clientp* is the pointer you set with CURLOPT_SEEKDATA(3).
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.
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.
67# DEFAULT
69NULL
71# %PROTOCOLS%
73# EXAMPLE
75~~~c
76#include <unistd.h> /* for lseek */
78struct data {
79 int our_fd;
80};
81static int seek_cb(void *clientp, curl_off_t offset, int origin)
83 struct data *d = (struct data *)clientp;
84 lseek(d->our_fd, offset, origin);
85 return CURL_SEEKFUNC_OK;
88int main(void)
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 }
97~~~
99# %AVAILABILITY%
101# RETURN VALUE
103curl_easy_setopt(3) returns a CURLcode indicating success or error.
105CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
106libcurl-errors(3).
Diagnostics4 git calls · 306 ms
CallStatusSizeTime0306 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200149 B · hit3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=149
git.response.cache=HIT
git.response.duration_ms=3
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=149
git.pkt.payload.max=78
git.ls_refs.count=2
git.ls_refs.head=refs/heads/master
fetchblob:none · deepen 10200287 KiB · hit24 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=279
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=24
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=31c911efe5652725e930f4d2e60c9060e5f6646d
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=10
git.pkt.data=8
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=293470
git.pkt.payload.max=65516
git.sideband.band1.bytes=293354
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=87
git.pack.bytes=293354
git.pack.ofs_delta=0
git.pack.ref_delta=1
git.pack.chain.max=1
git.pack.trailer=6a646bcda6740bab42e321b51998b52ea15146c0
git.pack.full=86
Open pack map
fetch2001.4 KiB279 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=1469
git.response.cache=MISS
git.response.duration_ms=279
git.fetch.wants=2f4d96806e520ac25470ef98569416c51820db2b
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=1469
git.pkt.payload.max=1448
git.sideband.band1.bytes=1447
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/curl.git
Ref
refs/heads/master
Commit
31c911efe5652725e930f4d2e60c9060e5f6646d
cf-ray
a5e33226794f18aa
Request
74e6f5d4…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format