1curl_share_setopt(3)            libcurl Manual            curl_share_setopt(3)
2
3
4

NAME

6       curl_share_setopt - Set options for a shared object
7

SYNOPSIS

9       #include <curl/curl.h>
10
11       CURLSHcode curl_share_setopt(CURLSH *share, CURLSHoption option, param‐
12       eter);
13

DESCRIPTION

15       Set the option to parameter for the given share.
16

OPTIONS

18       CURLSHOPT_LOCKFUNC
19              The parameter must be a pointer to a function matching the  fol‐
20              lowing prototype:
21
22              void    lock_function(CURL    *handle,    curl_lock_data   data,
23              curl_lock_access access, void *userptr);
24
25              The data argument tells what kind of data libcurl wants to lock.
26              Make  sure that the callback uses a different lock for each kind
27              of data.
28
29              access defines what access type libcurl wants, shared or single.
30
31              userptr is the pointer you set with CURLSHOPT_USERDATA.
32
33       CURLSHOPT_UNLOCKFUNC
34              The parameter must be a pointer to a function matching the  fol‐
35              lowing prototype:
36
37              void  unlock_function(CURL  *handle,  curl_lock_data  data, void
38              *userptr);
39
40              data defines what data libcurl wants to  unlock,  and  you  must
41              make  sure that only one lock is given at any time for each kind
42              of data.
43
44              userptr is the pointer you set with CURLSHOPT_USERDATA.
45
46       CURLSHOPT_SHARE
47              The parameter specifies a type of data that  should  be  shared.
48              This may be set to one of the values described below.
49
50              CURL_LOCK_DATA_COOKIE
51                     Cookie  data will be shared across the easy handles using
52                     this shared object.  Note that this does not activate  an
53                     easy handle's cookie handling. You can do that separately
54                     by using CURLOPT_COOKIEFILE(3) for example.
55
56              CURL_LOCK_DATA_DNS
57                     Cached DNS hosts will be shared across the  easy  handles
58                     using  this  shared  object.  Note  that when you use the
59                     multi interface, all easy handles added to the same multi
60                     handle will share DNS cache by default without using this
61                     option.
62
63              CURL_LOCK_DATA_SSL_SESSION
64                     SSL session IDs will be shared across  the  easy  handles
65                     using this shared object. This will reduce the time spent
66                     in the  SSL  handshake  when  reconnecting  to  the  same
67                     server.  Note  SSL session IDs are reused within the same
68                     easy handle by default. Note this  symbol  was  added  in
69                     7.10.3 but was not implemented until 7.23.0.
70
71              CURL_LOCK_DATA_CONNECT
72                     Put the connection cache in the share object and make all
73                     easy handles using this share object share the connection
74                     cache.
75
76                     Note  that  due  to  a known bug, it is not safe to share
77                     connections this way between multiple concurrent threads.
78
79                     Connections that are  used  for  HTTP/1.1  Pipelining  or
80                     HTTP/2  multiplexing  only get additional transfers added
81                     to them if the existing connection is held  by  the  same
82                     multi  or  easy  handle.  libcurl  does not support doing
83                     HTTP/2 streams in different threads using a  shared  con‐
84                     nection.
85
86                     Support  for  CURL_LOCK_DATA_CONNECT was added in 7.57.0,
87                     but the symbol existed before this.
88
89                     Note that when you use the multi interface, all easy han‐
90                     dles added to the same multi handle will share connection
91                     cache by default without using this option.
92
93              CURL_LOCK_DATA_PSL
94                     The Public Suffix List stored in the share object is made
95                     available  to  all  easy handle bound to the later. Since
96                     the Public Suffix List is  periodically  refreshed,  this
97                     avoids updates in too many different contexts.
98
99                     CURL_LOCK_DATA_PSL exists since 7.61.0.
100
101                     Note that when you use the multi interface, all easy han‐
102                     dles added to the same multi handle will share PSL  cache
103                     by default without using this option.
104
105       CURLSHOPT_UNSHARE
106              This  option  does the opposite of CURLSHOPT_SHARE. It specifies
107              that the specified parameter will no  longer  be  shared.  Valid
108              values are the same as those for CURLSHOPT_SHARE.
109
110       CURLSHOPT_USERDATA
111              The  parameter allows you to specify a pointer to data that will
112              be passed to the lock_function and unlock_function each time  it
113              is called.
114

RETURN VALUE

116       CURLSHE_OK  (zero)  means  that  the  option was set properly, non-zero
117       means an error occurred as <curl/curl.h> defines. See  the  libcurl-er‐
118       rors.3 man page for the full list with descriptions.
119

SEE ALSO

121       curl_share_cleanup(3), curl_share_init(3)
122
123
124
125libcurl 7.76.1                 November 04, 2020          curl_share_setopt(3)
Impressum