1---
2c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLSHOPT_SHARE
5Section: 3
6Source: libcurl
7See-also:
8  - CURLSHOPT_UNSHARE (3)
9  - curl_share_cleanup (3)
10  - curl_share_init (3)
11  - curl_share_setopt (3)
12---
13
14# NAME
15
16CURLSHOPT_SHARE - add data to share
17
18# SYNOPSIS
19
20~~~c
21#include <curl/curl.h>
22
23CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_SHARE, long type);
24~~~
25
26# DESCRIPTION
27
28The *type* parameter specifies what specific data that should be shared
29and kept in the share object that was created with curl_share_init(3).
30The given *type* must be be one of the values described below. You can set
31CURLSHOPT_SHARE(3) multiple times with different data arguments to have
32the share object share multiple types of data. Unset a type again by setting
33CURLSHOPT_UNSHARE(3).
34
35## CURL_LOCK_DATA_COOKIE
36
37Cookie data is shared across the easy handles using this shared object. Note
38that this does not activate an easy handle's cookie handling. You can do that
39separately by using CURLOPT_COOKIEFILE(3) for example.
40
41## CURL_LOCK_DATA_DNS
42
43Cached DNS hosts are shared across the easy handles using this shared
44object. Note that when you use the multi interface, all easy handles added to
45the same multi handle share DNS cache by default without using this option.
46
47## CURL_LOCK_DATA_SSL_SESSION
48
49SSL session IDs are shared across the easy handles using this shared
50object. This reduces the time spent in the SSL handshake when reconnecting to
51the same server. Note SSL session IDs are reused within the same easy handle
52by default. Note this symbol was added in 7.10.3 but was not implemented until
537.23.0.
54
55## CURL_LOCK_DATA_CONNECT
56
57Put the connection cache in the share object and make all easy handles using
58this share object share the connection cache.
59
60It is not supported to share connections between multiple concurrent threads.
61
62Connections that are used for HTTP/1.1 Pipelining or HTTP/2 multiplexing only
63get additional transfers added to them if the existing connection is held by
64the same multi or easy handle. libcurl does not support doing HTTP/2 streams
65in different threads using a shared connection.
66
67Support for **CURL_LOCK_DATA_CONNECT** was added in 7.57.0, but the symbol
68existed before this.
69
70Note that when you use the multi interface, all easy handles added to the same
71multi handle shares connection cache by default without using this option.
72
73## CURL_LOCK_DATA_PSL
74
75The Public Suffix List stored in the share object is made available to all
76easy handle bound to the later. Since the Public Suffix List is periodically
77refreshed, this avoids updates in too many different contexts.
78
79Added in 7.61.0.
80
81Note that when you use the multi interface, all easy handles added to the same
82multi handle shares PSL cache by default without using this option.
83
84## CURL_LOCK_DATA_HSTS
85
86The in-memory HSTS cache.
87
88It is not supported to share the HSTS between multiple concurrent threads.
89
90Added in 7.88.0
91
92# PROTOCOLS
93
94All
95
96# EXAMPLE
97
98~~~c
99int main(void)
100{
101  CURLSHcode sh;
102  CURLSH *share = curl_share_init();
103  sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE);
104  if(sh)
105    printf("Error: %s\n", curl_share_strerror(sh));
106}
107~~~
108
109# AVAILABILITY
110
111Added in 7.10
112
113# RETURN VALUE
114
115CURLSHE_OK (zero) means that the option was set properly, non-zero means an
116error occurred. See libcurl-errors(3) for the full list with
117descriptions.
118