diff options
Diffstat (limited to 'docs/libcurl/opts/CURLOPT_COOKIELIST.3')
-rw-r--r-- | docs/libcurl/opts/CURLOPT_COOKIELIST.3 | 51 |
1 files changed, 50 insertions, 1 deletions
diff --git a/docs/libcurl/opts/CURLOPT_COOKIELIST.3 b/docs/libcurl/opts/CURLOPT_COOKIELIST.3 index 815def1b..937c79db 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIELIST.3 +++ b/docs/libcurl/opts/CURLOPT_COOKIELIST.3 @@ -36,6 +36,16 @@ Such a cookie can be either a single line in Netscape / Mozilla format or just regular HTTP-style header (Set-Cookie: ...) format. This will also enable the cookie engine. This adds that single cookie to the internal cookie store. +If you use the Set-Cookie format and don't specify a domain then the cookie +is sent for any domain and will not be modified. If a server sets a cookie of +the same name (or maybe you've imported one) then both will be sent on a future +transfer to that server, likely not what you intended. Either set a domain in +Set-Cookie (doing that will include sub domains) or use the Netscape format as +shown in EXAMPLE. + +Starting in 7.43.0 the aforementioned any-domain cookies will not appear in the +lists exported by \fICURLINFO_COOKIELIST(3)\fP and \fICURLOPT_COOKIEJAR(3)\fP. + Additionally, there are commands available that perform actions if you pass in these exact strings: .IP ALL @@ -55,7 +65,46 @@ NULL .SH PROTOCOLS HTTP .SH EXAMPLE -TODO +.nf +/* This example shows an inline import of a cookie in Netscape format. +You can set the cookie as HttpOnly to prevent XSS attacks by prepending +#HttpOnly_ to the hostname. That may be useful if the cookie will later +be imported by a browser. +*/ + +#define SEP "\\t" /* Tab separates the fields */ + +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 */ + +/* my_cookie is imported immediately via CURLOPT_COOKIELIST. +*/ +curl_easy_setopt(curl, CURLOPT_COOKIELIST, my_cookie); + +/* The list of cookies in cookies.txt will 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's considered a "live" +cookie. A live cookie won't be 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 */ + +res = curl_easy_perform(curl); /* cookies imported from cookies.txt */ + +curl_easy_cleanup(curl); /* cookies exported to cookies.txt */ +.fi .SH AVAILABILITY ALL was added in 7.14.1 |