HTTP-COOKIES.md: describe the cookie file format

... and refer to that file from from CURLOPT_COOKIEFILE.3 and
CURLOPT_COOKIELIST.3

Assisted-by: Jay Satiro
Reported-by: bsammon on github
Fixes #4805
Closes #4806

diff --git a/docs/HTTP-COOKIES.md b/docs/HTTP-COOKIES.md
index 06790f8a7e4533e416700ad03d61e8a8ee8df506..62367c2a9abfaec7cc67769b8f2e5ae9a89d0630 100644 (file)
--- a/docs/HTTP-COOKIES.md
+++ b/docs/HTTP-COOKIES.md
@@ -43,6 +43,24 @@
   When libcurl saves a cookiejar, it creates a file header of its own in which
   there is a URL mention that will link to the web version of this document.
 
+## Cookie file format
+
+  The cookie file format is text based and stores one cookie per line. Lines
+  that start with `#` are treated as comments.
+
+  Each line that each specifies a single cookie consists of seven text fields
+  separated with TAB characters.
+
+  |Field| Type  | Example     | Meaning                                       |
+  |---|---------|-------------|-----------------------------------------------|
+  | 0 | string  | example.com | Domain name                                   |
+  | 1 | boolean | FALSE       | Include subdomains                            |
+  | 2 | string  | /foobar/    | Path                                          |
+  | 3 | boolean | TRUE        | Send/receive over HTTPS only                  |
+  | 4 | number  | 1462299217  | Expires at – seconds since Jan 1st 1970, or 0 |
+  | 5 | string  | person      | Name of the cookie                            |
+  | 6 | string  | daniel      | Value of the cookie                           |
+
 ## Cookies with curl the command line tool
 
   curl has a full cookie "engine" built in. If you just activate it, you can

diff --git a/docs/libcurl/opts/CURLOPT_COOKIEFILE.3 b/docs/libcurl/opts/CURLOPT_COOKIEFILE.3
index fb33e41f07c99f4b4210471b253aac5d148c9725..f327ec14816fdb11890e3ab4ebe4336eafd6cd3f 100644 (file)
--- a/docs/libcurl/opts/CURLOPT_COOKIEFILE.3
+++ b/docs/libcurl/opts/CURLOPT_COOKIEFILE.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -75,6 +75,10 @@ if(curl) {
   curl_easy_cleanup(curl);
 }
 .fi
+.SH "Cookie file format"
+The cookie file format and general cookie concepts in curl are described in
+the HTTP-COOKIES.md file, also hosted online here:
+https://curl.haxx.se/docs/http-cookies.html
 .SH AVAILABILITY
 As long as HTTP is supported
 .SH RETURN VALUE

diff --git a/docs/libcurl/opts/CURLOPT_COOKIELIST.3 b/docs/libcurl/opts/CURLOPT_COOKIELIST.3
index 7de4da88243c5909a7aa31989d322a65dba85114..f46d12eb945f4185f5c596d670aaa2cba5409183 100644 (file)
--- a/docs/libcurl/opts/CURLOPT_COOKIELIST.3
+++ b/docs/libcurl/opts/CURLOPT_COOKIELIST.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2016, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -104,6 +104,10 @@ curl_easy_perform(curl);  /* cookies imported from cookies.txt */
 
 curl_easy_cleanup(curl);  /* cookies exported to cookies.txt */
 .fi
+.SH "Cookie file format"
+The cookie file format and general cookie concepts in curl are described in
+the HTTP-COOKIES.md file, also hosted online here:
+https://curl.haxx.se/docs/http-cookies.html
 .SH AVAILABILITY
 ALL was added in 7.14.1