Artifactspublic-v0

curl

master
ply4 git calls155 ms289 KiB2 cachedprotocol v2
165 lines5.3 KiBRaw

NAME

curl_easy_header - get an HTTP header

SYNOPSIS

c
#include <curl/curl.h>

CURLHcode curl_easy_header(CURL *easy,
                           const char *name,
                           size_t nameindex,
                           unsigned int origin,
                           int request,
                           struct curl_header **hout);

DESCRIPTION

curl_easy_header(3) returns a pointer to a "curl_header" struct in hout with data for the HTTP response header name. The case insensitive null-terminated header name should be specified without colon.

nameindex 0 means asking for the first instance of the header. If the returned header struct has amount set larger than 1, it means there are more instances of the same header name available to get. Asking for a too big index makes CURLHE_BADINDEX get returned.

The origin argument is for specifying which headers to receive, as a single HTTP transfer might provide headers from several different places and they may then have different importance to the user and headers using the same name might be used. The origin is a bitmask for what header sources you want. See the descriptions below.

The request argument tells libcurl from which request you want headers from. A single transfer might consist of a series of HTTP requests and this argument lets you specify which particular individual request you want the headers from. 0 being the first request and then the number increases for further redirects or when multi-state authentication is used. Passing in -1 is a shortcut to "the last" request in the series, independently of the actual amount of requests used.

libcurl stores and provides the actually used "correct" headers. If for example two headers with the same name arrive and the latter overrides the former, then only the latter is provided. If the first header survives the second, then only the first one is provided. An application using this API does not have to bother about multiple headers used wrongly.

The memory for the returned struct is associated with the easy handle and subsequent calls to curl_easy_header(3) clobber the struct used in the previous calls for the same easy handle. The application needs to copy the data if it wants to keep it around. The memory used for the struct gets freed with calling curl_easy_cleanup(3) of the easy handle.

The first line in an HTTP response is called the status line. It is not considered a header by this function. Headers are the "name: value" lines following the status.

This function can be used before (all) headers have been received and is fine to call from within libcurl callbacks. It returns the state of the headers at the time it is called.

The header struct

c
struct curl_header {
  char *name;
  char *value;
  size_t amount;
  size_t index;
  unsigned int origin;
  void *anchor;
};

The data name field points to, is the same as the requested name, but might have a different case.

The data value field points to, comes exactly as delivered over the network but with leading and trailing whitespace and newlines stripped off. The value data is null-terminated. For legacy HTTP/1 "folded headers", this API provides the full single value in an unfolded manner with a single whitespace between the lines.

amount is how many headers using this name that exist, within the origin and request scope asked for.

index is the zero based entry number of this particular header, which in case this header was used more than once in the requested scope can be larger than 0 but is always less than amount.

The origin field in the "curl_header" struct has one of the origin bits set, indicating where from the header originates. At the time of this writing, there are 5 bits with defined use. The undocumented 27 remaining bits are reserved for future use and must not be assumed to have any particular value.

anchor is a private handle used by libcurl internals. Do not modify.

ORIGINS

CURLH_HEADER

The header arrived as a header from the server.

CURLH_TRAILER

The header arrived as a trailer. A header that arrives after the body.

CURLH_CONNECT

The header arrived in a CONNECT response. A CONNECT request is being done to setup a transfer "through" an HTTP(S) proxy.

CURLH_1XX

The header arrived in an HTTP 1xx response. A 1xx response is an "intermediate" response that might happen before the "real" response.

CURLH_PSEUDO

The header is an HTTP/2 or HTTP/3 pseudo header

%PROTOCOLS%

EXAMPLE

c
int main(void)
{
  struct curl_header *type;
  CURL *curl = curl_easy_init();
  if(curl) {
    CURLHcode h;
    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
    curl_easy_perform(curl);
    h = curl_easy_header(curl, "Content-Type", 0, CURLH_HEADER, -1, &type);
    curl_easy_cleanup(curl);
  }
}

%AVAILABILITY%

RETURN VALUE

This function returns a CURLHcode indicating success or error. CURLHE_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: curl_easy_header
5Section: 3
6Source: libcurl
7See-also:
8 - CURLINFO_CONTENT_TYPE (3)
9 - CURLOPT_HEADERFUNCTION (3)
10 - curl_easy_nextheader (3)
11 - curl_easy_perform (3)
12 - libcurl-errors (3)
13Protocol:
14 - HTTP
15Added-in: 7.83.0
16---
18# NAME
20curl_easy_header - get an HTTP header
22# SYNOPSIS
24~~~c
25#include <curl/curl.h>
27CURLHcode curl_easy_header(CURL *easy,
28 const char *name,
29 size_t nameindex,
30 unsigned int origin,
31 int request,
32 struct curl_header **hout);
33~~~
35# DESCRIPTION
37curl_easy_header(3) returns a pointer to a "curl_header" struct in **hout**
38with data for the HTTP response header *name*. The case insensitive
39null-terminated header name should be specified without colon.
41*nameindex* 0 means asking for the first instance of the header. If the
42returned header struct has **amount** set larger than 1, it means there are
43more instances of the same header name available to get. Asking for a too big
44index makes **CURLHE_BADINDEX** get returned.
46The *origin* argument is for specifying which headers to receive, as a single
47HTTP transfer might provide headers from several different places and they may
48then have different importance to the user and headers using the same name
49might be used. The *origin* is a bitmask for what header sources you want. See
50the descriptions below.
52The *request* argument tells libcurl from which request you want headers
53from. A single transfer might consist of a series of HTTP requests and this
54argument lets you specify which particular individual request you want the
55headers from. 0 being the first request and then the number increases for
56further redirects or when multi-state authentication is used. Passing in -1 is
57a shortcut to "the last" request in the series, independently of the actual
58amount of requests used.
60libcurl stores and provides the actually used "correct" headers. If for
61example two headers with the same name arrive and the latter overrides the
62former, then only the latter is provided. If the first header survives the
63second, then only the first one is provided. An application using this API
64does not have to bother about multiple headers used wrongly.
66The memory for the returned struct is associated with the easy handle and
67subsequent calls to curl_easy_header(3) clobber the struct used in the
68previous calls for the same easy handle. The application needs to copy the data if
69it wants to keep it around. The memory used for the struct gets freed with
70calling curl_easy_cleanup(3) of the easy handle.
72The first line in an HTTP response is called the status line. It is not
73considered a header by this function. Headers are the "name: value" lines
74following the status.
76This function can be used before (all) headers have been received and is fine
77to call from within libcurl callbacks. It returns the state of the headers at
78the time it is called.
80# The header struct
82~~~c
83struct curl_header {
84 char *name;
85 char *value;
86 size_t amount;
87 size_t index;
88 unsigned int origin;
89 void *anchor;
90};
91~~~
93The data **name** field points to, is the same as the requested name, but
94might have a different case.
96The data **value** field points to, comes exactly as delivered over the
97network but with leading and trailing whitespace and newlines stripped
98off. The `value` data is null-terminated. For legacy HTTP/1 "folded headers",
99this API provides the full single value in an unfolded manner with a single
100whitespace between the lines.
102**amount** is how many headers using this name that exist, within the origin
103and request scope asked for.
105**index** is the zero based entry number of this particular header, which in
106case this header was used more than once in the requested scope can be larger
107than 0 but is always less than **amount**.
109The **origin** field in the "curl_header" struct has one of the origin bits
110set, indicating where from the header originates. At the time of this writing,
111there are 5 bits with defined use. The undocumented 27 remaining bits are
112reserved for future use and must not be assumed to have any particular value.
114**anchor** is a private handle used by libcurl internals. Do not modify.
116# ORIGINS
118## CURLH_HEADER
120The header arrived as a header from the server.
122## CURLH_TRAILER
124The header arrived as a trailer. A header that arrives after the body.
126## CURLH_CONNECT
128The header arrived in a CONNECT response. A CONNECT request is being done to
129setup a transfer "through" an HTTP(S) proxy.
131## CURLH_1XX
133The header arrived in an HTTP 1xx response. A 1xx response is an "intermediate"
134response that might happen before the "real" response.
136## CURLH_PSEUDO
138The header is an HTTP/2 or HTTP/3 pseudo header
140# %PROTOCOLS%
142# EXAMPLE
144~~~c
145int main(void)
147 struct curl_header *type;
148 CURL *curl = curl_easy_init();
149 if(curl) {
150 CURLHcode h;
151 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
152 curl_easy_perform(curl);
153 h = curl_easy_header(curl, "Content-Type", 0, CURLH_HEADER, -1, &type);
154 curl_easy_cleanup(curl);
155 }
157~~~
159# %AVAILABILITY%
161# RETURN VALUE
163This function returns a CURLHcode indicating success or error. CURLHE_OK (0)
164means everything was OK, non-zero means an error occurred, see
165libcurl-errors(3).
Diagnostics4 git calls · 155 ms
CallStatusSizeTime0155 ms
discover200152 B2 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
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=3
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
fetch2002.4 KiB150 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=150
git.response.bytes=2507
git.response.cache=MISS
git.response.duration_ms=150
git.fetch.wants=1e48a728c217c7594c832987143fd5009d9049cc
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=2507
git.pkt.payload.max=2486
git.sideband.band1.bytes=2485
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
a5e317e98c4ecf5b
Request
03d696aa…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format