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     ! 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)"