Artifactspublic-v0

curl

master
ply4 git calls226 ms289 KiB2 cachedprotocol v2
154 lines4.7 KiBRaw

NAME

CURLOPT_COOKIELIST - add to or manipulate cookies held in memory

SYNOPSIS

c
#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIELIST,
                          char *cookie);

DESCRIPTION

Pass a char pointer to a cookie string.

Such a cookie can be either a single line in Netscape / Mozilla format or regular HTTP-style header (Set-Cookie:) format. This option also enables the cookie engine. This adds that single cookie to the internal cookie store.

We strongly advice against loading cookies from an HTTP header file, as that is an inferior data exchange format.

Exercise caution if you are using this option and multiple transfers may occur. If you use the Set-Cookie format and the string does not specify a domain, then the cookie is sent for any domain (even after redirects are followed) and cannot be modified by a server-set cookie. If a server sets a cookie of the same name (or maybe you have imported one) then both are sent on future transfers to that server, likely not what you intended. To address these issues set a domain in Set-Cookie (doing that includes subdomains) or much better: use the Netscape file format.

Cookies added through this API bypass automatic Public Suffix List (PSL) checking because the handle's internal PSL engine has not yet been initialized when the call is made. Under normal transfer operations, PSL validation prevents cookies from being set on broad or shared domains - such as .com, .co.uk, or .github.io - which would otherwise create security vulnerabilities by allowing unrelated subdomains to access sensitive cookie data. Because the library skips this safety check during manual cookie insertion, the caller assumes full responsibility for domain validation. Applications using this interface must independently verify that the target domain attribute represents a valid host and does not match a public suffix before injecting the cookie into the handle.

Additionally, there are commands available that perform actions if you pass in these exact strings:

ALL

erases all cookies held in memory

SESS

erases all session cookies held in memory

FLUSH

writes all known cookies to the file specified by CURLOPT_COOKIEJAR(3)

RELOAD

loads all cookies from the files specified by CURLOPT_COOKIEFILE(3). If CURLOPT_COOKIESESSION(3) is enabled before this reload, it is applied to this load operation as well and all session cookies are discarded.

DEFAULT

NULL

%PROTOCOLS%

EXAMPLE

c
/* an inline import of a cookie in Netscape format. */

#define SEP "\t"  /* Tab separates the fields */

int main(void)
{
  const char *my_cookie =
    "example.com"    /* Hostname */
    SEP "FALSE"      /* Include subdomains */
    SEP "/"          /* Path */
    SEP "FALSE"      /* Secure */
    SEP "0"          /* Expiry in epoch time format. 0 == Session */
    SEP "foo"        /* Name */
    SEP "bar";       /* Value */

  CURL *curl = curl_easy_init();
  if(curl) {
    CURLcode result;
    /* my_cookie is imported immediately via CURLOPT_COOKIELIST. */
    curl_easy_setopt(curl, CURLOPT_COOKIELIST, my_cookie);

    /* The list of cookies in cookies.txt are not be imported until right
       before a transfer is performed. Cookies in the list that have the same
       hostname, path and name as in my_cookie are skipped. That is because
       libcurl has already imported my_cookie and it is considered a "live"
       cookie. A live cookie is not replaced by one read from a file. */
    curl_easy_setopt(curl, CURLOPT_COOKIEFILE, "cookies.txt");  /* import */

    /* Cookies are exported after curl_easy_cleanup is called. The server
       may have added, deleted or modified cookies by then. The cookies that
       were skipped on import are not exported. */
    curl_easy_setopt(curl, CURLOPT_COOKIEJAR, "cookies.txt");  /* export */

    result = curl_easy_perform(curl);  /* cookies imported from cookies.txt */

    curl_easy_cleanup(curl);  /* cookies exported to cookies.txt */
  }
}

The cookie file format and general cookie concepts in curl are described online here: https://curl.se/docs/http-cookies.html

HISTORY

ALL was added in 7.14.1

SESS was added in 7.15.4

FLUSH was added in 7.17.1

RELOAD was added in 7.39.0

%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_COOKIELIST
5Section: 3
6Source: libcurl
7See-also:
8 - CURLINFO_COOKIELIST (3)
9 - CURLOPT_COOKIE (3)
10 - CURLOPT_COOKIEFILE (3)
11 - CURLOPT_COOKIEJAR (3)
12Protocol:
13 - HTTP
14Added-in: 7.14.1
15---
17# NAME
19CURLOPT_COOKIELIST - add to or manipulate cookies held in memory
21# SYNOPSIS
23~~~c
24#include <curl/curl.h>
26CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIELIST,
27 char *cookie);
28~~~
30# DESCRIPTION
32Pass a char pointer to a *cookie* string.
34Such a cookie can be either a single line in Netscape / Mozilla format or
35regular HTTP-style header (`Set-Cookie:`) format. This option also enables the
36cookie engine. This adds that single cookie to the internal cookie store.
38We strongly advice against loading cookies from an HTTP header file, as that
39is an inferior data exchange format.
41Exercise caution if you are using this option and multiple transfers may
42occur. If you use the `Set-Cookie` format and the string does not specify a
43domain, then the cookie is sent for any domain (even after redirects are
44followed) and cannot be modified by a server-set cookie. If a server sets a
45cookie of the same name (or maybe you have imported one) then both are sent on
46future transfers to that server, likely not what you intended. To address
47these issues set a domain in `Set-Cookie` (doing that includes subdomains) or
48much better: use the Netscape file format.
50Cookies added through this API bypass automatic Public Suffix List (PSL)
51checking because the handle's internal PSL engine has not yet been initialized
52when the call is made. Under normal transfer operations, PSL validation
53prevents cookies from being set on broad or shared domains - such as `.com`,
54`.co.uk`, or `.github.io` - which would otherwise create security
55vulnerabilities by allowing unrelated subdomains to access sensitive cookie
56data. Because the library skips this safety check during manual cookie
57insertion, the caller assumes full responsibility for domain validation.
58Applications using this interface must independently verify that the target
59domain attribute represents a valid host and does not match a public suffix
60before injecting the cookie into the handle.
62Additionally, there are commands available that perform actions if you pass in
63these exact strings:
65## `ALL`
67erases all cookies held in memory
69## `SESS`
71erases all session cookies held in memory
73## `FLUSH`
75writes all known cookies to the file specified by CURLOPT_COOKIEJAR(3)
77## `RELOAD`
79loads all cookies from the files specified by CURLOPT_COOKIEFILE(3). If
80CURLOPT_COOKIESESSION(3) is enabled before this reload, it is applied to this
81load operation as well and all session cookies are discarded.
83# DEFAULT
85NULL
87# %PROTOCOLS%
89# EXAMPLE
91~~~c
92/* an inline import of a cookie in Netscape format. */
94#define SEP "\t" /* Tab separates the fields */
96int main(void)
98 const char *my_cookie =
99 "example.com" /* Hostname */
100 SEP "FALSE" /* Include subdomains */
101 SEP "/" /* Path */
102 SEP "FALSE" /* Secure */
103 SEP "0" /* Expiry in epoch time format. 0 == Session */
104 SEP "foo" /* Name */
105 SEP "bar"; /* Value */
107 CURL *curl = curl_easy_init();
108 if(curl) {
109 CURLcode result;
110 /* my_cookie is imported immediately via CURLOPT_COOKIELIST. */
111 curl_easy_setopt(curl, CURLOPT_COOKIELIST, my_cookie);
113 /* The list of cookies in cookies.txt are not be imported until right
114 before a transfer is performed. Cookies in the list that have the same
115 hostname, path and name as in my_cookie are skipped. That is because
116 libcurl has already imported my_cookie and it is considered a "live"
117 cookie. A live cookie is not replaced by one read from a file. */
118 curl_easy_setopt(curl, CURLOPT_COOKIEFILE, "cookies.txt"); /* import */
120 /* Cookies are exported after curl_easy_cleanup is called. The server
121 may have added, deleted or modified cookies by then. The cookies that
122 were skipped on import are not exported. */
123 curl_easy_setopt(curl, CURLOPT_COOKIEJAR, "cookies.txt"); /* export */
125 result = curl_easy_perform(curl); /* cookies imported from cookies.txt */
127 curl_easy_cleanup(curl); /* cookies exported to cookies.txt */
128 }
130~~~
132# Cookie file format
134The cookie file format and general cookie concepts in curl are described
135online here: https://curl.se/docs/http-cookies.html
137# HISTORY
139**ALL** was added in 7.14.1
141**SESS** was added in 7.15.4
143**FLUSH** was added in 7.17.1
145**RELOAD** was added in 7.39.0
147# %AVAILABILITY%
149# RETURN VALUE
151curl_easy_setopt(3) returns a CURLcode indicating success or error.
153CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
154libcurl-errors(3).
Diagnostics4 git calls · 226 ms
CallStatusSizeTime0226 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
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=3
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
fetch2002.2 KiB199 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=199
git.response.bytes=2281
git.response.cache=MISS
git.response.duration_ms=199
git.fetch.wants=e55699b49809e43822c864223efb552a763c2e53
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=2281
git.pkt.payload.max=2260
git.sideband.band1.bytes=2259
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
a5e35a6d4ca9dfff
Request
07072238…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format