.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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();
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), "
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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.
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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();
}
}
.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
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.
\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();
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) "
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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
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
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)"
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();
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), "
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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
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), "
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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
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) "
.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
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), "
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
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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();
/* 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), "
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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.
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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";
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),"
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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);
.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)"
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"
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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.
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
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"
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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.
.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), "
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
\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.
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.
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
\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;
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),"
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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;
/* 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),"
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
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),"
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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:
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;
/* 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),"
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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;
/* 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),"
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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;
/* 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),"
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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;
/* 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)"
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;
/* 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),"
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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;
/* 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),"
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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)"
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
- 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;
/* 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),"
.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.
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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"
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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.
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) "
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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.
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
}
} 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.
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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.
/* 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
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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)"
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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"
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)"
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.
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
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), "
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), "
.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
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
/* 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) "
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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) ",
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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;
}
.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)"
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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.
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
.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
.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
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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;
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), "
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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;
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), "
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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.
.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;
.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)"
.fi
.SH DESCRIPTION
Frees all the resources associated with the given CURLU handle!
-.SH RETURN VALUE
-none
.SH EXAMPLE
.nf
CURLU *url = curl_url();
.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), "
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;
.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), "
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;
.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)"
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;
.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)"
.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"
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
-.\" * 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
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.
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"
my @manpages=@ARGV;
my $errors = 0;
-my %blessed;
-my @order = (
+my %optblessed;
+my %funcblessed;
+my @optorder = (
'NAME',
'SYNOPSIS',
'DESCRIPTION',
'RETURN VALUE',
'SEE ALSO'
);
+my @funcorder = (
+ 'NAME',
+ 'SYNOPSIS',
+ 'DESCRIPTION',
+ 'EXAMPLE',
+ 'AVAILABILITY',
+ 'RETURN VALUE',
+ 'SEE ALSO'
+ );
my %shline; # section => line number
my %symbol;
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;
}
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
}
}
}
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) {
projects / thirdparty / curl.git / commitdiff
