docs/libcurl/libcurl-share.3

   1 .\" **************************************************************************
   2 .\" *                                  _   _ ____  _
   3 .\" *  Project                     ___| | | |  _ \| |
   4 .\" *                             / __| | | | |_) | |
   5 .\" *                            | (__| |_| |  _ <| |___
   6 .\" *                             \___|\___/|_| \_\_____|
   7 .\" *
   8 .\" * Copyright (C) 1998 - 2017, 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 libcurl-share 3 "November 27, 2017" "libcurl 7.59.0" "libcurl share interface"
  23
  24 .SH NAME
  25 libcurl-share \- how to use the share interface
  26 .SH DESCRIPTION
  27 This is an overview on how to use the libcurl share interface in your C
  28 programs. There are specific man pages for each function mentioned in
  29 here.
  30
  31 All functions in the share interface are prefixed with curl_share.
  32
  33 .SH "OBJECTIVES"
  34 The share interface was added to enable sharing of data between curl
  35 \&"handles".
  36 .SH "ONE SET OF DATA - MANY TRANSFERS"
  37 You can have multiple easy handles share data between them. Have them update
  38 and use the \fBsame\fP cookie database, DNS cache, TLS session cache and/or
  39 connection cache! This way, each single transfer will take advantage from data
  40 updates made by the other transfer(s).
  41 .SH "SHARE OBJECT"
  42 You create a shared object with \fIcurl_share_init(3)\fP. It returns a handle
  43 for a newly created one.
  44
  45 You tell the shared object what data you want it to share by using
  46 \fIcurl_share_setopt(3)\fP.
  47
  48 Since you can use this share from multiple threads, and libcurl has no
  49 internal thread synchronization, you must provide mutex callbacks if you're
  50 using this multi-threaded. You set lock and unlock functions with
  51 \fIcurl_share_setopt(3)\fP too.
  52
  53 Then, you make an easy handle to use this share, you set the
  54 \fICURLOPT_SHARE(3)\fP option with \fIcurl_easy_setopt(3)\fP, and pass in
  55 share handle. You can make any number of easy handles share the same share
  56 handle.
  57
  58 To make an easy handle stop using that particular share, you set
  59 \fICURLOPT_SHARE(3)\fP to NULL for that easy handle. To make a handle stop
  60 sharing a particular data, you can \fICURLSHOPT_UNSHARE\fP it.
  61
  62 When you're done using the share, make sure that no easy handle is still using
  63 it, and call \fIcurl_share_cleanup(3)\fP on the handle.
  64 .SH "SEE ALSO"
  65 .BR curl_share_init "(3), " curl_share_setopt "(3), " curl_share_cleanup "(3)"
  66 .BR libcurl-errors "(3), " libcurl-easy "(3), " libcurl-multi "(3) "