options: API for meta-data about easy options

 const struct curl_easyoption *curl_easy_option_by_name(const char *name);

 const struct curl_easyoption *curl_easy_option_by_id (CURLoption id);

 const struct curl_easyoption *
 curl_easy_option_next(const struct curl_easyoption *prev);

The purpose is to provide detailed enough information to allow for
example libcurl bindings to get option information at run-time about
what easy options that exist and what arguments they expect.

Assisted-by: Jeroen Ooms
Closes #5365

5 files changed, 186 insertions, 8 deletions

diff --git a/docs/libcurl/Makefile.inc b/docs/libcurl/Makefile.inc
index 332056a19..fb7ea89a9 100644
--- a/docs/libcurl/Makefile.inc
+++ b/docs/libcurl/Makefile.inc
@@ -28,6 +28,9 @@ man_MANS = \
  curl_easy_escape.3 \
  curl_easy_getinfo.3 \
  curl_easy_init.3 \
+ curl_easy_option_by_id.3 \
+ curl_easy_option_by_name.3 \
+ curl_easy_option_next.3 \
  curl_easy_pause.3 \
  curl_easy_perform.3 \
  curl_easy_recv.3 \
diff --git a/docs/libcurl/curl_easy_option_by_id.3 b/docs/libcurl/curl_easy_option_by_id.3
new file mode 100644
index 000000000..e8130faf8
--- /dev/null
+++ b/docs/libcurl/curl_easy_option_by_id.3
@@ -0,0 +1,46 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, 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.haxx.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 curl_easy_option_by_id 3 "15 May 2020" "libcurl 7.71.0" "libcurl Manual"
+.SH NAME
+curl_easy_option_by_id - find an easy setopt option by id
+.SH SYNOPSIS
+.nf
+#include <curl/curl.h>
+
+const struct curl_easyoption *curl_easy_option_by_id(CURLoption id);
+.fi
+.SH DESCRIPTION
+Given a CURLoption \fBid\fP, this function returns a pointer to the
+curl_easyoption struct, holding information about the
+\fIcurl_easy_setopt(3)\fP option using that id. The option id is the CURLOPT_
+prefix ones provided in the standard curl/curl.h header file. This function
+will return the non-aliases version for the cases where there is an alias
+function as well.
+
+If libcurl has no option with the given id, this function returns NULL.
+.SH AVAILABILITY
+This function was added in libcurl 7.71.0
+.SH RETURN VALUE
+A pointer to the curl_easyoption struct for the option or NULL.
+.SH "SEE ALSO"
+.BR curl_easy_option_by_name "(3)," curl_easy_option_next "(3),"
+.BR curl_easy_setopt "(3),"
diff --git a/docs/libcurl/curl_easy_option_by_name.3 b/docs/libcurl/curl_easy_option_by_name.3
new file mode 100644
index 000000000..cc9ce3885
--- /dev/null
+++ b/docs/libcurl/curl_easy_option_by_name.3
@@ -0,0 +1,44 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, 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.haxx.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 curl_easy_option_by_name 3 "15 May 2020" "libcurl 7.71.0" "libcurl Manual"
+.SH NAME
+curl_easy_option_by_name - find an easy setopt option by name
+.SH SYNOPSIS
+.nf
+#include <curl/curl.h>
+
+const struct curl_easyoption *curl_easy_option_by_name(const char *name);
+.fi
+.SH DESCRIPTION
+Given a \fBname\fP, this function returns a pointer to the curl_easyoption
+struct, holding information about the \fIcurl_easy_setopt(3)\fP option using
+that name. The name should be specified without the "CURLOPT_" prefix and the
+name comparison is made case insensitive.
+
+If libcurl has no option with the given name, this function returns NULL.
+.SH AVAILABILITY
+This function was added in libcurl 7.71.0
+.SH RETURN VALUE
+A pointer to the curl_easyoption struct for the option or NULL.
+.SH "SEE ALSO"
+.BR curl_easy_option_next "(3)," curl_easy_option_by_id "(3),"
+.BR curl_easy_setopt "(3),"
diff --git a/docs/libcurl/curl_easy_option_next.3 b/docs/libcurl/curl_easy_option_next.3
new file mode 100644
index 000000000..732e8d7cd
--- /dev/null
+++ b/docs/libcurl/curl_easy_option_next.3
@@ -0,0 +1,74 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2020, 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.haxx.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 curl_easy_option_next 3 "15 May 2020" "libcurl 7.71.0" "libcurl Manual"
+.SH NAME
+curl_easy_option_next - iterate over easy setopt options
+.SH SYNOPSIS
+.nf
+#include <curl/curl.h>
+
+typedef enum {
+  CURLOT_LONG,    /* long (a range of values) */
+  CURLOT_VALUES,  /*      (a defined set or bitmask) */
+  CURLOT_OFF_T,   /* curl_off_t (a range of values) */
+  CURLOT_OBJECT,  /* pointer (void *) */
+  CURLOT_STRING,  /*         (char * to zero terminated buffer) */
+  CURLOT_SLIST,   /*         (struct curl_slist *) */
+  CURLOT_CBPTR,   /*         (void * passed as-is to a callback) */
+  CURLOT_BLOB,    /* blob (struct curl_blob *) */
+  CURLOT_FUNCTION /* function pointer */
+} curl_easytype;
+
+/* The CURLOPTTYPE_* id ranges can still be used to figure out what type/size
+   to use for curl_easy_setopt() for the given id */
+struct curl_easyoption {
+  const char *name;
+  CURLoption id;
+  curl_easytype type;
+  unsigned int flags;
+};
+
+const struct curl_easyoption *
+curl_easy_option_next(const struct curl_easyoption *prev);
+.fi
+.SH DESCRIPTION
+This function returns a pointer to the first or the next curl_easyoption
+struct, providing an ability to iterate over all known options for
+\fIcurl_easy_setopt(3)\fP in this instance of libcurl.
+
+Pass a \fBNULL\fP argument as \fBprev\fP to get the first option returned, or
+pass in the current option to get the next one returned. If there is no more
+option to return, \fIcurl_easy_option_next(3)\fP returns NULL.
+
+The options returned by this functions are the ones known to this libcurl and
+information about what argument type they want.
+
+If the \fBCURLOT_FLAG_ALIAS\fP bit is set in the flags field, it means the
+name is provided for backwards compatibility as an alias.
+.SH AVAILABILITY
+This function was added in libcurl 7.71.0
+.SH RETURN VALUE
+A pointer to the curl_easyoption struct for the next option or NULL if no more
+options.
+.SH "SEE ALSO"
+.BR curl_easy_option_by_name "(3)," curl_easy_option_by_id "(3),"
+.BR curl_easy_setopt "(3),"
diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions
index 0e2faacec..82a8e8b3d 100644
--- a/docs/libcurl/symbols-in-versions
+++ b/docs/libcurl/symbols-in-versions
@@ -352,12 +352,14 @@ CURLM_UNKNOWN_OPTION            7.15.4
 CURLM_WAKEUP_FAILURE            7.68.0
 CURLOPT                         7.69.0
 CURLOPTTYPE_BLOB                7.71.0
+CURLOPTTYPE_CBPOINT             7.73.0
 CURLOPTTYPE_FUNCTIONPOINT       7.1
 CURLOPTTYPE_LONG                7.1
 CURLOPTTYPE_OBJECTPOINT         7.1
 CURLOPTTYPE_OFF_T               7.11.0
 CURLOPTTYPE_SLISTPOINT          7.65.2
 CURLOPTTYPE_STRINGPOINT         7.46.0
+CURLOPTTYPE_VALUES              7.73.0
 CURLOPT_ABSTRACT_UNIX_SOCKET    7.53.0
 CURLOPT_ACCEPTTIMEOUT_MS        7.24.0
 CURLOPT_ACCEPT_ENCODING         7.21.6
@@ -520,8 +522,6 @@ CURLOPT_PROGRESSDATA            7.1
 CURLOPT_PROGRESSFUNCTION        7.1           7.32.0
 CURLOPT_PROTOCOLS               7.19.4
 CURLOPT_PROXY                   7.1
-CURLOPT_PROXY_ISSUERCERT        7.71.0
-CURLOPT_PROXY_ISSUERCERT_BLOB   7.71.0
 CURLOPT_PROXYAUTH               7.10.7
 CURLOPT_PROXYHEADER             7.37.0
 CURLOPT_PROXYPASSWORD           7.19.1
@@ -532,15 +532,17 @@ CURLOPT_PROXYUSERPWD            7.1
 CURLOPT_PROXY_CAINFO            7.52.0
 CURLOPT_PROXY_CAPATH            7.52.0
 CURLOPT_PROXY_CRLFILE           7.52.0
+CURLOPT_PROXY_ISSUERCERT        7.71.0
+CURLOPT_PROXY_ISSUERCERT_BLOB   7.71.0
 CURLOPT_PROXY_KEYPASSWD         7.52.0
 CURLOPT_PROXY_PINNEDPUBLICKEY   7.52.0
 CURLOPT_PROXY_SERVICE_NAME      7.43.0
 CURLOPT_PROXY_SSLCERT           7.52.0
-CURLOPT_PROXY_SSLCERT_BLOB      7.71.0
 CURLOPT_PROXY_SSLCERTTYPE       7.52.0
+CURLOPT_PROXY_SSLCERT_BLOB      7.71.0
 CURLOPT_PROXY_SSLKEY            7.52.0
-CURLOPT_PROXY_SSLKEY_BLOB       7.71.0
 CURLOPT_PROXY_SSLKEYTYPE        7.52.0
+CURLOPT_PROXY_SSLKEY_BLOB       7.71.0
 CURLOPT_PROXY_SSLVERSION        7.52.0
 CURLOPT_PROXY_SSL_CIPHER_LIST   7.52.0
 CURLOPT_PROXY_SSL_OPTIONS       7.52.0
@@ -601,15 +603,15 @@ CURLOPT_SSH_KNOWNHOSTS          7.19.6
 CURLOPT_SSH_PRIVATE_KEYFILE     7.16.1
 CURLOPT_SSH_PUBLIC_KEYFILE      7.16.1
 CURLOPT_SSLCERT                 7.1
-CURLOPT_SSLCERT_BLOB            7.71.0
 CURLOPT_SSLCERTPASSWD           7.1.1         7.17.0
 CURLOPT_SSLCERTTYPE             7.9.3
+CURLOPT_SSLCERT_BLOB            7.71.0
 CURLOPT_SSLENGINE               7.9.3
 CURLOPT_SSLENGINE_DEFAULT       7.9.3
 CURLOPT_SSLKEY                  7.9.3
-CURLOPT_SSLKEY_BLOB             7.71.0
 CURLOPT_SSLKEYPASSWD            7.9.3         7.17.0
 CURLOPT_SSLKEYTYPE              7.9.3
+CURLOPT_SSLKEY_BLOB             7.71.0
 CURLOPT_SSLVERSION              7.1
 CURLOPT_SSL_CIPHER_LIST         7.9
 CURLOPT_SSL_CTX_DATA            7.10.6
@@ -667,6 +669,15 @@ CURLOPT_WRITEINFO               7.1
 CURLOPT_XFERINFODATA            7.32.0
 CURLOPT_XFERINFOFUNCTION        7.32.0
 CURLOPT_XOAUTH2_BEARER          7.33.0
+CURLOT_BLOB                     7.73.0
+CURLOT_CBPTR                    7.73.0
+CURLOT_FUNCTION                 7.73.0
+CURLOT_LONG                     7.73.0
+CURLOT_OBJECT                   7.73.0
+CURLOT_OFF_T                    7.73.0
+CURLOT_SLIST                    7.73.0
+CURLOT_STRING                   7.73.0
+CURLOT_VALUES                   7.73.0
 CURLPAUSE_ALL                   7.18.0
 CURLPAUSE_CONT                  7.18.0
 CURLPAUSE_RECV                  7.18.0
@@ -792,9 +803,9 @@ CURLSSLOPT_ALLOW_BEAST          7.25.0
 CURLSSLOPT_NATIVE_CA            7.71.0
 CURLSSLOPT_NO_PARTIALCHAIN      7.68.0
 CURLSSLOPT_NO_REVOKE            7.44.0
+CURLSSLOPT_REVOKE_BEST_EFFORT   7.70.0
 CURLSSLSET_NO_BACKENDS          7.56.0
 CURLSSLSET_OK                   7.56.0
-CURLSSLOPT_REVOKE_BEST_EFFORT   7.70.0
 CURLSSLSET_TOO_LATE             7.56.0
 CURLSSLSET_UNKNOWN_BACKEND      7.56.0
 CURLUE_BAD_HANDLE               7.62.0
@@ -1007,9 +1018,9 @@ CURL_VERSION_SPNEGO             7.10.8
 CURL_VERSION_SSL                7.10
 CURL_VERSION_SSPI               7.13.2
 CURL_VERSION_TLSAUTH_SRP        7.21.4
+CURL_VERSION_UNICODE            7.72.0
 CURL_VERSION_UNIX_SOCKETS       7.40.0
 CURL_VERSION_ZSTD               7.72.0
-CURL_VERSION_UNICODE            7.72.0
 CURL_WAIT_POLLIN                7.28.0
 CURL_WAIT_POLLOUT               7.28.0
 CURL_WAIT_POLLPRI               7.28.0