curl/curl
1
1
Fork 0
mirror of https://github.com/curl/curl.git synced 2025-09-18 01:52:41 +03:00
Code Issues Packages Projects Releases Wiki Activity

man pages: require all to use the same section header order

Browse Source 
This is the same order we already enforce among the options' man pages:
consistency is good. Add lots of previously missing examples.

Adjust the manpage-syntax script for this purpose, used in test 1173.

Closes #7904
This commit is contained in:
Daniel Stenberg 2021-10-25 08:54:08 +02:00
parent c2e804ca47
commit 24155569d8
No known key found for this signature in database
GPG Key ID: 5CC908FDB71E12C2
74 changed files with 709 additions and 271 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
docs/libcurl/curl_easy_cleanup.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,12 +49,6 @@ memory associated with it!
Passing in a NULL pointer in \fIhandle\fP will make this function return
immediately with no action.
.SH "OLD TIMES"
For libcurl versions before 7.17,: after you've called this function, you can
safely remove all the strings you've previously told libcurl to use, as it
won't use them anymore now.
.SH RETURN VALUE
None
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
@ -65,6 +59,10 @@ if(curl) {
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in libcurl 7.1
.SH RETURN VALUE
None
.SH "SEE ALSO"
.BR curl_easy_init "(3), " curl_easy_duphandle "(3), "
.BR curl_easy_reset "(3), "

17
docs/libcurl/curl_easy_duphandle.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
@ -45,6 +45,21 @@ NULL).
In multi-threaded programs, this function must be called in a synchronous way,
the input handle may not be in use when cloned.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
CURL *nother;
if(curl) {
CURLcode res;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
nother = curl_easy_duphandle(curl);
res = curl_easy_perform(nother);
curl_easy_cleanup(nother);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in libcurl 7.9
.SH RETURN VALUE
If this function returns NULL, something went wrong and no valid handle was
returned.

10
docs/libcurl/curl_easy_escape.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,10 +49,6 @@ uses.
The caller of \fIcurl_easy_escape(3)\fP must make sure that the data passed in
to the function is encoded correctly.
.SH AVAILABILITY
Added in 7.15.4 and replaces the old \fIcurl_escape(3)\fP function.
.SH RETURN VALUE
A pointer to a null-terminated string or NULL if it failed.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
@ -64,5 +60,9 @@ if(curl) {
}
}
.fi
.SH AVAILABILITY
Added in 7.15.4 and replaces the old \fIcurl_escape(3)\fP function.
.SH RETURN VALUE
A pointer to a null-terminated string or NULL if it failed.
.SH "SEE ALSO"
.BR curl_easy_unescape "(3), " curl_free "(3), " RFC 3986

22
docs/libcurl/curl_easy_getinfo.3
View File

@ -282,6 +282,28 @@ Total time of the previous request.
The time it took for all redirection steps
include name lookup, connect, pretransfer and transfer before final
transaction was started. So, this is zero if no redirection took place.
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://www.example.com/");
res = curl_easy_perform(curl);
if(CURLE_OK == res) {
char *ct;
/* ask for the content-type */
res = curl_easy_getinfo(curl, CURLINFO_CONTENT_TYPE, &ct);
if((CURLE_OK == res) && ct)
printf("We received Content-Type: %s\n", ct);
}
/* always cleanup */
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in libcurl 7.4.1
.SH RETURN VALUE
If the operation was successful, CURLE_OK is returned. Otherwise an
appropriate error code will be returned.

8
docs/libcurl/curl_easy_init.3
View File

@ -41,9 +41,6 @@ You are strongly advised to not allow this automatic behavior, by calling
\fIcurl_global_init(3)\fP yourself properly. See the description in
\fBlibcurl\fP(3) of global environment requirements for details of how to use
this function.
.SH RETURN VALUE
If this function returns NULL, something went wrong and you cannot use the
other curl functions.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
@ -54,6 +51,11 @@ if(curl) {
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
If this function returns NULL, something went wrong and you cannot use the
other curl functions.
.SH "SEE ALSO"
.BR curl_easy_cleanup "(3), " curl_global_init "(3), " curl_easy_reset "(3), "
.BR curl_easy_perform "(3) "

9
docs/libcurl/curl_easy_option_by_id.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
@ -37,6 +37,13 @@ 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 EXAMPLE
.nf
const struct curl_easyoption *opt = curl_easy_option_by_id(CURLOPT_URL);
if(opt) {
printf("This option wants type %x\n", opt->type);
}
.fi
.SH AVAILABILITY
This function was added in libcurl 7.73.0
.SH RETURN VALUE

9
docs/libcurl/curl_easy_option_by_name.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,6 +35,13 @@ 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 EXAMPLE
.nf
const struct curl_easyoption *opt = curl_easy_option_by_name("URL");
if(opt) {
printf("This option wants CURLoption %x\n", (int)opt->id);
}
.fi
.SH AVAILABILITY
This function was added in libcurl 7.73.0
.SH RETURN VALUE

12
docs/libcurl/curl_easy_option_next.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
@ -64,6 +64,16 @@ 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 */
const struct curl_easyoption *opt;
opt = curl_easy_option_by_next(NULL);
while(opt) {
printf("Name: %s\n", opt->name);
opt = curl_easy_option_by_next(opt);
}
.fi
.SH AVAILABILITY
This function was added in libcurl 7.73.0
.SH RETURN VALUE

19
docs/libcurl/curl_easy_pause.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
@ -68,10 +68,6 @@ function is called again without this bit set. Thus, the read callback
Convenience define that pauses both directions.
.IP CURLPAUSE_CONT
Convenience define that unpauses both directions.
.SH RETURN VALUE
CURLE_OK (zero) means that the option was set properly, and a non-zero return
code means something wrong occurred after the new state was set. See the
\fIlibcurl-errors(3)\fP man page for the full list with descriptions.
.SH LIMITATIONS
The pausing of transfers does not work with protocols that work without
network connectivity, like FILE://. Trying to pause such a transfer, in any
@ -88,8 +84,11 @@ buffering 32 megabyte of data for a paused stream.
When such a paused stream is unpaused again, any buffered data will be
delivered first.
.SH AVAILABILITY
Added in libcurl 7.18.0.
.SH EXAMPLE
.nf
/* pause a transfer in both directions */
curl_easy_pause(curl, CURL_READFUNC_PAUSE | CURL_WRITEFUNC_PAUSE);
.fi
.SH "MEMORY USE"
When pausing a read by returning the magic return code from a write callback,
the read data is already in libcurl's internal buffers so it'll have to keep
@ -103,5 +102,11 @@ effect that if you download something that is compressed a lot, it can result
in a very large data amount needing to be allocated to save the data during
the pause. This said, you should probably consider not using paused receiving
if you allow libcurl to uncompress data automatically.
.SH AVAILABILITY
Added in libcurl 7.18.0.
.SH RETURN VALUE
CURLE_OK (zero) means that the option was set properly, and a non-zero return
code means something wrong occurred after the new state was set. See the
\fIlibcurl-errors(3)\fP man page for the full list with descriptions.
.SH "SEE ALSO"
.BR curl_easy_cleanup "(3), " curl_easy_reset "(3)"

14
docs/libcurl/curl_easy_perform.3
View File

@ -52,12 +52,6 @@ easy_handles.
While the \fBeasy_handle\fP is added to a multi handle, it cannot be used by
\fIcurl_easy_perform(3)\fP.
.SH RETURN VALUE
CURLE_OK (0) means everything was ok, non-zero means an error occurred as
.I <curl/curl.h>
defines - see \fIlibcurl-errors(3)\fP. If the \fICURLOPT_ERRORBUFFER(3)\fP was
set with \fIcurl_easy_setopt(3)\fP there will be a readable error message in
the error buffer when non-zero is returned.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
@ -68,6 +62,14 @@ if(curl) {
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
CURLE_OK (0) means everything was ok, non-zero means an error occurred as
.I <curl/curl.h>
defines - see \fIlibcurl-errors(3)\fP. If the \fICURLOPT_ERRORBUFFER(3)\fP was
set with \fIcurl_easy_setopt(3)\fP there will be a readable error message in
the error buffer when non-zero is returned.
.SH "SEE ALSO"
.BR curl_easy_init "(3), " curl_easy_setopt "(3), "
.BR curl_multi_add_handle "(3), " curl_multi_perform "(3), "

19
docs/libcurl/curl_easy_recv.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
@ -60,7 +60,22 @@ read which would include any cached data.
Furthermore if you wait on the socket and it tells you there is data to read,
\fIcurl_easy_recv(3)\fP may return \fBCURLE_AGAIN\fP if the only data that was
read was for internal SSL processing, and no other data is available.
.SH EXAMPLE
.nf
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* Do not do the transfer - only connect to host */
curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L);
res = curl_easy_perform(curl);
if(res == CURLE_OK) {
/* Extract the socket from the curl handle -
we'll need it for waiting. */
res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd);
/* read data */
res = curl_easy_recv(curl, buf, sizeof(buf), &nread);
}
.fi
.SH AVAILABILITY
Added in 7.18.2.
.SH RETURN VALUE
@ -76,8 +91,6 @@ Reading exactly 0 bytes indicates a closed connection.
If there's no socket available to use from the previous transfer, this function
returns \fBCURLE_UNSUPPORTED_PROTOCOL\fP.
.SH EXAMPLE
See \fBsendrecv.c\fP in \fBdocs/examples\fP directory for usage example.
.SH "SEE ALSO"
.BR curl_easy_setopt "(3), " curl_easy_perform "(3), "
.BR curl_easy_getinfo "(3), "

10
docs/libcurl/curl_easy_reset.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,6 +35,14 @@ it was just created with \fIcurl_easy_init(3)\fP.
It does not change the following information kept in the handle: live
connections, the Session ID cache, the DNS cache, the cookies, the shares or
the alt-svc cache.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
/* ... the handle is used and options are set ... */
curl_easy_reset(curl);
.fi
.SH AVAILABILITY
This function was added in libcurl 7.12.1
.SH RETURN VALUE

19
docs/libcurl/curl_easy_send.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
@ -53,7 +53,22 @@ obtained using \fIcurl_easy_getinfo(3)\fP with \fICURLINFO_ACTIVESOCKET(3)\fP.
Furthermore if you wait on the socket and it tells you it's writable,
\fIcurl_easy_send(3)\fP may return \fBCURLE_AGAIN\fP if the only data that was
sent was for internal SSL processing, and no other data could be sent.
.SH EXAMPLE
.nf
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* Do not do the transfer - only connect to host */
curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L);
res = curl_easy_perform(curl);
if(res == CURLE_OK) {
/* Extract the socket from the curl handle -
we'll need it for waiting. */
res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd);
/* send data */
res = curl_easy_send(curl, "hello", 5, &sent);
}
.fi
.SH AVAILABILITY
Added in 7.18.2.
.SH RETURN VALUE
@ -68,8 +83,6 @@ system facilities to wait until the socket is writable, and retry.
If there's no socket available to use from the previous transfer, this function
returns \fBCURLE_UNSUPPORTED_PROTOCOL\fP.
.SH EXAMPLE
See \fBsendrecv.c\fP in \fBdocs/examples\fP directory for usage example.
.SH "SEE ALSO"
.BR curl_easy_setopt "(3), " curl_easy_perform "(3), " curl_easy_getinfo "(3), "
.BR curl_easy_recv "(3) "

22
docs/libcurl/curl_easy_setopt.3
View File

@ -672,6 +672,18 @@ Mode for creating new remote directories. See \fICURLOPT_NEW_DIRECTORY_PERMS(3)\
.SH TELNET OPTIONS
.IP CURLOPT_TELNETOPTIONS
TELNET options. See \fICURLOPT_TELNETOPTIONS(3)\fP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
res = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
\fICURLE_OK\fP (zero) means that the option was set properly, non-zero means an
error occurred as \fI<curl/curl.h>\fP defines. See the \fIlibcurl-errors(3)\fP
@ -689,16 +701,6 @@ the library is too old to support it or the option was removed in a recent
version, this function will return \fICURLE_UNKNOWN_OPTION\fP. If support for
the option was disabled at compile-time, it will return
\fICURLE_NOT_BUILT_IN\fP.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
res = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH "SEE ALSO"
.BR curl_easy_init "(3), " curl_easy_cleanup "(3), " curl_easy_reset "(3), "
.BR curl_easy_getinfo "(3), " curl_multi_setopt "(3), "

9
docs/libcurl/curl_easy_strerror.3
View File

@ -32,6 +32,15 @@ CURLcode error code passed in the argument \fIerrornum\fP.
Typically applications also appreciate \fICURLOPT_ERRORBUFFER(3)\fP for more
specific error descriptions generated at run-time.
.SH EXAMPLE
.nf
/* Perform the request, res will get the return code */
res = curl_easy_perform(curl);
/* Check for errors */
if(res != CURLE_OK)
fprintf(stderr, "curl_easy_perform() failed: %s\n",
curl_easy_strerror(res));
.fi
.SH AVAILABILITY
This function was added in libcurl 7.12.0
.SH RETURN VALUE

16
docs/libcurl/curl_easy_unescape.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
@ -46,6 +46,20 @@ longer string can be unescaped if the string length is returned in this
parameter.
You must \fIcurl_free(3)\fP the returned string when you're done with it.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
int decodelen;
char *decoded = curl_easy_unescape(curl, "%63%75%72%6c", 12, &decodelen);
if(decoded) {
/* don't assume printf() works on the decoded data! */
printf("Decoded: ");
/* ... */
curl_free(decoded);
}
}
.fi
.SH AVAILABILITY
Added in 7.15.4 and replaces the old \fIcurl_unescape(3)\fP function.
.SH RETURN VALUE

20
docs/libcurl/curl_easy_upkeep.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
@ -41,14 +41,6 @@ is called, an HTTP/2 PING frame is sent on the connection.
This function must be explicitly called in order to perform the upkeep work.
The connection upkeep interval is set with
\fICURLOPT_UPKEEP_INTERVAL_MS(3)\fP.
.SH AVAILABILITY
Added in 7.62.0.
.SH RETURN VALUE
On success, returns \fBCURLE_OK\fP.
On failure, returns the appropriate error code.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
@ -73,5 +65,13 @@ if(curl) {
/* always cleanup */
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.62.0.
.SH RETURN VALUE
On success, returns \fBCURLE_OK\fP.
On failure, returns the appropriate error code.
.SH SEE ALSO
.BR CURLOPT_TCP_KEEPALIVE "(3), "
.BR CURLOPT_TCP_KEEPIDLE "(3), "

10
docs/libcurl/curl_escape.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,14 @@ If the 'length' argument is set to 0, curl_escape() will use strlen() on the
input 'url' string to find out the size.
You must \fIcurl_free(3)\fP the returned string when you're done with it.
.SH EXAMPLE
.nf
char *output = curl_escape("data to convert", 15);
if(output) {
printf("Encoded: %s\\n", output);
curl_free(output);
}
.fi
.SH AVAILABILITY
Since 7.15.4, \fIcurl_easy_escape(3)\fP should be used. This function will
be removed in a future release.

26
docs/libcurl/curl_formadd.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
@ -170,20 +170,8 @@ the \fICURLOPT_HTTPPOST(3)\fP option), you must not free the list until after
you've called \fIcurl_easy_cleanup(3)\fP for the curl handle.
See example below.
.SH AVAILABILITY
Deprecated in 7.56.0. Before this release, field names were allowed to
contain zero-valued bytes. The pseudo-filename "-" to read stdin is
discouraged although still supported, but data is not read before being
actually sent: the effective data size can then not be automatically
determined, resulting in a chunked encoding transfer. Backslashes and
double quotes in field and file names are now escaped before transmission.
.SH RETURN VALUE
0 means everything was ok, non-zero means an error occurred corresponding
to a CURL_FORMADD_* constant defined in
.I <curl/curl.h>
.SH EXAMPLE
.nf
struct curl_httppost* post = NULL;
struct curl_httppost* last = NULL;
char namebuffer[] = "name buffer";
@ -260,7 +248,17 @@ to a CURL_FORMADD_* constant defined in
CURLFORM_FILECONTENT, ".bashrc", CURLFORM_END);
/* Set the form info */
curl_easy_setopt(curl, CURLOPT_HTTPPOST, post);
.SH AVAILABILITY
Deprecated in 7.56.0. Before this release, field names were allowed to
contain zero-valued bytes. The pseudo-filename "-" to read stdin is
discouraged although still supported, but data is not read before being
actually sent: the effective data size can then not be automatically
determined, resulting in a chunked encoding transfer. Backslashes and
double quotes in field and file names are now escaped before transmission.
.SH RETURN VALUE
0 means everything was ok, non-zero means an error occurred corresponding
to a CURL_FORMADD_* constant defined in
.I <curl/curl.h>
.SH "SEE ALSO"
.BR curl_easy_setopt "(3),"
.BR curl_formfree "(3),"

18
docs/libcurl/curl_formfree.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
@ -43,6 +43,22 @@ the \fIcurl_formadd(3)\fP invoke(s).
Passing in a NULL pointer in \fIform\fP will make this function return
immediately with no action.
.SH EXAMPLE
.nf
/* Fill in a file upload field */
curl_formadd(&formpost,
&lastptr,
CURLFORM_COPYNAME, "file",
CURLFORM_FILE, "nice-image.jpg",
CURLFORM_END);
curl_easy_setopt(curl, CURLOPT_HTTPPOST, formpost);
curl_easy_perform(curl);
/* then cleanup the formpost chain */
curl_formfree(formpost);
.fi
.SH AVAILABILITY
Deprecated in 7.56.0.
.SH RETURN VALUE

7
docs/libcurl/curl_formget.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
@ -44,11 +44,8 @@ callback should return the buffer length passed to it on success.
If the \fBCURLFORM_STREAM\fP option is used in the formpost, it will prevent
\fIcurl_formget(3)\fP from working until you've performed the actual HTTP
request as only then will libcurl get the actual read callback to use!
.SH RETURN VALUE
0 means everything was ok, non-zero means an error occurred
.SH EXAMPLE
.nf
size_t print_httppost_callback(void *arg, const char *buf, size_t len)
{
fwrite(buf, len, 1, stdout);
@ -67,5 +64,7 @@ request as only then will libcurl get the actual read callback to use!
.SH AVAILABILITY
This function was added in libcurl 7.15.5. The form API is deprecated in
libcurl 7.56.0.
.SH RETURN VALUE
0 means everything was ok, non-zero means an error occurred
.SH "SEE ALSO"
.BR curl_formadd "(3), " curl_mime_init "(3)"

10
docs/libcurl/curl_free.3
View File

@ -34,6 +34,16 @@ differences in memory management between your application and libcurl.
Passing in a NULL pointer in \fIptr\fP will make this function return
immediately with no action.
.SH EXAMPLE
.nf
char *width = curl_getenv("COLUMNS");
if(width) {
/* it was set! */
curl_free(width);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
None
.SH "SEE ALSO"

59
docs/libcurl/curl_getdate.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
@ -62,36 +62,39 @@ If a decimal number of the form YYYYMMDD appears, then YYYY is read as the
year, MM as the month number and DD as the day of the month, for the specified
calendar date.
.PP
.SH EXAMPLES
.SH EXAMPLE
.nf
Sun, 06 Nov 1994 08:49:37 GMT
Sunday, 06-Nov-94 08:49:37 GMT
Sun Nov 6 08:49:37 1994
06 Nov 1994 08:49:37 GMT
06-Nov-94 08:49:37 GMT
Nov 6 08:49:37 1994
06 Nov 1994 08:49:37
06-Nov-94 08:49:37
1994 Nov 6 08:49:37
GMT 08:49:37 06-Nov-94 Sunday
94 6 Nov 08:49:37
1994 Nov 6
06-Nov-94
Sun Nov 6 94
1994.Nov.6
Sun/Nov/6/94/GMT
Sun, 06 Nov 1994 08:49:37 CET
06 Nov 1994 08:49:37 EST
Sun, 12 Sep 2004 15:05:58 -0700
Sat, 11 Sep 2004 21:32:11 +0200
20040912 15:05:58 -0700
20040911 +0200
time_t t;
t = curl_getdate("Sun, 06 Nov 1994 08:49:37 GMT", NULL);
t = curl_getdate("Sunday, 06-Nov-94 08:49:37 GMT", NULL);
t = curl_getdate("Sun Nov 6 08:49:37 1994", NULL);
t = curl_getdate("06 Nov 1994 08:49:37 GMT", NULL);
t = curl_getdate("06-Nov-94 08:49:37 GMT", NULL);
t = curl_getdate("Nov 6 08:49:37 1994", NULL);
t = curl_getdate("06 Nov 1994 08:49:37", NULL);
t = curl_getdate("06-Nov-94 08:49:37", NULL);
t = curl_getdate("1994 Nov 6 08:49:37", NULL);
t = curl_getdate("GMT 08:49:37 06-Nov-94 Sunday", NULL);
t = curl_getdate("94 6 Nov 08:49:37", NULL);
t = curl_getdate("1994 Nov 6", NULL);
t = curl_getdate("06-Nov-94", NULL);
t = curl_getdate("Sun Nov 6 94", NULL);
t = curl_getdate("1994.Nov.6", NULL);
t = curl_getdate("Sun/Nov/6/94/GMT", NULL);
t = curl_getdate("Sun, 06 Nov 1994 08:49:37 CET", NULL);
t = curl_getdate("06 Nov 1994 08:49:37 EST", NULL);
t = curl_getdate("Sun, 12 Sep 2004 15:05:58 -0700", NULL);
t = curl_getdate("Sat, 11 Sep 2004 21:32:11 +0200", NULL);
t = curl_getdate("20040912 15:05:58 -0700", NULL);
t = curl_getdate("20040911 +0200", NULL);
.fi
.SH STANDARDS
This parser was written to handle date formats specified in RFC 822 (including
the update in RFC 1123) using time zone name or time zone delta and RFC 850
(obsoleted by RFC 1036) and ANSI C's asctime() format. These formats are the
only ones RFC 7231 says HTTP applications may use.
This parser handles date formats specified in RFC 822 (including the update in
RFC 1123) using time zone name or time zone delta and RFC 850 (obsoleted by
RFC 1036) and ANSI C's asctime() format. These formats are the only ones RFC
7231 says HTTP applications may use.
.SH AVAILABILITY
Always
.SH RETURN VALUE
This function returns -1 when it fails to parse the date string. Otherwise it
returns the number of seconds as described.

8
docs/libcurl/curl_getenv.3
View File

@ -33,6 +33,14 @@ emulate its behavior and provide an identical interface for all operating
systems libcurl builds on (including win32).
You must \fIcurl_free(3)\fP the returned string when you're done with it.
.SH EXAMPLE
.nf
char *width = curl_getenv("COLUMNS");
if(width) {
/* it was set! */
curl_free(width);
}
.fi
.SH AVAILABILITY
This function will be removed from the public libcurl API in a near future. It
will instead be made "available" by source code access only, and then as

10
docs/libcurl/curl_global_cleanup.3
View File

@ -49,6 +49,16 @@ containing libcurl is dynamically unloaded while libcurl-created threads are
still running then your program may crash or other corruption may occur. We
recommend you do not run libcurl from any module that may be unloaded
dynamically. This behavior may be addressed in the future.
.SH EXAMPLE
.nf
curl_global_init(CURL_GLOBAL_DEFAULT);
/* use libcurl, then before exiting... */
curl_global_cleanup();
.fi
.SH AVAILABILITY
Added in 7.8
.SH RETURN VALUE
None
.SH "SEE ALSO"

12
docs/libcurl/curl_global_init.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
@ -92,6 +92,16 @@ This bit has no point since 7.69.0 but its behavior is instead the default.
Before 7.69.0: when this flag is set, curl will acknowledge EINTR condition
when connecting or when waiting for data. Otherwise, curl waits until full
timeout elapses. (Added in 7.30.0)
.SH EXAMPLE
.nf
curl_global_init(CURL_GLOBAL_DEFAULT);
/* use libcurl, then before exiting... */
curl_global_cleanup();
.fi
.SH AVAILABILITY
Added in 7.8
.SH RETURN VALUE
If this function returns non-zero, something went wrong and you cannot use the
other curl functions.

12
docs/libcurl/curl_global_init_mem.3
View File

@ -56,14 +56,20 @@ To replace calloc()
.RE
This function is otherwise the same as \fIcurl_global_init(3)\fP, please refer
to that man page for documentation.
.SH "CAUTION"
.SH CAUTION
Manipulating these gives considerable powers to the application to severely
screw things up for libcurl. Take care!
.SH EXAMPLE
.nf
curl_global_init_mem(CURL_GLOBAL_DEFAULT, curl_malloc_cb,
curl_free_cb, curl_realloc_cb,
curl_strdup_cb, curl_calloc_cb);
.fi
.SH AVAILABILITY
Added in 7.12.0
.SH RETURN VALUE
CURLE_OK (0) means everything was ok, non-zero means an error occurred as
\fI<curl/curl.h>\fP defines - see \fIlibcurl-errors(3)\fP.
.SH AVAILABILITY
Added in 7.12.0
.SH "SEE ALSO"
.BR curl_global_init "(3), "
.BR curl_global_cleanup "(3), "

17
docs/libcurl/curl_global_sslset.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
@ -82,7 +82,19 @@ attempt to change it will result in a \fBCURLSSLSET_TOO_LATE\fP.
\fBThis function is not thread safe.\fP You must not call it when any other
thread in the program (i.e. a thread sharing the same memory) is running.
This doesn't just mean no other thread that is using libcurl.
.SH EXAMPLE
.nf
/* choose a specific backend */
curl_global_sslset(CURLSSLBACKEND_WOLFSSL, NULL, NULL);
/* list the available ones */
const curl_ssl_backend **list;
curl_global_sslset((curl_sslbackend)-1, NULL, &list);
for(i = 0; list[i]; i++)
printf("SSL backend #%d: '%s' (ID: %d)\n",
i, list[i]->name, list[i]->id);
.fi
.SH AVAILABILITY
This function was added in libcurl 7.56.0. Before this version, there was no
support for choosing SSL backends at runtime.
@ -90,7 +102,8 @@ support for choosing SSL backends at runtime.
If this function returns CURLSSLSET_OK, the backend was successfully selected.
If the chosen backend is unknown (or support for the chosen backend has not
been compiled into libcurl), the function returns \fICURLSSLSET_UNKNOWN_BACKEND\fP.
been compiled into libcurl), the function returns
\fICURLSSLSET_UNKNOWN_BACKEND\fP.
If the backend had been configured previously, or if \fIcurl_global_init(3)\fP
has already been called, the function returns \fICURLSSLSET_TOO_LATE\fP.

10
docs/libcurl/curl_mime_addpart.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
@ -34,10 +34,6 @@ subsequently be populated using functions from the mime API.
\fImime\fP is the handle of the mime structure in which the new part must be
appended.
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
A mime part structure handle, or NULL upon failure.
.SH EXAMPLE
.nf
curl_mime *mime;
@ -53,6 +49,10 @@ A mime part structure handle, or NULL upon failure.
curl_mime_data(part, "This is the field data", CURL_ZERO_TERMINATED);
curl_mime_name(part, "data");
.fi
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
A mime part structure handle, or NULL upon failure.
.SH "SEE ALSO"
.BR curl_mime_init "(3),"
.BR curl_mime_name "(3),"

10
docs/libcurl/curl_mime_data.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
@ -44,10 +44,6 @@ is retained. It is possible to unassign part's contents by setting
Setting very large data is memory consuming: one might consider using
\fIcurl_mime_data_cb(3)\fP in such a case.
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
CURLE_OK or a CURL error code upon failure.
.SH EXAMPLE
.nf
curl_mime *mime;
@ -62,6 +58,10 @@ CURLE_OK or a CURL error code upon failure.
/* add data to the part */
curl_mime_data(part, "raw contents to send", CURL_ZERO_TERMINATED);
.fi
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
CURLE_OK or a CURL error code upon failure.
.SH "SEE ALSO"
.BR curl_mime_addpart "(3),"
.BR curl_mime_data_cb "(3),"

9
docs/libcurl/curl_mime_data_cb.3
View File

@ -96,11 +96,6 @@ duplicated: the \fIarg\fP pointer argument is also duplicated, resulting in
the pointed item to be shared between the original and the copied handle.
In particular, special attention should be given to the \fIfreefunc\fP
procedure code since it will be called twice with the same argument.
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
CURLE_OK or a CURL error code upon failure.
.SH EXAMPLE
Sending a huge data string will cause the same amount of memory to be
allocated: to avoid overhead resources consumption, one might want to use a
@ -160,6 +155,10 @@ int seek_callback(void *arg, curl_off_t offset, int origin)
curl_mime_data_cb(part, hugectl.size, read_callback, seek_callback, NULL,
&hugectl);
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
CURLE_OK or a CURL error code upon failure.
.SH "SEE ALSO"
.BR curl_mime_addpart "(3),"
.BR curl_mime_data "(3),"

12
docs/libcurl/curl_mime_encoder.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
@ -41,7 +41,7 @@ Setting a part's encoder twice is valid: only the value set by the last call is
retained.
Upon multipart rendering, the part's content is encoded according to the
pertaining scheme and a corresponding \fIContent-Transfer-Encoding"\fP header
pertaining scheme and a corresponding \fI"Content-Transfer-Encoding"\fP header
is added to the part.
Supported encoding schemes are:
@ -70,10 +70,6 @@ If the original data is already encoded in such a scheme, a custom
Encoding should not be applied to multiparts, thus the use of this
function on a part with content set with \fIcurl_mime_subparts\fP() is
strongly discouraged.
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
CURLE_OK or a CURL error code upon failure.
.SH EXAMPLE
.nf
curl_mime *mime;
@ -91,6 +87,10 @@ CURLE_OK or a CURL error code upon failure.
/* encode file data in base64 for transfer */
curl_mime_encoder(part, "base64");
.fi
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
CURLE_OK or a CURL error code upon failure.
.SH "SEE ALSO"
.BR curl_mime_addpart "(3),"
.BR curl_mime_headers "(3),"

16
docs/libcurl/curl_mime_filedata.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
@ -53,13 +53,6 @@ will be transferred as chunks by HTTP and rejected by IMAP.
Setting a part's contents twice is valid: only the value set by the last call
is retained.
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
CURLE_OK or a CURL error code upon failure. CURLE_READ_ERROR is only an
indication that the file is not yet readable: it can be safely ignored at
this time, but the file must be made readable before the pertaining
easy handle is performed.
.SH EXAMPLE
.nf
curl_mime *mime;
@ -77,6 +70,13 @@ easy handle is performed.
/* set name */
curl_mime_name(part, "data");
.fi
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
CURLE_OK or a CURL error code upon failure. CURLE_READ_ERROR is only an
indication that the file is not yet readable: it can be safely ignored at
this time, but the file must be made readable before the pertaining
easy handle is performed.
.SH "SEE ALSO"
.BR curl_mime_addpart "(3),"
.BR curl_mime_data "(3),"

10
docs/libcurl/curl_mime_filename.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
@ -42,10 +42,6 @@ to NULL to remove a previously attached remote file name.
The remote file name string is copied into the part, thus the associated
storage may safely be released or reused after call. Setting a part's file
name twice is valid: only the value set by the last call is retained.
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
CURLE_OK or a CURL error code upon failure.
.SH EXAMPLE
.nf
curl_mime *mime;
@ -66,6 +62,10 @@ CURLE_OK or a CURL error code upon failure.
/* set name */
curl_mime_name(part, "data");
.fi
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
CURLE_OK or a CURL error code upon failure.
.SH "SEE ALSO"
.BR curl_mime_addpart "(3),"
.BR curl_mime_filedata "(3),"

12
docs/libcurl/curl_mime_free.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
@ -42,6 +42,16 @@ not be explicitly freed as they are by the top structure freeing.
Passing in a NULL pointer in \fImime\fP will make this function return
immediately with no action.
.SH EXAMPLE
.nf
/* Build the mime message. */
mime = curl_mime_init(curl);
/* ... */
/* Free multipart message. */
curl_mime_free(mime);
.fi
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE

10
docs/libcurl/curl_mime_headers.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
@ -42,10 +42,6 @@ freed explicitly.
Setting a part's custom headers list twice is valid: only the value set by
the last call is retained.
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
CURLE_OK or a CURL error code upon failure.
.SH EXAMPLE
.nf
struct curl_slist *headers = NULL;
@ -61,5 +57,9 @@ CURLE_OK or a CURL error code upon failure.
/* set name */
curl_mime_name(part, "numbers");
.fi
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
CURLE_OK or a CURL error code upon failure.
.SH "SEE ALSO"
.BR curl_mime_addpart "(3)"

11
docs/libcurl/curl_mime_init.3
View File

@ -37,14 +37,8 @@ call.
Using a mime handle is the recommended way to post an HTTP form, format and
send a multi-part e-mail with SMTP or upload such an e-mail to an IMAP server.
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
A mime struct handle, or NULL upon failure.
.SH EXAMPLE
.nf
CURL *easy = curl_easy_init();
curl_mime *mime;
curl_mimepart *part;
@ -63,7 +57,10 @@ A mime struct handle, or NULL upon failure.
/* Clean-up. */
curl_easy_cleanup(easy);
curl_mime_free(mime);
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
A mime struct handle, or NULL upon failure.
.SH "SEE ALSO"
.BR curl_mime_addpart "(3),"
.BR curl_mime_free "(3),"

10
docs/libcurl/curl_mime_name.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,10 +39,6 @@ The name string is copied into the part, thus the associated storage may
safely be released or reused after call. Setting a part's name twice is valid:
only the value set by the last call is retained. It is possible to "unname" a
part by setting \fIname\fP to NULL.
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
CURLE_OK or a CURL error code upon failure.
.SH EXAMPLE
.nf
curl_mime *mime;
@ -57,6 +53,10 @@ CURLE_OK or a CURL error code upon failure.
/* give the part a name */
curl_mime_name(part, "shoe_size");
.fi
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
CURLE_OK or a CURL error code upon failure.
.SH "SEE ALSO"
.BR curl_mime_addpart "(3),"
.BR curl_mime_data "(3),"

26
docs/libcurl/curl_mime_subparts.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
@ -42,12 +42,32 @@ subsequent calls to mime API functions.
Setting a part's contents twice is valid: only the value set by the last call
is retained. It is possible to unassign previous part's contents by setting
\fIsubparts\fP to NULL.
.SH EXAMPLE
.nf
/* The inline part is an alternative proposing the html and the text
versions of the e-mail. */
alt = curl_mime_init(curl);
/* HTML message. */
part = curl_mime_addpart(alt);
curl_mime_data(part, inline_html, CURL_ZERO_TERMINATED);
curl_mime_type(part, "text/html");
/* Text message. */
part = curl_mime_addpart(alt);
curl_mime_data(part, inline_text, CURL_ZERO_TERMINATED);
/* Create the inline part. */
part = curl_mime_addpart(mime);
curl_mime_subparts(part, alt);
curl_mime_type(part, "multipart/alternative");
slist = curl_slist_append(NULL, "Content-Disposition: inline");
curl_mime_headers(part, slist, 1);
.fi
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
CURLE_OK or a CURL error code upon failure.
.SH EXAMPLE
TODO
.SH "SEE ALSO"
.BR curl_mime_addpart "(3),"
.BR curl_mime_init "(3)"

10
docs/libcurl/curl_mime_type.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
@ -53,10 +53,6 @@ extension, or application/octet-stream by default.
- For a multipart part, multipart/mixed.
.br
- text/plain in other cases.
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
CURLE_OK or a CURL error code upon failure.
.SH EXAMPLE
.nf
curl_mime *mime;
@ -77,6 +73,10 @@ CURLE_OK or a CURL error code upon failure.
/* set name */
curl_mime_name(part, "image");
.fi
.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
CURLE_OK or a CURL error code upon failure.
.SH "SEE ALSO"
.BR curl_mime_addpart "(3),"
.BR curl_mime_name "(3),"

5
docs/libcurl/curl_mprintf.3
View File

@ -239,6 +239,11 @@ by the corresponding argument.
.TP
.B %
A '%' is written. No argument is converted.
.SH EXAMPLE
.nf
mprintf("My name is %s\n", name);
mprintf("Pi is almost %f\n", 25/8);
.fi
.SH AVAILABILITY
These functions will be removed from the public libcurl API in the future. Do
not use them in new programs or projects.

13
docs/libcurl/curl_multi_add_handle.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
@ -64,6 +64,17 @@ first the easy handle and then the multi handle:
2 - \fIcurl_easy_cleanup(3)\fP
3 - \fIcurl_multi_cleanup(3)\fP
.SH EXAMPLE
.nf
/* init a multi stack */
multi_handle = curl_multi_init();
/* add individual transfers */
curl_multi_add_handle(multi_handle, http_handle);
curl_multi_add_handle(multi_handle, http_handle2);
.fi
.SH AVAILABILITY
ADded in 7.9.6
.SH RETURN VALUE
CURLMcode type, general libcurl multi interface error code.
.SH "SEE ALSO"

15
docs/libcurl/curl_multi_assign.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
@ -46,9 +46,16 @@ The idea here being that this association (socket to private pointer) is
something that just about every application that uses this API will need and
then libcurl can just as well do it since it already has an internal hash
table lookup for this.
.SH "RETURN VALUE"
.SH EXAMPLE
.nf
/* make our struct pointer associated with socket fd */
mc = curl_multi_assign(multi_handle, fd, ourstructp);
.fi
.SH AVAILABILITY
Added in 7.15.5
.SH RETURN VALUE
The standard CURLMcode for multi interface error codes.
.SH "TYPICAL USAGE"
.SH TYPICAL USAGE
In a typical application you allocate a struct or at least use some kind of
semi-dynamic data for each socket that we must wait for action on when using
the \fIcurl_multi_socket_action(3)\fP approach.
@ -57,7 +64,5 @@ When our socket-callback gets called by libcurl and we get to know about yet
another socket to wait for, we can use \fIcurl_multi_assign(3)\fP to point out
the particular data so that when we get updates about this same socket again,
we don't have to find the struct associated with this socket by ourselves.
.SH AVAILABILITY
This function was added in libcurl 7.15.5.
.SH "SEE ALSO"
.BR curl_multi_setopt "(3), " curl_multi_socket_action "(3) "

11
docs/libcurl/curl_multi_cleanup.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
@ -43,6 +43,15 @@ removed
Passing in a NULL pointer in \fImulti_handle\fP will make this function return
CURLM_BAD_HANDLE immediately with no other action.
.SH EXAMPLE
.nf
/* when the multi transfer is done ... */
/* remove all easy handles, then: */
curl_multi_cleanup(multi_handle);
.fi
.SH AVAILABILITY
Added in 7.9.6
.SH RETURN VALUE
CURLMcode type, general libcurl multi interface error code. On success,
CURLM_OK is returned.

17
docs/libcurl/curl_multi_fdset.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,6 +75,21 @@ large file descriptor in an fd_set implies an out of bounds write which can
cause crashes, or worse. The effect of NOT storing it will possibly save you
from the crash, but will make your program NOT wait for sockets it should wait
for...
.SH EXAMPLE
.nf
/* get file descriptors from the transfers */
mc = curl_multi_fdset(multi_handle, &fdread, &fdwrite, &fdexcep, &maxfd);
if(mc != CURLM_OK) {
fprintf(stderr, "curl_multi_fdset() failed, code %d.\n", mc);
break;
}
/* wait for activity on one of the sockets */
rc = select(maxfd + 1, &fdread, &fdwrite, &fdexcep, &timeout);
.fi
.SH AVAILABILITY
Added in 7.9.6
.SH RETURN VALUE
CURLMcode type, general libcurl multi interface error code. See
\fIlibcurl-errors(3)\fP

6
docs/libcurl/curl_multi_info_read.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
@ -86,7 +86,9 @@ do {
}
} while(m);
.fi
.SH "RETURN VALUE"
.SH AVAILABILITY
Added in 7.9.6
.SH RETURN VALUE
A pointer to a filled-in struct, or NULL if it failed or ran out of
structs. It also writes the number of messages left in the queue (after this
read) in the integer the second argument points to.

13
docs/libcurl/curl_multi_init.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
@ -32,6 +32,17 @@ This function returns a CURLM handle to be used as input to all the other
multi-functions, sometimes referred to as a multi handle in some places in the
documentation. This init call MUST have a corresponding call to
\fIcurl_multi_cleanup(3)\fP when the operation is complete.
.SH EXAMPLE
.fi
/* init a multi stack */
multi_handle = curl_multi_init();
/* add individual transfers */
curl_multi_add_handle(multi_handle, http_handle);
curl_multi_add_handle(multi_handle, http_handle2);
.nf
.SH AVAILABILITY
Added in 7.9.6
.SH RETURN VALUE
If this function returns NULL, something went wrong and you cannot use the
other curl functions.

4
docs/libcurl/curl_multi_perform.3
View File

@ -70,7 +70,9 @@ do {
/* if there are still transfers, loop! */
} while(still_running);
.fi
.SH "RETURN VALUE"
.SH AVAILABILITY
Added in 7.9.6
.SH RETURN VALUE
CURLMcode type, general libcurl multi interface error code.
This function returns errors regarding the whole multi stack. Problems on

6
docs/libcurl/curl_multi_poll.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
@ -107,11 +107,11 @@ do {
curl_multi_remove_handle(multi_handle, easy_handle);
.fi
.SH AVAILABILITY
Added in libcurl 7.66.0.
.SH RETURN VALUE
CURLMcode type, general libcurl multi interface error code. See
\fIlibcurl-errors(3)\fP
.SH AVAILABILITY
This function was added in libcurl 7.66.0.
.SH "SEE ALSO"
.BR curl_multi_fdset "(3), " curl_multi_perform "(3), "
.BR curl_multi_wait "(3), " curl_multi_wakeup "(3)"

16
docs/libcurl/curl_multi_remove_handle.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,20 @@ other easy handles and transfers will remain unaffected.
It is fine to remove a handle at any time during a transfer, just not from
within any libcurl callback function.
.SH EXAMPLE
.nf
/* when an easy handle has completed, remove it */
msg = curl_multi_info_read(multi_handle, &queued);
if(msg) {
if(msg->msg == CURLMSG_DONE) {
/* a transfer ended */
fprintf(stderr, "Transfer completed\n");
curl_multi_remove_handle(multi_handle, msg->easy_handle);
}
}
.fi
.SH AVAILABILITY
Added in 7.9.6
.SH RETURN VALUE
CURLMcode type, general libcurl multi interface error code.
.SH "SEE ALSO"

9
docs/libcurl/curl_multi_setopt.3
View File

@ -69,12 +69,17 @@ See \fICURLMOPT_TIMERFUNCTION(3)\fP
See \fICURLMOPT_TIMERDATA(3)\fP
.IP CURLMOPT_MAX_CONCURRENT_STREAMS
See \fICURLMOPT_MAX_CONCURRENT_STREAMS(3)\fP
.SH EXAMPLE
.fi
/* Limit the amount of simultaneous connections curl should allow: */
curl_multi_setopt(handle, CURLMOPT_MAXCONNECTS, (long)MAX_PARALLEL);
.nf
.SH AVAILABILITY
Added in libcurl 7.15.4.
.SH RETURN VALUE
The standard CURLMcode for multi interface error codes. Note that it returns a
CURLM_UNKNOWN_OPTION if you try setting an option that this version of libcurl
doesn't know of.
.SH AVAILABILITY
This function was added in libcurl 7.15.4.
.SH "SEE ALSO"
.BR curl_multi_cleanup "(3), " curl_multi_init "(3), "
.BR curl_multi_socket "(3), " curl_multi_info_read "(3)"

33
docs/libcurl/curl_multi_socket.3
View File

@ -66,17 +66,14 @@ equivalent to \fIcurl_multi_socket_action(3)\fP with \fBev_bitmask\fP set to
Force libcurl to (re-)check all its internal sockets and transfers instead of
just a single one by calling \fIcurl_multi_socket_all(3)\fP. Note that there
should not be any reason to use this function!
.SH "CALLBACK DETAILS"
.SH CALLBACK
The socket \fBcallback\fP function uses a prototype like this
.nf
int curl_socket_callback(CURL *easy, /* easy handle */
curl_socket_t s, /* socket */
int action, /* see values below */
void *userp, /* private callback pointer */
void *socketp); /* private socket pointer */
.fi
The callback MUST return 0.
@ -109,22 +106,6 @@ strictly associated to the given socket.
The \fIuserp\fP argument is a private pointer you have previously set with
\fIcurl_multi_setopt(3)\fP and the \fICURLMOPT_SOCKETDATA(3)\fP option.
.SH "RETURN VALUE"
CURLMcode type, general libcurl multi interface error code.
Legacy: If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this basically means
that you should call \fIcurl_multi_socket(3)\fP again, before you wait for
more actions on libcurl's sockets. You don't have to do it immediately, but
the return code means that libcurl may have more data available to return or
that there may be more data to send off before it is "satisfied".
In modern libcurls, \fICURLM_CALL_MULTI_PERFORM\fP or
\fICURLM_CALL_MULTI_SOCKET\fP should not be returned and no application needs
to care about them.
NOTE that the return code is for the whole multi stack. Problems still might have
occurred on individual transfers even when one of these functions
return OK.
.SH "TYPICAL USAGE"
1. Create a multi handle
@ -147,12 +128,24 @@ socket(s) that got action. If no activity is detected and the timeout expires,
call \fIcurl_multi_socket_action(3)\fP with \fICURL_SOCKET_TIMEOUT\fP
8. Go back to step 6.
.SH EXAMPLE
.nf
/* the event-library gets told when there activity on the socket 'fd',
which we translate to a call to curl_multi_socket_action() */
int running;
rc = curl_multi_socket(multi_handle, fd, &running);
.fi
.SH AVAILABILITY
This function was added in libcurl 7.15.4, and is deemed stable since
7.16.0.
\fIcurl_multi_socket(3)\fP is deprecated, use
\fIcurl_multi_socket_action(3)\fP instead!
.SH "RETURN VALUE"
CURLMcode type, general libcurl multi interface error code.
The return code is for the whole multi stack. Problems still might have
occurred on individual transfers even when one of these functions return OK.
.SH "SEE ALSO"
.BR curl_multi_cleanup "(3), " curl_multi_init "(3), "
.BR curl_multi_fdset "(3), " curl_multi_info_read "(3), "

12
docs/libcurl/curl_multi_socket_action.3
View File

@ -88,11 +88,19 @@ callback has been told.
8, When activity is detected, call curl_multi_socket_action() for the
socket(s) that got action. If no activity is detected and the timeout expires,
call \fIcurl_multi_socket_action(3)\fP with \fICURL_SOCKET_TIMEOUT\fP.
.SH EXAMPLE
.nf
/* the event-library gets told when there activity on the socket 'fd',
which we translate to a call to curl_multi_socket_action() */
int running;
rc = curl_multi_socket_action(multi_handle, fd, EVENT,
&running);
.fi
.SH AVAILABILITY
This function was added in libcurl 7.15.4, and is deemed stable since 7.16.0.
.SH RETURN VALUE
CURLMcode type, general libcurl multi interface error code. See
\fIlibcurl-errors(3)\fP
.SH AVAILABILITY
This function was added in libcurl 7.15.4, and is deemed stable since 7.16.0.
.SH "SEE ALSO"
.BR curl_multi_cleanup "(3), " curl_multi_init "(3), "
.BR curl_multi_fdset "(3), " curl_multi_info_read "(3), "

8
docs/libcurl/curl_multi_strerror.3
View File

@ -29,6 +29,14 @@ curl_multi_strerror - return string describing error code
.SH DESCRIPTION
The curl_multi_strerror() function returns a string describing the CURLMcode
error code passed in the argument \fIerrornum\fP.
.SH EXAMPLE
.nf
int still_running;
CURLMcode mc = curl_multi_perform(multi_handle, &still_running);
if(mc)
printf("error: %s\n", curl_multi_strerror(mc));
.fi
.SH AVAILABILITY
This function was added in libcurl 7.12.0
.SH RETURN VALUE

8
docs/libcurl/curl_multi_timeout.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
@ -65,14 +65,14 @@ timeout.tv_usec = (timeo % 1000) * 1000;
/* wait for activities no longer than the set timeout */
select(maxfd+1, &fdread, &fdwrite, &fdexcep, &timeout);
.fi
.SH "RETURN VALUE"
The standard CURLMcode for multi interface error codes.
.SH "TYPICAL USAGE"
.SH TYPICAL USAGE
Call \fIcurl_multi_timeout(3)\fP, then wait for action on the sockets. You
figure out which sockets to wait for by calling \fIcurl_multi_fdset(3)\fP or
by a previous call to \fIcurl_multi_socket(3)\fP.
.SH AVAILABILITY
This function was added in libcurl 7.15.4.
.SH RETURN VALUE
The standard CURLMcode for multi interface error codes.
.SH "SEE ALSO"
.BR curl_multi_fdset "(3), " curl_multi_info_read "(3), "
.BR curl_multi_socket "(3), " curl_multi_setopt "(3) "

6
docs/libcurl/curl_multi_wait.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
@ -114,10 +114,10 @@ do {
curl_multi_remove_handle(multi_handle, easy_handle);
.fi
.SH AVAILABILITY
This function was added in libcurl 7.28.0.
.SH RETURN VALUE
CURLMcode type, general libcurl multi interface error code. See
\fIlibcurl-errors(3)\fP
.SH AVAILABILITY
This function was added in libcurl 7.28.0.
.SH "SEE ALSO"
.BR curl_multi_fdset "(3), " curl_multi_perform "(3)", curl_multi_poll "(3) ",

10
docs/libcurl/curl_multi_wakeup.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
@ -41,10 +41,6 @@ possible that multiple calls to this function will wake up the same waiting
operation.
This function has no effect on \fIcurl_multi_wait(3)\fP calls.
.SH RETURN VALUE
CURLMcode type, general libcurl multi interface error code.
.SH AVAILABILITY
Added in 7.68.0
.SH EXAMPLE
.nf
CURL *easy_handle;
@ -82,5 +78,9 @@ if(something makes us decide to stop thread 1) {
}
.fi
.SH AVAILABILITY
Added in 7.68.0
.SH RETURN VALUE
CURLMcode type, general libcurl multi interface error code.
.SH "SEE ALSO"
.BR curl_multi_poll "(3), " curl_multi_wait "(3)"

12
docs/libcurl/curl_share_cleanup.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
@ -33,6 +33,16 @@ when this function has been called.
Passing in a NULL pointer in \fIshare_handle\fP will make this function return
immediately with no action.
.SH EXAMPLE
.nf
CURLSHcode sh
share = curl_share_init();
sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT);
/* use the share, then ... */
curl_share_cleanup(share);
.fi
.SH AVAILABILITY
Added in libcurl 7.10
.SH RETURN VALUE
CURLSHE_OK (zero) means that the option was set properly, non-zero means an
error occurred as \fI<curl/curl.h>\fP defines. See the \fIlibcurl-errors.3\fP

12
docs/libcurl/curl_share_init.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,6 +36,16 @@ documentation. This init call MUST have a corresponding call to
This \fIshare handle\fP is what you pass to curl using the
\fICURLOPT_SHARE(3)\fP option with \fIcurl_easy_setopt(3)\fP, to make that
specific curl handle use the data in this share.
.SH EXAMPLE
.nf
CURLSHcode sh
share = curl_share_init();
sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT);
if(sh)
printf("Error: %s\n", curl_share_strerror(sh));
.fi
.SH AVAILABILITY
Added in libcurl 7.10
.SH RETURN VALUE
If this function returns NULL, something went wrong (out of memory, etc.)
and therefore the share object was not created.

12
docs/libcurl/curl_share_setopt.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
@ -106,6 +106,16 @@ the same as those for \fICURLSHOPT_SHARE\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.
.SH EXAMPLE
.nf
CURLSHcode sh
share = curl_share_init();
sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT);
if(sh)
printf("Error: %s\n", curl_share_strerror(sh));
.fi
.SH AVAILABILITY
Added in libcurl 7.10
.SH RETURN VALUE
CURLSHE_OK (zero) means that the option was set properly, non-zero means an
error occurred as \fI<curl/curl.h>\fP defines. See the \fIlibcurl-errors.3\fP

8
docs/libcurl/curl_share_strerror.3
View File

@ -29,6 +29,14 @@ curl_share_strerror - return string describing error code
.SH DESCRIPTION
The curl_share_strerror() function returns a string describing the CURLSHcode
error code passed in the argument \fIerrornum\fP.
.SH EXAMPLE
.nf
CURLSHcode sh
share = curl_share_init();
sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT);
if(sh)
printf("Error: %s\n", curl_share_strerror(sh));
.fi
.SH AVAILABILITY
This function was added in libcurl 7.12.0
.SH RETURN VALUE

14
docs/libcurl/curl_slist_append.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
@ -37,11 +37,6 @@ returns. \fIcurl_slist_append(3)\fP copies the string.
The list should be freed again (after usage) with
\fIcurl_slist_free_all(3)\fP.
.SH RETURN VALUE
A null pointer is returned if anything went wrong, otherwise the new list
pointer is returned. To avoid overwriting an existing non-empty list on
failure, the new list should be returned to a temporary variable which can
be tested for NULL before updating the original list pointer.
.SH EXAMPLE
.nf
CURL *handle;
@ -68,5 +63,12 @@ curl_easy_perform(handle);
curl_slist_free_all(slist); /* free the list again */
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
A null pointer is returned if anything went wrong, otherwise the new list
pointer is returned. To avoid overwriting an existing non-empty list on
failure, the new list should be returned to a temporary variable which can
be tested for NULL before updating the original list pointer.
.SH "SEE ALSO"
.BR curl_slist_free_all "(3), "

8
docs/libcurl/curl_slist_free_all.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
@ -33,8 +33,6 @@ linked list.
Passing in a NULL pointer in \fIlist\fP will make this function return
immediately with no action.
.SH RETURN VALUE
Nothing.
.SH EXAMPLE
.nf
CURL *handle;
@ -51,5 +49,9 @@ curl_easy_perform(handle);
curl_slist_free_all(slist); /* free the list again */
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Nothing.
.SH "SEE ALSO"
.BR curl_slist_append "(3), "

9
docs/libcurl/curl_strequal.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
@ -41,6 +41,13 @@ first \fIlen\fP characters of \fIstr1\fP.
These functions are provided by libcurl to enable applications to compare
strings in a truly portable manner. There are no standard portable case
insensitive string comparison functions. These two work on all platforms.
.SH EXAMPLE
.nf
if(curl_strequal(name, input))
printf("Name and input matches\n");
if(curl_strnequal(name, input, 5))
printf("Name and input matches in the 5 first bytes\n");
.fi
.SH AVAILABILITY
These functions will be removed from the public libcurl API in a near
future. They will instead be made "available" by source code access only, and

16
docs/libcurl/curl_unescape.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,20 @@ If the 'length' argument is set to 0, curl_unescape() will use strlen() on the
input 'url' string to find out the size.
You must \fIcurl_free(3)\fP the returned string when you're done with it.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
int decodelen;
char *decoded = curl_unescape("%63%75%72%6c", 12, &decodelen);
if(decoded) {
/* don't assume printf() works on the decoded data! */
printf("Decoded: ");
/* ... */
curl_free(decoded);
}
}
.fi
.SH AVAILABILITY
Since 7.15.4, \fIcurl_easy_unescape(3)\fP should be used. This function will
be removed in a future release.

4
docs/libcurl/curl_url.3
View File

@ -29,8 +29,6 @@ CURLU *curl_url();
.SH DESCRIPTION
This function will allocates and returns a pointer to a fresh CURLU handle, to
be used for further use of the URL API.
.SH RETURN VALUE
Returns a \fBCURLU *\fP if successful, or NULL if out of memory.
.SH EXAMPLE
.nf
CURLUcode rc;
@ -48,6 +46,8 @@ Returns a \fBCURLU *\fP if successful, or NULL if out of memory.
.fi
.SH AVAILABILITY
Added in curl 7.62.0
.SH RETURN VALUE
Returns a \fBCURLU *\fP if successful, or NULL if out of memory.
.SH "SEE ALSO"
.BR curl_url_cleanup "(3), " curl_url_get "(3), " curl_url_set "(3), "
.BR curl_url_dup "(3), " curl_url_strerror "(3), " CURLOPT_CURLU "(3)"

4
docs/libcurl/curl_url_cleanup.3
View File

@ -29,8 +29,6 @@ void curl_url_cleanup(CURLU *handle);
.fi
.SH DESCRIPTION
Frees all the resources associated with the given CURLU handle!
.SH RETURN VALUE
none
.SH EXAMPLE
.nf
CURLU *url = curl_url();
@ -39,6 +37,8 @@ none
.fi
.SH AVAILABILITY
Added in curl 7.62.0
.SH RETURN VALUE
none
.SH "SEE ALSO"
.BR curl_url_dup "(3), " curl_url "(3), " curl_url_set "(3), "
.BR curl_url_get "(3), " CURLOPT_CURLU "(3), "

4
docs/libcurl/curl_url_dup.3
View File

@ -31,8 +31,6 @@ CURLU *curl_url_dup(CURLU *inhandle);
Duplicates a given CURLU \fIinhandle\fP and all its contents and returns a
pointer to a new CURLU handle. The new handle also needs to be freed with
\fIcurl_url_cleanup(3)\fP.
.SH RETURN VALUE
Returns a new handle or NULL if out of memory.
.SH EXAMPLE
.nf
CURLUcode rc;
@ -47,6 +45,8 @@ Returns a new handle or NULL if out of memory.
.fi
.SH AVAILABILITY
Added in curl 7.62.0
.SH RETURN VALUE
Returns a new handle or NULL if out of memory.
.SH "SEE ALSO"
.BR curl_url_cleanup "(3), " curl_url "(3), " curl_url_set "(3), "
.BR curl_url_get "(3), " CURLOPT_CURLU "(3), "

12
docs/libcurl/curl_url_get.3
View File

@ -105,12 +105,6 @@ A zero-length query will lead \fIpart\fP to be set to a zero-length string.
The query part will also get pluses converted to space when asked to URL
decode on get with the CURLU_URLDECODE bit.
.IP CURLUPART_FRAGMENT
.SH RETURN VALUE
Returns a CURLUcode error value, which is CURLUE_OK (0) if everything went
fine. See the \fIlibcurl-errors(3)\fP man page for the full list with
descriptions.
If this function returns an error, no URL part is returned.
.SH EXAMPLE
.nf
CURLUcode rc;
@ -128,6 +122,12 @@ If this function returns an error, no URL part is returned.
.fi
.SH AVAILABILITY
Added in curl 7.62.0. CURLUPART_ZONEID was added in 7.65.0.
.SH RETURN VALUE
Returns a CURLUcode error value, which is CURLUE_OK (0) if everything went
fine. See the \fIlibcurl-errors(3)\fP man page for the full list with
descriptions.
If this function returns an error, no URL part is returned.
.SH "SEE ALSO"
.BR curl_url_cleanup "(3), " curl_url "(3), " curl_url_set "(3), "
.BR curl_url_dup "(3), " curl_url_strerror "(3), " CURLOPT_CURLU "(3)"

20
docs/libcurl/curl_url_set.3
View File

@ -134,16 +134,6 @@ When space is used and allowed in a URL, it will be stored as-is unless
space before stored. This affects how the URL will be constructed when
\fIcurl_url_get(3)\fP is subsequently used to extract the full URL or
individual parts.
.SH RETURN VALUE
Returns a CURLUcode error value, which is CURLUE_OK (0) if everything went
fine. See the \fIlibcurl-errors(3)\fP man page for the full list with
descriptions.
A URL string passed on to \fIcurl_url_set(3)\fP for the \fBCURLUPART_URL\fP
part, must be shorter than 8000000 bytes otherwise it returns
\fBCURLUE_MALFORMED_INPUT\fP (added in 7.65.0).
If this function returns an error, no URL part is set.
.SH EXAMPLE
.nf
CURLUcode rc;
@ -158,6 +148,16 @@ If this function returns an error, no URL part is set.
.fi
.SH AVAILABILITY
Added in curl 7.62.0. CURLUPART_ZONEID was added in 7.65.0.
.SH RETURN VALUE
Returns a CURLUcode error value, which is CURLUE_OK (0) if everything went
fine. See the \fIlibcurl-errors(3)\fP man page for the full list with
descriptions.
A URL string passed on to \fIcurl_url_set(3)\fP for the \fBCURLUPART_URL\fP
part, must be shorter than 8000000 bytes otherwise it returns
\fBCURLUE_MALFORMED_INPUT\fP (added in 7.65.0).
If this function returns an error, no URL part is set.
.SH "SEE ALSO"
.BR curl_url_cleanup "(3), " curl_url "(3), " curl_url_get "(3), "
.BR curl_url_dup "(3), " curl_url_strerror "(3), " CURLOPT_CURLU "(3)"

12
docs/libcurl/curl_url_strerror.3
View File

@ -29,8 +29,18 @@ curl_url_strerror - return string describing error code
.SH DESCRIPTION
The curl_url_strerror() function returns a string describing the CURLUcode
error code passed in the argument \fIerrornum\fP.
.SH EXAMPLE
.nf
CURLUcode rc;
CURLU *url = curl_url();
rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
if(rc)
printf("URL error: %s\n", curl_url_strerror(rc));
curl_url_cleanup(url);
.fi
.SH AVAILABILITY
This function was added in libcurl 7.80.0
Added in libcurl 7.80.0
.SH RETURN VALUE
A pointer to a null-terminated string.
.SH "SEE ALSO"

9
docs/libcurl/curl_version.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
@ -32,6 +32,13 @@ Returns a human readable string with the version number of libcurl and some of
its important components (like OpenSSL version).
We recommend using \fIcurl_version_info(3)\fP instead!
.SH EXAMPLE
.nf
printf("libcurl version %s\n", curl_version());
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
A pointer to a null-terminated string. The string resides in a statically
allocated buffer and must not be freed by the caller.

10
docs/libcurl/curl_version_info.3
View File

@ -223,6 +223,16 @@ libcurl has no libz support, this is NULL.
names protocols that libcurl supports (using lowercase letters). The protocol
names are the same as would be used in URLs. The array is terminated by a NULL
entry.
.SH EXAMPLE
.nf
curl_version_info_data *ver = curl_version_info(CURLVERSION_NOW);
printf("libcurl version %u.%u.%u\n",
(ver->version_num >> 16) & 0xff,
(ver->version_num >> 8) & 0xff,
ver->version_num & 0xff,
.fi
.SH AVAILABILITY
Added in libcurl 7.10
.SH RETURN VALUE
A pointer to a curl_version_info_data struct.
.SH "SEE ALSO"

40
tests/manpage-syntax.pl
View File

@ -35,8 +35,9 @@ my $symbolsinversions=shift @ARGV;
my @manpages=@ARGV;
my $errors = 0;
my %blessed;
my @order = (
my %optblessed;
my %funcblessed;
my @optorder = (
'NAME',
'SYNOPSIS',
'DESCRIPTION',
@ -47,6 +48,15 @@ my @order = (
'RETURN VALUE',
'SEE ALSO'
);
my @funcorder = (
'NAME',
'SYNOPSIS',
'DESCRIPTION',
'EXAMPLE',
'AVAILABILITY',
'RETURN VALUE',
'SEE ALSO'
);
my %shline; # section => line number
my %symbol;
@ -67,16 +77,25 @@ sub scanmanpage {
my $inex = 0;
my $exsize = 0;
my $shc = 0;
my $optpage = 0; # option or function
my @sh;
open(M, "<$file") || die "no such file: $file";
if($file =~ /[\/\\]CURL[^\/\\]*.3/) {
if($file =~ /[\/\\](CURL|curl_)[^\/\\]*.3/) {
# This is the man page for an libcurl option. It requires an example!
$reqex = 1;
if($1 eq "CURL") {
$optpage = 1;
}
}
my $line = 1;
while(<M>) {
chomp;
if($_ =~ /^.so /) {
# this man page is just a referral
close(M);
return;
}
if($_ =~ /^\.SH EXAMPLE/i) {
$inex = 1;
}
@ -142,12 +161,15 @@ sub scanmanpage {
my $i = 0;
my $shused = 1;
my @shorig = @sh;
my @order = $optpage ? @optorder : @funcorder;
my $blessed = $optpage ? \%optblessed : \%funcblessed;
while($got) {
my $finesh;
$got = shift(@sh);
if($got) {
if($blessed{$got}) {
$i = $blessed{$got};
if($$blessed{$got}) {
$i = $$blessed{$got};
$finesh = $got; # a mandatory one
}
}
@ -189,8 +211,12 @@ if(!$symbol{'CURLALTSVC_H1'}) {
}
my $ind = 1;
for my $s (@order) {
$blessed{$s} = $ind++
for my $s (@optorder) {
$optblessed{$s} = $ind++
}
$ind = 1;
for my $s (@funcorder) {
$funcblessed{$s} = $ind++
}
for my $m (@manpages) {