Return to curl_share_setopt.3 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs / libcurl

Annotation of embedaddon/curl/docs/libcurl/curl_share_setopt.3, revision 1.1.1.1

1.1       misho       1: .\" **************************************************************************
                      2: .\" *                                  _   _ ____  _
                      3: .\" *  Project                     ___| | | |  _ \| |
                      4: .\" *                             / __| | | | |_) | |
                      5: .\" *                            | (__| |_| |  _ <| |___
                      6: .\" *                             \___|\___/|_| \_\_____|
                      7: .\" *
                      8: .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
                      9: .\" *
                     10: .\" * This software is licensed as described in the file COPYING, which
                     11: .\" * you should have received as part of this distribution. The terms
                     12: .\" * are also available at https://curl.haxx.se/docs/copyright.html.
                     13: .\" *
                     14: .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
                     15: .\" * copies of the Software, and permit persons to whom the Software is
                     16: .\" * furnished to do so, under the terms of the COPYING file.
                     17: .\" *
                     18: .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
                     19: .\" * KIND, either express or implied.
                     20: .\" *
                     21: .\" **************************************************************************
                     22: .TH curl_share_setopt 3 "March 23, 2020" "libcurl 7.70.0" "libcurl Manual"
                     23: 
                     24: .SH NAME
                     25: curl_share_setopt - Set options for a shared object
                     26: .SH SYNOPSIS
                     27: .B #include <curl/curl.h>
                     28: .sp
                     29: CURLSHcode curl_share_setopt(CURLSH *share, CURLSHoption option, parameter);
                     30: .ad
                     31: .SH DESCRIPTION
                     32: Set the \fIoption\fP to \fIparameter\fP for the given \fIshare\fP.
                     33: .SH OPTIONS
                     34: .IP CURLSHOPT_LOCKFUNC
                     35: The \fIparameter\fP must be a pointer to a function matching the following
                     36: prototype:
                     37: 
                     38: void lock_function(CURL *handle, curl_lock_data data, curl_lock_access access,
                     39: void *userptr);
                     40: 
                     41: The \fIdata\fP argument tells what kind of data libcurl wants to lock. Make
                     42: sure that the callback uses a different lock for each kind of data.
                     43: 
                     44: \fIaccess\fP defines what access type libcurl wants, shared or single.
                     45: 
                     46: \fIuserptr\fP is the pointer you set with \fICURLSHOPT_USERDATA\fP.
                     47: .IP CURLSHOPT_UNLOCKFUNC
                     48: The \fIparameter\fP must be a pointer to a function matching the following
                     49: prototype:
                     50: 
                     51: void unlock_function(CURL *handle, curl_lock_data data, void *userptr);
                     52: 
                     53: \fIdata\fP defines what data libcurl wants to unlock, and you must make sure
                     54: that only one lock is given at any time for each kind of data.
                     55: 
                     56: \fIuserptr\fP is the pointer you set with \fICURLSHOPT_USERDATA\fP.
                     57: .IP CURLSHOPT_SHARE
                     58: The \fIparameter\fP specifies a type of data that should be shared. This may
                     59: be set to one of the values described below.
                     60: .RS
                     61: .IP CURL_LOCK_DATA_COOKIE
                     62: Cookie data will be shared across the easy handles using this shared object.
                     63: Note that this does not activate an easy handle's cookie handling. You can do
                     64: that separately by using \fICURLOPT_COOKIEFILE(3)\fP for example.
                     65: .IP CURL_LOCK_DATA_DNS
                     66: Cached DNS hosts will be shared across the easy handles using this shared
                     67: object. Note that when you use the multi interface, all easy handles added to
                     68: the same multi handle will share DNS cache by default without using this
                     69: option.
                     70: .IP CURL_LOCK_DATA_SSL_SESSION
                     71: SSL session IDs will be shared across the easy handles using this shared
                     72: object. This will reduce the time spent in the SSL handshake when reconnecting
                     73: to the same server. Note SSL session IDs are reused within the same easy handle
                     74: by default. Note this symbol was added in 7.10.3 but was not implemented until
                     75: 7.23.0.
                     76: .IP CURL_LOCK_DATA_CONNECT
                     77: Put the connection cache in the share object and make all easy handles using
                     78: this share object share the connection cache. Using this, you can for example
                     79: do multi-threaded libcurl use with one handle in each thread, and yet have a
                     80: shared pool of unused connections and this way get way better connection
                     81: re-use than if you use one separate pool in each thread.
                     82: 
                     83: Connections that are used for HTTP/1.1 Pipelining or HTTP/2 multiplexing only
                     84: get additional transfers added to them if the existing connection is held by
                     85: the same multi or easy handle. libcurl does not support doing HTTP/2 streams
                     86: in different threads using a shared connection.
                     87: 
                     88: Support for \fBCURL_LOCK_DATA_CONNECT\fP was added in 7.57.0, but the symbol
                     89: existed before this.
                     90: 
                     91: Note that when you use the multi interface, all easy handles added to the same
                     92: multi handle will share connection cache by default without using this option.
                     93: .IP CURL_LOCK_DATA_PSL
                     94: The Public Suffix List stored in the share object is made available to all
                     95: easy handle bound to the later. Since the Public Suffix List is periodically
                     96: refreshed, this avoids updates in too many different contexts.
                     97: 
                     98: \fBCURL_LOCK_DATA_PSL\fP exists since 7.61.0.
                     99: 
                    100: Note that when you use the multi interface, all easy handles added to the same
                    101: multi handle will share PSL cache by default without using this option.
                    102: .RE
                    103: .IP CURLSHOPT_UNSHARE
                    104: This option does the opposite of \fICURLSHOPT_SHARE\fP. It specifies that
                    105: the specified \fIparameter\fP will no longer be shared. Valid values are
                    106: the same as those for \fICURLSHOPT_SHARE\fP.
                    107: .IP CURLSHOPT_USERDATA
                    108: The \fIparameter\fP allows you to specify a pointer to data that will be passed
                    109: to the lock_function and unlock_function each time it is called.
                    110: .SH RETURN VALUE
                    111: CURLSHE_OK (zero) means that the option was set properly, non-zero means an
                    112: error occurred as \fI<curl/curl.h>\fP defines. See the \fIlibcurl-errors.3\fP
                    113: man page for the full list with descriptions.
                    114: .SH "SEE ALSO"
                    115: .BR curl_share_cleanup "(3), " curl_share_init "(3)"