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 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options"
  24 .SH NAME
  25 CURLOPT_COOKIELIST \- add to or manipulate cookies held in memory
  26 .SH SYNOPSIS
  27 .nf
  28 #include <curl/curl.h>
  29
  30 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIELIST,
  31                           char *cookie);
  32 .SH DESCRIPTION
  33 Pass a char * to a \fIcookie\fP string.
  34
  35 Such a cookie can be either a single line in Netscape / Mozilla format or just
  36 regular HTTP-style header (Set-Cookie: ...) format. This will also enable the
  37 cookie engine. This adds that single cookie to the internal cookie store.
  38
  39 Exercise caution if you are using this option and multiple transfers may occur.
  40 If you use the Set-Cookie format and don't specify a domain then the cookie is
  41 sent for any domain (even after redirects are followed) and cannot be modified
  42 by a server-set cookie. If a server sets a cookie of the same name (or maybe
  43 you've imported one) then both will be sent on a future transfer to that
  44 server, likely not what you intended. To address these issues set a domain in
  45 Set-Cookie (doing that will include sub-domains) or use the Netscape format as
  46 shown in EXAMPLE.
  47
  48 Additionally, there are commands available that perform actions if you pass in
  49 these exact strings:
  50 .IP ALL
  51 erases all cookies held in memory
  52
  53 .IP SESS
  54 erases all session cookies held in memory
  55
  56 .IP FLUSH
  57 writes all known cookies to the file specified by \fICURLOPT_COOKIEJAR(3)\fP
  58
  59 .IP RELOAD
  60 loads all cookies from the files specified by \fICURLOPT_COOKIEFILE(3)\fP
  61
  62 .SH DEFAULT
  63 NULL
  64 .SH PROTOCOLS
  65 HTTP
  66 .SH EXAMPLE
  67 .nf
  68 /* This example shows an inline import of a cookie in Netscape format.
  69 You can set the cookie as HttpOnly to prevent XSS attacks by prepending
  70 #HttpOnly_ to the hostname. That may be useful if the cookie will later
  71 be imported by a browser.
  72 */
  73
  74 #define SEP  "\\t"  /* Tab separates the fields */
  75
  76 char *my_cookie =
  77   "example.com"    /* Hostname */
  78   SEP "FALSE"      /* Include subdomains */
  79   SEP "/"          /* Path */
  80   SEP "FALSE"      /* Secure */
  81   SEP "0"          /* Expiry in epoch time format. 0 == Session */
  82   SEP "foo"        /* Name */
  83   SEP "bar";       /* Value */
  84
  85 /* my_cookie is imported immediately via CURLOPT_COOKIELIST.
  86 */
  87 curl_easy_setopt(curl, CURLOPT_COOKIELIST, my_cookie);
  88
  89 /* The list of cookies in cookies.txt will not be imported until right
  90 before a transfer is performed. Cookies in the list that have the same
  91 hostname, path and name as in my_cookie are skipped. That is because
  92 libcurl has already imported my_cookie and it's considered a "live"
  93 cookie. A live cookie won't be replaced by one read from a file.
  94 */
  95 curl_easy_setopt(curl, CURLOPT_COOKIEFILE, "cookies.txt");  /* import */
  96
  97 /* Cookies are exported after curl_easy_cleanup is called. The server
  98 may have added, deleted or modified cookies by then. The cookies that
  99 were skipped on import are not exported.
 100 */
 101 curl_easy_setopt(curl, CURLOPT_COOKIEJAR, "cookies.txt");  /* export */
 102
 103 res = curl_easy_perform(curl);  /* cookies imported from cookies.txt */
 104
 105 curl_easy_cleanup(curl);  /* cookies exported to cookies.txt */
 106 .fi
 107 .SH AVAILABILITY
 108 ALL was added in 7.14.1
 109
 110 SESS was added in 7.15.4
 111
 112 FLUSH was added in 7.17.1
 113
 114 RELOAD was added in 7.39.0
 115 .SH RETURN VALUE
 116 Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
 117 CURLE_OUT_OF_MEMORY if there was insufficient heap space.
 118 .SH "SEE ALSO"
 119 .BR CURLOPT_COOKIEFILE "(3), " CURLOPT_COOKIEJAR "(3), " CURLOPT_COOKIE "(3), "
 120 .BR CURLINFO_COOKIELIST "(3), "