docs/libcurl/opts/CURLOPT_COOKIELIST.3

   1 .\" **************************************************************************
   2 .\" *                                  _   _ ____  _
   3 .\" *  Project                     ___| | | |  _ \| |
   4 .\" *                             / __| | | | |_) | |
   5 .\" *                            | (__| |_| |  _ <| |___
   6 .\" *                             \___|\___/|_| \_\_____|
   7 .\" *
   8 .\" * Copyright (C) 1998 - 2016, Daniel Stenberg, <daniel@haxx.se>, et al.
   9 .\" *
  10 .\" * This software is licensed as described in the file COPYING, which
  11 .\" * you should have received as part of this distribution. The terms
  12 .\" * are also available at https://curl.haxx.se/docs/copyright.html.
  13 .\" *
  14 .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
  15 .\" * copies of the Software, and permit persons to whom the Software is
  16 .\" * furnished to do so, under the terms of the COPYING file.
  17 .\" *
  18 .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  19 .\" * KIND, either express or implied.
  20 .\" *
  21 .\" **************************************************************************
  22 .\"
  23 .TH CURLOPT_COOKIELIST 3 "April 26, 2016" "libcurl 7.59.0" "curl_easy_setopt options"
  24
  25 .SH NAME
  26 CURLOPT_COOKIELIST \- add to or manipulate cookies held in memory
  27 .SH SYNOPSIS
  28 .nf
  29 #include <curl/curl.h>
  30
  31 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIELIST,
  32                           char *cookie);
  33 .SH DESCRIPTION
  34 Pass a char * to a \fIcookie\fP string.
  35
  36 Such a cookie can be either a single line in Netscape / Mozilla format or just
  37 regular HTTP-style header (Set-Cookie: ...) format. This will also enable the
  38 cookie engine. This adds that single cookie to the internal cookie store.
  39
  40 Exercise caution if you are using this option and multiple transfers may occur.
  41 If you use the Set-Cookie format and don't specify a domain then the cookie is
  42 sent for any domain (even after redirects are followed) and cannot be modified
  43 by a server-set cookie. If a server sets a cookie of the same name (or maybe
  44 you've imported one) then both will be sent on a future transfer to that
  45 server, likely not what you intended. To address these issues set a domain in
  46 Set-Cookie (doing that will include sub-domains) or use the Netscape format as
  47 shown in EXAMPLE.
  48
  49 Additionally, there are commands available that perform actions if you pass in
  50 these exact strings:
  51 .IP ALL
  52 erases all cookies held in memory
  53
  54 .IP SESS
  55 erases all session cookies held in memory
  56
  57 .IP FLUSH
  58 writes all known cookies to the file specified by \fICURLOPT_COOKIEJAR(3)\fP
  59
  60 .IP RELOAD
  61 loads all cookies from the files specified by \fICURLOPT_COOKIEFILE(3)\fP
  62
  63 .SH DEFAULT
  64 NULL
  65 .SH PROTOCOLS
  66 HTTP
  67 .SH EXAMPLE
  68 .nf
  69 /* This example shows an inline import of a cookie in Netscape format.
  70 You can set the cookie as HttpOnly to prevent XSS attacks by prepending
  71 #HttpOnly_ to the hostname. That may be useful if the cookie will later
  72 be imported by a browser.
  73 */
  74
  75 #define SEP  "\\t"  /* Tab separates the fields */
  76
  77 char *my_cookie =
  78   "example.com"    /* Hostname */
  79   SEP "FALSE"      /* Include subdomains */
  80   SEP "/"          /* Path */
  81   SEP "FALSE"      /* Secure */
  82   SEP "0"          /* Expiry in epoch time format. 0 == Session */
  83   SEP "foo"        /* Name */
  84   SEP "bar";       /* Value */
  85
  86 /* my_cookie is imported immediately via CURLOPT_COOKIELIST.
  87 */
  88 curl_easy_setopt(curl, CURLOPT_COOKIELIST, my_cookie);
  89
  90 /* The list of cookies in cookies.txt will not be imported until right
  91 before a transfer is performed. Cookies in the list that have the same
  92 hostname, path and name as in my_cookie are skipped. That is because
  93 libcurl has already imported my_cookie and it's considered a "live"
  94 cookie. A live cookie won't be replaced by one read from a file.
  95 */
  96 curl_easy_setopt(curl, CURLOPT_COOKIEFILE, "cookies.txt");  /* import */
  97
  98 /* Cookies are exported after curl_easy_cleanup is called. The server
  99 may have added, deleted or modified cookies by then. The cookies that
 100 were skipped on import are not exported.
 101 */
 102 curl_easy_setopt(curl, CURLOPT_COOKIEJAR, "cookies.txt");  /* export */
 103
 104 curl_easy_perform(curl);  /* cookies imported from cookies.txt */
 105
 106 curl_easy_cleanup(curl);  /* cookies exported to cookies.txt */
 107 .fi
 108 .SH AVAILABILITY
 109 ALL was added in 7.14.1
 110
 111 SESS was added in 7.15.4
 112
 113 FLUSH was added in 7.17.1
 114
 115 RELOAD was added in 7.39.0
 116 .SH RETURN VALUE
 117 Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
 118 CURLE_OUT_OF_MEMORY if there was insufficient heap space.
 119 .SH "SEE ALSO"
 120 .BR CURLOPT_COOKIEFILE "(3), " CURLOPT_COOKIEJAR "(3), " CURLOPT_COOKIE "(3), "
 121 .BR CURLINFO_COOKIELIST "(3), "