quickjs-tart

quickjs-based runtime for wallet-core logic
Log | Files | Refs | README | LICENSE

CURLOPT_COOKIELIST.md (3892B)

      1 ---
      2 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
      3 SPDX-License-Identifier: curl
      4 Title: CURLOPT_COOKIELIST
      5 Section: 3
      6 Source: libcurl
      7 See-also:
      8   - CURLINFO_COOKIELIST (3)
      9   - CURLOPT_COOKIE (3)
     10   - CURLOPT_COOKIEFILE (3)
     11   - CURLOPT_COOKIEJAR (3)
     12 Protocol:
     13   - HTTP
     14 Added-in: 7.14.1
     15 ---
     16 
     17 # NAME
     18 
     19 CURLOPT_COOKIELIST - add to or manipulate cookies held in memory
     20 
     21 # SYNOPSIS
     22 
     23 ~~~c
     24 #include <curl/curl.h>
     25 
     26 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIELIST,
     27                           char *cookie);
     28 ~~~
     29 
     30 # DESCRIPTION
     31 
     32 Pass a char pointer to a *cookie* string.
     33 
     34 Such a cookie can be either a single line in Netscape / Mozilla format or just
     35 regular HTTP-style header (`Set-Cookie:`) format. This option also enables the
     36 cookie engine. This adds that single cookie to the internal cookie store.
     37 
     38 We strongly advice against loading cookies from an HTTP header file, as that
     39 is an inferior data exchange format.
     40 
     41 Exercise caution if you are using this option and multiple transfers may
     42 occur. If you use the `Set-Cookie` format and the string does not specify a
     43 domain, then the cookie is sent for any domain (even after redirects are
     44 followed) and cannot be modified by a server-set cookie. If a server sets a
     45 cookie of the same name (or maybe you have imported one) then both are sent on
     46 future transfers to that server, likely not what you intended. To address
     47 these issues set a domain in `Set-Cookie` (doing that includes subdomains) or
     48 much better: use the Netscape file format.
     49 
     50 Additionally, there are commands available that perform actions if you pass in
     51 these exact strings:
     52 
     53 ## `ALL`
     54 
     55 erases all cookies held in memory
     56 
     57 ## `SESS`
     58 
     59 erases all session cookies held in memory
     60 
     61 ## `FLUSH`
     62 
     63 writes all known cookies to the file specified by CURLOPT_COOKIEJAR(3)
     64 
     65 ## `RELOAD`
     66 
     67 loads all cookies from the files specified by CURLOPT_COOKIEFILE(3)
     68 
     69 # DEFAULT
     70 
     71 NULL
     72 
     73 # %PROTOCOLS%
     74 
     75 # EXAMPLE
     76 
     77 ~~~c
     78 /* an inline import of a cookie in Netscape format. */
     79 
     80 #define SEP  "\t"  /* Tab separates the fields */
     81 
     82 int main(void)
     83 {
     84   const char *my_cookie =
     85     "example.com"    /* Hostname */
     86     SEP "FALSE"      /* Include subdomains */
     87     SEP "/"          /* Path */
     88     SEP "FALSE"      /* Secure */
     89     SEP "0"          /* Expiry in epoch time format. 0 == Session */
     90     SEP "foo"        /* Name */
     91     SEP "bar";       /* Value */
     92 
     93   CURL *curl = curl_easy_init();
     94   if(curl) {
     95     /* my_cookie is imported immediately via CURLOPT_COOKIELIST. */
     96     curl_easy_setopt(curl, CURLOPT_COOKIELIST, my_cookie);
     97 
     98     /* The list of cookies in cookies.txt are not be imported until right
     99        before a transfer is performed. Cookies in the list that have the same
    100        hostname, path and name as in my_cookie are skipped. That is because
    101        libcurl has already imported my_cookie and it's considered a "live"
    102        cookie. A live cookie is not replaced by one read from a file.
    103     */
    104     curl_easy_setopt(curl, CURLOPT_COOKIEFILE, "cookies.txt");  /* import */
    105 
    106     /* Cookies are exported after curl_easy_cleanup is called. The server
    107        may have added, deleted or modified cookies by then. The cookies that
    108        were skipped on import are not exported.
    109     */
    110     curl_easy_setopt(curl, CURLOPT_COOKIEJAR, "cookies.txt");  /* export */
    111 
    112     curl_easy_perform(curl);  /* cookies imported from cookies.txt */
    113 
    114     curl_easy_cleanup(curl);  /* cookies exported to cookies.txt */
    115   }
    116 }
    117 ~~~
    118 
    119 # Cookie file format
    120 
    121 The cookie file format and general cookie concepts in curl are described
    122 online here: https://curl.se/docs/http-cookies.html
    123 
    124 # HISTORY
    125 
    126 **ALL** was added in 7.14.1
    127 
    128 **SESS** was added in 7.15.4
    129 
    130 **FLUSH** was added in 7.17.1
    131 
    132 **RELOAD** was added in 7.39.0
    133 
    134 # %AVAILABILITY%
    135 
    136 # RETURN VALUE
    137 
    138 curl_easy_setopt(3) returns a CURLcode indicating success or error.
    139 
    140 CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
    141 libcurl-errors(3).