1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Title: CURLOPT_COOKIEFILE 5Section: 3 6Source: libcurl 7See-also: 8 - CURLOPT_COOKIE (3) 9 - CURLOPT_COOKIEJAR (3) 10 - CURLOPT_COOKIESESSION (3) 11Protocol: 12 - HTTP 13--- 14 15# NAME 16 17CURLOPT_COOKIEFILE - filename to read cookies from 18 19# SYNOPSIS 20 21~~~c 22#include <curl/curl.h> 23 24CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIEFILE, char *filename); 25~~~ 26 27# DESCRIPTION 28 29Pass a pointer to a null-terminated string as parameter. It should point to 30the filename of your file holding cookie data to read. The cookie data can be 31in either the old Netscape / Mozilla cookie data format or just regular HTTP 32headers (Set-Cookie style) dumped to a file. 33 34It also enables the cookie engine, making libcurl parse and send cookies on 35subsequent requests with this handle. 36 37By passing the empty string ("") to this option, you enable the cookie engine 38without reading any initial cookies. If you tell libcurl the filename is "-" 39(just a single minus sign), libcurl instead reads from stdin. 40 41This option only **reads** cookies. To make libcurl write cookies to file, 42see CURLOPT_COOKIEJAR(3). 43 44If you read cookies from a plain HTTP headers file and it does not specify a 45domain in the Set-Cookie line, then the cookie is not sent since the cookie 46domain cannot match the target URL's. To address this, set a domain in 47Set-Cookie line (doing that includes subdomains) or preferably: use the 48Netscape format. 49 50If you use this option multiple times, you add more files to read cookies 51from. 52 53The application does not have to keep the string around after setting this 54option. 55 56Setting this option to NULL (since 7.77.0) explicitly disables the cookie 57engine and clears the list of files to read cookies from. 58 59# SECURITY 60 61This document previously mentioned how specifying a non-existing file can also 62enable the cookie engine. While true, we strongly advise against using that 63method as it is too hard to be sure that files that stay that way in the long 64run. 65 66# DEFAULT 67 68NULL 69 70# EXAMPLE 71 72~~~c 73int main(void) 74{ 75 CURL *curl = curl_easy_init(); 76 if(curl) { 77 CURLcode res; 78 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); 79 80 /* get cookies from an existing file */ 81 curl_easy_setopt(curl, CURLOPT_COOKIEFILE, "/tmp/cookies.txt"); 82 83 res = curl_easy_perform(curl); 84 85 curl_easy_cleanup(curl); 86 } 87} 88~~~ 89 90# Cookie file format 91 92The cookie file format and general cookie concepts in curl are described 93online here: https://curl.se/docs/http-cookies.html 94 95# AVAILABILITY 96 97As long as HTTP is supported 98 99# RETURN VALUE 100 101Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. 102