docs/libcurl/libcurl-share.3

   1 .\" **************************************************************************
   2 .\" *                                  _   _ ____  _
   3 .\" *  Project                     ___| | | |  _ \| |
   4 .\" *                             / __| | | | |_) | |
   5 .\" *                            | (__| |_| |  _ <| |___
   6 .\" *                             \___|\___/|_| \_\_____|
   7 .\" *
   8 .\" * Copyright (C) 1998 - 2014, 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 "February 03, 2016" "libcurl 7.56.1" "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! This
  39 way, each single transfer will take advantage from data updates made by the
  40 other transfer(s). The sharing interface, however, does not share active or
  41 persistent connections between different easy handles.
  42 .SH "SHARE OBJECT"
  43 You create a shared object with \fIcurl_share_init(3)\fP. It returns a handle
  44 for a newly created one.
  45
  46 You tell the shared object what data you want it to share by using
  47 \fIcurl_share_setopt(3)\fP.
  48
  49 Since you can use this share from multiple threads, and libcurl has no
  50 internal thread synchronization, you must provide mutex callbacks if you're
  51 using this multi-threaded. You set lock and unlock functions with
  52 \fIcurl_share_setopt(3)\fP too.
  53
  54 Then, you make an easy handle to use this share, you set the
  55 \fICURLOPT_SHARE(3)\fP option with \fIcurl_easy_setopt(3)\fP, and pass in
  56 share handle. You can make any number of easy handles share the same share
  57 handle.
  58
  59 To make an easy handle stop using that particular share, you set
  60 \fICURLOPT_SHARE(3)\fP to NULL for that easy handle. To make a handle stop
  61 sharing a particular data, you can \fICURLSHOPT_UNSHARE\fP it.
  62
  63 When you're done using the share, make sure that no easy handle is still using
  64 it, and call \fIcurl_share_cleanup(3)\fP on the handle.
  65 .SH "SEE ALSO"
  66 .BR curl_share_init "(3), " curl_share_setopt "(3), " curl_share_cleanup "(3)"
  67 .BR libcurl-errors "(3), " libcurl-easy "(3), " libcurl-multi "(3) "