Artifactspublic-v0

curl

master
ply4 git calls871 ms289 KiB2 cachedprotocol v2
131 lines3.8 KiBRaw

NAME

CURLOPT_READFUNCTION - read callback for data uploads

SYNOPSIS

c
#include <curl/curl.h>

size_t read_callback(char *buffer, size_t size, size_t nitems, void *userdata);

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_READFUNCTION, read_callback);

DESCRIPTION

Pass a pointer to your callback function, as the prototype shows above.

This callback function gets called by libcurl as soon as it needs to read data in order to send it to the peer - like if you ask it to upload or post data to the server. The data area pointed at by the pointer buffer should be filled up with at most nitems number of bytes by your function. size is always 1.

Set the userdata argument with the CURLOPT_READDATA(3) option.

Your function must return the actual number of bytes that it stored in the data area pointed at by the pointer buffer. Returning 0 signals end-of-file to the library and causes it to stop the current transfer.

If you stop the current transfer by returning 0 "pre-maturely" (i.e before the server expected it, like when you have said you would upload N bytes and you upload less than N bytes), you may experience that the server "hangs" waiting for the rest of the data that is not sent.

The read callback may return CURL_READFUNC_ABORT to stop the current operation immediately, resulting in a CURLE_ABORTED_BY_CALLBACK error code from the transfer.

The callback can return CURL_READFUNC_PAUSE to cause reading from this connection to pause. See curl_easy_pause(3) for further details.

Bugs: when doing TFTP uploads, you must return the exact amount of data that the callback wants, or it is considered the final packet by the server end and the transfer ends there.

If you set this callback pointer to NULL, or do not set it at all, the default internal read function is used. It is doing an fread() on the FILE * userdata set with CURLOPT_READDATA(3).

You can set the total size of the data you are sending by using CURLOPT_INFILESIZE_LARGE(3) or CURLOPT_POSTFIELDSIZE_LARGE(3), depending on the type of transfer. For some transfer types it may be required and it allows for better error checking.

When this option is used in combination with telling libcurl to follow redirects with CURLOPT_FOLLOWLOCATION(3), the data might need to be rewound and sent again. The CURLOPT_SEEKFUNCTION(3) can then be invoked for that rewind operation.

DEFAULT

fread(3)

%PROTOCOLS%

EXAMPLE

c
static size_t read_callback(char *ptr, size_t size, size_t nmemb,
                            void *userdata)
{
  FILE *readhere = (FILE *)userdata;
  curl_off_t nread;

  /* copy as much data as possible into the 'ptr' buffer, but no more than
     'size' * 'nmemb' bytes. */
  size_t retcode = fread(ptr, size, nmemb, readhere);

  nread = (curl_off_t)retcode;

  fprintf(stderr, "*** We read %" CURL_FORMAT_CURL_OFF_T
          " bytes from file\n", nread);
  return retcode;
}

int main(int argc, char *argv[])
{
  FILE *file = fopen(argv[1], "rb");
  CURLcode result;

  CURL *curl = curl_easy_init();
  if(curl) {
    /* set callback to use */
    curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_callback);

    /* pass in suitable argument to callback */
    curl_easy_setopt(curl, CURLOPT_READDATA, (void *)file);

    result = curl_easy_perform(curl);
  }
}

HISTORY

CURL_READFUNC_PAUSE return code was added in 7.18.0 and CURL_READFUNC_ABORT was added in 7.12.1.

%AVAILABILITY%

RETURN VALUE

This returns CURLE_OK.

1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_READFUNCTION
5Section: 3
6Source: libcurl
7See-also:
8 - CURLOPT_POST (3)
9 - CURLOPT_READDATA (3)
10 - CURLOPT_SEEKFUNCTION (3)
11 - CURLOPT_UPLOAD (3)
12 - CURLOPT_UPLOAD_BUFFERSIZE (3)
13 - CURLOPT_WRITEFUNCTION (3)
14Protocol:
15 - All
16Added-in: 7.1
17---
19# NAME
21CURLOPT_READFUNCTION - read callback for data uploads
23# SYNOPSIS
25~~~c
26#include <curl/curl.h>
28size_t read_callback(char *buffer, size_t size, size_t nitems, void *userdata);
30CURLcode curl_easy_setopt(CURL *handle, CURLOPT_READFUNCTION, read_callback);
31~~~
33# DESCRIPTION
35Pass a pointer to your callback function, as the prototype shows above.
37This callback function gets called by libcurl as soon as it needs to read data
38in order to send it to the peer - like if you ask it to upload or post data to
39the server. The data area pointed at by the pointer *buffer* should be filled
40up with at most *nitems* number of bytes by your function. *size* is always 1.
42Set the *userdata* argument with the CURLOPT_READDATA(3) option.
44Your function must return the actual number of bytes that it stored in the
45data area pointed at by the pointer *buffer*. Returning 0 signals
46end-of-file to the library and causes it to stop the current transfer.
48If you stop the current transfer by returning 0 "pre-maturely" (i.e before the
49server expected it, like when you have said you would upload N bytes and you
50upload less than N bytes), you may experience that the server "hangs" waiting
51for the rest of the data that is not sent.
53The read callback may return *CURL_READFUNC_ABORT* to stop the current
54operation immediately, resulting in a *CURLE_ABORTED_BY_CALLBACK* error
55code from the transfer.
57The callback can return *CURL_READFUNC_PAUSE* to cause reading from this
58connection to pause. See curl_easy_pause(3) for further details.
60**Bugs**: when doing TFTP uploads, you must return the exact amount of data
61that the callback wants, or it is considered the final packet by the server
62end and the transfer ends there.
64If you set this callback pointer to NULL, or do not set it at all, the default
65internal read function is used. It is doing an fread() on the FILE * userdata
66set with CURLOPT_READDATA(3).
68You can set the total size of the data you are sending by using
69CURLOPT_INFILESIZE_LARGE(3) or CURLOPT_POSTFIELDSIZE_LARGE(3),
70depending on the type of transfer. For some transfer types it may be required
71and it allows for better error checking.
73When this option is used in combination with telling libcurl to follow
74redirects with CURLOPT_FOLLOWLOCATION(3), the data might need to be rewound
75and sent again. The CURLOPT_SEEKFUNCTION(3) can then be invoked for that
76rewind operation.
78# DEFAULT
80fread(3)
82# %PROTOCOLS%
84# EXAMPLE
86~~~c
87static size_t read_callback(char *ptr, size_t size, size_t nmemb,
88 void *userdata)
90 FILE *readhere = (FILE *)userdata;
91 curl_off_t nread;
93 /* copy as much data as possible into the 'ptr' buffer, but no more than
94 'size' * 'nmemb' bytes. */
95 size_t retcode = fread(ptr, size, nmemb, readhere);
97 nread = (curl_off_t)retcode;
99 fprintf(stderr, "*** We read %" CURL_FORMAT_CURL_OFF_T
100 " bytes from file\n", nread);
101 return retcode;
104int main(int argc, char *argv[])
106 FILE *file = fopen(argv[1], "rb");
107 CURLcode result;
109 CURL *curl = curl_easy_init();
110 if(curl) {
111 /* set callback to use */
112 curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_callback);
114 /* pass in suitable argument to callback */
115 curl_easy_setopt(curl, CURLOPT_READDATA, (void *)file);
117 result = curl_easy_perform(curl);
118 }
120~~~
122# HISTORY
124CURL_READFUNC_PAUSE return code was added in 7.18.0 and CURL_READFUNC_ABORT
125was added in 7.12.1.
127# %AVAILABILITY%
129# RETURN VALUE
131This returns CURLE_OK.
Diagnostics4 git calls · 871 ms
CallStatusSizeTime0871 ms
discover200152 B2 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
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 · hit2 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
git.response.bytes=149
git.response.cache=HIT
git.response.duration_ms=2
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 · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=866
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=3
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.8 KiB866 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=1884
git.response.cache=MISS
git.response.duration_ms=866
git.fetch.wants=e0345e832ae33a89bda54304cbc399b4baa3f85e
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=1884
git.pkt.payload.max=1863
git.sideband.band1.bytes=1862
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
a5e3215f7d4b5aae
Request
008af1a1…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format