docs/libcurl/curl_easy_cleanup.3+5 -7
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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), " |
docs/libcurl/curl_easy_duphandle.3+16 -1
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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. |
docs/libcurl/curl_easy_escape.3+5 -5
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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 |
docs/libcurl/curl_easy_getinfo.3+22 -0
| @@ -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. |
docs/libcurl/curl_easy_init.3+5 -3
| @@ -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) " |
docs/libcurl/curl_easy_option_by_id.3+8 -1
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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 |
docs/libcurl/curl_easy_option_by_name.3+8 -1
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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 |
docs/libcurl/curl_easy_option_next.3+11 -1
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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 |
docs/libcurl/curl_easy_pause.3+12 -7
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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)" |
docs/libcurl/curl_easy_perform.3+8 -6
| @@ -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), " |
docs/libcurl/curl_easy_recv.3+16 -3
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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), " |
docs/libcurl/curl_easy_reset.3+9 -1
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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 |
docs/libcurl/curl_easy_send.3+16 -3
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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) " |
docs/libcurl/curl_easy_setopt.3+12 -10
| @@ -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), " |
docs/libcurl/curl_easy_strerror.3+9 -0
| @@ -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 |
docs/libcurl/curl_easy_unescape.3+15 -1
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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 |
docs/libcurl/curl_easy_upkeep.3+10 -10
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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), " |
docs/libcurl/curl_escape.3+9 -1
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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. |
docs/libcurl/curl_formadd.3+12 -14
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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)," |
docs/libcurl/curl_formfree.3+17 -1
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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 |
docs/libcurl/curl_formget.3+3 -4
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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)" |
docs/libcurl/curl_free.3+10 -0
| @@ -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" |
docs/libcurl/curl_getdate.3+31 -28
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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. |
docs/libcurl/curl_getenv.3+8 -0
| @@ -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 |
docs/libcurl/curl_global_cleanup.3+10 -0
| @@ -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" |
docs/libcurl/curl_global_init.3+11 -1
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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. |
docs/libcurl/curl_global_init_mem.3+9 -3
| @@ -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), " |
docs/libcurl/curl_global_sslset.3+15 -2
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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. |
docs/libcurl/curl_mime_addpart.3+5 -5
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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)," |
docs/libcurl/curl_mime_data.3+5 -5
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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)," |
docs/libcurl/curl_mime_data_cb.3+4 -5
| @@ -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)," |
docs/libcurl/curl_mime_encoder.3+6 -6
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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)," |
docs/libcurl/curl_mime_filedata.3+8 -8
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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)," |
docs/libcurl/curl_mime_filename.3+5 -5
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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)," |
docs/libcurl/curl_mime_free.3+11 -1
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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 |
docs/libcurl/curl_mime_headers.3+5 -5
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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)" |
docs/libcurl/curl_mime_init.3+4 -7
| @@ -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)," |
docs/libcurl/curl_mime_name.3+5 -5
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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)," |
docs/libcurl/curl_mime_subparts.3+23 -3
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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)" |
docs/libcurl/curl_mime_type.3+5 -5
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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)," |
docs/libcurl/curl_mprintf.3+5 -0
| @@ -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. |
docs/libcurl/curl_multi_add_handle.3+12 -1
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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" |
docs/libcurl/curl_multi_assign.3+10 -5
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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) " |
docs/libcurl/curl_multi_cleanup.3+10 -1
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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. |
docs/libcurl/curl_multi_fdset.3+16 -1
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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 |
docs/libcurl/curl_multi_info_read.3+4 -2
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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. |
docs/libcurl/curl_multi_init.3+12 -1
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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. |
docs/libcurl/curl_multi_perform.3+3 -1
| @@ -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 |
docs/libcurl/curl_multi_poll.3+3 -3
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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)" |
docs/libcurl/curl_multi_remove_handle.3+15 -1
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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" |
docs/libcurl/curl_multi_setopt.3+7 -2
| @@ -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)" |
docs/libcurl/curl_multi_socket.3+13 -20
| @@ -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), " |
docs/libcurl/curl_multi_socket_action.3+10 -2
| @@ -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), " |
docs/libcurl/curl_multi_strerror.3+8 -0
| @@ -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 |
docs/libcurl/curl_multi_timeout.3+4 -4
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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) " |
docs/libcurl/curl_multi_wait.3+3 -3
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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) ", |
docs/libcurl/curl_multi_wakeup.3+5 -5
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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)" |
docs/libcurl/curl_share_cleanup.3+11 -1
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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 |
docs/libcurl/curl_share_init.3+11 -1
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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. |
docs/libcurl/curl_share_setopt.3+11 -1
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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 |
docs/libcurl/curl_share_strerror.3+8 -0
| @@ -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 |
docs/libcurl/curl_slist_append.3+8 -6
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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), " |
docs/libcurl/curl_slist_free_all.3+5 -3
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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), " |
docs/libcurl/curl_strequal.3+8 -1
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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 |
docs/libcurl/curl_unescape.3+15 -1
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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. |
docs/libcurl/curl_url.3+2 -2
| @@ -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)" |
docs/libcurl/curl_url_cleanup.3+2 -2
| @@ -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), " |
docs/libcurl/curl_url_dup.3+2 -2
| @@ -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), " |
docs/libcurl/curl_url_get.3+6 -6
| @@ -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)" |
docs/libcurl/curl_url_set.3+10 -10
| @@ -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)" |
docs/libcurl/curl_url_strerror.3+11 -1
| @@ -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" |
docs/libcurl/curl_version.3+8 -1
| @@ -5,7 +5,7 @@ |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| - | .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <[email protected]>, et al. |
| + | .\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <[email protected]>, 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. |
docs/libcurl/curl_version_info.3+10 -0
| @@ -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" |
tests/manpage-syntax.pl+33 -7
| @@ -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) { |