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