1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Title: CURLOPT_COOKIE 5Section: 3 6Source: libcurl 7See-also: 8 - CURLINFO_COOKIELIST (3) 9 - CURLOPT_COOKIEFILE (3) 10 - CURLOPT_COOKIEJAR (3) 11 - CURLOPT_COOKIELIST (3) 12 - CURLOPT_HTTPHEADER (3) 13Protocol: 14 - HTTP 15Added-in: 7.1 16--- 17 18# NAME 19 20CURLOPT_COOKIE - HTTP Cookie header 21 22# SYNOPSIS 23 24~~~c 25#include <curl/curl.h> 26 27CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIE, char *cookie); 28~~~ 29 30# DESCRIPTION 31 32Pass a pointer to a null-terminated string as parameter. It is used to set one 33or more cookies in the HTTP request. The format of the string should be 34NAME=CONTENTS, where NAME is the cookie name and CONTENTS is what the cookie 35should contain. 36 37To set multiple cookies, set them all using a single option concatenated like 38this: "name1=content1; name2=content2;" etc. libcurl does not syntax check the 39data but assumes the application gives it what it needs to send. 40 41This option sets the cookie header explicitly in the outgoing request(s). If 42multiple requests are done due to authentication, followed redirections or 43similar, they all get this cookie passed on. 44 45The cookies set by this option are separate from the internal cookie storage 46held by the cookie engine and they are not be modified by it. If you enable 47the cookie engine and either you have imported a cookie of the same name (e.g. 48'foo') or the server has set one, it has no effect on the cookies you set 49here. A request to the server sends both the 'foo' held by the cookie engine 50and the 'foo' held by this option. To set a cookie that is instead held by the 51cookie engine and can be modified by the server use CURLOPT_COOKIELIST(3). 52 53Since this custom cookie is appended to the Cookie: header in addition to any 54cookies set by the cookie engine, there is a risk that the header ends up too 55long and thereby getting the entire request rejected by the server. 56 57The application does not have to keep the string around after setting this 58option. 59 60Using this option multiple times makes the last set string override the 61previous ones. Set it to NULL to disable its use again. 62 63This option does not enable the cookie engine. Use CURLOPT_COOKIEFILE(3) or 64CURLOPT_COOKIEJAR(3) to enable parsing and sending cookies automatically. 65 66# DEFAULT 67 68NULL, no cookies 69 70# %PROTOCOLS% 71 72# EXAMPLE 73 74~~~c 75int main(void) 76{ 77 CURL *curl = curl_easy_init(); 78 if(curl) { 79 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); 80 81 curl_easy_setopt(curl, CURLOPT_COOKIE, "tool=curl; fun=yes;"); 82 83 curl_easy_perform(curl); 84 } 85} 86~~~ 87 88# %AVAILABILITY% 89 90# RETURN VALUE 91 92Returns CURLE_OK if HTTP is enabled, CURLE_UNKNOWN_OPTION if not, or 93CURLE_OUT_OF_MEMORY if there was insufficient heap space. 94
