curl_share_setopt.3: split out options into their own manpages

CURLSHOPT_LOCKFUNC.3
CURLSHOPT_SHARE.3
CURLSHOPT_UNLOCKFUNC.3
CURLSHOPT_UNSHARE.3
CURLSHOPT_USERDATA.3

Closes #7998

7 files changed, 370 insertions, 70 deletions

diff --git a/docs/libcurl/curl_share_setopt.3 b/docs/libcurl/curl_share_setopt.3
index 35be8aeed..3e99d6ff9 100644
--- a/docs/libcurl/curl_share_setopt.3
+++ b/docs/libcurl/curl_share_setopt.3
@@ -31,78 +31,13 @@ CURLSHcode curl_share_setopt(CURLSH *share, CURLSHoption option, parameter);
 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.
+See \fICURLSHOPT_LOCKFUNC(3)\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.
+See \fICURLSHOPT_UNLOCKFUNC(3)\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.
-
-Note that due to a known bug, it is not safe to share connections this way
-between multiple concurrent threads.
-
-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
+See \fICURLSHOPT_SHARE(3)\fP.
 .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.
+See \fICURLSHOPT_UNSHARE(3)\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.
diff --git a/docs/libcurl/opts/CURLSHOPT_LOCKFUNC.3 b/docs/libcurl/opts/CURLSHOPT_LOCKFUNC.3
new file mode 100644
index 000000000..c58d28a1c
--- /dev/null
+++ b/docs/libcurl/opts/CURLSHOPT_LOCKFUNC.3
@@ -0,0 +1,70 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2021, 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.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 CURLSHOPT_LOCKFUNC 3 "8 Aug 2003" "libcurl 7.10.7" "libcurl Manual"
+.SH NAME
+CURLSHOPT_LOCKFUNC - mutex lock callback
+.SH SYNOPSIS
+.nf
+#include <curl/curl.h>
+
+void lockcb(CURL *handle, curl_lock_data data, curl_lock_access access,
+            void *userptr);
+
+CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_LOCKFUNC, lockcb);
+.fi
+.SH DESCRIPTION
+Set a mutex lock callback for the share object, to allow it to get used by
+multiple threads concurrently. There's a corresponding
+\fICURLSHOPT_UNLOCKFUNC(3)\fP callback called when the mutex is again relased.
+
+The \fIlockcb\fP argument must be a pointer to a function matching the
+prototype shown above. The arguments to the callback are:
+
+\fIhandle\fP is the currently active easy handle in use when the share object
+is intended to get used.
+
+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 private pointer you set with \fICURLSHOPT_USERDATA\fP.
+This pointer is not used by libcurl itself.
+.SH PROTOCOLS
+All
+.SH EXAMPLE
+.nf
+  CURLSHcode sh
+  share = curl_share_init();
+  sh = curl_share_setopt(share, CURLSHOPT_LOCKFUNC, mutex_lock);
+  if(sh)
+    printf("Error: %s\\n", curl_share_strerror(sh));
+.fi
+.SH AVAILABILITY
+Added in 7.10
+.SH RETURN VALUE
+CURLSHE_OK (zero) means that the option was set properly, non-zero means an
+error occurred. See \fIlibcurl-errors(3)\fP for the full list with
+descriptions.
+.SH "SEE ALSO"
+.BR CURLSHOPT_UNLOCKFUNC "(3), "
+.BR curl_share_setopt "(3), " curl_share_cleanup "(3), " curl_share_init "(3)"
diff --git a/docs/libcurl/opts/CURLSHOPT_SHARE.3 b/docs/libcurl/opts/CURLSHOPT_SHARE.3
new file mode 100644
index 000000000..5e5cc3524
--- /dev/null
+++ b/docs/libcurl/opts/CURLSHOPT_SHARE.3
@@ -0,0 +1,97 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2021, 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.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 CURLSHOPT_SHARE 3 "8 Aug 2003" "libcurl 7.10.7" "libcurl Manual"
+.SH NAME
+CURLSHOPT_SHARE - add data to share
+.SH SYNOPSIS
+.nf
+#include <curl/curl.h>
+
+CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_SHARE, long type);
+.fi
+.SH DESCRIPTION
+The \fItype\fP parameter specifies what specific data that should be shared
+and kept in the share object that was created with \fIcurl_share_init(3)\fP.
+The given \fItype\fP must be be one of the values described below. You can set
+\fICURLSHOPT_SHARE(3)\fP multiple times with different data arguments to have
+the share object share multiple types of data. Unset a type again by setting
+\fICURLSHOPT_UNSHARE(3)\fP.
+.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.
+
+Note that due to a known bug, it is not safe to share connections this way
+between multiple concurrent threads.
+
+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.
+
+Added in 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.
+.SH PROTOCOLS
+All
+.SH EXAMPLE
+.nf
+  CURLSHcode sh
+  share = curl_share_init();
+  sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE);
+  if(sh)
+    printf("Error: %s\\n", curl_share_strerror(sh));
+.fi
+.SH AVAILABILITY
+Added in 7.10
+.SH RETURN VALUE
+CURLSHE_OK (zero) means that the option was set properly, non-zero means an
+error occurred. See \fIlibcurl-errors(3)\fP for the full list with
+descriptions.
+.SH "SEE ALSO"
+.BR CURLSHOPT_UNSHARE "(3), "
+.BR curl_share_setopt "(3), " curl_share_cleanup "(3), " curl_share_init "(3)"
diff --git a/docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.3 b/docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.3
new file mode 100644
index 000000000..586cb4a2e
--- /dev/null
+++ b/docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.3
@@ -0,0 +1,69 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2021, 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.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 CURLSHOPT_UNLOCKFUNC 3 "8 Aug 2003" "libcurl 7.10.7" "libcurl Manual"
+.SH NAME
+CURLSHOPT_UNLOCKFUNC - mutex unlock callback
+.SH SYNOPSIS
+.nf
+#include <curl/curl.h>
+
+void unlockcb(CURL *handle, curl_lock_data data, curl_lock_access access,
+              void *userptr);
+
+CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_UNLOCKFUNC, unlockcb);
+.fi
+.SH DESCRIPTION
+Set a mutex unlock callback for the share object. There's a corresponding
+\fICURLSHOPT_LOCKFUNC(3)\fP callback called when the mutex is first locked.
+
+The \fIunlockcb\fP argument must be a pointer to a function matching the
+prototype shown above. The arguments to the callback are:
+
+\fIhandle\fP is the currently active easy handle in use when the share object
+is released.
+
+The \fIdata\fP argument tells what kind of data libcurl wants to unlock. 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 private pointer you set with \fICURLSHOPT_USERDATA\fP.
+This pointer is not used by libcurl itself.
+.SH PROTOCOLS
+All
+.SH EXAMPLE
+.nf
+  CURLSHcode sh
+  share = curl_share_init();
+  sh = curl_share_setopt(share, CURLSHOPT_UNLOCKFUNC, mutex_unlock);
+  if(sh)
+    printf("Error: %s\\n", curl_share_strerror(sh));
+.fi
+.SH AVAILABILITY
+Added in 7.10
+.SH RETURN VALUE
+CURLSHE_OK (zero) means that the option was set properly, non-zero means an
+error occurred. See \fIlibcurl-errors(3)\fP for the full list with
+descriptions.
+.SH "SEE ALSO"
+.BR CURLSHOPT_LOCKFUNC "(3), "
+.BR curl_share_setopt "(3), " curl_share_cleanup "(3), " curl_share_init "(3)"
diff --git a/docs/libcurl/opts/CURLSHOPT_UNSHARE.3 b/docs/libcurl/opts/CURLSHOPT_UNSHARE.3
new file mode 100644
index 000000000..1f9accc3c
--- /dev/null
+++ b/docs/libcurl/opts/CURLSHOPT_UNSHARE.3
@@ -0,0 +1,70 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2021, 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.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 CURLSHOPT_UNSHARE 3 "8 Aug 2003" "libcurl 7.10.7" "libcurl Manual"
+.SH NAME
+CURLSHOPT_UNSHARE - remove data to share
+.SH SYNOPSIS
+.nf
+#include <curl/curl.h>
+
+CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_UNSHARE, long type);
+.fi
+.SH DESCRIPTION
+The \fItype\fP parameter specifies what specific data that should no longer be
+shared and kept in the share object that was created with
+\fIcurl_share_init(3)\fP. In other words, stop sharing that data in this
+shared object. The given \fItype\fP must be be one of the values described
+below. You can set \fICURLSHOPT_UNSHARE(3)\fP multiple times with different
+data arguments to remove multiple types from the shared object. Add data to
+share again with \fICURLSHOPT_SHARE(3)\fP.
+.IP CURL_LOCK_DATA_COOKIE
+Cookie data will no longer be shared across the easy handles using this shared
+object.
+.IP CURL_LOCK_DATA_DNS
+Cached DNS hosts will be no longer be shared across the easy handles using
+this shared object.
+.IP CURL_LOCK_DATA_SSL_SESSION
+SSL session IDs will no longer be shared across the easy handles using this
+shared object.
+.IP CURL_LOCK_DATA_CONNECT
+The connection cache is no longer shared.
+.IP CURL_LOCK_DATA_PSL
+The Public Suffix List is no longer shared.
+.SH PROTOCOLS
+All
+.SH EXAMPLE
+.nf
+  CURLSHcode sh
+  share = curl_share_init();
+  sh = curl_share_setopt(share, CURLSHOPT_UNSHARE, CURL_LOCK_DATA_COOKIE);
+  if(sh)
+    printf("Error: %s\\n", curl_share_strerror(sh));
+.fi
+.SH AVAILABILITY
+Added in 7.10
+.SH RETURN VALUE
+CURLSHE_OK (zero) means that the option was set properly, non-zero means an
+error occurred. See \fIlibcurl-errors(3)\fP for the full list with
+descriptions.
+.SH "SEE ALSO"
+.BR CURLSHOPT_SHARE "(3), "
+.BR curl_share_setopt "(3), " curl_share_cleanup "(3), " curl_share_init "(3)"
diff --git a/docs/libcurl/opts/CURLSHOPT_USERDATA.3 b/docs/libcurl/opts/CURLSHOPT_USERDATA.3
new file mode 100644
index 000000000..21ce2706b
--- /dev/null
+++ b/docs/libcurl/opts/CURLSHOPT_USERDATA.3
@@ -0,0 +1,54 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2021, 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.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 CURLSHOPT_USERDATA 3 "8 Aug 2003" "libcurl 7.10.7" "libcurl Manual"
+.SH NAME
+CURLSHOPT_USERDATA - pointer passed to the (un)lock mutex callbacks
+.SH SYNOPSIS
+.nf
+#include <curl/curl.h>
+
+CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_USERDATA, void *ptr);
+.fi
+.SH DESCRIPTION
+The \fIptr\fP parameter is held verbatim by libcurl and is passed on as the
+\fIuserptr\fP argument to the callbacks set with \fICURLSHOPT_LOCKFUNC(3)\fP
+and \fICURLSHOPT_LOCKFUNC(3)\fP.
+.SH PROTOCOLS
+All
+.SH EXAMPLE
+.nf
+  CURLSHcode sh
+  struct secrets private_stuff;
+  share = curl_share_init();
+  sh = curl_share_setopt(share, CURLSHOPT_USERDATA, &private_stuff);
+  if(sh)
+    printf("Error: %s\\n", curl_share_strerror(sh));
+.fi
+.SH AVAILABILITY
+Added in 7.10
+.SH RETURN VALUE
+CURLSHE_OK (zero) means that the option was set properly, non-zero means an
+error occurred. See \fIlibcurl-errors(3)\fP for the full list with
+descriptions.
+.SH "SEE ALSO"
+.BR CURLSHOPT_LOCKFUNC "(3), "
+.BR curl_share_setopt "(3), " curl_share_cleanup "(3), " curl_share_init "(3)"
diff --git a/docs/libcurl/opts/Makefile.inc b/docs/libcurl/opts/Makefile.inc
index 55a0a3b7c..6b153c13f 100644
--- a/docs/libcurl/opts/Makefile.inc
+++ b/docs/libcurl/opts/Makefile.inc
@@ -399,4 +399,9 @@ man_MANS =                                      \
   CURLOPT_WRITEFUNCTION.3                       \
   CURLOPT_XFERINFODATA.3                        \
   CURLOPT_XFERINFOFUNCTION.3                    \
-  CURLOPT_XOAUTH2_BEARER.3
+  CURLOPT_XOAUTH2_BEARER.3                      \
+  CURLSHOPT_LOCKFUNC.3                          \
+  CURLSHOPT_SHARE.3                             \
+  CURLSHOPT_UNLOCKFUNC.3                        \
+  CURLSHOPT_UNSHARE.3                           \
+  CURLSHOPT_USERDATA.3