mirror/curl
2
0
Fork 0
mirror of https://github.com/curl/curl.git synced 2025-03-01 15:15:34 +08:00
Code Issues Packages Projects Releases Wiki Activity

opt-docs: verify man page sections + order

Browse Source 
In every libcurl option man page there are now 8 mandatory sections that
must use the right name in the correct order and test 1173 verifies
this. Only 14 man pages needed adjustments.

The sections and the order is as follows:

 - NAME
 - SYNOPSIS
 - DESCRIPTION
 - PROTOCOLS
 - EXAMPLE
 - AVAILABILITY
 - RETURN VALUE
 - SEE ALSO

Reviewed-by: Daniel Gustafsson
Closes #7656
This commit is contained in:
Daniel Stenberg 2021-09-01 10:26:36 +02:00
parent 1731a77989
commit 12a2ed970f
No known key found for this signature in database
GPG Key ID: 5CC908FDB71E12C2
16 changed files with 149 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.3
View File

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * 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
@ -28,26 +28,27 @@ CURLOPT_ABSTRACT_UNIX_SOCKET \- set an abstract Unix domain socket
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ABSTRACT_UNIX_SOCKET, char *path);
.SH DESCRIPTION
Enables the use of an abstract Unix domain socket instead of establishing a TCP
connection to a host. The parameter should be a char * to a null-terminated string
holding the path of the socket. The path will be set to \fIpath\fP prefixed by a
NULL byte (this is the convention for abstract sockets, however it should be stressed
that the path passed to this function should not contain a leading NULL).
Enables the use of an abstract Unix domain socket instead of establishing a
TCP connection to a host. The parameter should be a char * to a
null-terminated string holding the path of the socket. The path will be set to
\fIpath\fP prefixed by a NULL byte (this is the convention for abstract
sockets, however it should be stressed that the path passed to this function
should not contain a leading NULL).
On non-supporting platforms, the abstract address will be interpreted as an empty
string and fail gracefully, generating a run-time error.
This option shares the same semantics as
.BR CURLOPT_UNIX_SOCKET_PATH "(3)
in which documentation more details can be found. Internally, these two options share
the same storage and therefore only one of them can be set per handle.
On non-supporting platforms, the abstract address will be interpreted as an
empty string and fail gracefully, generating a run-time error.
This option shares the same semantics as \fICURLOPT_UNIX_SOCKET_PATH(3)\fP in
which documentation more details can be found. Internally, these two options
share the same storage and therefore only one of them can be set per handle.
.SH DEFAULT
Default is NULL.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
curl_easy_setopt(curl_handle, CURLOPT_ABSTRACT_UNIX_SOCKET, "/tmp/foo.sock");
curl_easy_setopt(curl_handle, CURLOPT_URL, "http://localhost/");
curl_easy_setopt(curl_handle, CURLOPT_ABSTRACT_UNIX_SOCKET, "/tmp/foo.sock");
curl_easy_setopt(curl_handle, CURLOPT_URL, "http://localhost/");
.fi
.SH AVAILABILITY

7
docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.3
View File

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * 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
@ -40,6 +40,8 @@ Eyeballs RFC 6555 says "It is RECOMMENDED that connection attempts be paced
currently defaults to 200 ms. Firefox and Chrome currently default to 300 ms.
.SH DEFAULT
CURL_HET_DEFAULT (currently defined as 200L)
.SH PROTOCOLS
All except FILE
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
@ -57,3 +59,6 @@ if(curl) {
Added in 7.59.0
.SH RETURN VALUE
Returns CURLE_OK
.SH SEE ALSO
.BR CURLOPT_CONNECTTIMEOUT_MS "(3), "
.BR CURLOPT_TIMEOUT "(3), " CURLOPT_LOW_SPEED_LIMIT "(3), "

4
docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.3
View File

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * 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
@ -55,3 +55,5 @@ if(curl) {
Along with HTTP. Added in 7.60.0.
.SH RETURN VALUE
Returns CURLE_OK if HTTP is enabled, and CURLE_UNKNOWN_OPTION if not.
.SH SEE ALSO
.BR CURLOPT_PROXY "(3), "

4
docs/libcurl/opts/CURLOPT_HEADER.3
View File

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * 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
@ -62,6 +62,8 @@ if(curl) {
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Provided in all libcurl versions.
.SH RETURN VALUE
Returns CURLE_OK.
.SH "SEE ALSO"

10
docs/libcurl/opts/CURLOPT_MIMEPOST.3
View File

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * 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
@ -40,13 +40,13 @@ This option is the preferred way of posting an HTTP form, replacing and
extending the deprecated \fICURLOPT_HTTPPOST(3)\fP option.
.SH PROTOCOLS
HTTP, SMTP, IMAP.
.SH AVAILABILITY
Since 7.56.0.
.SH RETURN VALUE
This will return CURLE_OK.
.SH EXAMPLE
Using this option implies the use of several mime structure building
functions: see https://curl.se/libcurl/c/smtp-mime.html for a complete
example.
.SH AVAILABILITY
Since 7.56.0.
.SH RETURN VALUE
This will return CURLE_OK.
.SH "SEE ALSO"
.BR curl_mime_init "(3)"

4
docs/libcurl/opts/CURLOPT_NOSIGNAL.3
View File

@ -49,6 +49,8 @@ cases when they may still happen, contrary to our desire. In addition, using
raised.
.SH DEFAULT
0
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
@ -66,3 +68,5 @@ if(curl) {
Added in 7.10
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH SEE ALSO
.BR CURLOPT_TIMEOUT "(3), "

6
docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.3
View File

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * 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
@ -67,8 +67,6 @@ could be a privacy violation and unexpected.
0
.SH PROTOCOLS
All TLS-based protocols
.SH AVAILABLE
Added in 7.52.0
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
@ -82,6 +80,8 @@ if(curl) {
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.52.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"

4
docs/libcurl/opts/CURLOPT_SSL_FALSESTART.3
View File

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * 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
@ -53,3 +53,5 @@ Secure Transport (on iOS 7.0 or later, or OS X 10.9 or later) TLS backends.
.SH RETURN VALUE
Returns CURLE_OK if false start is supported by the SSL backend, otherwise
returns CURLE_NOT_BUILT_IN.
.SH SEE ALSO
.BR CURLOPT_TCP_FASTOPEN "(3), "

4
docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.3
View File

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * 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
@ -52,3 +52,5 @@ El Capitan.
.SH RETURN VALUE
Returns CURLE_OK if fast open is supported by the operating system, otherwise
returns CURLE_NOT_BUILT_IN.
.SH SEE ALSO
.BR CURLOPT_SSL_FALSESTART "(3), "

4
docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.3
View File

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2016, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * 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
@ -69,3 +69,5 @@ if(curl) {
Added in 7.48.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH SEE ALSO
.BR CURLOPT_TFTP_BLKSIZE "(3), "

6
docs/libcurl/opts/CURLOPT_TRAILERDATA.3
View File

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * 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
@ -27,7 +27,7 @@ CURLOPT_TRAILERDATA \- Custom pointer passed to the trailing headers callback
#include <curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TRAILERDATA, void *userdata);
.SH DESCRIPTION:
.SH DESCRIPTION
Data pointer to be passed to the HTTP trailer callback function.
.SH DEFAULT
NULL
@ -45,5 +45,7 @@ curl_easy_setopt(hndl, CURLOPT_TRAILERDATA, &data);
A more complete example can be found in examples/http_trailers.html
.SH AVAILABILITY
This option was added in curl 7.64.0 and is present if HTTP support is enabled
.SH RETURN VALUE
Returns CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_TRAILERFUNCTION "(3), "

4
docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.3
View File

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * 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
@ -97,5 +97,7 @@ if(curl) {
}
.SH AVAILABILITY
This option was added in curl 7.64.0 and is present if HTTP support is enabled
.SH RETURN VALUE
Returns CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_TRAILERDATA "(3), "

30
docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.3
View File

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * 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
@ -40,12 +40,10 @@ curl does not need to resolve the DNS hostname in the URL.
The maximum path length on Cygwin, Linux and Solaris is 107. On other platforms
it might be even less.
Proxy and TCP options such as
.BR CURLOPT_TCP_NODELAY "(3)
are not supported. Proxy options such as
.BR CURLOPT_PROXY "(3)
have no effect either as these are TCP-oriented, and asking a proxy server to
connect to a certain Unix domain socket is not possible.
Proxy and TCP options such as \fICURLOPT_TCP_NODELAY(3)\fP are not
supported. Proxy options such as \fICURLOPT_PROXY(3)\fP have no effect either
as these are TCP-oriented, and asking a proxy server to connect to a certain
Unix domain socket is not possible.
The application does not have to keep the string around after setting this
option.
@ -59,19 +57,19 @@ Given that you have an nginx server running, listening on /tmp/nginx.sock, you
can request an HTTP resource with:
.nf
curl_easy_setopt(curl_handle, CURLOPT_UNIX_SOCKET_PATH, "/tmp/nginx.sock");
curl_easy_setopt(curl_handle, CURLOPT_URL, "http://localhost/");
curl_easy_setopt(curl_handle, CURLOPT_UNIX_SOCKET_PATH, "/tmp/nginx.sock");
curl_easy_setopt(curl_handle, CURLOPT_URL, "http://localhost/");
.fi
If you are on Linux and somehow have a need for paths larger than 107 bytes, you
could use the proc filesystem to bypass the limitation:
If you are on Linux and somehow have a need for paths larger than 107 bytes,
you could use the proc filesystem to bypass the limitation:
.nf
int dirfd = open(long_directory_path_to_socket, O_DIRECTORY | O_RDONLY);
char path[108];
snprintf(path, sizeof(path), "/proc/self/fd/%d/nginx.sock", dirfd);
curl_easy_setopt(curl_handle, CURLOPT_UNIX_SOCKET_PATH, path);
/* Be sure to keep dirfd valid until you discard the handle */
int dirfd = open(long_directory_path_to_socket, O_DIRECTORY | O_RDONLY);
char path[108];
snprintf(path, sizeof(path), "/proc/self/fd/%d/nginx.sock", dirfd);
curl_easy_setopt(curl_handle, CURLOPT_UNIX_SOCKET_PATH, path);
/* Be sure to keep dirfd valid until you discard the handle */
.fi
.SH AVAILABILITY
Since 7.40.0.

7
docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.3
View File

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * 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
@ -42,6 +42,8 @@ is called, an HTTP/2 PING frame is sent on the connection.
.SH DEFAULT
CURL_UPKEEP_INTERVAL_DEFAULT (currently defined as 60000L, which is 60 seconds)
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
@ -71,3 +73,6 @@ if(curl) {
Added in 7.62.0
.SH RETURN VALUE
Returns CURLE_OK
.SH SEE ALSO
.BR CURLOPT_TCP_KEEPALIVE "(3), "

10
docs/libcurl/opts/CURLOPT_WRITEFUNCTION.3
View File

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * 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
@ -74,10 +74,6 @@ do that.
libcurl will use 'fwrite' as a callback by default.
.SH PROTOCOLS
For all protocols
.SH AVAILABILITY
Support for the CURL_WRITEFUNC_PAUSE return code was added in version 7.18.0.
.SH RETURN VALUE
This will return CURLE_OK.
.SH EXAMPLE
.nf
struct memory {
@ -110,6 +106,10 @@ This will return CURLE_OK.
/* we pass our 'chunk' struct to the callback function */
curl_easy_setopt(curl_handle, CURLOPT_WRITEDATA, (void *)&chunk);
.fi
.SH AVAILABILITY
Support for the CURL_WRITEFUNC_PAUSE return code was added in version 7.18.0.
.SH RETURN VALUE
This will return CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_WRITEDATA "(3), " CURLOPT_READFUNCTION "(3), "
.BR CURLOPT_HEADERFUNCTION "(3), "

73
tests/manpage-syntax.pl
View File

@ -32,11 +32,27 @@ use warnings;
my @manpages=@ARGV;
my $errors = 0;
my %blessed;
my @order = (
'NAME',
'SYNOPSIS',
'DESCRIPTION',
#'DEFAULT', # CURLINFO_ has no default
'PROTOCOLS',
'EXAMPLE',
'AVAILABILITY',
'RETURN VALUE',
'SEE ALSO'
);
my %shline; # section => line number
sub scanmanpage {
my ($file) = @_;
my $reqex = 0;
my $inex = 0;
my $exsize = 0;
my $shc = 0;
my @sh;
print "Check $file\n";
open(M, "<$file") || die "no such file: $file";
@ -46,15 +62,22 @@ sub scanmanpage {
}
my $line = 1;
while(<M>) {
if($_ =~ /^.SH EXAMPLE/) {
if($_ =~ /^.SH EXAMPLE/i) {
$inex = 1;
}
elsif($_ =~ /^.SH/) {
elsif($_ =~ /^.SH/i) {
$inex = 0;
}
elsif($inex) {
$exsize++;
}
if($_ =~ /^.SH (.*)/i) {
my $n = $1;
# remove enclosing quotes
$n =~ s/\"(.*)\"\z/$1/;
push @sh, $n;
$shline{$n} = $line;
}
if($_ =~ /^\'/) {
print STDERR "$file:$line line starts with single quote!\n";
@ -75,12 +98,52 @@ sub scanmanpage {
}
close(M);
if($reqex && ($exsize < 2)) {
print STDERR "$file:$line missing EXAMPLE section\n";
$errors++;
if($reqex) {
# only for libcurl options man-pages
if($exsize < 2) {
print STDERR "$file:$line missing EXAMPLE section\n";
$errors++;
}
my $got;
my $i = 0;
my $shused = 1;
do {
$got = shift(@sh);
if($got) {
$i = $blessed{$got};
}
if($i && $got) {
# mandatory section
if($i != $shused) {
printf STDERR "$file:%u Got $got, when %s was expected\n",
$shline{$got},
$order[$shused-1];
$errors++;
return;
}
$shused++;
if($i == 9) {
# last mandatory one, exit
$got="";
}
}
} while($got);
if($i != 8) {
printf STDERR "$file:$line missing mandatory section: %s\n",
$order[$i];
$errors++;
}
}
}
my $ind = 1;
for my $s (@order) {
$blessed{$s} = $ind++
}
for my $m (@manpages) {
scanmanpage($m);