mirror of
https://github.com/moparisthebest/curl
synced 2024-11-17 15:05:02 -05:00
485d4470d3
Follow-up to d0a7ee3 which fixed a bug in 7.66.0 that caused
CURL_LOCK_DATA_COOKIE to enable the easy handle's cookie engine.
Bug: https://curl.haxx.se/mail/lib-2020-03/0019.html
Reported-by: Felipe Gasper
Closes https://github.com/curl/curl/pull/5048
115 lines
5.2 KiB
Groff
115 lines
5.2 KiB
Groff
.\" **************************************************************************
|
|
.\" * _ _ ____ _
|
|
.\" * Project ___| | | | _ \| |
|
|
.\" * / __| | | | |_) | |
|
|
.\" * | (__| |_| | _ <| |___
|
|
.\" * \___|\___/|_| \_\_____|
|
|
.\" *
|
|
.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al.
|
|
.\" *
|
|
.\" * This software is licensed as described in the file COPYING, which
|
|
.\" * you should have received as part of this distribution. The terms
|
|
.\" * are also available at https://curl.haxx.se/docs/copyright.html.
|
|
.\" *
|
|
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
|
|
.\" * copies of the Software, and permit persons to whom the Software is
|
|
.\" * furnished to do so, under the terms of the COPYING file.
|
|
.\" *
|
|
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
|
|
.\" * KIND, either express or implied.
|
|
.\" *
|
|
.\" **************************************************************************
|
|
.TH curl_share_setopt 3 "8 Aug 2003" "libcurl 7.10.7" "libcurl Manual"
|
|
.SH NAME
|
|
curl_share_setopt - Set options for a shared object
|
|
.SH SYNOPSIS
|
|
.B #include <curl/curl.h>
|
|
.sp
|
|
CURLSHcode curl_share_setopt(CURLSH *share, CURLSHoption option, parameter);
|
|
.ad
|
|
.SH DESCRIPTION
|
|
Set the \fIoption\fP to \fIparameter\fP for the given \fIshare\fP.
|
|
.SH OPTIONS
|
|
.IP CURLSHOPT_LOCKFUNC
|
|
The \fIparameter\fP must be a pointer to a function matching the following
|
|
prototype:
|
|
|
|
void lock_function(CURL *handle, curl_lock_data data, curl_lock_access access,
|
|
void *userptr);
|
|
|
|
The \fIdata\fP argument tells what kind of data libcurl wants to lock. Make
|
|
sure that the callback uses a different lock for each kind of data.
|
|
|
|
\fIaccess\fP defines what access type libcurl wants, shared or single.
|
|
|
|
\fIuserptr\fP is the pointer you set with \fICURLSHOPT_USERDATA\fP.
|
|
.IP CURLSHOPT_UNLOCKFUNC
|
|
The \fIparameter\fP must be a pointer to a function matching the following
|
|
prototype:
|
|
|
|
void unlock_function(CURL *handle, curl_lock_data data, void *userptr);
|
|
|
|
\fIdata\fP defines what data libcurl wants to unlock, and you must make sure
|
|
that only one lock is given at any time for each kind of data.
|
|
|
|
\fIuserptr\fP is the pointer you set with \fICURLSHOPT_USERDATA\fP.
|
|
.IP CURLSHOPT_SHARE
|
|
The \fIparameter\fP specifies a type of data that should be shared. This may
|
|
be set to one of the values described below.
|
|
.RS
|
|
.IP CURL_LOCK_DATA_COOKIE
|
|
Cookie data will be shared across the easy handles using this shared object.
|
|
Note that this does not activate an easy handle's cookie handling. You can do
|
|
that separately by using \fICURLOPT_COOKIEFILE(3)\fP for example.
|
|
.IP CURL_LOCK_DATA_DNS
|
|
Cached DNS hosts will be shared across the easy handles using this shared
|
|
object. Note that when you use the multi interface, all easy handles added to
|
|
the same multi handle will share DNS cache by default without using this
|
|
option.
|
|
.IP CURL_LOCK_DATA_SSL_SESSION
|
|
SSL session IDs will be shared across the easy handles using this shared
|
|
object. This will reduce the time spent in the SSL handshake when reconnecting
|
|
to the same server. Note SSL session IDs are reused within the same easy handle
|
|
by default. Note this symbol was added in 7.10.3 but was not implemented until
|
|
7.23.0.
|
|
.IP CURL_LOCK_DATA_CONNECT
|
|
Put the connection cache in the share object and make all easy handles using
|
|
this share object share the connection cache. Using this, you can for example
|
|
do multi-threaded libcurl use with one handle in each thread, and yet have a
|
|
shared pool of unused connections and this way get way better connection
|
|
re-use than if you use one separate pool in each thread.
|
|
|
|
Connections that are used for HTTP/1.1 Pipelining or HTTP/2 multiplexing only
|
|
get additional transfers added to them if the existing connection is held by
|
|
the same multi or easy handle. libcurl does not support doing HTTP/2 streams
|
|
in different threads using a shared connection.
|
|
|
|
Support for \fBCURL_LOCK_DATA_CONNECT\fP was added in 7.57.0, but the symbol
|
|
existed before this.
|
|
|
|
Note that when you use the multi interface, all easy handles added to the same
|
|
multi handle will share connection cache by default without using this option.
|
|
.IP CURL_LOCK_DATA_PSL
|
|
The Public Suffix List stored in the share object is made available to all
|
|
easy handle bound to the later. Since the Public Suffix List is periodically
|
|
refreshed, this avoids updates in too many different contexts.
|
|
|
|
\fBCURL_LOCK_DATA_PSL\fP exists since 7.61.0.
|
|
|
|
Note that when you use the multi interface, all easy handles added to the same
|
|
multi handle will share PSL cache by default without using this option.
|
|
.RE
|
|
.IP CURLSHOPT_UNSHARE
|
|
This option does the opposite of \fICURLSHOPT_SHARE\fP. It specifies that
|
|
the specified \fIparameter\fP will no longer be shared. Valid values are
|
|
the same as those for \fICURLSHOPT_SHARE\fP.
|
|
.IP CURLSHOPT_USERDATA
|
|
The \fIparameter\fP allows you to specify a pointer to data that will be passed
|
|
to the lock_function and unlock_function each time it is called.
|
|
.SH RETURN VALUE
|
|
CURLSHE_OK (zero) means that the option was set properly, non-zero means an
|
|
error occurred as \fI<curl/curl.h>\fP defines. See the \fIlibcurl-errors.3\fP
|
|
man page for the full list with descriptions.
|
|
.SH "SEE ALSO"
|
|
.BR curl_share_cleanup "(3), " curl_share_init "(3)"
|