docs/libcurl/opts/CURLOPT_COOKIELIST.3

   1 .\" **************************************************************************
   2 .\" *                                  _   _ ____  _
   3 .\" *  Project                     ___| | | |  _ \| |
   4 .\" *                             / __| | | | |_) | |
   5 .\" *                            | (__| |_| |  _ <| |___
   6 .\" *                             \___|\___/|_| \_\_____|
   7 .\" *
   8 .\" * Copyright (C) 1998 - 2014, 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 http://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 If you use the Set-Cookie format and don't specify a domain then the cookie
  40 is sent for any domain and will not be modified. If a server sets a cookie of
  41 the same name (or maybe you've imported one) then both will be sent on a future
  42 transfer to that server, likely not what you intended. Either set a domain in
  43 Set-Cookie (doing that will include sub domains) or use the Netscape format as
  44 shown in EXAMPLE.
  45
  46 Starting in 7.43.0 the aforementioned any-domain cookies will not appear in the
  47 lists exported by \fICURLINFO_COOKIELIST(3)\fP and \fICURLOPT_COOKIEJAR(3)\fP.
  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 res = 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), "