curl_share_setopt(3)

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.  Using this, you can for example do multi-threaded
75                     libcurl use with one handle in each thread, and yet  have
76                     a  shared pool of unused connections and this way get way
77                     better connection re-use than if  you  use  one  separate
78                     pool in each thread.
79
80                     Connections  that  are  used  for  HTTP/1.1 Pipelining or
81                     HTTP/2 multiplexing only get additional  transfers  added
82                     to  them  if  the existing connection is held by the same
83                     multi or easy handle.  libcurl  does  not  support  doing
84                     HTTP/2  streams  in different threads using a shared con‐
85                     nection.
86
87                     Support for CURL_LOCK_DATA_CONNECT was added  in  7.57.0,
88                     but the symbol existed before this.
89
90                     Note that when you use the multi interface, all easy han‐
91                     dles added to the same multi handle will share connection
92                     cache by default without using this option.
93
94              CURL_LOCK_DATA_PSL
95                     The Public Suffix List stored in the share object is made
96                     available to all easy handle bound to  the  later.  Since
97                     the  Public  Suffix  List is periodically refreshed, this
98                     avoids updates in too many different contexts.
99
100                     CURL_LOCK_DATA_PSL exists since 7.61.0.
101
102                     Note that when you use the multi interface, all easy han‐
103                     dles  added to the same multi handle will share PSL cache
104                     by default without using this option.
105
106       CURLSHOPT_UNSHARE
107              This option does the opposite of CURLSHOPT_SHARE.  It  specifies
108              that  the  specified  parameter  will no longer be shared. Valid
109              values are the same as those for CURLSHOPT_SHARE.
110
111       CURLSHOPT_USERDATA
112              The parameter allows you to specify a pointer to data that  will
113              be  passed to the lock_function and unlock_function each time it
114              is called.
115

RETURN VALUE

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

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

RETURN VALUE

SEE ALSO