aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/curl.114
-rw-r--r--docs/libcurl/curl_easy_getinfo.38
-rw-r--r--docs/libcurl/opts/CURLOPT_COOKIEFILE.38
-rw-r--r--docs/libcurl/opts/CURLOPT_COOKIEJAR.36
-rw-r--r--docs/libcurl/opts/CURLOPT_COOKIELIST.317
5 files changed, 40 insertions, 13 deletions
diff --git a/docs/curl.1 b/docs/curl.1
index b49c492b2..6b3feab33 100644
--- a/docs/curl.1
+++ b/docs/curl.1
@@ -213,7 +213,7 @@ be in the format "NAME1=VALUE1; NAME2=VALUE2".
If no '=' symbol is used in the line, it is treated as a filename to use to
read previously stored cookie lines from, which should be used in this session
-if they match. Using this method also activates the "cookie parser" which will
+if they match. Using this method also activates the cookie engine which will
make curl record incoming cookies too, which may be handy if you're using this
in combination with the \fI-L, --location\fP option. The file format of the
file to read cookies from should be plain HTTP headers or the Netscape/Mozilla
@@ -223,6 +223,15 @@ The file specified with \fI-b, --cookie\fP is only used as input. No cookies
will be written to the file. To store cookies, use the \fI-c, --cookie-jar\fP
option.
+Exercise caution if you are using this option and multiple transfers may occur.
+If you use the NAME1=VALUE1; format, or in a file use the Set-Cookie format and
+don't specify a domain, then the cookie is sent for any domain (even after
+redirects are followed) and cannot be modified by a server-set cookie. If the
+cookie engine is enabled and a server sets a cookie of the same name then both
+will be sent on a future transfer to that server, likely not what you intended.
+To address these issues set a domain in Set-Cookie (doing that will include
+sub-domains) or use the Netscape format.
+
If this option is used several times, the last one will be used.
.IP "-B, --use-ascii"
(FTP/LDAP) Enable ASCII transfer. For FTP, this can also be enforced by using
@@ -254,6 +263,9 @@ won't fail or even report an error clearly. Using -v will get a warning
displayed, but that is the only visible feedback you get about this possibly
lethal situation.
+Since 7.43.0 cookies that were imported in the Set-Cookie format without a
+domain name are not exported by this option.
+
If this option is used several times, the last specified file name will be
used.
.IP "-C, --continue-at <offset>"
diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3
index e5ac5009b..e72c6ba7d 100644
--- a/docs/libcurl/curl_easy_getinfo.3
+++ b/docs/libcurl/curl_easy_getinfo.3
@@ -132,8 +132,12 @@ Pass a pointer to a 'struct curl_slist *' to receive a linked-list of all
cookies cURL knows (expired ones, too). Don't forget to
\fIcurl_slist_free_all(3)\fP the list after it has been used. If there are no
cookies (cookies for the handle have not been enabled or simply none have been
-received) 'struct curl_slist *' will be set to point to NULL. (Added in
-7.14.1)
+received) 'struct curl_slist *' will be set to point to NULL.
+
+Since 7.43.0 cookies that were imported in the Set-Cookie format without a
+domain name are not exported by this option.
+
+(Added in 7.14.1)
.IP CURLINFO_LASTSOCKET
Pass a pointer to a long to receive the last socket used by this curl
session. If the socket is no longer valid, -1 is returned. When you finish
diff --git a/docs/libcurl/opts/CURLOPT_COOKIEFILE.3 b/docs/libcurl/opts/CURLOPT_COOKIEFILE.3
index a4c3b02b3..643d8e32f 100644
--- a/docs/libcurl/opts/CURLOPT_COOKIEFILE.3
+++ b/docs/libcurl/opts/CURLOPT_COOKIEFILE.3
@@ -43,6 +43,14 @@ cookies.
This option only \fBreads\fP cookies. To make libcurl write cookies to file,
see \fICURLOPT_COOKIEJAR(3)\fP.
+Exercise caution if you are using this option and multiple transfers may occur.
+If you use the Set-Cookie format and don't specify a domain then the cookie is
+sent for any domain (even after redirects are followed) and cannot be modified
+by a server-set cookie. If a server sets a cookie of the same name then both
+will be sent on a future transfer to that server, likely not what you intended.
+To address these issues set a domain in Set-Cookie (doing that will include
+sub-domains) or use the Netscape format.
+
If you use this option multiple times, you just add more files to read.
Subsequent files will add more cookies.
.SH DEFAULT
diff --git a/docs/libcurl/opts/CURLOPT_COOKIEJAR.3 b/docs/libcurl/opts/CURLOPT_COOKIEJAR.3
index 936d4d8a4..e21540b3a 100644
--- a/docs/libcurl/opts/CURLOPT_COOKIEJAR.3
+++ b/docs/libcurl/opts/CURLOPT_COOKIEJAR.3
@@ -43,6 +43,9 @@ If the cookie jar file can't be created or written to (when the
error for this. Using \fICURLOPT_VERBOSE(3)\fP or
\fICURLOPT_DEBUGFUNCTION(3)\fP will get a warning to display, but that is the
only visible feedback you get about this possibly lethal situation.
+
+Since 7.43.0 cookies that were imported in the Set-Cookie format without a
+domain name are not exported by this option.
.SH DEFAULT
NULL
.SH PROTOCOLS
@@ -55,4 +58,5 @@ Along with HTTP
Returns CURLE_OK if HTTP is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
-.BR CURLOPT_COOKIEFILE "(3), " CURLOPT_COOKIE "(3), " CURLOPT_COOKIELIST "(3), "
+.BR CURLOPT_COOKIEFILE "(3), " CURLOPT_COOKIE "(3), "
+.BR CURLOPT_COOKIELIST "(3), "
diff --git a/docs/libcurl/opts/CURLOPT_COOKIELIST.3 b/docs/libcurl/opts/CURLOPT_COOKIELIST.3
index 937c79db8..ca30ec2a6 100644
--- a/docs/libcurl/opts/CURLOPT_COOKIELIST.3
+++ b/docs/libcurl/opts/CURLOPT_COOKIELIST.3
@@ -36,16 +36,15 @@ Such a cookie can be either a single line in Netscape / Mozilla format or just
regular HTTP-style header (Set-Cookie: ...) format. This will also enable the
cookie engine. This adds that single cookie to the internal cookie store.
-If you use the Set-Cookie format and don't specify a domain then the cookie
-is sent for any domain and will not be modified. If a server sets a cookie of
-the same name (or maybe you've imported one) then both will be sent on a future
-transfer to that server, likely not what you intended. Either set a domain in
-Set-Cookie (doing that will include sub domains) or use the Netscape format as
+Exercise caution if you are using this option and multiple transfers may occur.
+If you use the Set-Cookie format and don't specify a domain then the cookie is
+sent for any domain (even after redirects are followed) and cannot be modified
+by a server-set cookie. If a server sets a cookie of the same name (or maybe
+you've imported one) then both will be sent on a future transfer to that
+server, likely not what you intended. To address these issues set a domain in
+Set-Cookie (doing that will include sub-domains) or use the Netscape format as
shown in EXAMPLE.
-Starting in 7.43.0 the aforementioned any-domain cookies will not appear in the
-lists exported by \fICURLINFO_COOKIELIST(3)\fP and \fICURLOPT_COOKIEJAR(3)\fP.
-
Additionally, there are commands available that perform actions if you pass in
these exact strings:
.IP ALL
@@ -117,4 +116,4 @@ RELOAD was added in 7.39.0
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
-.BR CURLOPT_COOKIEFILE "(3), " CURLOPT_COOKIEJAR "(3), " CURLOPT_COOKIE "(3), "
+.BR CURLOPT_COOKIEFILE "(3), " CURLOPT_COOKIEJAR "(3), " CURLOPT_COOKIE "(3), "