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