Artifactspublic-v0

curl

master
ply4 git calls489 ms289 KiB2 cachedprotocol v2
140 lines3.8 KiBRaw

NAME

CURLOPT_WRITEFUNCTION - callback for writing received data

SYNOPSIS

c
#include <curl/curl.h>

size_t write_callback(char *ptr, size_t size, size_t nmemb, void *userdata);

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WRITEFUNCTION, write_callback);

DESCRIPTION

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

This callback function gets called by libcurl as soon as there is data received that needs to be saved. For most transfers, this callback gets called many times and each invoke delivers another chunk of data. ptr points to the delivered data, and the size of that data is nmemb; size is always 1.

The data passed to this function is not null-terminated.

The callback function is passed as much data as possible in all invokes, but you must not make any assumptions. It may be one byte, it may be thousands. The maximum amount of body data that is passed to the write callback is defined in the curl.h header file: CURL_MAX_WRITE_SIZE (the usual default is 16K). If CURLOPT_HEADER(3) is enabled, which makes header data get passed to the write callback, you can get up to CURL_MAX_HTTP_HEADER bytes of header data passed into it. This usually means 100K.

The CURLOPT_WRITEFUNCTION(3) callback receives the final response payload. When CURLOPT_FOLLOWLOCATION(3) is enabled, libcurl automatically handles intermediate 3xx redirects, meaning their HTTP bodies are skipped and not passed to this callback.

This function may be called with zero bytes data if the transferred file is empty.

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

Your callback should return the number of bytes actually taken care of. If that amount differs from the amount passed to your callback function, it signals an error condition to the library. This causes the transfer to get aborted and the libcurl function used returns CURLE_WRITE_ERROR.

You can also abort the transfer by returning CURL_WRITEFUNC_ERROR (added in 7.87.0), which makes CURLE_WRITE_ERROR get returned.

If the callback function returns CURL_WRITEFUNC_PAUSE it pauses this transfer. See curl_easy_pause(3) for further details.

Set this option to NULL to get the internal default function used instead of your callback. The internal default function writes the data to the FILE * given with CURLOPT_WRITEDATA(3).

DEFAULT

fwrite(3)

%PROTOCOLS%

EXAMPLE

c
#include <stdlib.h> /* for realloc */
#include <string.h> /* for memcpy */

struct memory {
  char *response;
  size_t size;
};

static size_t cb(char *data, size_t size, size_t nmemb, void *clientp)
{
  size_t realsize = nmemb;
  struct memory *mem = (struct memory *)clientp;

  char *ptr = realloc(mem->response, mem->size + realsize + 1);
  if(!ptr)
    return 0;  /* out of memory */

  mem->response = ptr;
  memcpy(&(mem->response[mem->size]), data, realsize);
  mem->size += realsize;
  mem->response[mem->size] = 0;

  return realsize;
}

int main(void)
{
  struct memory chunk = { 0 };
  CURLcode result;
  CURL *curl = curl_easy_init();
  if(curl) {
    /* send all data to this function */
    curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, cb);

    /* we pass our 'chunk' struct to the callback function */
    curl_easy_setopt(curl, CURLOPT_WRITEDATA, (void *)&chunk);

    /* send a request */
    result = curl_easy_perform(curl);

    /* remember to free the buffer */
    free(chunk.response);

    curl_easy_cleanup(curl);
  }
}

HISTORY

Support for the CURL_WRITEFUNC_PAUSE return code was added in version 7.18.0.

%AVAILABILITY%

RETURN VALUE

This returns CURLE_OK.

1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_WRITEFUNCTION
5Section: 3
6Source: libcurl
7See-also:
8 - CURLOPT_HEADERFUNCTION (3)
9 - CURLOPT_READFUNCTION (3)
10 - CURLOPT_WRITEDATA (3)
11Protocol:
12 - All
13Added-in: 7.1
14---
16# NAME
18CURLOPT_WRITEFUNCTION - callback for writing received data
20# SYNOPSIS
22~~~c
23#include <curl/curl.h>
25size_t write_callback(char *ptr, size_t size, size_t nmemb, void *userdata);
27CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WRITEFUNCTION, write_callback);
28~~~
30# DESCRIPTION
32Pass a pointer to your callback function, which should match the prototype
33shown above.
35This callback function gets called by libcurl as soon as there is data
36received that needs to be saved. For most transfers, this callback gets called
37many times and each invoke delivers another chunk of data. *ptr* points to the
38delivered data, and the size of that data is *nmemb*; *size* is always 1.
40The data passed to this function is not null-terminated.
42The callback function is passed as much data as possible in all invokes, but
43you must not make any assumptions. It may be one byte, it may be thousands.
44The maximum amount of body data that is passed to the write callback is
45defined in the curl.h header file: *CURL_MAX_WRITE_SIZE* (the usual default is
4616K). If CURLOPT_HEADER(3) is enabled, which makes header data get passed to
47the write callback, you can get up to *CURL_MAX_HTTP_HEADER* bytes of header
48data passed into it. This usually means 100K.
50The CURLOPT_WRITEFUNCTION(3) callback receives the final response payload.
51When CURLOPT_FOLLOWLOCATION(3) is enabled, libcurl automatically handles
52intermediate 3xx redirects, meaning their HTTP bodies are skipped and not
53passed to this callback.
55This function may be called with zero bytes data if the transferred file is
56empty.
58Set the *userdata* argument with the CURLOPT_WRITEDATA(3) option.
60Your callback should return the number of bytes actually taken care of. If
61that amount differs from the amount passed to your callback function, it
62signals an error condition to the library. This causes the transfer to get
63aborted and the libcurl function used returns *CURLE_WRITE_ERROR*.
65You can also abort the transfer by returning CURL_WRITEFUNC_ERROR (added in
667.87.0), which makes *CURLE_WRITE_ERROR* get returned.
68If the callback function returns CURL_WRITEFUNC_PAUSE it pauses this transfer.
69See curl_easy_pause(3) for further details.
71Set this option to NULL to get the internal default function used instead of
72your callback. The internal default function writes the data to the FILE *
73given with CURLOPT_WRITEDATA(3).
75# DEFAULT
77fwrite(3)
79# %PROTOCOLS%
81# EXAMPLE
83~~~c
84#include <stdlib.h> /* for realloc */
85#include <string.h> /* for memcpy */
87struct memory {
88 char *response;
89 size_t size;
90};
92static size_t cb(char *data, size_t size, size_t nmemb, void *clientp)
94 size_t realsize = nmemb;
95 struct memory *mem = (struct memory *)clientp;
97 char *ptr = realloc(mem->response, mem->size + realsize + 1);
98 if(!ptr)
99 return 0; /* out of memory */
101 mem->response = ptr;
102 memcpy(&(mem->response[mem->size]), data, realsize);
103 mem->size += realsize;
104 mem->response[mem->size] = 0;
106 return realsize;
109int main(void)
111 struct memory chunk = { 0 };
112 CURLcode result;
113 CURL *curl = curl_easy_init();
114 if(curl) {
115 /* send all data to this function */
116 curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, cb);
118 /* we pass our 'chunk' struct to the callback function */
119 curl_easy_setopt(curl, CURLOPT_WRITEDATA, (void *)&chunk);
121 /* send a request */
122 result = curl_easy_perform(curl);
124 /* remember to free the buffer */
125 free(chunk.response);
127 curl_easy_cleanup(curl);
128 }
130~~~
132# HISTORY
134Support for the CURL_WRITEFUNC_PAUSE return code was added in version 7.18.0.
136# %AVAILABILITY%
138# RETURN VALUE
140This returns CURLE_OK.
Diagnostics4 git calls · 489 ms
CallStatusSizeTime0489 ms
discover200152 B4 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 · hit4 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=4
git.response.bytes=149
git.response.cache=HIT
git.response.duration_ms=4
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 · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=483
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=2
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 KiB483 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=1857
git.response.cache=MISS
git.response.duration_ms=483
git.fetch.wants=792ed3d3b8ffa901cd2dfcbe048c2eebc5e98d63
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=1857
git.pkt.payload.max=1836
git.sideband.band1.bytes=1835
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
a5e32eda5cda8821
Request
c4279706…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format