1--- 2c: Copyright (C) Daniel Stenberg, <daniel.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) 12--- 13 14# NAME 15 16CURLOPT_COOKIELIST - add to or manipulate cookies held in memory 17 18# SYNOPSIS 19 20~~~c 21#include <curl/curl.h> 22 23CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIELIST, 24 char *cookie); 25~~~ 26 27# DESCRIPTION 28 29Pass a char pointer to a *cookie* string. 30 31Such a cookie can be either a single line in Netscape / Mozilla format or just 32regular HTTP-style header (Set-Cookie: ...) format. This option also enables 33the cookie engine. This adds that single cookie to the internal cookie store. 34 35We strongly advice against loading cookies from an HTTP header file, as that 36is an inferior data exchange format. 37 38Exercise caution if you are using this option and multiple transfers may 39occur. If you use the Set-Cookie format and the string does not specify a 40domain, then the cookie is sent for any domain (even after redirects are 41followed) and cannot be modified by a server-set cookie. If a server sets a 42cookie of the same name (or maybe you have imported one) then both are sent on 43future transfers to that server, likely not what you intended. To address 44these issues set a domain in Set-Cookie (doing that includes subdomains) or 45much better: use the Netscape file format. 46 47Additionally, there are commands available that perform actions if you pass in 48these exact strings: 49 50## ALL 51 52erases all cookies held in memory 53 54## SESS 55 56erases all session cookies held in memory 57 58## FLUSH 59 60writes all known cookies to the file specified by CURLOPT_COOKIEJAR(3) 61 62## RELOAD 63 64loads all cookies from the files specified by CURLOPT_COOKIEFILE(3) 65 66# DEFAULT 67 68NULL 69 70# PROTOCOLS 71 72HTTP 73 74# EXAMPLE 75 76~~~c 77/* an inline import of a cookie in Netscape format. */ 78 79#define SEP "\t" /* Tab separates the fields */ 80 81int main(void) 82{ 83 char *my_cookie = 84 "example.com" /* Hostname */ 85 SEP "FALSE" /* Include subdomains */ 86 SEP "/" /* Path */ 87 SEP "FALSE" /* Secure */ 88 SEP "0" /* Expiry in epoch time format. 0 == Session */ 89 SEP "foo" /* Name */ 90 SEP "bar"; /* Value */ 91 92 CURL *curl = curl_easy_init(); 93 if(curl) { 94 /* my_cookie is imported immediately via CURLOPT_COOKIELIST. */ 95 curl_easy_setopt(curl, CURLOPT_COOKIELIST, my_cookie); 96 97 /* The list of cookies in cookies.txt are not be imported until right 98 before a transfer is performed. Cookies in the list that have the same 99 hostname, path and name as in my_cookie are skipped. That is because 100 libcurl has already imported my_cookie and it's considered a "live" 101 cookie. A live cookie is not replaced by one read from a file. 102 */ 103 curl_easy_setopt(curl, CURLOPT_COOKIEFILE, "cookies.txt"); /* import */ 104 105 /* Cookies are exported after curl_easy_cleanup is called. The server 106 may have added, deleted or modified cookies by then. The cookies that 107 were skipped on import are not exported. 108 */ 109 curl_easy_setopt(curl, CURLOPT_COOKIEJAR, "cookies.txt"); /* export */ 110 111 curl_easy_perform(curl); /* cookies imported from cookies.txt */ 112 113 curl_easy_cleanup(curl); /* cookies exported to cookies.txt */ 114 } 115} 116~~~ 117 118# Cookie file format 119 120The cookie file format and general cookie concepts in curl are described 121online here: https://curl.se/docs/http-cookies.html 122 123# AVAILABILITY 124 125**ALL** was added in 7.14.1 126 127**SESS** was added in 7.15.4 128 129**FLUSH** was added in 7.17.1 130 131**RELOAD** was added in 7.39.0 132 133# RETURN VALUE 134 135Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or 136CURLE_OUT_OF_MEMORY if there was insufficient heap space. 137