From ad1dfc594f886bbf8f0ba9fd160ae38698f15e3c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 24 Nov 2023 17:52:15 +0100 Subject: [PATCH] docs/libcurl: SYNSOPSIS cleanup - use the correct include file - make sure they are declared as in the header file - fix minor nroff syntax mistakes (missing .fi) These are verified by verify-synopsis.pl, which extracts the SYNPOSIS code and runs it through gcc. Closes #12402 --- .github/scripts/spellcheck.words | 1 + docs/libcurl/curl_easy_header.3 | 1 + docs/libcurl/curl_easy_option_next.3 | 36 +++++++++++---------- docs/libcurl/curl_easy_recv.3 | 2 +- docs/libcurl/curl_easy_send.3 | 2 +- docs/libcurl/curl_formget.3 | 3 +- docs/libcurl/curl_getdate.3 | 2 +- docs/libcurl/curl_global_sslset.3 | 48 +++++++++++++++------------- docs/libcurl/curl_multi_fdset.3 | 2 +- docs/libcurl/curl_multi_poll.3 | 2 +- docs/libcurl/curl_multi_setopt.3 | 12 +++---- docs/libcurl/curl_multi_strerror.3 | 1 + docs/libcurl/curl_multi_wait.3 | 2 +- docs/libcurl/curl_share_strerror.3 | 1 + docs/libcurl/curl_strequal.3 | 4 +-- docs/libcurl/curl_url_dup.3 | 2 +- docs/libcurl/curl_url_get.3 | 2 +- docs/libcurl/curl_url_strerror.3 | 1 + docs/libcurl/curl_ws_meta.3 | 19 +++++------ docs/libcurl/curl_ws_recv.3 | 2 +- docs/libcurl/curl_ws_send.3 | 2 +- 21 files changed, 79 insertions(+), 68 deletions(-) diff --git a/.github/scripts/spellcheck.words b/.github/scripts/spellcheck.words index 8856afc314..4bee9bf600 100644 --- a/.github/scripts/spellcheck.words +++ b/.github/scripts/spellcheck.words @@ -898,6 +898,7 @@ winssl Wireshark wolfSSH wolfSSL +ws WS WSS www diff --git a/docs/libcurl/curl_easy_header.3 b/docs/libcurl/curl_easy_header.3 index 3aa62649e4..4898180ed1 100644 --- a/docs/libcurl/curl_easy_header.3 +++ b/docs/libcurl/curl_easy_header.3 @@ -34,6 +34,7 @@ CURLHcode curl_easy_header(CURL *easy, unsigned int origin, int request, struct curl_header **hout); +.fi .SH DESCRIPTION \fIcurl_easy_header(3)\fP returns a pointer to a "curl_header" struct in \fBhout\fP with data for the HTTP response header \fIname\fP. The case diff --git a/docs/libcurl/curl_easy_option_next.3 b/docs/libcurl/curl_easy_option_next.3 index 48dba678b2..2f636451fd 100644 --- a/docs/libcurl/curl_easy_option_next.3 +++ b/docs/libcurl/curl_easy_option_next.3 @@ -28,6 +28,25 @@ curl_easy_option_next - iterate over easy setopt options .nf #include +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 \fIcurl_easyoption\fP +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 struct +.nf typedef enum { CURLOT_LONG, /* long (a range of values) */ CURLOT_VALUES, /* (a defined set or bitmask) */ @@ -48,24 +67,7 @@ struct curl_easyoption { 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 \fIcurl_easyoption\fP -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 EXAMPLE .nf /* iterate over all available options */ diff --git a/docs/libcurl/curl_easy_recv.3 b/docs/libcurl/curl_easy_recv.3 index c215a544f5..3d724696f9 100644 --- a/docs/libcurl/curl_easy_recv.3 +++ b/docs/libcurl/curl_easy_recv.3 @@ -27,7 +27,7 @@ curl_easy_recv - receives raw data on an "easy" connection .SH SYNOPSIS .nf -#include +#include CURLcode curl_easy_recv(CURL *curl, void *buffer, size_t buflen, size_t *n); .fi diff --git a/docs/libcurl/curl_easy_send.3 b/docs/libcurl/curl_easy_send.3 index 4da5a2387c..95fdc0779c 100644 --- a/docs/libcurl/curl_easy_send.3 +++ b/docs/libcurl/curl_easy_send.3 @@ -27,7 +27,7 @@ curl_easy_send - sends raw data over an "easy" connection .SH SYNOPSIS .nf -#include +#include CURLcode curl_easy_send(CURL *curl, const void *buffer, size_t buflen, size_t *n); diff --git a/docs/libcurl/curl_formget.3 b/docs/libcurl/curl_formget.3 index 89bf84dacd..cd6b76926b 100644 --- a/docs/libcurl/curl_formget.3 +++ b/docs/libcurl/curl_formget.3 @@ -29,7 +29,8 @@ curl_formget - serialize a previously built multipart form POST chain #include int curl_formget(struct curl_httppost * form, void *userp, - curl_formget_callback append ); + curl_formget_callback append); +.fi .SH DESCRIPTION curl_formget() is used to serialize data previously built/appended with \fIcurl_formadd(3)\fP. Accepts a void pointer as second argument named diff --git a/docs/libcurl/curl_getdate.3 b/docs/libcurl/curl_getdate.3 index cd2cd63925..b4c07e8c95 100644 --- a/docs/libcurl/curl_getdate.3 +++ b/docs/libcurl/curl_getdate.3 @@ -28,7 +28,7 @@ curl_getdate - Convert a date string to number of seconds .nf #include -time_t curl_getdate(char *datestring, time_t *now); +time_t curl_getdate(const char *datestring, const time_t *now); .fi .SH DESCRIPTION \fIcurl_getdate(3)\fP returns the number of seconds since the Epoch, January diff --git a/docs/libcurl/curl_global_sslset.3 b/docs/libcurl/curl_global_sslset.3 index e1d5bdfb42..e9fd54b227 100644 --- a/docs/libcurl/curl_global_sslset.3 +++ b/docs/libcurl/curl_global_sslset.3 @@ -28,31 +28,9 @@ curl_global_sslset - Select SSL backend to use with libcurl .nf #include -typedef struct { - curl_sslbackend id; - const char *name; -} curl_ssl_backend; - -typedef enum { - CURLSSLBACKEND_NONE = 0, - CURLSSLBACKEND_OPENSSL = 1, /* or one of its forks */ - CURLSSLBACKEND_GNUTLS = 2, - CURLSSLBACKEND_NSS = 3, - CURLSSLBACKEND_GSKIT = 5, /* deprecated */ - CURLSSLBACKEND_POLARSSL = 6, /* deprecated */ - CURLSSLBACKEND_WOLFSSL = 7, - CURLSSLBACKEND_SCHANNEL = 8, - CURLSSLBACKEND_SECURETRANSPORT = 9, - CURLSSLBACKEND_AXTLS = 10, /* deprecated */ - CURLSSLBACKEND_MBEDTLS = 11, - CURLSSLBACKEND_MESALINK = 12, /* deprecated */ - CURLSSLBACKEND_BEARSSL = 13, - CURLSSLBACKEND_RUSTLS = 14 -} curl_sslbackend; - CURLsslset curl_global_sslset(curl_sslbackend id, const char *name, - curl_ssl_backend ***avail); + const curl_ssl_backend ***avail); .fi .SH DESCRIPTION This function configures at runtime which SSL backend to use with @@ -99,6 +77,30 @@ provide the same API. \fIcurl_version_info(3)\fP can return more specific info about the exact OpenSSL flavor and version number is use. +.SH struct +.nf +typedef struct { + curl_sslbackend id; + const char *name; +} curl_ssl_backend; + +typedef enum { + CURLSSLBACKEND_NONE = 0, + CURLSSLBACKEND_OPENSSL = 1, /* or one of its forks */ + CURLSSLBACKEND_GNUTLS = 2, + CURLSSLBACKEND_NSS = 3, + CURLSSLBACKEND_GSKIT = 5, /* deprecated */ + CURLSSLBACKEND_POLARSSL = 6, /* deprecated */ + CURLSSLBACKEND_WOLFSSL = 7, + CURLSSLBACKEND_SCHANNEL = 8, + CURLSSLBACKEND_SECURETRANSPORT = 9, + CURLSSLBACKEND_AXTLS = 10, /* deprecated */ + CURLSSLBACKEND_MBEDTLS = 11, + CURLSSLBACKEND_MESALINK = 12, /* deprecated */ + CURLSSLBACKEND_BEARSSL = 13, + CURLSSLBACKEND_RUSTLS = 14 +} curl_sslbackend; +.fi .SH EXAMPLE .nf /* choose a specific backend */ diff --git a/docs/libcurl/curl_multi_fdset.3 b/docs/libcurl/curl_multi_fdset.3 index dbcb5b2b50..d569b84e92 100644 --- a/docs/libcurl/curl_multi_fdset.3 +++ b/docs/libcurl/curl_multi_fdset.3 @@ -33,7 +33,7 @@ CURLMcode curl_multi_fdset(CURLM *multi_handle, fd_set *write_fd_set, fd_set *exc_fd_set, int *max_fd); -.ad +.fi .SH DESCRIPTION This function extracts file descriptor information from a given multi_handle. libcurl returns its \fIfd_set\fP sets. The application can use these to diff --git a/docs/libcurl/curl_multi_poll.3 b/docs/libcurl/curl_multi_poll.3 index c70912316e..8ea7bd1024 100644 --- a/docs/libcurl/curl_multi_poll.3 +++ b/docs/libcurl/curl_multi_poll.3 @@ -33,7 +33,7 @@ CURLMcode curl_multi_poll(CURLM *multi_handle, unsigned int extra_nfds, int timeout_ms, int *numfds); -.ad +.fi .SH DESCRIPTION \fIcurl_multi_poll(3)\fP polls all file descriptors used by the curl easy handles contained in the given multi handle set. It blocks until activity is diff --git a/docs/libcurl/curl_multi_setopt.3 b/docs/libcurl/curl_multi_setopt.3 index f097653559..38e170656a 100644 --- a/docs/libcurl/curl_multi_setopt.3 +++ b/docs/libcurl/curl_multi_setopt.3 @@ -28,17 +28,17 @@ curl_multi_setopt \- set options for a curl multi handle .nf #include -CURLMcode curl_multi_setopt(CURLM *multi_handle, CURLMoption option, param); +CURLMcode curl_multi_setopt(CURLM *multi_handle, CURLMoption option, parameter); .fi .SH DESCRIPTION \fIcurl_multi_setopt(3)\fP is used to tell a libcurl multi handle how to behave. By using the appropriate options to \fIcurl_multi_setopt(3)\fP, you can change libcurl's behavior when using that multi handle. All options are -set with the \fIoption\fP followed by the parameter \fIparam\fP. That -parameter can be a \fBlong\fP, a \fBfunction pointer\fP, an \fBobject -pointer\fP or a \fBcurl_off_t\fP type, depending on what the specific option -expects. Read this manual carefully as bad input values may cause libcurl to -behave badly. You can only set one option in each function call. +set with the \fIoption\fP followed by the \fIparameter\fP. That parameter can +be a \fBlong\fP, a \fBfunction pointer\fP, an \fBobject pointer\fP or a +\fBcurl_off_t\fP type, depending on what the specific option expects. Read +this manual carefully as bad input values may cause libcurl to behave +badly. You can only set one option in each function call. .SH OPTIONS .IP CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE diff --git a/docs/libcurl/curl_multi_strerror.3 b/docs/libcurl/curl_multi_strerror.3 index 99cf166315..11538b0e01 100644 --- a/docs/libcurl/curl_multi_strerror.3 +++ b/docs/libcurl/curl_multi_strerror.3 @@ -29,6 +29,7 @@ curl_multi_strerror - return string describing error code #include const char *curl_multi_strerror(CURLMcode errornum); +.fi .SH DESCRIPTION This function returns a string describing the \fICURLMcode\fP error code passed in the argument \fIerrornum\fP. diff --git a/docs/libcurl/curl_multi_wait.3 b/docs/libcurl/curl_multi_wait.3 index 565fdb8de1..0698bcad73 100644 --- a/docs/libcurl/curl_multi_wait.3 +++ b/docs/libcurl/curl_multi_wait.3 @@ -33,7 +33,7 @@ CURLMcode curl_multi_wait(CURLM *multi_handle, unsigned int extra_nfds, int timeout_ms, int *numfds); -.ad +.fi .SH DESCRIPTION \fIcurl_multi_wait(3)\fP polls all file descriptors used by the curl easy handles contained in the given multi handle set. It blocks until activity is diff --git a/docs/libcurl/curl_share_strerror.3 b/docs/libcurl/curl_share_strerror.3 index a6a7010a39..a8329efa06 100644 --- a/docs/libcurl/curl_share_strerror.3 +++ b/docs/libcurl/curl_share_strerror.3 @@ -29,6 +29,7 @@ curl_share_strerror - return string describing error code #include const char *curl_share_strerror(CURLSHcode errornum); +.fi .SH DESCRIPTION The \fIcurl_share_strerror(3)\fP function returns a string describing the \fICURLSHcode\fP error code passed in the argument \fIerrornum\fP. diff --git a/docs/libcurl/curl_strequal.3 b/docs/libcurl/curl_strequal.3 index c66c6529ae..881b0d70de 100644 --- a/docs/libcurl/curl_strequal.3 +++ b/docs/libcurl/curl_strequal.3 @@ -28,8 +28,8 @@ curl_strequal, curl_strnequal - case insensitive string comparisons .nf #include -int curl_strequal(char *str1, char *str2); -int curl_strnequal(char *str1, char *str2, size_t length); +int curl_strequal(const char *str1, const char *str2); +int curl_strnequal(const char *str1, const char *str2, size_t length); .fi .SH DESCRIPTION The diff --git a/docs/libcurl/curl_url_dup.3 b/docs/libcurl/curl_url_dup.3 index a2e9850b5e..059515e1d0 100644 --- a/docs/libcurl/curl_url_dup.3 +++ b/docs/libcurl/curl_url_dup.3 @@ -28,7 +28,7 @@ curl_url_dup - duplicate a URL handle .nf #include -CURLU *curl_url_dup(CURLU *inhandle); +CURLU *curl_url_dup(const CURLU *inhandle); .fi .SH DESCRIPTION Duplicates the URL object the input \fICURLU\fP \fIinhandle\fP identifies and diff --git a/docs/libcurl/curl_url_get.3 b/docs/libcurl/curl_url_get.3 index 815e5587e4..34c56c3cd7 100644 --- a/docs/libcurl/curl_url_get.3 +++ b/docs/libcurl/curl_url_get.3 @@ -28,7 +28,7 @@ curl_url_get - extract a part from a URL .nf #include -CURLUcode curl_url_get(CURLU *url, +CURLUcode curl_url_get(const CURLU *url, CURLUPart part, char **content, unsigned int flags); diff --git a/docs/libcurl/curl_url_strerror.3 b/docs/libcurl/curl_url_strerror.3 index e7665f24af..382a4049d2 100644 --- a/docs/libcurl/curl_url_strerror.3 +++ b/docs/libcurl/curl_url_strerror.3 @@ -29,6 +29,7 @@ curl_url_strerror - return string describing error code #include const char *curl_url_strerror(CURLUcode errornum); +.fi .SH DESCRIPTION This function returns a string describing the CURLUcode error code passed in the argument \fIerrornum\fP. diff --git a/docs/libcurl/curl_ws_meta.3 b/docs/libcurl/curl_ws_meta.3 index d9ab43a119..04b6759270 100644 --- a/docs/libcurl/curl_ws_meta.3 +++ b/docs/libcurl/curl_ws_meta.3 @@ -27,14 +27,7 @@ curl_ws_meta - meta data WebSocket information .SH SYNOPSIS .nf -#include - -struct curl_ws_frame { - int age; /* zero */ - int flags; /* See the CURLWS_* defines */ - curl_off_t offset; /* the offset of this data into the frame */ - curl_off_t bytesleft; /* number of pending bytes left of the payload */ -}; +#include const struct curl_ws_frame *curl_ws_meta(CURL *curl); .fi @@ -53,7 +46,15 @@ what transfer the question is about, but as there is no such pointer provided to the callback by libcurl itself, applications that want to use \fIcurl_ws_meta(3)\fP need to pass it on to the callback on its own. -.SH "struct fields" +.SH "struct curl_ws_frame" +.nf +struct curl_ws_frame { + int age; + int flags; + curl_off_t offset; + curl_off_t bytesleft; +}; +.fi .IP age This field specify the age of this struct. It is always zero for now. .IP flags diff --git a/docs/libcurl/curl_ws_recv.3 b/docs/libcurl/curl_ws_recv.3 index a9df029e81..dcfcbe5d8d 100644 --- a/docs/libcurl/curl_ws_recv.3 +++ b/docs/libcurl/curl_ws_recv.3 @@ -27,7 +27,7 @@ curl_ws_recv - receive WebSocket data .SH SYNOPSIS .nf -#include +#include CURLcode curl_ws_recv(CURL *curl, void *buffer, size_t buflen, size_t *recv, const struct curl_ws_frame **meta); diff --git a/docs/libcurl/curl_ws_send.3 b/docs/libcurl/curl_ws_send.3 index 9df2cc164f..0dd52fcfe0 100644 --- a/docs/libcurl/curl_ws_send.3 +++ b/docs/libcurl/curl_ws_send.3 @@ -27,7 +27,7 @@ curl_ws_send - send WebSocket data .SH SYNOPSIS .nf -#include +#include CURLcode curl_ws_send(CURL *curl, const void *buffer, size_t buflen, size_t *sent, curl_off_t fragsize,