romenskiy2012/curl
1
0
Fork 0
mirror of https://github.com/curl/curl.git synced 2026-05-30 06:37:30 +03:00
Code Issues Projects Releases Packages Wiki Activity

opt-docs: make sure all man pages have examples

Browse source 
Extended manpage-syntax.pl (run by test 1173) to check that every man
page for a libcurl option has an EXAMPLE section that is more than two
lines. Then fixed all errors it found and added examples.

Reviewed-by: Daniel Gustafsson
Closes #7656
This commit is contained in:
Daniel Stenberg 2021-09-01 09:23:37 +02:00
parent c8210ef06d
commit 1731a77989
No known key found for this signature in database
GPG key ID: 5CC908FDB71E12C2
11 changed files with 237 additions and 16 deletions
Download patch file Download diff file Expand all files Collapse all files

28
docs/libcurl/opts/CURLOPT_DEBUGDATA.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
@ -36,7 +36,31 @@ NULL
.SH PROTOCOLS
All
.SH EXAMPLE
https://curl.se/libcurl/c/debug.html
.nf
int main(void)
{
CURL *curl;
CURLcode res;
struct data my_tracedata;
curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_DEBUGFUNCTION, my_trace);
curl_easy_setopt(curl, CURLOPT_DEBUGDATA, &my_tracedata);
/* the DEBUGFUNCTION has no effect until we enable VERBOSE */
curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L);
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
res = curl_easy_perform(curl);
/* always cleanup */
curl_easy_cleanup(curl);
}
return 0;
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE

18
docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.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
@ -39,6 +39,22 @@ necessary then.
.SH DEFAULT
.SH PROTOCOLS
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/file.txt");
/* contact us back, aka "active" FTP */
curl_easy_setopt(curl, CURLOPT_FTPPORT, "-");
/* FTP the way the neanderthals did it */
curl_easy_setopt(curl, CURLOPT_FTP_USE_EPRT, 0L);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.10.5
.SH RETURN VALUE

15
docs/libcurl/opts/CURLOPT_NOSIGNAL.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
@ -49,6 +49,19 @@ cases when they may still happen, contrary to our desire. In addition, using
raised.
.SH DEFAULT
0
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_NOSIGNAL, 1L);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.10
.SH RETURN VALUE

11
docs/libcurl/opts/CURLOPT_PIPEWAIT.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
@ -54,6 +54,15 @@ and support level.
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_PIPEWAIT, 1L);
/* now add this easy handle to the multi handle */
}
.fi
.SH AVAILABILITY
Added in 7.43.0
.SH RETURN VALUE

29
docs/libcurl/opts/CURLOPT_PROGRESSDATA.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
@ -35,7 +35,32 @@ The default value of this parameter is NULL.
.SH PROTOCOLS
All
.SH EXAMPLE
https://curl.se/libcurl/c/progressfunc.html
.nf
struct progress {
char *private;
size_t size;
};
static size_t progress_callback(void *clientp,
double dltotal,
double dlnow,
double ultotal,
double ulnow)
{
struct memory *progress = (struct progress *)userp;
/* use the values */
return 0; /* all is good */
}
struct progress data;
/* pass struct to callback */
curl_easy_setopt(curl_handle, CURLOPT_PROGRESSDATA, &data);
curl_easy_setopt(curl_handle, CURLOPT_PROGRESSFUNCTION, progress_callback);
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE

29
docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.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
@ -78,7 +78,32 @@ users.
.SH PROTOCOLS
All
.SH EXAMPLE
https://curl.se/libcurl/c/progressfunc.html
.nf
struct progress {
char *private;
size_t size;
};
static size_t progress_callback(void *clientp,
double dltotal,
double dlnow,
double ultotal,
double ulnow)
{
struct memory *progress = (struct progress *)userp;
/* use the values */
return 0; /* all is good */
}
struct progress data;
/* pass struct to callback */
curl_easy_setopt(curl_handle, CURLOPT_PROGRESSDATA, &data);
curl_easy_setopt(curl_handle, CURLOPT_PROGRESSFUNCTION, progress_callback);
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE

25
docs/libcurl/opts/CURLOPT_PUT.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
@ -38,6 +38,29 @@ This option is \fBdeprecated\fP since version 7.12.1. Use
0, disabled
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
/* we want to use our own read function */
curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_callback);
/* enable PUT */
curl_easy_setopt(curl, CURLOPT_PUT, 1L);
/* specify target */
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/to/newfile");
/* now specify which pointer to pass to our callback */
curl_easy_setopt(curl, CURLOPT_READDATA, hd_src);
/* Set the size of the file to upload */
curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, (curl_off_t)fsize);
/* Now run off and do what you've been told! */
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Deprecated since 7.12.1. Do not use.
.SH RETURN VALUE

18
docs/libcurl/opts/CURLOPT_WILDCARDMATCH.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
@ -78,7 +78,21 @@ Using the rules above, a file name pattern can be constructed:
.SH PROTOCOLS
This feature is only supported for FTP download.
.SH EXAMPLE
See https://curl.se/libcurl/c/ftp-wildcard.html
.nf
/* initialization of easy handle */
handle = curl_easy_init();
/* turn on wildcard matching */
curl_easy_setopt(handle, CURLOPT_WILDCARDMATCH, 1L);
/* callback is called before download of concrete file started */
curl_easy_setopt(handle, CURLOPT_CHUNK_BGN_FUNCTION, file_is_coming);
/* callback is called after data from the file have been transferred */
curl_easy_setopt(handle, CURLOPT_CHUNK_END_FUNCTION, file_is_downloaded);
/* See more on https://curl.se/libcurl/c/ftp-wildcard.html */
.fi
.SH AVAILABILITY
Added in 7.21.0
.SH RETURN VALUE

29
docs/libcurl/opts/CURLOPT_XFERINFODATA.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
@ -37,7 +37,32 @@ The default value of this parameter is NULL.
.SH PROTOCOLS
All
.SH EXAMPLE
https://curl.se/libcurl/c/progressfunc.html
.nf
struct progress {
char *private;
size_t size;
};
static size_t progress_callback(void *clientp,
curl_off_t dltotal,
curl_off_t dlnow,
curl_off_t ultotal,
curl_off_t ulnow)
{
struct memory *progress = (struct progress *)userp;
/* use the values */
return 0; /* all is good */
}
struct progress data;
/* pass struct to callback */
curl_easy_setopt(curl_handle, CURLOPT_XFERINFODATA, &data);
curl_easy_setopt(curl_handle, CURLOPT_XFERINFOFUNCTION, progress_callback);
.fi
.SH AVAILABILITY
Added in 7.32.0
.SH RETURN VALUE

29
docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.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
@ -75,7 +75,32 @@ users.
.SH PROTOCOLS
All
.SH EXAMPLE
https://curl.se/libcurl/c/progressfunc.html
.nf
struct progress {
char *private;
size_t size;
};
static size_t progress_callback(void *clientp,
curl_off_t dltotal,
curl_off_t dlnow,
curl_off_t ultotal,
curl_off_t ulnow)
{
struct memory *progress = (struct progress *)userp;
/* use the values */
return 0; /* all is good */
}
struct progress data;
/* pass struct to callback */
curl_easy_setopt(curl_handle, CURLOPT_XFERINFODATA, &data);
curl_easy_setopt(curl_handle, CURLOPT_XFERINFOFUNCTION, progress_callback);
.fi
.SH AVAILABILITY
Added in 7.32.0. This callback replaces \fICURLOPT_PROGRESSFUNCTION(3)\fP
.SH RETURN VALUE

22
tests/manpage-syntax.pl
View file

@ -34,11 +34,28 @@ my $errors = 0;
sub scanmanpage {
my ($file) = @_;
my $reqex = 0;
my $inex = 0;
my $exsize = 0;
print "Check $file\n";
open(M, "<$file") || die "no such file: $file";
if($file =~ /\/CURL[^\/]*.3/) {
# This is the man page for an libcurl option. It requires an example!
$reqex = 1;
}
my $line = 1;
while(<M>) {
if($_ =~ /^.SH EXAMPLE/) {
$inex = 1;
}
elsif($_ =~ /^.SH/) {
$inex = 0;
}
elsif($inex) {
$exsize++;
}
if($_ =~ /^\'/) {
print STDERR "$file:$line line starts with single quote!\n";
$errors++;
@ -57,6 +74,11 @@ sub scanmanpage {
$line++;
}
close(M);
if($reqex && ($exsize < 2)) {
print STDERR "$file:$line missing EXAMPLE section\n";
$errors++;
}
}