share/man/man3/CURLOPT_GSSAPI_DELEGATION.3 0000644 00000004646 14751150677 0013263 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_GSSAPI_DELEGATION 3 "October 22, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_GSSAPI_DELEGATION \- allowed GSS-API delegation
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_GSSAPI_DELEGATION, long level);
.fi
.SH DESCRIPTION
Set the long parameter \fIlevel\fP to \fBCURLGSSAPI_DELEGATION_FLAG\fP to
allow unconditional GSSAPI credential delegation. The delegation is disabled
by default since 7.21.7. Set the parameter to
\fBCURLGSSAPI_DELEGATION_POLICY_FLAG\fP to delegate only if the OK-AS-DELEGATE
flag is set in the service ticket in case this feature is supported by the
GSS-API implementation and the definition of \fIGSS_C_DELEG_POLICY_FLAG\fP was
available at compile-time.
.SH DEFAULT
CURLGSSAPI_DELEGATION_NONE
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode ret;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
/* delegate if okayed by policy */
curl_easy_setopt(curl, CURLOPT_GSSAPI_DELEGATION,
(long)CURLGSSAPI_DELEGATION_POLICY_FLAG);
ret = curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.22.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_HTTPAUTH "(3), " CURLOPT_PROXYAUTH "(3), "
share/man/man3/CURLOPT_LOGIN_OPTIONS.3 0000644 00000005055 14751150677 0012660 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_LOGIN_OPTIONS 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_LOGIN_OPTIONS \- login options
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_LOGIN_OPTIONS, char *options);
.fi
.SH DESCRIPTION
Pass a char * as parameter, which should be pointing to the null-terminated
\fIoptions\fP string to use for the transfer.
For more information about the login options please see RFC2384, RFC5092 and
the IETF draft \fBdraft-earhart-url-smtp-00.txt\fP.
\fICURLOPT_LOGIN_OPTIONS(3)\fP can be used to set protocol specific login
options, such as the preferred authentication mechanism via "AUTH=NTLM" or
"AUTH=*", and should be used in conjunction with the \fICURLOPT_USERNAME(3)\fP
option.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
Only IMAP, LDAP, POP3 and SMTP support login options.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "smtp://example.com/");
curl_easy_setopt(curl, CURLOPT_LOGIN_OPTIONS, "AUTH=*");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.34.0. Support for OpenLDAP added in 7.82.0.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_USERNAME "(3), " CURLOPT_PASSWORD "(3), "
share/man/man3/CURLOPT_PROXY_ISSUERCERT.3 0000644 00000006230 14751150677 0013262 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXY_ISSUERCERT 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXY_ISSUERCERT \- proxy issuer SSL certificate filename
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_ISSUERCERT, char *file);
.fi
.SH DESCRIPTION
Pass a char * to a null-terminated string naming a \fIfile\fP holding a CA
certificate in PEM format. If the option is set, an additional check against
the peer certificate is performed to verify the issuer of the the HTTPS proxy
is indeed the one associated with the certificate provided by the option.
This additional check is useful in multi-level PKI where one needs to enforce
that the peer certificate is from a specific branch of the tree.
This option makes sense only when used in combination with the
\fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP option. Otherwise, the result of the
check is not considered as failure.
A specific error code (CURLE_SSL_ISSUER_ERROR) is defined with the option,
which is returned if the setup of the SSL/TLS session has failed due to a
mismatch with the issuer of peer certificate
(\fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP has to be set too for the check to
fail).
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
All TLS-based protocols
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
/* using an HTTPS proxy */
curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost:443");
curl_easy_setopt(curl, CURLOPT_PROXY_ISSUERCERT, "/etc/certs/cacert.pem");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.71.0. This option is supported by the OpenSSL backends.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_PROXY_SSL_VERIFYPEER "(3), " CURLOPT_PROXY_SSL_VERIFYHOST "(3), "
.BR CURLOPT_SSL_VERIFYPEER "(3), " CURLOPT_SSL_VERIFYHOST "(3), "
share/man/man3/CURLINFO_RTSP_SERVER_CSEQ.3 0000644 00000004347 14751150677 0013362 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_RTSP_SERVER_CSEQ 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_RTSP_SERVER_CSEQ \- get the next RTSP server CSeq
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_RTSP_SERVER_CSEQ,
long *cseq);
.fi
.SH DESCRIPTION
Pass a pointer to a long to receive the next CSeq that will be expected by the
application.
Listening for server initiated requests is not implemented!
Applications wishing to resume an RTSP session on another connection should
retrieve this info before closing the active connection.
.SH PROTOCOLS
RTSP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res;
curl_easy_setopt(curl, CURLOPT_URL, "rtsp://rtsp.example.com");
res = curl_easy_perform(curl);
if(res == CURLE_OK) {
long cseq;
curl_easy_getinfo(curl, CURLINFO_RTSP_SERVER_CSEQ, &cseq);
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.20.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
share/man/man3/CURLOPT_SSL_VERIFYHOST.3 0000644 00000007545 14751150677 0013026 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SSL_VERIFYHOST 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSL_VERIFYHOST \- verify the certificate's name against host
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_VERIFYHOST, long verify);
.fi
.SH DESCRIPTION
Pass a long as parameter specifying what to \fIverify\fP.
This option determines whether libcurl verifies that the server cert is for
the server it is known as.
When negotiating TLS and SSL connections, the server sends a certificate
indicating its identity.
When \fICURLOPT_SSL_VERIFYHOST(3)\fP is 2, that certificate must indicate that
the server is the server to which you meant to connect, or the connection
fails. Simply put, it means it has to have the same name in the certificate as
is in the URL you operate against.
Curl considers the server the intended one when the Common Name field or a
Subject Alternate Name field in the certificate matches the host name in the
URL to which you told Curl to connect.
If \fIverify\fP value is set to 1:
In 7.28.0 and earlier: treated as a debug option of some sorts, not supported
anymore due to frequently leading to programmer mistakes.
From 7.28.1 to 7.65.3: setting it to 1 made curl_easy_setopt() return an error
and leaving the flag untouched.
From 7.66.0: treats 1 and 2 the same.
When the \fIverify\fP value is 0, the connection succeeds regardless of the
names in the certificate. Use that ability with caution!
The default value for this option is 2.
This option controls checking the server's certificate's claimed identity.
The server could be lying. To control lying, see
\fICURLOPT_SSL_VERIFYPEER(3)\fP.
.SH LIMITATIONS
Secure Transport: If \fIverify\fP value is 0, then SNI is also disabled. SNI is
a TLS extension that sends the hostname to the server. The server may use that
information to do such things as sending back a specific certificate for the
hostname, or forwarding the request to a specific origin server. Some hostnames
may be inaccessible if SNI is not sent.
NSS: If \fICURLOPT_SSL_VERIFYPEER(3)\fP is zero,
\fICURLOPT_SSL_VERIFYHOST(3)\fP is also set to zero and cannot be overridden.
.SH DEFAULT
2
.SH PROTOCOLS
All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* Set the default value: strict name check please */
curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 2L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
If built TLS enabled.
.SH RETURN VALUE
Returns CURLE_OK if TLS is supported, and CURLE_UNKNOWN_OPTION if not.
If 1 is set as argument, \fICURLE_BAD_FUNCTION_ARGUMENT\fP is returned.
.SH "SEE ALSO"
.BR CURLOPT_SSL_VERIFYPEER "(3), " CURLOPT_CAINFO "(3), "
share/man/man3/CURLOPT_PROXY_SERVICE_NAME.3 0000644 00000004462 14751150677 0013477 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXY_SERVICE_NAME 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXY_SERVICE_NAME \- proxy authentication service name
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SERVICE_NAME,
char *name);
.fi
.SH DESCRIPTION
Pass a char * as parameter to a string holding the \fIname\fP of the
service. The default service name is \fB"HTTP"\fP for HTTP based proxies and
\fB"rcmd"\fP for SOCKS5. This option allows you to change it.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
See above
.SH PROTOCOLS
All network protocols
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode ret;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_PROXY_SERVICE_NAME, "custom");
ret = curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.43.0 for HTTP proxies, 7.49.0 for SOCKS5 proxies.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_PROXY "(3), " CURLOPT_PROXYTYPE "(3), "
share/man/man3/CURLOPT_DEBUGDATA.3 0000644 00000004421 14751150677 0012051 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_DEBUGDATA 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_DEBUGDATA \- pointer passed to the debug callback
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DEBUGDATA, void *pointer);
.fi
.SH DESCRIPTION
Pass a \fIpointer\fP to whatever you want passed in to your
\fICURLOPT_DEBUGFUNCTION(3)\fP in the last void * argument. This pointer is
not used by libcurl, it is only passed to the callback.
.SH DEFAULT
NULL
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
int main(void)
{
CURL *curl;
CURLcode res;
struct data my_tracedata;
curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_DEBUGFUNCTION, my_trace);
curl_easy_setopt(curl, CURLOPT_DEBUGDATA, &my_tracedata);
/* the DEBUGFUNCTION has no effect until we enable VERBOSE */
curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L);
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
res = curl_easy_perform(curl);
/* always cleanup */
curl_easy_cleanup(curl);
}
return 0;
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_STDERR "(3), " CURLOPT_DEBUGFUNCTION "(3), "
share/man/man3/CURLOPT_PROTOCOLS_STR.3 0000644 00000006426 14751150677 0012714 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROTOCOLS_STR 3 "September 13, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROTOCOLS_STR \- allowed protocols
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROTOCOLS_STR, char *spec);
.fi
.SH DESCRIPTION
Pass a pointer to a string that holds a comma-separated list of case
insensitive protocol names (URL schemes) to allow in the transfer. This
option allows applications to use libcurl built to support a wide range of
protocols but still limit specific transfers to only be allowed to use a
subset of them. By default, libcurl accepts all protocols it was built with
support for. See also \fICURLOPT_REDIR_PROTOCOLS_STR(3)\fP.
If trying to set a non-existing protocol or if no matching protocol at all is
set, it returns error.
These are the available protocols:
DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS,
MQTT, POP3, POP3S, RTMP, RTMPE, RTMPS, RTMPT, RTMPTE, RTMPTS, RTSP, SCP, SFTP,
SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS, WSS
You can set "ALL" as a short-cut to enable all protocols. Note that by setting
all, you may enable protocols that were not supported the day you write this
but are introduced in a future libcurl version.
\fIcurl_version_info(3)\fP can be used to get a list of all supported
protocols in the current libcurl. \fICURLINFO_SCHEME(3)\fP is the recommended
way to figure out the protocol used in a previous transfer.
.SH DEFAULT
All protocols built-in
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
/* pass in the URL from an external source */
curl_easy_setopt(curl, CURLOPT_URL, argv[1]);
/* only allow HTTP, TFTP and SFTP */
curl_easy_setopt(curl, CURLOPT_PROTOCOLS_STR, "http,tftp,sftp");
/* Perform the request */
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.85.0
.SH RETURN VALUE
Returns CURLE_UNKNOWN_OPTION if the option is not implemented,
CURLE_UNSUPPORTED_PROTOCOL if a listed protocol is not supported or disabled,
CURLE_BAD_FUNCTION_ARGUMENT if no protocol is listed else CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_REDIR_PROTOCOLS_STR "(3), " CURLOPT_URL "(3), "
.BR curl_version_info "(3), " CURLINFO_SCHEME "(3), "
share/man/man3/CURLINFO_RETRY_AFTER.3 0000644 00000004752 14751150677 0012517 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_RETRY_AFTER 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_RETRY_AFTER \- returns the Retry-After retry delay
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_RETRY_AFTER,
curl_off_t *retry);
.fi
.SH DESCRIPTION
Pass a pointer to a curl_off_t variable to receive the number of seconds the
HTTP server suggests the client should wait until the next request is
issued. The information from the "Retry-After:" header.
While the HTTP header might contain a fixed date string, the
\fICURLINFO_RETRY_AFTER(3)\fP will always return number of seconds to wait -
or zero if there was no header or the header could not be parsed.
.SH DEFAULT
Returns zero delay if there was no header.
.SH PROTOCOLS
HTTP(S)
.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);
if(res == CURLE_OK) {
curl_off_t wait = 0;
curl_easy_getinfo(curl, CURLINFO_RETRY_AFTER, &wait);
if(wait)
printf("Wait for %" CURL_FORMAT_CURL_OFF_T " seconds\\n", wait);
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.66.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_STDERR "(3), " CURLOPT_HEADERFUNCTION "(3), "
share/man/man3/CURLOPT_PROXY_SSLVERSION.3 0000644 00000007036 14751150677 0013306 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXY_SSLVERSION 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXY_SSLVERSION \- preferred HTTPS proxy TLS version
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSLVERSION,
long version);
.fi
.SH DESCRIPTION
Pass a long as parameter to control which version of SSL/TLS to attempt to use
when connecting to an HTTPS proxy.
Use one of the available defines for this purpose. The available options are:
.RS
.IP CURL_SSLVERSION_DEFAULT
The default action. This will attempt to figure out the remote SSL protocol
version.
.IP CURL_SSLVERSION_TLSv1
TLSv1.x
.IP CURL_SSLVERSION_TLSv1_0
TLSv1.0
.IP CURL_SSLVERSION_TLSv1_1
TLSv1.1
.IP CURL_SSLVERSION_TLSv1_2
TLSv1.2
.IP CURL_SSLVERSION_TLSv1_3
TLSv1.3
.RE
The maximum TLS version can be set by using \fIone\fP of the
CURL_SSLVERSION_MAX_ macros below. It is also possible to OR \fIone\fP of the
CURL_SSLVERSION_ macros with \fIone\fP of the CURL_SSLVERSION_MAX_ macros.
The MAX macros are not supported for WolfSSL.
.RS
.IP CURL_SSLVERSION_MAX_DEFAULT
The flag defines the maximum supported TLS version as TLSv1.2, or the default
value from the SSL library.
(Added in 7.54.0)
.IP CURL_SSLVERSION_MAX_TLSv1_0
The flag defines maximum supported TLS version as TLSv1.0.
(Added in 7.54.0)
.IP CURL_SSLVERSION_MAX_TLSv1_1
The flag defines maximum supported TLS version as TLSv1.1.
(Added in 7.54.0)
.IP CURL_SSLVERSION_MAX_TLSv1_2
The flag defines maximum supported TLS version as TLSv1.2.
(Added in 7.54.0)
.IP CURL_SSLVERSION_MAX_TLSv1_3
The flag defines maximum supported TLS version as TLSv1.3.
(Added in 7.54.0)
.RE
In versions of curl prior to 7.54 the CURL_SSLVERSION_TLS options were
documented to allow \fIonly\fP the specified TLS version, but behavior was
inconsistent depending on the TLS library.
.SH DEFAULT
CURL_SSLVERSION_DEFAULT
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* ask libcurl to use TLS version 1.0 or later */
curl_easy_setopt(curl, CURLOPT_SSLVERSION, CURL_SSLVERSION_TLSv1);
/* Perform the request */
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.52.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_USE_SSL "(3), " CURLOPT_HTTP_VERSION "(3), "
.BR CURLOPT_IPRESOLVE "(3) " CURLOPT_SSLVERSION "(3), "
share/man/man3/CURLOPT_SOCKS5_AUTH.3 0000644 00000005057 14751150677 0012367 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SOCKS5_AUTH 3 "October 22, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SOCKS5_AUTH \- methods for SOCKS5 proxy authentication
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKS5_AUTH, long bitmask);
.fi
.SH DESCRIPTION
Pass a long as parameter, which is set to a bitmask, to tell libcurl which
authentication method(s) are allowed for SOCKS5 proxy authentication. The only
supported flags are \fICURLAUTH_BASIC\fP, which allows username/password
authentication, \fICURLAUTH_GSSAPI\fP, which allows GSS-API authentication, and
\fICURLAUTH_NONE\fP, which allows no authentication. Set the actual user name
and password with the \fICURLOPT_PROXYUSERPWD(3)\fP option.
.SH DEFAULT
CURLAUTH_BASIC|CURLAUTH_GSSAPI
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* request to use a SOCKS5 proxy */
curl_easy_setopt(curl, CURLOPT_PROXY, "socks5://user:pass@myproxy.com");
/* enable username/password authentication only */
curl_easy_setopt(curl, CURLOPT_SOCKS5_AUTH, (long)CURLAUTH_BASIC);
/* Perform the request */
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.55.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_NOT_BUILT_IN if the bitmask contains unsupported flags.
.SH "SEE ALSO"
.BR CURLOPT_PROXY "(3), " CURLOPT_PROXYTYPE "(3)"
share/man/man3/CURLINFO_SIZE_UPLOAD_T.3 0000644 00000004245 14751150677 0012767 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_SIZE_UPLOAD_T 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_SIZE_UPLOAD_T \- get the number of uploaded bytes
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SIZE_UPLOAD_T,
curl_off_t *uploadp);
.fi
.SH DESCRIPTION
Pass a pointer to a \fIcurl_off_t\fP to receive the total amount of bytes that
were uploaded.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* Perform the request */
res = curl_easy_perform(curl);
if(!res) {
curl_off_t ul;
res = curl_easy_getinfo(curl, CURLINFO_SIZE_UPLOAD_T, &ul);
if(!res) {
printf("Uploaded %" CURL_FORMAT_CURL_OFF_T " bytes\\n", ul);
}
}
}
.fi
.SH AVAILABILITY
Added in 7.55.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
.BR CURLINFO_SIZE_DOWNLOAD_T "(3), " CURLINFO_SIZE_UPLOAD "(3), "
share/man/man3/curl_multi_wait.3 0000644 00000011015 14751150677 0012561 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_multi_wait 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_multi_wait - polls on all easy handles in a multi handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_wait(CURLM *multi_handle,
struct curl_waitfd extra_fds[],
unsigned int extra_nfds,
int timeout_ms,
int *numfds);
.ad
.SH DESCRIPTION
\fIcurl_multi_wait(3)\fP polls all file descriptors used by the curl easy
handles contained in the given multi handle set. It will block until activity
is detected on at least one of the handles or \fItimeout_ms\fP has passed.
Alternatively, if the multi handle has a pending internal timeout that has a
shorter expiry time than \fItimeout_ms\fP, that shorter time will be used
instead to make sure timeout accuracy is reasonably kept.
The calling application may pass additional \fIcurl_waitfd\fP structures which
are similar to \fIpoll(2)\fP's \fIpollfd\fP structure to be waited on in the
same call.
On completion, if \fInumfds\fP is non-NULL, it will be populated with the
total number of file descriptors on which interesting events occurred. This
number can include both libcurl internal descriptors as well as descriptors
provided in \fIextra_fds\fP.
If no extra file descriptors are provided and libcurl has no file descriptor
to offer to wait for, this function will return immediately. (Try
\fIcurl_multi_poll(3)\fP instead if you rather avoid this behavior.)
This function is encouraged to be used instead of select(3) when using the
multi interface to allow applications to easier circumvent the common problem
with 1024 maximum file descriptors.
.SH curl_waitfd
.nf
struct curl_waitfd {
curl_socket_t fd;
short events;
short revents;
};
.fi
.IP CURL_WAIT_POLLIN
Bit flag to \fIcurl_waitfd.events\fP indicating the socket should poll on read
events such as new data received.
.IP CURL_WAIT_POLLPRI
Bit flag to \fIcurl_waitfd.events\fP indicating the socket should poll on high
priority read events such as out of band data.
.IP CURL_WAIT_POLLOUT
Bit flag to \fIcurl_waitfd.events\fP indicating the socket should poll on
write events such as the socket being clear to write without blocking.
.SH EXAMPLE
.nf
CURL *easy_handle;
CURLM *multi_handle;
/* add the individual easy handle */
curl_multi_add_handle(multi_handle, easy_handle);
do {
CURLMcode mc;
int numfds;
mc = curl_multi_perform(multi_handle, &still_running);
if(mc == CURLM_OK ) {
/* wait for activity, timeout or "nothing" */
mc = curl_multi_wait(multi_handle, NULL, 0, 1000, &numfds);
}
if(mc != CURLM_OK) {
fprintf(stderr, "curl_multi failed, code %d.\\n", mc);
break;
}
/* 'numfds' being zero means either a timeout or no file descriptors to
wait for. Try timeout on first occurrence, then assume no file
descriptors and no file descriptors to wait for means wait for 100
milliseconds. */
if(!numfds) {
repeats++; /* count number of repeated zero numfds */
if(repeats > 1) {
WAITMS(100); /* sleep 100 milliseconds */
}
}
else
repeats = 0;
} while(still_running);
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 "SEE ALSO"
.BR curl_multi_fdset "(3), " curl_multi_perform "(3)", curl_multi_poll "(3) ",
share/man/man3/CURLOPT_ADDRESS_SCOPE.3 0000644 00000004130 14751150677 0012604 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_ADDRESS_SCOPE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_ADDRESS_SCOPE \- scope id for IPv6 addresses
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ADDRESS_SCOPE, long scope);
.fi
.SH DESCRIPTION
Pass a long specifying the scope id value to use when connecting to IPv6 addresses.
.SH DEFAULT
0
.SH PROTOCOLS
All, when using IPv6
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode ret;
long my_scope_id;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
my_scope_id = if_nametoindex("eth0");
curl_easy_setopt(curl, CURLOPT_ADDRESS_SCOPE, my_scope_id);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.19.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
Returns CURLE_BAD_FUNCTION_ARGUMENT if set to a negative value.
.SH "SEE ALSO"
.BR CURLOPT_STDERR "(3), " CURLOPT_DEBUGFUNCTION "(3), "
share/man/man3/CURLOPT_SSL_CTX_FUNCTION.3 0000644 00000015036 14751150677 0013261 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SSL_CTX_FUNCTION 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSL_CTX_FUNCTION \- SSL context callback for OpenSSL, wolfSSL or mbedTLS
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode ssl_ctx_callback(CURL *curl, void *ssl_ctx, void *userptr);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_CTX_FUNCTION,
ssl_ctx_callback);
.SH DESCRIPTION
This option only works for libcurl powered by OpenSSL, wolfSSL, mbedTLS or
BearSSL. If libcurl was built against another SSL library this functionality
is absent.
Pass a pointer to your callback function, which should match the prototype
shown above.
This callback function gets called by libcurl just before the initialization
of an SSL connection after having processed all other SSL related options to
give a last chance to an application to modify the behavior of the SSL
initialization. The \fIssl_ctx\fP parameter is actually a pointer to the SSL
library's \fISSL_CTX\fP for OpenSSL or wolfSSL, a pointer to
\fImbedtls_ssl_config\fP for mbedTLS or a pointer to
\fIbr_ssl_client_context\fP for BearSSL. If an error is returned from the
callback no attempt to establish a connection is made and the perform
operation will return the callback's error code. Set the \fIuserptr\fP
argument with the \fICURLOPT_SSL_CTX_DATA(3)\fP option.
This function will get called on all new connections made to a server, during
the SSL negotiation. The \fIssl_ctx\fP will point to a newly initialized object
each time, but note the pointer may be the same as from a prior call.
To use this properly, a non-trivial amount of knowledge of your SSL library is
necessary. For example, you can use this function to call library-specific
callbacks to add additional validation code for certificates, and even to
change the actual URI of an HTTPS request.
WARNING: The \fICURLOPT_SSL_CTX_FUNCTION(3)\fP callback allows the application
to reach in and modify SSL details in the connection without libcurl itself
knowing anything about it, which then subsequently can lead to libcurl
unknowingly reusing SSL connections with different properties. To remedy this
you may set \fICURLOPT_FORBID_REUSE(3)\fP from the callback function.
WARNING: If you are using DNS-over-HTTPS (DoH) via \fICURLOPT_DOH_URL(3)\fP
then this callback will also be called for those transfers and the curl handle
is set to an internal handle. \fBThis behavior is subject to change.\fP We
recommend before performing your transfer set \fICURLOPT_PRIVATE(3)\fP on your
curl handle so you can identify it in the context callback. If you have a
reason to modify DoH SSL context please let us know on the curl-library
mailing list because we are considering removing this capability.
.SH DEFAULT
NULL
.SH PROTOCOLS
All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
.SH EXAMPLE
.nf
/* OpenSSL specific */
#include <openssl/ssl.h>
#include <curl/curl.h>
#include <stdio.h>
static CURLcode sslctx_function(CURL *curl, void *sslctx, void *parm)
{
X509_STORE *store;
X509 *cert = NULL;
BIO *bio;
char *mypem = parm;
/* get a BIO */
bio = BIO_new_mem_buf(mypem, -1);
/* use it to read the PEM formatted certificate from memory into an
* X509 structure that SSL can use
*/
PEM_read_bio_X509(bio, &cert, 0, NULL);
if(cert == NULL)
printf("PEM_read_bio_X509 failed...\\n");
/* get a pointer to the X509 certificate store (which may be empty) */
store = SSL_CTX_get_cert_store((SSL_CTX *)sslctx);
/* add our certificate to this store */
if(X509_STORE_add_cert(store, cert) == 0)
printf("error adding certificate\\n");
/* decrease reference counts */
X509_free(cert);
BIO_free(bio);
/* all set to go */
return CURLE_OK;
}
int main(void)
{
CURL * ch;
CURLcode rv;
char *mypem = /* example CA cert PEM - shortened */
"-----BEGIN CERTIFICATE-----\\n"
"MIIHPTCCBSWgAwIBAgIBADANBgkqhkiG9w0BAQQFADB5MRAwDgYDVQQKEwdSb290\\n"
"IENBMR4wHAYDVQQLExVodHRwOi8vd3d3LmNhY2VydC5vcmcxIjAgBgNVBAMTGUNB\\n"
"IENlcnQgU2lnbmluZyBBdXRob3JpdHkxITAfBgkqhkiG9w0BCQEWEnN1cHBvcnRA\\n"
"Y2FjZXJ0Lm9yZzAeFw0wMzAzMzAxMjI5NDlaFw0zMzAzMjkxMjI5NDlaMHkxEDAO\\n"
"GCSNe9FINSkYQKyTYOGWhlC0elnYjyELn8+CkcY7v2vcB5G5l1YjqrZslMZIBjzk\\n"
"zk6q5PYvCdxTby78dOs6Y5nCpqyJvKeyRKANihDjbPIky/qbn3BHLt4Ui9SyIAmW\\n"
"omTxJBzcoTWcFbLUvFUufQb1nA5V9FrWk9p2rSVzTMVD\\n"
"-----END CERTIFICATE-----\\n";
curl_global_init(CURL_GLOBAL_ALL);
ch = curl_easy_init();
curl_easy_setopt(ch, CURLOPT_SSLCERTTYPE, "PEM");
curl_easy_setopt(ch, CURLOPT_SSL_VERIFYPEER, 1L);
curl_easy_setopt(ch, CURLOPT_URL, "https://www.example.com/");
/* Retrieve page using cacerts' certificate -> will succeed
* load the certificate by installing a function doing the necessary
* "modifications" to the SSL CONTEXT just before link init
*/
curl_easy_setopt(ch, CURLOPT_SSL_CTX_FUNCTION, *sslctx_function);
curl_easy_setopt(ch, CURLOPT_SSL_CTX_DATA, mypem);
rv = curl_easy_perform(ch);
if(!rv)
printf("*** transfer succeeded ***\\n");
else
printf("*** transfer failed ***\\n");
curl_easy_cleanup(ch);
curl_global_cleanup();
return rv;
}
.fi
.SH AVAILABILITY
Added in 7.11.0 for OpenSSL, in 7.42.0 for wolfSSL, in 7.54.0 for mbedTLS,
in 7.83.0 in BearSSL. Other SSL backends are not supported.
.SH RETURN VALUE
CURLE_OK if supported; or an error such as:
CURLE_NOT_BUILT_IN - Not supported by the SSL backend
CURLE_UNKNOWN_OPTION
.SH "SEE ALSO"
.BR CURLOPT_SSL_CTX_DATA "(3), " CURLOPT_SSL_VERIFYPEER "(3), "
share/man/man3/CURLSHOPT_UNSHARE.3 0000644 00000005524 14751150677 0012136 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH CURLSHOPT_UNSHARE 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
CURLSHOPT_UNSHARE - remove data to share
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_UNSHARE, long type);
.fi
.SH DESCRIPTION
The \fItype\fP parameter specifies what specific data that should no longer be
shared and kept in the share object that was created with
\fIcurl_share_init(3)\fP. In other words, stop sharing that data in this
shared object. The given \fItype\fP must be be one of the values described
below. You can set \fICURLSHOPT_UNSHARE(3)\fP multiple times with different
data arguments to remove multiple types from the shared object. Add data to
share again with \fICURLSHOPT_SHARE(3)\fP.
.IP CURL_LOCK_DATA_COOKIE
Cookie data will no longer be shared across the easy handles using this shared
object.
.IP CURL_LOCK_DATA_DNS
Cached DNS hosts will be no longer be shared across the easy handles using
this shared object.
.IP CURL_LOCK_DATA_SSL_SESSION
SSL session IDs will no longer be shared across the easy handles using this
shared object.
.IP CURL_LOCK_DATA_CONNECT
The connection cache is no longer shared.
.IP CURL_LOCK_DATA_PSL
The Public Suffix List is no longer shared.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURLSHcode sh;
share = curl_share_init();
sh = curl_share_setopt(share, CURLSHOPT_UNSHARE, CURL_LOCK_DATA_COOKIE);
if(sh)
printf("Error: %s\\n", curl_share_strerror(sh));
.fi
.SH AVAILABILITY
Added in 7.10
.SH RETURN VALUE
CURLSHE_OK (zero) means that the option was set properly, non-zero means an
error occurred. See \fIlibcurl-errors(3)\fP for the full list with
descriptions.
.SH "SEE ALSO"
.BR CURLSHOPT_SHARE "(3), "
.BR curl_share_setopt "(3), " curl_share_cleanup "(3), " curl_share_init "(3)"
share/man/man3/CURLOPT_STREAM_DEPENDS.3 0000644 00000005374 14751150677 0012736 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_STREAM_DEPENDS 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_STREAM_DEPENDS \- stream this transfer depends on
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_STREAM_DEPENDS,
CURL *dephandle);
.fi
.SH DESCRIPTION
Pass a CURL * pointer in \fIdephandle\fP to identify the stream within the
same connection that this stream is depending upon. This option clears the
exclusive bit and is mutually exclusive to the
\fICURLOPT_STREAM_DEPENDS_E(3)\fP option.
The spec says "Including a dependency expresses a preference to allocate
resources to the identified stream rather than to the dependent stream."
This option can be set during transfer.
\fIdephandle\fP must not be the same as \fIhandle\fP, that will cause this
function to return an error. It must be another easy handle, and it also needs
to be a handle of a transfer that will be sent over the same HTTP/2 connection
for this option to have an actual effect.
.SH DEFAULT
NULL
.SH PROTOCOLS
HTTP/2
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
CURL *curl2 = curl_easy_init(); /* a second handle */
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/one");
/* the second depends on the first */
curl_easy_setopt(curl2, CURLOPT_URL, "https://example.com/two");
curl_easy_setopt(curl2, CURLOPT_STREAM_DEPENDS, curl);
/* then add both to a multi handle and transfer them! */
}
.fi
.SH AVAILABILITY
Added in 7.46.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_STREAM_WEIGHT "(3), " CURLOPT_STREAM_DEPENDS_E "(3), "
share/man/man3/CURLINFO_CAINFO.3 0000644 00000004641 14751150677 0011625 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_CAINFO 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_CAINFO \- get the default built-in CA certificate path
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CAINFO, char **path);
.fi
.SH DESCRIPTION
Pass a pointer to a char pointer to receive the pointer to a null-terminated
string holding the default built-in path used for the \fICURLOPT_CAINFO(3)\fP
option unless set by the user.
Note that in a situation where libcurl has been built to support multiple TLS
libraries, this option might return a string even if the specific TLS library
currently set to be used does not support \fICURLOPT_CAINFO(3)\fP.
This is a path identifying a single file containing CA certificates.
The \fBpath\fP pointer will be NULL if there is no default path.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res;
char *cainfo = NULL;
curl_easy_getinfo(curl, CURLINFO_CAINFO, &cainfo);
if(cainfo)
printf("default ca info path: %s\\n", cainfo);
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.84.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLINFO_CAPATH "(3), "
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
share/man/man3/CURLOPT_PROXY_SSLCERT.3 0000644 00000005732 14751150677 0012717 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXY_SSLCERT 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXY_SSLCERT \- HTTPS proxy client certificate
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSLCERT, char *cert);
.fi
.SH DESCRIPTION
This option is for connecting to an HTTPS proxy, not an HTTPS server.
Pass a pointer to a null-terminated string as parameter. The string should be
the file name of your client certificate used to connect to the HTTPS proxy.
The default format is "P12" on Secure Transport and "PEM" on other engines,
and can be changed with \fICURLOPT_PROXY_SSLCERTTYPE(3)\fP.
With NSS or Secure Transport, this can also be the nickname of the certificate
you wish to authenticate with as it is named in the security database. If you
want to use a file from the current directory, please precede it with "./"
prefix, in order to avoid confusion with a nickname.
When using a client certificate, you most likely also need to provide a
private key with \fICURLOPT_PROXY_SSLKEY(3)\fP.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
Used with HTTPS proxy
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy");
curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERT, "client.pem");
curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEY, "key.pem");
curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "s3cret");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.52.0
.SH RETURN VALUE
Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_PROXY_SSLCERTTYPE "(3), " CURLOPT_PROXY_SSLKEY "(3), "
.BR CURLOPT_SSLCERT "(3), "
share/man/man3/CURLOPT_PRE_PROXY.3 0000644 00000006575 14751150677 0012234 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PRE_PROXY 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PRE_PROXY \- pre-proxy host to use
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PRE_PROXY, char *preproxy);
.fi
.SH DESCRIPTION
Set the \fIpreproxy\fP to use for the upcoming request. The parameter
should be a char * to a null-terminated string holding the host name or dotted
numerical IP address. A numerical IPv6 address must be written within
[brackets].
To specify port number in this string, append :[port] to the end of the host
name. The proxy's port number may optionally be specified with the separate
option \fICURLOPT_PROXYPORT(3)\fP. If not specified, libcurl will default to
using port 1080 for proxies.
A pre proxy is a SOCKS proxy that curl connects to before it connects to the
HTTP(S) proxy specified in the \fICURLOPT_PROXY\fP option. The pre proxy can
only be a SOCKS proxy.
The pre proxy string should be prefixed with [scheme]:// to specify which kind
of socks is used. Use socks4://, socks4a://, socks5:// or socks5h:// (the last
one to enable socks5 and asking the proxy to do the resolving, also known as
\fICURLPROXY_SOCKS5_HOSTNAME\fP type) to request the specific SOCKS version to
be used. Otherwise SOCKS4 is used as default.
Setting the pre proxy string to "" (an empty string) will explicitly disable
the use of a pre proxy.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
Default is NULL, meaning no pre proxy is used.
When you set a host name to use, do not assume that there's any particular
single port number used widely for proxies. Specify it!
.SH PROTOCOLS
All except file://. Note that some protocols do not work well over proxy.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/file.txt");
curl_easy_setopt(curl, CURLOPT_PRE_PROXY, "socks4://socks-proxy:1080");
curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy:80");
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.52.0
.SH RETURN VALUE
Returns CURLE_OK if proxies are supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_PROXY "(3), " CURLOPT_HTTPPROXYTUNNEL "(3), "
share/man/man3/CURLOPT_TRAILERFUNCTION.3 0000644 00000007506 14751150677 0013050 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_TRAILERFUNCTION 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_TRAILERFUNCTION \- callback for sending trailing headers
.SH SYNOPSIS
.nf
#include <curl.h>
int curl_trailer_callback(struct curl_slist ** list, void *userdata);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TRAILERFUNCTION,
curl_trailer_callback *func);
.fi
.SH DESCRIPTION
Pass a pointer to a callback function.
This callback function will be called once right before sending the final
CR LF in an HTTP chunked transfer to fill a list of trailing headers to be
sent before finishing the HTTP transfer.
You can set the userdata argument with the \fICURLOPT_TRAILERDATA(3)\fP
option.
The trailing headers included in the linked list must not be CRLF-terminated,
because libcurl will add the appropriate line termination characters after
each header item.
If you use curl_slist_append to add trailing headers to the curl_slist then
libcurl will duplicate the strings, and will free the curl_slist and the
duplicates once the trailers have been sent.
If one of the trailing header fields is not formatted correctly it will be
ignored and an info message will be emitted.
The return value can either be \fBCURL_TRAILERFUNC_OK\fP or
\fBCURL_TRAILERFUNC_ABORT\fP which would respectively instruct libcurl to
either continue with sending the trailers or to abort the request.
If you set this option to NULL, then the transfer proceeds as usual
without any interruptions.
.SH DEFAULT
NULL
.SH PROTOCOLS
HTTP
.SH EXAMPLE
#include <curl/curl.h>
static int trailer_cb(struct curl_slist **tr, void *data)
{
/* libcurl will free the list */
*tr = curl_slist_append(*tr, "My-super-awesome-trailer: trailer-stuff");
return CURL_TRAILERFUNC_OK;
}
CURL *curl = curl_easy_init();
if(curl) {
/* Set the URL of the request */
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
/* Now set it as a put */
curl_easy_setopt(curl, CURLOPT_PUT, 1L);
/* Assuming we have a function that will return the data to be pushed
Let that function be read_cb */
curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_cb);
struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Trailer: My-super-awesome-trailer");
res = curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
/* Set the trailers filling callback */
curl_easy_setopt(curl, CURLOPT_TRAILERFUNCTION, trailer_cb);
/* Perform the request, res will get the return code */
res = curl_easy_perform(curl);
curl_easy_cleanup(curl);
curl_slist_free_all(headers);
}
.SH AVAILABILITY
This option was added in curl 7.64.0 and is present if HTTP support is enabled
.SH RETURN VALUE
Returns CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_TRAILERDATA "(3), "
share/man/man3/CURLINFO_TOTAL_TIME.3 0000644 00000004503 14751150677 0012364 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_TOTAL_TIME 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_TOTAL_TIME \- get total time of previous transfer
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TOTAL_TIME, double *timep);
.fi
.SH DESCRIPTION
Pass a pointer to a double to receive the total time in seconds for the
previous transfer, including name resolving, TCP connect etc. The double
represents the time in seconds, including fractions.
When a redirect is followed, the time from each request is added together.
See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
double total;
curl_easy_setopt(curl, CURLOPT_URL, url);
res = curl_easy_perform(curl);
if(CURLE_OK == res) {
res = curl_easy_getinfo(curl, CURLINFO_TOTAL_TIME, &total);
if(CURLE_OK == res) {
printf("Time: %.1f", total);
}
}
/* always cleanup */
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.4.1
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), " CURLINFO_TOTAL_TIME_T "(3)"
share/man/man3/CURLOPT_PROXY_PINNEDPUBLICKEY.3 0000644 00000010517 14751150677 0014022 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXY_PINNEDPUBLICKEY 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXY_PINNEDPUBLICKEY \- pinned public key for https proxy
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_PINNEDPUBLICKEY, char *pinnedpubkey);
.fi
.SH DESCRIPTION
Pass a pointer to a null-terminated string as parameter. The string can be the
file name of your pinned public key. The file format expected is "PEM" or "DER".
The string can also be any number of base64 encoded sha256 hashes preceded by
"sha256//" and separated by ";"
When negotiating a TLS or SSL connection, the https proxy sends a certificate
indicating its identity. A public key is extracted from this certificate and
if it does not exactly match the public key provided to this option, curl will
abort the connection before sending or receiving any data.
On mismatch, \fICURLE_SSL_PINNEDPUBKEYNOTMATCH\fP is returned.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy:443");
curl_easy_setopt(curl, CURLOPT_PROXY_PINNEDPUBLICKEY,
"sha256//YhKJKSzoTt2b5FP18fvpHo7fJYqQCjAa3HWY3tvRMwE=;sha256//t62CeU2tQiqkexU74Gxa2eg7fRbEgoChTociMee9wno=");
/* Perform the request */
curl_easy_perform(curl);
}
.fi
.SH PUBLIC KEY EXTRACTION
If you do not have the https proxy server's public key file you can extract it
from the https proxy server's certificate.
.nf
# retrieve the server's certificate if you do not already have it
#
# be sure to examine the certificate to see if it is what you expected
#
# Windows-specific:
# - Use NUL instead of /dev/null.
# - OpenSSL may wait for input instead of disconnecting. Hit enter.
# - If you do not have sed, then just copy the certificate into a file:
# Lines from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE-----.
#
openssl s_client -servername www.example.com -connect www.example.com:443 < /dev/null | sed -n "/-----BEGIN/,/-----END/p" > www.example.com.pem
# extract public key in pem format from certificate
openssl x509 -in www.example.com.pem -pubkey -noout > www.example.com.pubkey.pem
# convert public key from pem to der
openssl asn1parse -noout -inform pem -in www.example.com.pubkey.pem -out www.example.com.pubkey.der
# sha256 hash and base64 encode der to string for use
openssl dgst -sha256 -binary www.example.com.pubkey.der | openssl base64
.fi
The public key in PEM format contains a header, base64 data and a
footer:
.nf
-----BEGIN PUBLIC KEY-----
[BASE 64 DATA]
-----END PUBLIC KEY-----
.fi
.SH AVAILABILITY
PEM/DER support:
7.52.0: GSKit, GnuTLS, NSS, OpenSSL, mbedTLS, wolfSSL
sha256 support:
7.52.0: GnuTLS, NSS, OpenSSL, mbedTLS, wolfSSL
Other SSL backends not supported.
.SH RETURN VALUE
Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_PROXY_SSL_VERIFYPEER "(3), "
.BR CURLOPT_PROXY_SSL_VERIFYHOST "(3), "
.BR CURLOPT_PROXY_CAINFO "(3), "
.BR CURLOPT_PROXY_CAPATH "(3), "
share/man/man3/CURLOPT_DNS_LOCAL_IP4.3 0000644 00000004726 14751150677 0012613 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_DNS_LOCAL_IP4 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_DNS_LOCAL_IP4 \- IPv4 address to bind DNS resolves to
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_LOCAL_IP4, char *address);
.fi
.SH DESCRIPTION
Set the local IPv4 \fIaddress\fP that the resolver should bind to. The
argument should be of type char * and contain a single numerical IPv4 address
as a string. Set this option to NULL to use the default setting (do not bind
to a specific IP address).
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
curl_easy_setopt(curl, CURLOPT_DNS_LOCAL_IP4, "192.168.0.14");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
This option requires that libcurl was built with a resolver backend that
supports this operation. The c-ares backend is the only such one.
Added in 7.33.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not,
CURLE_NOT_BUILT_IN if support was disabled at compile-time, or
CURLE_BAD_FUNCTION_ARGUMENT when given a bad address.
.SH "SEE ALSO"
.BR CURLOPT_DNS_INTERFACE "(3), " CURLOPT_DNS_LOCAL_IP6 "(3), "
share/man/man3/CURLOPT_NETRC_FILE.3 0000644 00000004522 14751150677 0012245 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_NETRC_FILE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_NETRC_FILE \- file name to read .netrc info from
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NETRC_FILE, char *file);
.fi
.SH DESCRIPTION
Pass a char * as parameter, pointing to a null-terminated string containing
the full path name to the \fIfile\fP you want libcurl to use as .netrc
file. If this option is omitted, and \fICURLOPT_NETRC(3)\fP is set, libcurl
will attempt to find a .netrc file in the current user's home
directory.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode ret;
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/");
curl_easy_setopt(curl, CURLOPT_NETRC, CURL_NETRC_OPTIONAL);
curl_easy_setopt(curl, CURLOPT_NETRC_FILE, "/tmp/magic-netrc");
ret = curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.10.9
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_NETRC "(3), " CURLOPT_USERNAME "(3), "
share/man/man3/CURLINFO_TOTAL_TIME_T.3 0000644 00000004707 14751150677 0012655 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 2022 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_TOTAL_TIME_T 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_TOTAL_TIME_T \- get total time of previous transfer in microseconds
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TOTAL_TIME_T,
curl_off_t *timep);
.fi
.SH DESCRIPTION
Pass a pointer to a curl_off_t to receive the total time in microseconds
for the previous transfer, including name resolving, TCP connect etc.
The curl_off_t represents the time in microseconds.
When a redirect is followed, the time from each request is added together.
See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
curl_off_t total;
curl_easy_setopt(curl, CURLOPT_URL, url);
res = curl_easy_perform(curl);
if(CURLE_OK == res) {
res = curl_easy_getinfo(curl, CURLINFO_TOTAL_TIME_T, &total);
if(CURLE_OK == res) {
printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", total / 1000000,
(long)(total % 1000000));
}
}
/* always cleanup */
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.61.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), " CURLINFO_TOTAL_TIME "(3)"
share/man/man3/CURLOPT_CLOSESOCKETFUNCTION.3 0000644 00000005172 14751150677 0013521 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_CLOSESOCKETFUNCTION 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_CLOSESOCKETFUNCTION \- callback to socket close replacement
.SH SYNOPSIS
.nf
#include <curl/curl.h>
int closesocket_callback(void *clientp, curl_socket_t item);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CLOSESOCKETFUNCTION,
closesocket_callback);
.fi
.SH DESCRIPTION
Pass a pointer to your callback function, which should match the prototype
shown above.
This callback function gets called by libcurl instead of the \fIclose(3)\fP or
\fIclosesocket(3)\fP call when sockets are closed (not for any other file
descriptors). This is pretty much the reverse to the
\fICURLOPT_OPENSOCKETFUNCTION(3)\fP option. Return 0 to signal success and 1
if there was an error.
The \fIclientp\fP pointer is set with
\fICURLOPT_CLOSESOCKETDATA(3)\fP. \fIitem\fP is the socket libcurl wants to be
closed.
.SH DEFAULT
By default libcurl uses the standard socket close function.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
static int closesocket(void *clientp, curl_socket_t item)
{
printf("libcurl wants to close %d now\\n", (int)item);
return 0;
}
/* call this function to close sockets */
curl_easy_setopt(curl, CURLOPT_CLOSESOCKETFUNCTION, closesocket);
curl_easy_setopt(curl, CURLOPT_CLOSESOCKETDATA, &sockfd);
.fi
.SH AVAILABILITY
Added in 7.21.7
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_CLOSESOCKETDATA "(3), " CURLOPT_OPENSOCKETFUNCTION "(3), "
share/man/man3/CURLOPT_NOPROXY.3 0000644 00000006461 14751150677 0011755 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_NOPROXY 3 "October 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_NOPROXY \- disable proxy use for specific hosts
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NOPROXY, char *noproxy);
.fi
.SH DESCRIPTION
Pass a pointer to a null-terminated string. The string consists of a comma
separated list of host names that do not require a proxy to get reached, even
if one is specified. The only wildcard available is a single * character,
which matches all hosts, and effectively disables the proxy. Each name in this
list is matched as either a domain which contains the hostname, or the
hostname itself. For example, "ample.com" would match ample.com, ample.com:80,
and www.ample.com, but not www.example.com or ample.com.org.
If the name in the \fInoproxy\fP list has a leading period, it is a domain
match against the provided host name. This way ".example.com" will switch off
proxy use for both "www.example.com" as well as for "foo.example.com".
Setting the \fInoproxy\fP string to "" (an empty string) will explicitly
enable the proxy for all host names, even if there is an environment variable
set for it.
Enter IPv6 numerical addresses in the list of host names without enclosing
brackets:
"example.com,::1,localhost"
The application does not have to keep the string around after setting this
option.
.SH "Environment variables"
If there's an environment variable called \fBno_proxy\fP (or \fBNO_PROXY\fP),
it will be used if the \fICURLOPT_NOPROXY(3)\fP option is not set. It works
exactly the same way.
.SH DEFAULT
NULL
.SH PROTOCOLS
Most
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
/* accept various URLs */
curl_easy_setopt(curl, CURLOPT_URL, input);
/* use this proxy */
curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy:80");
/* ... but make sure this host name is not proxied */
curl_easy_setopt(curl, CURLOPT_NOPROXY, "www.example.com");
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.19.4
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_PROXY "(3), " CURLOPT_PROXYAUTH "(3), "
share/man/man3/CURLOPT_SOCKS5_GSSAPI_NEC.3 0000644 00000004375 14751150677 0013303 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SOCKS5_GSSAPI_NEC 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SOCKS5_GSSAPI_NEC \- SOCKS proxy GSSAPI negotiation protection
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKS5_GSSAPI_NEC, long nec);
.fi
.SH DESCRIPTION
Pass a long set to 1 to enable or 0 to disable. As part of the GSSAPI
negotiation a protection mode is negotiated. The RFC1961 says in section
4.3/4.4 it should be protected, but the NEC reference implementation does not.
If enabled, this option allows the unprotected exchange of the protection mode
negotiation.
.SH DEFAULT
?
.SH PROTOCOLS
Most
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_PROXY, "socks5://proxy");
curl_easy_setopt(curl, CURLOPT_SOCKS5_GSSAPI_NEC, 1L);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.19.4
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_SOCKS5_GSSAPI_SERVICE "(3), " CURLOPT_PROXY "(3), "
share/man/man3/CURLINFO_NAMELOOKUP_TIME_T.3 0000644 00000004646 14751150677 0013446 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 2022 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_NAMELOOKUP_TIME_T 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_NAMELOOKUP_TIME_T \- get the name lookup time in microseconds
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_NAMELOOKUP_TIME_T,
curl_off_t *timep);
.fi
.SH DESCRIPTION
Pass a pointer to a curl_off_t to receive the total time in microseconds
from the start until the name resolving was completed.
When a redirect is followed, the time from each request is added together.
See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
curl_off_t namelookup;
curl_easy_setopt(curl, CURLOPT_URL, url);
res = curl_easy_perform(curl);
if(CURLE_OK == res) {
res = curl_easy_getinfo(curl, CURLINFO_NAMELOOKUP_TIME_T, &namelookup);
if(CURLE_OK == res) {
printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", namelookup / 1000000,
(long)(namelookup % 1000000));
}
}
/* always cleanup */
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.61.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), " CURLINFO_NAMELOOKUP_TIME "(3)"
share/man/man3/CURLOPT_PROXYAUTH.3 0000644 00000005455 14751150677 0012204 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXYAUTH 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXYAUTH \- HTTP proxy authentication methods
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYAUTH, long bitmask);
.fi
.SH DESCRIPTION
Pass a long as parameter, which is set to a bitmask, to tell libcurl which
HTTP authentication method(s) you want it to use for your proxy
authentication. If more than one bit is set, libcurl will first query the
site to see what authentication methods it supports and then pick the best one
you allow it to use. For some methods, this will induce an extra network
round-trip. Set the actual name and password with the
\fICURLOPT_PROXYUSERPWD(3)\fP option.
The bitmask can be constructed by the bits listed and described in the
\fICURLOPT_HTTPAUTH(3)\fP man page.
.SH DEFAULT
CURLAUTH_BASIC
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode ret;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
/* use this proxy */
curl_easy_setopt(curl, CURLOPT_PROXY, "http://local.example.com:1080");
/* allow whatever auth the proxy speaks */
curl_easy_setopt(curl, CURLOPT_PROXYAUTH, CURLAUTH_ANY);
/* set the proxy credentials */
curl_easy_setopt(curl, CURLOPT_PROXYUSERPWD, "james:007");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.10.7
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_NOT_BUILT_IN if the bitmask specified no supported authentication
methods.
.SH "SEE ALSO"
.BR CURLOPT_PROXY "(3), " CURLOPT_PROXYTYPE "(3), "
.BR CURLOPT_PROXYUSERPWD "(3), " CURLOPT_PROXYPORT "(3), "
share/man/man3/CURLOPT_FRESH_CONNECT.3 0000644 00000004357 14751150677 0012621 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_FRESH_CONNECT 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_FRESH_CONNECT \- force a new connection to be used
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FRESH_CONNECT, long fresh);
.fi
.SH DESCRIPTION
Pass a long. Set to 1 to make the next transfer use a new (fresh) connection
by force instead of trying to re-use an existing one. This option should be
used with caution and only if you understand what it does as it may seriously
impact performance.
Related functionality is \fICURLOPT_FORBID_REUSE(3)\fP which makes sure the
connection is closed after use so that it will not be re-used.
Set \fIfresh\fP to 0 to have libcurl attempt re-using an existing connection
(default behavior).
.SH DEFAULT
0
.SH PROTOCOLS
Most
.SH EXAMPLE
.nf
{
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_FRESH_CONNECT, 1L);
/* this transfer must use a new connection, not reuse an existing */
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_FORBID_REUSE "(3), "
share/man/man3/CURLOPT_SSH_KNOWNHOSTS.3 0000644 00000005001 14751150677 0013016 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SSH_KNOWNHOSTS 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSH_KNOWNHOSTS \- file name holding the SSH known hosts
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_KNOWNHOSTS, char *fname);
.fi
.SH DESCRIPTION
Pass a pointer to a null-terminated string holding the file name of the
known_host file to use. The known_hosts file should use the OpenSSH file
format as supported by libssh2. If this file is specified, libcurl will only
accept connections with hosts that are known and present in that file, with a
matching public key. Use \fICURLOPT_SSH_KEYFUNCTION(3)\fP to alter the default
behavior on host and key matches and mismatches.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
SFTP and SCP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file");
curl_easy_setopt(curl, CURLOPT_SSH_KNOWNHOSTS,
"/home/clarkkent/.ssh/known_hosts");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.19.6
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_SSH_AUTH_TYPES "(3), " CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 "(3), "
share/man/man3/CURLMOPT_PIPELINING.3 0000644 00000007266 14751150677 0012356 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLMOPT_PIPELINING 3 "October 19, 2022" "libcurl 7.86.0" "curl_multi_setopt options"
.SH NAME
CURLMOPT_PIPELINING \- enable HTTP pipelining and multiplexing
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PIPELINING, long bitmask);
.fi
.SH DESCRIPTION
Pass in the \fBbitmask\fP parameter to instruct libcurl to enable HTTP
pipelining and/or HTTP/2 multiplexing for this multi handle.
When enabled, libcurl will attempt to use those protocol features when doing
parallel requests to the same hosts.
For pipelining, this means that if you add a second request that can use an
already existing connection, the second request will be \&"piped" on the same
connection rather than being executed in parallel.
For multiplexing, this means that follow-up requests can re-use an existing
connection and send the new request multiplexed over that at the same time as
other transfers are already using that single connection.
There are several other related options that are interesting to tweak and
adjust to alter how libcurl spreads out requests on different connections or
not etc.
Before 7.43.0, this option was set to 1 and 0 to enable and disable HTTP/1.1
pipelining.
Starting in 7.43.0, \fBbitmask\fP's second bit also has a meaning, and you can
ask for pipelining and multiplexing independently of each other by toggling
the correct bits.
.IP CURLPIPE_NOTHING (0)
Default, which means doing no attempts at pipelining or multiplexing.
.IP CURLPIPE_HTTP1 (1)
If this bit is set, libcurl will try to pipeline HTTP/1.1 requests on
connections that are already established and in use to hosts.
This bit is deprecated and has no effect since version 7.62.0.
.IP CURLPIPE_MULTIPLEX (2)
If this bit is set, libcurl will try to multiplex the new transfer over an
existing connection if possible. This requires HTTP/2.
.SH DEFAULT
Since 7.62.0, \fBCURLPIPE_MULTIPLEX\fP is enabled by default.
Before that, default was \fBCURLPIPE_NOTHING\fP.
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
.nf
CURLM *m = curl_multi_init();
/* try HTTP/2 multiplexing */
curl_multi_setopt(m, CURLMOPT_PIPELINING, CURLPIPE_MULTIPLEX);
.fi
.SH AVAILABILITY
Added in 7.16.0. Multiplex support bit added in 7.43.0. HTTP/1 Pipelining
support was disabled in 7.62.0.
.SH RETURN VALUE
Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLMOPT_MAX_PIPELINE_LENGTH "(3), "
.BR CURLMOPT_PIPELINING_SITE_BL "(3), "
.BR CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE "(3), "
.BR CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE "(3), "
.BR CURLMOPT_MAXCONNECTS "(3), "
.BR CURLMOPT_MAX_HOST_CONNECTIONS "(3), "
share/man/man3/CURLOPT_SERVICE_NAME.3 0000644 00000004516 14751150677 0012476 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SERVICE_NAME 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SERVICE_NAME \- authentication service name
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SERVICE_NAME, char *name);
.fi
.SH DESCRIPTION
Pass a char * as parameter to a string holding the \fIname\fP of the service
for DIGEST-MD5, SPNEGO and Kerberos 5 authentication mechanisms. The default
service names are "ftp", "HTTP", "imap", "ldap", "pop" and "smtp". This option
allows you to change them.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
See above
.SH PROTOCOLS
HTTP, FTP, IMAP, LDAP, POP3 and SMTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode ret;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_SERVICE_NAME, "custom");
ret = curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.43.0 for HTTP, 7.49.0 for FTP, IMAP, POP3 and SMTP,
7.82.0 for OpenLDAP.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_PROXY "(3), " CURLOPT_PROXYTYPE "(3), "
share/man/man3/CURLOPT_DEFAULT_PROTOCOL.3 0000644 00000005762 14751150677 0013207 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_DEFAULT_PROTOCOL 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_DEFAULT_PROTOCOL \- default protocol to use if the URL is missing a
scheme name
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DEFAULT_PROTOCOL,
char *protocol);
.fi
.SH DESCRIPTION
This option tells libcurl to use \fIprotocol\fP if the URL is missing a scheme
name.
Use one of these protocol (scheme) names:
dict, file, ftp, ftps, gopher, http, https, imap, imaps, ldap, ldaps, pop3,
pop3s, rtsp, scp, sftp, smb, smbs, smtp, smtps, telnet, tftp
An unknown or unsupported protocol causes error
\fICURLE_UNSUPPORTED_PROTOCOL\fP when libcurl parses a URL without a
scheme. Parsing happens when \fIcurl_easy_perform(3)\fP or
\fIcurl_multi_perform(3)\fP is called. The protocols supported by libcurl will
vary depending on how it was built. Use \fIcurl_version_info(3)\fP if you need
a list of protocol names supported by the build of libcurl that you are using.
This option does not change the default proxy protocol (http).
Without this option libcurl would make a guess based on the host, see
\fICURLOPT_URL(3)\fP for details.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL (make a guess based on the host)
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
/* set a URL without a scheme */
curl_easy_setopt(curl, CURLOPT_URL, "example.com");
/* set the default protocol (scheme) for schemeless URLs */
curl_easy_setopt(curl, CURLOPT_DEFAULT_PROTOCOL, "https");
/* Perform the request */
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.45.0
.SH RETURN VALUE
CURLE_OK if the option is supported.
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
CURLE_UNKNOWN_OPTION if the option is not supported.
.SH "SEE ALSO"
.BR CURLOPT_URL "(3), "
share/man/man3/CURLOPT_PROXYUSERPWD.3 0000644 00000005036 14751150677 0012567 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXYUSERPWD 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXYUSERPWD \- user name and password to use for proxy authentication
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYUSERPWD, char *userpwd);
.fi
.SH DESCRIPTION
Pass a char * as parameter, which should be [user name]:[password] to use for
the connection to the HTTP proxy. Both the name and the password will be URL
decoded before use, so to include for example a colon in the user name you
should encode it as %3A. (This is different to how \fICURLOPT_USERPWD(3)\fP is
used - beware.)
Use \fICURLOPT_PROXYAUTH(3)\fP to specify the authentication method.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
This is NULL by default.
.SH PROTOCOLS
Used with all protocols that can use a proxy
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
curl_easy_setopt(curl, CURLOPT_PROXY, "http://localhost:8080");
curl_easy_setopt(curl, CURLOPT_PROXYUSERPWD, "clark%20kent:superman");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK if proxies are supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_PROXY "(3), " CURLOPT_PROXYTYPE "(3), "
share/man/man3/CURLOPT_NOPROGRESS.3 0000644 00000004200 14751150677 0012265 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_NOPROGRESS 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_NOPROGRESS \- switch off the progress meter
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NOPROGRESS, long onoff);
.fi
.SH DESCRIPTION
If \fIonoff\fP is to 1, it tells the library to shut off the progress meter
completely for requests done with this \fIhandle\fP. It will also prevent the
\fICURLOPT_XFERINFOFUNCTION(3)\fP or \fICURLOPT_PROGRESSFUNCTION(3)\fP from
getting called.
.SH DEFAULT
1, meaning it normally runs without a progress meter.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* enable progress meter */
curl_easy_setopt(curl, CURLOPT_NOPROGRESS, 0L);
/* Perform the request */
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_XFERINFOFUNCTION "(3), "
.BR CURLOPT_PROGRESSFUNCTION "(3), "
.BR CURLOPT_VERBOSE "(3), "
share/man/man3/CURLOPT_POSTQUOTE.3 0000644 00000004744 14751150677 0012204 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_POSTQUOTE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_POSTQUOTE \- (S)FTP commands to run after the transfer
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTQUOTE,
struct curl_slist *cmds);
.fi
.SH DESCRIPTION
Pass a pointer to a linked list of FTP or SFTP commands to pass to the server
after your FTP transfer request. The commands will only be run if no error
occurred. The linked list should be a fully valid list of struct curl_slist
structs properly filled in as described for \fICURLOPT_QUOTE(3)\fP.
Disable this operation again by setting a NULL to this option.
.SH DEFAULT
NULL
.SH PROTOCOLS
SFTP and FTP
.SH EXAMPLE
.nf
struct curl_slist *cmdlist = NULL;
cmdlist = curl_slist_append(cmdlist, "RNFR source-name");
cmdlist = curl_slist_append(cmdlist, "RNTO new-name");
curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/foo.bin");
/* pass in the FTP commands to run after the transfer */
curl_easy_setopt(curl, CURLOPT_POSTQUOTE, cmdlist);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
If support for the protocols are built-in.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_QUOTE "(3), " CURLOPT_PREQUOTE "(3), "
share/man/man3/CURLOPT_PROXY_SSL_CIPHER_LIST.3 0000644 00000007160 14751150677 0014123 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXY_SSL_CIPHER_LIST 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXY_SSL_CIPHER_LIST \- ciphers to use for HTTPS proxy
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSL_CIPHER_LIST,
char *list);
.fi
.SH DESCRIPTION
Pass a char *, pointing to a null-terminated string holding the list of
ciphers to use for the connection to the HTTPS proxy. The list must be
syntactically correct, it consists of one or more cipher strings separated by
colons. Commas or spaces are also acceptable separators but colons are
normally used, \&!, \&- and \&+ can be used as operators.
For OpenSSL and GnuTLS valid examples of cipher lists include \fBRC4-SHA\fP,
\fBSHA1+DES\fP, \fBTLSv1\fP and \fBDEFAULT\fP. The default list is normally
set when you compile OpenSSL.
For NSS, valid examples of cipher lists include \fBrsa_rc4_128_md5\fP,
\fBrsa_aes_128_sha\fP, etc. With NSS you do not add/remove ciphers. If one uses
this option then all known ciphers are disabled and only those passed in are
enabled.
For WolfSSL, valid examples of cipher lists include \fBECDHE-RSA-RC4-SHA\fP,
\fBAES256-SHA:AES256-SHA256\fP, etc.
For BearSSL, valid examples of cipher lists include
\fBECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256\fP, or when using IANA names
\fBTLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256:TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256\fP,
etc.
With BearSSL you do not add/remove ciphers. If one uses this option then all
known ciphers are disabled and only those passed in are enabled.
you will find more details about cipher lists on this URL:
https://curl.se/docs/ssl-ciphers.html
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL, use internal default
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost");
curl_easy_setopt(curl, CURLOPT_PROXY_SSL_CIPHER_LIST, "TLSv1");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.52.0, in 7.83.0 for BearSSL
If built TLS enabled.
.SH RETURN VALUE
Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_PROXY_TLS13_CIPHERS "(3), " CURLOPT_PROXY_SSLVERSION "(3), "
.BR CURLOPT_SSL_CIPHER_LIST "(3), " CURLOPT_TLS13_CIPHERS "(3), "
.BR CURLOPT_SSLVERSION "(3), "
share/man/man3/curl_global_init.3 0000644 00000011451 14751150677 0012672 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_global_init 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_global_init - Global libcurl initialization
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_global_init(long flags);
.fi
.SH DESCRIPTION
This function sets up the program environment that libcurl needs. Think of it
as an extension of the library loader.
This function must be called at least once within a program (a program is all
the code that shares a memory space) before the program calls any other
function in libcurl. The environment it sets up is constant for the life of
the program and is the same for every program, so multiple calls have the same
effect as one call.
The flags option is a bit pattern that tells libcurl exactly what features to
init, as described below. Set the desired bits by ORing the values together.
In normal operation, you must specify CURL_GLOBAL_ALL. Do not use any other
value unless you are familiar with it and mean to control internal operations
of libcurl.
This function is thread-safe since libcurl 7.84.0 if
\fIcurl_version_info(3)\fP has the CURL_VERSION_THREADSAFE feature bit set
(most platforms).
If this is not thread-safe, you must not call this function when any other
thread in the program (i.e. a thread sharing the same memory) is running.
This does not just mean no other thread that is using libcurl. Because
\fIcurl_global_init(3)\fP calls functions of other libraries that are
similarly thread unsafe, it could conflict with any other thread that uses
these other libraries.
If you are initializing libcurl from a Windows DLL you should not initialize
it from \fIDllMain\fP or a static initializer because Windows holds the loader
lock during that time and it could cause a deadlock.
See the description in \fIlibcurl(3)\fP of global environment requirements for
details of how to use this function.
.SH FLAGS
.IP CURL_GLOBAL_ALL
Initialize everything possible. This sets all known bits except
\fBCURL_GLOBAL_ACK_EINTR\fP.
.IP CURL_GLOBAL_SSL
(This flag's presence or absence serves no meaning since 7.57.0. The
description below is for older libcurl versions.)
Initialize SSL.
The implication here is that if this bit is not set, the initialization of the
SSL layer needs to be done by the application or at least outside of
libcurl. The exact procedure how to do SSL initialization depends on the TLS
backend libcurl uses.
Doing TLS based transfers without having the TLS layer initialized may lead to
unexpected behaviors.
.IP CURL_GLOBAL_WIN32
Initialize the Win32 socket libraries.
The implication here is that if this bit is not set, the initialization of
winsock has to be done by the application or you risk getting undefined
behaviors. This option exists for when the initialization is handled outside
of libcurl so there's no need for libcurl to do it again.
.IP CURL_GLOBAL_NOTHING
Initialize nothing extra. This sets no bit.
.IP CURL_GLOBAL_DEFAULT
A sensible default. It will init both SSL and Win32. Right now, this equals
the functionality of the \fBCURL_GLOBAL_ALL\fP mask.
.IP CURL_GLOBAL_ACK_EINTR
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.
.SH "SEE ALSO"
.BR curl_global_init_mem "(3), "
.BR curl_global_cleanup "(3), "
.BR curl_global_sslset "(3), "
.BR curl_easy_init "(3) "
.BR libcurl "(3) "
share/man/man3/CURLOPT_SSL_VERIFYPEER.3 0000644 00000010371 14751150677 0012773 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SSL_VERIFYPEER 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSL_VERIFYPEER \- verify the peer's SSL certificate
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_VERIFYPEER, long verify);
.fi
.SH DESCRIPTION
Pass a long as parameter to enable or disable.
This option determines whether curl verifies the authenticity of the peer's
certificate. A value of 1 means curl verifies; 0 (zero) means it does not.
When negotiating a TLS or SSL connection, the server sends a certificate
indicating its identity. Curl verifies whether the certificate is authentic,
i.e. that you can trust that the server is who the certificate says it is.
This trust is based on a chain of digital signatures, rooted in certification
authority (CA) certificates you supply. curl uses a default bundle of CA
certificates (the path for that is determined at build time) and you can
specify alternate certificates with the \fICURLOPT_CAINFO(3)\fP option or the
\fICURLOPT_CAPATH(3)\fP option.
When \fICURLOPT_SSL_VERIFYPEER(3)\fP is enabled, and the verification fails to
prove that the certificate is authentic, the connection fails. When the
option is zero, the peer certificate verification succeeds regardless.
Authenticating the certificate is not enough to be sure about the server. You
typically also want to ensure that the server is the server you mean to be
talking to. Use \fICURLOPT_SSL_VERIFYHOST(3)\fP for that. The check that the
host name in the certificate is valid for the host name you are connecting to
is done independently of the \fICURLOPT_SSL_VERIFYPEER(3)\fP option.
WARNING: disabling verification of the certificate allows bad guys to
man-in-the-middle the communication without you knowing it. Disabling
verification makes the communication insecure. Just having encryption on a
transfer is not enough as you cannot be sure that you are communicating with
the correct end-point.
NOTE: even when this option is disabled, depending on the used TLS backend,
curl may still load the certificate file specified in
\fICURLOPT_CAINFO(3)\fP. curl default settings in some distributions might use
quite a large file as a default setting for \fICURLOPT_CAINFO(3)\fP, so
loading the file can be quite expensive, especially when dealing with many
connections. Thus, in some situations, you might want to disable verification
fully to save resources by setting \fICURLOPT_CAINFO(3)\fP to NULL - but
please also consider the warning above!
.SH DEFAULT
By default, curl assumes a value of 1.
.SH PROTOCOLS
All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* Set the default value: strict certificate check please */
curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 1L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
If built TLS enabled.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_SSL_VERIFYHOST "(3), "
.BR CURLOPT_PROXY_SSL_VERIFYPEER "(3), "
.BR CURLOPT_PROXY_SSL_VERIFYHOST "(3), "
.BR CURLOPT_CAINFO "(3), "
share/man/man3/CURLOPT_HTTPPOST.3 0000644 00000006271 14751150677 0012063 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_HTTPPOST 3 "October 03, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_HTTPPOST \- multipart formpost content
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPPOST,
struct curl_httppost *formpost);
.SH DESCRIPTION
\fBThis option is deprecated.\fP Use \fICURLOPT_MIMEPOST(3)\fP instead.
Tells libcurl you want a \fBmultipart/formdata\fP HTTP POST to be made and you
instruct what data to pass on to the server in the \fIformpost\fP argument.
Pass a pointer to a linked list of \fIcurl_httppost\fP structs as parameter.
The easiest way to create such a list, is to use \fIcurl_formadd(3)\fP as
documented. The data in this list must remain intact as long as the curl
transfer is alive and is using it.
Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header.
You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP.
When setting \fICURLOPT_HTTPPOST(3)\fP, it will automatically set
\fICURLOPT_NOBODY(3)\fP to 0.
.SH DEFAULT
NULL
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
/* Fill in the file upload field. This makes libcurl load data from
the given file name when curl_easy_perform() is called. */
curl_formadd(&formpost,
&lastptr,
CURLFORM_COPYNAME, "sendfile",
CURLFORM_FILE, "postit2.c",
CURLFORM_END);
/* Fill in the filename field */
curl_formadd(&formpost,
&lastptr,
CURLFORM_COPYNAME, "filename",
CURLFORM_COPYCONTENTS, "postit2.c",
CURLFORM_END);
/* Fill in the submit field too, even if this is rarely needed */
curl_formadd(&formpost,
&lastptr,
CURLFORM_COPYNAME, "submit",
CURLFORM_COPYCONTENTS, "send",
CURLFORM_END);
.fi
.SH AVAILABILITY
As long as HTTP is enabled. Deprecated in 7.56.0.
.SH RETURN VALUE
Returns CURLE_OK if HTTP is enabled, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_POSTFIELDS "(3), " CURLOPT_POST "(3), " CURLOPT_MIMEPOST "(3),"
.BR curl_formadd "(3), " curl_formfree "(3), " curl_mime_init "(3)"
share/man/man3/CURLINFO_SPEED_UPLOAD_T.3 0000644 00000004271 14751150677 0013054 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_SPEED_UPLOAD_T 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_SPEED_UPLOAD_T \- get upload speed
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SPEED_UPLOAD_T,
curl_off_t *speed);
.fi
.SH DESCRIPTION
Pass a pointer to a \fIcurl_off_t\fP to receive the average upload speed that
curl measured for the complete upload. Measured in bytes/second.
.SH PROTOCOLS
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* Perform the request */
res = curl_easy_perform(curl);
if(!res) {
curl_off_t speed;
res = curl_easy_getinfo(curl, CURLINFO_SPEED_UPLOAD_T, &speed);
if(!res) {
printf("Upload speed %" CURL_FORMAT_CURL_OFF_T " bytes/sec\\n", speed);
}
}
}
.fi
.SH AVAILABILITY
Added in 7.55.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
.BR CURLINFO_SPEED_DOWNLOAD_T "(3), "
share/man/man3/curl_url_cleanup.3 0000644 00000003305 14751150677 0012717 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_url_cleanup 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_url_cleanup - free the URL handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
void curl_url_cleanup(CURLU *handle);
.fi
.SH DESCRIPTION
Frees all the resources associated with the given \fICURLU\fP handle!
.SH EXAMPLE
.nf
CURLU *url = curl_url();
curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
curl_url_cleanup(url);
.fi
.SH AVAILABILITY
Added in 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), "
share/man/man3/CURLOPT_PROXY_CRLFILE.3 0000644 00000006227 14751150677 0012660 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXY_CRLFILE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXY_CRLFILE \- HTTPS proxy Certificate Revocation List file
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_CRLFILE, char *file);
.fi
.SH DESCRIPTION
This option is for connecting to an HTTPS proxy, not an HTTPS server.
Pass a char * to a null-terminated string naming a \fIfile\fP with the
concatenation of CRL (in PEM format) to use in the certificate validation that
occurs during the SSL exchange.
When curl is built to use NSS or GnuTLS, there is no way to influence the use
of CRL passed to help in the verification process. When libcurl is built with
OpenSSL support, X509_V_FLAG_CRL_CHECK and X509_V_FLAG_CRL_CHECK_ALL are both
set, requiring CRL check against all the elements of the certificate chain if
a CRL file is passed.
This option makes sense only when used in combination with the
\fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP option.
A specific error code (\fICURLE_SSL_CRL_BADFILE\fP) is defined with the
option. It is returned when the SSL exchange fails because the CRL file cannot
be loaded. A failure in certificate verification due to a revocation
information found in the CRL does not trigger this specific error.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
Used with HTTPS proxy.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost:80");
curl_easy_setopt(curl, CURLOPT_PROXY_CRLFILE, "/etc/certs/crl.pem");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.52.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_PROXY_SSL_VERIFYPEER "(3), " CURLOPT_PROXY_SSL_VERIFYHOST "(3), "
.BR CURLOPT_SSL_VERIFYPEER "(3), " CURLOPT_SSL_VERIFYHOST "(3), "
share/man/man3/CURLOPT_HEADEROPT.3 0000644 00000006227 14751150677 0012112 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_HEADEROPT 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_HEADEROPT \- send HTTP headers to both proxy and host or separately
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HEADEROPT, long bitmask);
.fi
.SH DESCRIPTION
Pass a long that is a bitmask of options of how to deal with headers. The two
mutually exclusive options are:
\fBCURLHEADER_UNIFIED\fP - the headers specified in
\fICURLOPT_HTTPHEADER(3)\fP will be used in requests both to servers and
proxies. With this option enabled, \fICURLOPT_PROXYHEADER(3)\fP will not have
any effect.
\fBCURLHEADER_SEPARATE\fP - makes \fICURLOPT_HTTPHEADER(3)\fP headers only get
sent to a server and not to a proxy. Proxy headers must be set with
\fICURLOPT_PROXYHEADER(3)\fP to get used. Note that if a non-CONNECT request
is sent to a proxy, libcurl will send both server headers and proxy
headers. When doing CONNECT, libcurl will send \fICURLOPT_PROXYHEADER(3)\fP
headers only to the proxy and then \fICURLOPT_HTTPHEADER(3)\fP headers only to
the server.
.SH DEFAULT
CURLHEADER_SEPARATE (changed in 7.42.1, used CURLHEADER_UNIFIED before then)
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode ret;
struct curl_slist *list;
list = curl_slist_append(NULL, "Shoesize: 10");
list = curl_slist_append(list, "Accept:");
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_PROXY, "http://localhost:8080");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, list);
/* HTTPS over a proxy makes a separate CONNECT to the proxy, so tell
libcurl to not send the custom headers to the proxy. Keep them
separate! */
curl_easy_setopt(curl, CURLOPT_HEADEROPT, CURLHEADER_SEPARATE);
ret = curl_easy_perform(curl);
curl_slist_free_all(list);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.37.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_HTTPHEADER "(3), " CURLOPT_PROXYHEADER "(3), "
share/man/man3/CURLOPT_HSTSWRITEFUNCTION.3 0000644 00000006522 14751150677 0013337 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_HSTSWRITEFUNCTION 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_HSTSWRITEFUNCTION \- write callback for HSTS hosts
.SH SYNOPSIS
.nf
#include <curl/curl.h>
struct curl_hstsentry {
char *name;
size_t namelen;
unsigned int includeSubDomains:1;
char expire[18]; /* YYYYMMDD HH:MM:SS [null-terminated] */
};
struct curl_index {
size_t index; /* the provided entry's "index" or count */
size_t total; /* total number of entries to save */
};
CURLSTScode hstswrite(CURL *easy, struct curl_hstsentry *sts,
struct curl_index *count, void *userp);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTSWRITEFUNCTION, hstswrite);
.fi
.SH DESCRIPTION
Pass a pointer to your callback function, as the prototype shows above.
This callback function gets called by libcurl repeatedly to allow the
application to store the in-memory HSTS cache when libcurl is about to discard
it.
Set the \fIuserp\fP argument with the \fICURLOPT_HSTSWRITEDATA(3)\fP option or
it will be NULL.
When the callback is invoked, the \fIsts\fP pointer points to a populated
struct: Read the host name to 'name' (it is \fInamelen\fP bytes long and null
terminated. The \fIincludeSubDomains\fP field is non-zero if the entry matches
subdomains. The \fIexpire\fP string is a date stamp null-terminated string
using the syntax YYYYMMDD HH:MM:SS.
The callback should return \fICURLSTS_OK\fP if it succeeded and is prepared to
be called again (for another host) or \fICURLSTS_DONE\fP if there's nothing
more to do. It can also return \fICURLSTS_FAIL\fP to signal error.
This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to
do that.
.SH DEFAULT
NULL - no callback.
.SH PROTOCOLS
This feature is only used for HTTP(S) transfer.
.SH EXAMPLE
.nf
{
/* set HSTS read callback */
curl_easy_setopt(curl, CURLOPT_HSTSWRITEFUNCTION, hstswrite);
/* pass in suitable argument to the callback */
curl_easy_setopt(curl, CURLOPT_HSTSWRITEDATA, &hstspreload[0]);
result = curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.74.0
.SH RETURN VALUE
This will return CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_HSTSWRITEDATA "(3), " CURLOPT_HSTSWRITEFUNCTION "(3), "
.BR CURLOPT_HSTS "(3), " CURLOPT_HSTS_CTRL "(3), "
share/man/man3/CURLOPT_MAXREDIRS.3 0000644 00000004507 14751150677 0012134 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_MAXREDIRS 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_MAXREDIRS \- maximum number of redirects allowed
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXREDIRS, long amount);
.fi
.SH DESCRIPTION
Pass a long. The set number will be the redirection limit \fIamount\fP. If
that many redirections have been followed, the next redirect will cause an
error (\fICURLE_TOO_MANY_REDIRECTS\fP). This option only makes sense if the
\fICURLOPT_FOLLOWLOCATION(3)\fP is used at the same time.
Setting the limit to 0 will make libcurl refuse any redirect.
Set it to -1 for an infinite number of redirects.
.SH DEFAULT
-1, unlimited
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
/* enable redirect following */
curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
/* allow three redirects */
curl_easy_setopt(curl, CURLOPT_MAXREDIRS, 3L);
/* Perform the request */
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Along with HTTP
.SH RETURN VALUE
Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_FOLLOWLOCATION "(3), "
share/man/man3/CURLOPT_ACCEPT_ENCODING.3 0000644 00000010757 14751150677 0013007 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_ACCEPT_ENCODING 3 "September 28, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_ACCEPT_ENCODING \- automatic decompression of HTTP downloads
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ACCEPT_ENCODING, char *enc);
.fi
.SH DESCRIPTION
Pass a char * argument specifying what encoding you would like.
Sets the contents of the Accept-Encoding: header sent in an HTTP request, and
enables decoding of a response when a Content-Encoding: header is received.
libcurl potentially supports several different compressed encodings depending
on what support that has been built-in.
To aid applications not having to bother about what specific algorithms this
particular libcurl build supports, libcurl allows a zero-length string to be
set ("") to ask for an Accept-Encoding: header to be used that contains all
built-in supported encodings.
Alternatively, you can specify exactly the encoding or list of encodings you
want in the response. The following encodings are supported: \fIidentity\fP,
meaning non-compressed, \fIdeflate\fP which requests the server to compress
its response using the zlib algorithm, \fIgzip\fP which requests the gzip
algorithm, (since curl 7.57.0) \fIbr\fP which is brotli and (since curl
7.72.0) \fIzstd\fP which is zstd. Provide them in the string as a
comma-separated list of accepted encodings, like: \fB"br, gzip, deflate"\fP.
Set \fICURLOPT_ACCEPT_ENCODING(3)\fP to NULL to explicitly disable it, which
makes libcurl not send an Accept-Encoding: header and not decompress received
contents automatically.
You can also opt to just include the Accept-Encoding: header in your request
with \fICURLOPT_HTTPHEADER(3)\fP but then there will be no automatic
decompressing when receiving data.
This is a request, not an order; the server may or may not do it. This option
must be set (to any non-NULL value) or else any unsolicited encoding done by
the server is ignored.
Servers might respond with Content-Encoding even without getting a
Accept-Encoding: in the request. Servers might respond with a different
Content-Encoding than what was asked for in the request.
The Content-Length: servers send for a compressed response is supposed to
indicate the length of the compressed content so when auto decoding is enabled
it may not match the sum of bytes reported by the write callbacks (although,
sending the length of the non-compressed content is a common server mistake).
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* enable all supported built-in compressions */
curl_easy_setopt(curl, CURLOPT_ACCEPT_ENCODING, "");
/* Perform the request */
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
This option was called CURLOPT_ENCODING before 7.21.6
The specific libcurl you are using must have been built with zlib to be able to
decompress gzip and deflate responses, with the brotli library to
decompress brotli responses and with the zstd library to decompress zstd
responses.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_TRANSFER_ENCODING "(3), " CURLOPT_HTTPHEADER "(3), "
.BR CURLOPT_HTTP_CONTENT_DECODING "(3), "
share/man/man3/CURLINFO_APPCONNECT_TIME.3 0000644 00000005064 14751150677 0013136 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_APPCONNECT_TIME 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_APPCONNECT_TIME \- get the time until the SSL/SSH handshake is completed
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_APPCONNECT_TIME,
double *timep);
.fi
.SH DESCRIPTION
Pass a pointer to a double to receive the time, in seconds, it took from the
start until the SSL/SSH connect/handshake to the remote host was completed.
This time is most often close to the \fICURLINFO_PRETRANSFER_TIME(3)\fP time,
except for cases such as HTTP pipelining where the pretransfer time can be
delayed due to waits in line for the pipeline and more.
When a redirect is followed, the time from each request is added together.
See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
double connect;
curl_easy_setopt(curl, CURLOPT_URL, url);
res = curl_easy_perform(curl);
if(CURLE_OK == res) {
res = curl_easy_getinfo(curl, CURLINFO_APPCONNECT_TIME, &connect);
if(CURLE_OK == res) {
printf("Time: %.1f", connect);
}
}
/* always cleanup */
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.19.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), " CURLINFO_APPCONNECT_TIME_T "(3)"
share/man/man3/CURLOPT_DOH_URL.3 0000644 00000007142 14751150677 0011730 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 2022 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_DOH_URL 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_DOH_URL \- provide the DNS-over-HTTPS URL
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DOH_URL, char *URL);
.fi
.SH DESCRIPTION
Pass in a pointer to a \fIURL\fP for the DoH server to use for name
resolving. The parameter should be a char * to a null-terminated string which
must be URL-encoded in the following format: "https://host:port/path". It MUST
specify an HTTPS URL.
libcurl does not validate the syntax or use this variable until the transfer is
issued. Even if you set a crazy value here, \fIcurl_easy_setopt(3)\fP will
still return \fICURLE_OK\fP.
curl sends POST requests to the given DNS-over-HTTPS URL.
To find the DoH server itself, which might be specified using a name, libcurl
will use the default name lookup function. You can bootstrap that by providing
the address for the DoH server with \fICURLOPT_RESOLVE(3)\fP.
Disable DoH use again by setting this option to NULL.
.SH "INHERIT OPTIONS"
DoH lookups use SSL and some SSL settings from your transfer are inherited,
like \fICURLOPT_SSL_CTX_FUNCTION(3)\fP.
The hostname and peer certificate verification settings are not inherited but
can be controlled separately via \fICURLOPT_DOH_SSL_VERIFYHOST(3)\fP and
\fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP.
A set \fICURLOPT_OPENSOCKETFUNCTION(3)\fP callback is not inherited.
.SH "KNOWN BUGS"
Even when DoH is set to be used with this option, there are still some name
resolves that are performed without it, using the default name resolver
mechanism. This includes name resolves done for \fICURLOPT_INTERFACE(3)\fP,
\fICURLOPT_FTPPORT(3)\fP, a proxy type set to \fBCURLPROXY_SOCKS4\fP or
\fBCURLPROXY_SOCKS5\fP and probably some more.
.SH DEFAULT
NULL - there is no default DoH URL. If this option is not set, libcurl will use
the default name resolver.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_DOH_URL, "https://dns.example.com");
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.62.0
.SH RETURN VALUE
Returns CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insufficient
heap space.
Note that \fIcurl_easy_setopt(3)\fP will not immediately parse the given
string so when given a bad DoH URL, libcurl might not detect the problem until
it later tries to resolve a name with it.
.SH "SEE ALSO"
.BR CURLOPT_VERBOSE "(3), " CURLOPT_RESOLVE "(3), "
share/man/man3/CURLOPT_READFUNCTION.3 0000644 00000011161 14751150677 0012451 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_READFUNCTION 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_READFUNCTION \- read callback for data uploads
.SH SYNOPSIS
.nf
#include <curl/curl.h>
size_t read_callback(char *buffer, size_t size, size_t nitems, void *userdata);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_READFUNCTION, read_callback);
.fi
.SH DESCRIPTION
Pass a pointer to your callback function, as the prototype shows above.
This callback function gets called by libcurl as soon as it needs to read data
in order to send it to the peer - like if you ask it to upload or post data to
the server. The data area pointed at by the pointer \fIbuffer\fP should be
filled up with at most \fIsize\fP multiplied with \fInitems\fP number of bytes
by your function.
Set the \fIuserdata\fP argument with the \fICURLOPT_READDATA(3)\fP option.
Your function must return the actual number of bytes that it stored in the data
area pointed at by the pointer \fIbuffer\fP. Returning 0 will signal
end-of-file to the library and cause it to stop the current transfer.
If you stop the current transfer by returning 0 "pre-maturely" (i.e before the
server expected it, like when you have said you will upload N bytes and you
upload less than N bytes), you may experience that the server "hangs" waiting
for the rest of the data that will not come.
The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current
operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error
code from the transfer.
The callback can return \fICURL_READFUNC_PAUSE\fP to cause reading from this
connection to pause. See \fIcurl_easy_pause(3)\fP for further details.
\fBBugs\fP: when doing TFTP uploads, you must return the exact amount of data
that the callback wants, or it will be considered the final packet by the
server end and the transfer will end there.
If you set this callback pointer to NULL, or do not set it at all, the default
internal read function will be used. It is doing an fread() on the FILE *
userdata set with \fICURLOPT_READDATA(3)\fP.
You can set the total size of the data you are sending by using
\fICURLOPT_INFILESIZE_LARGE(3)\fP or \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP,
depending on the type of transfer. For some transfer types it may be required
and it allows for better error checking.
.SH DEFAULT
The default internal read callback is fread().
.SH PROTOCOLS
This is used for all protocols when doing uploads.
.SH EXAMPLE
.nf
size_t read_callback(char *ptr, size_t size, size_t nmemb, void *userdata)
{
FILE *readhere = (FILE *)userdata;
curl_off_t nread;
/* copy as much data as possible into the 'ptr' buffer, but no more than
'size' * 'nmemb' bytes! */
size_t retcode = fread(ptr, size, nmemb, readhere);
nread = (curl_off_t)retcode;
fprintf(stderr, "*** We read %" CURL_FORMAT_CURL_OFF_T
" bytes from file\\n", nread);
return retcode;
}
void setup(char *uploadthis)
{
FILE *file = fopen(uploadthis, "rb");
CURLcode result;
/* set callback to use */
curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_callback);
/* pass in suitable argument to callback */
curl_easy_setopt(curl, CURLOPT_READDATA, (void *)file);
result = curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
CURL_READFUNC_PAUSE return code was added in 7.18.0 and CURL_READFUNC_ABORT
was added in 7.12.1.
.SH RETURN VALUE
This will return CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_READDATA "(3), " CURLOPT_WRITEFUNCTION "(3), "
.BR CURLOPT_SEEKFUNCTION "(3), " CURLOPT_UPLOAD "(3), " CURLOPT_POST "(3), "
.BR CURLOPT_UPLOAD_BUFFERSIZE "(3), "
share/man/man3/CURLMOPT_PUSHDATA.3 0000644 00000005256 14751150677 0012126 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLMOPT_PUSHDATA 3 "May 17, 2022" "libcurl 7.86.0" "curl_multi_setopt options"
.SH NAME
CURLMOPT_PUSHDATA \- pointer to pass to push callback
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PUSHDATA, void *pointer);
.fi
.SH DESCRIPTION
Set \fIpointer\fP to pass as the last argument to the
\fICURLMOPT_PUSHFUNCTION(3)\fP callback. The pointer will not be touched or
used by libcurl itself, only passed on to the callback function.
.SH DEFAULT
NULL
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
.nf
/* only allow pushes for file names starting with "push-" */
int push_callback(CURL *parent,
CURL *easy,
size_t num_headers,
struct curl_pushheaders *headers,
void *userp)
{
char *headp;
int *transfers = (int *)userp;
FILE *out;
headp = curl_pushheader_byname(headers, ":path");
if(headp && !strncmp(headp, "/push-", 6)) {
fprintf(stderr, "The PATH is %s\\n", headp);
/* save the push here */
out = fopen("pushed-stream", "wb");
/* write to this file */
curl_easy_setopt(easy, CURLOPT_WRITEDATA, out);
(*transfers)++; /* one more */
return CURL_PUSH_OK;
}
return CURL_PUSH_DENY;
}
curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_callback);
curl_multi_setopt(multi, CURLMOPT_PUSHDATA, &counter);
.fi
.SH AVAILABILITY
Added in 7.44.0
.SH RETURN VALUE
Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLMOPT_PUSHFUNCTION "(3), " CURLMOPT_PIPELINING "(3), "
.BR CURLOPT_PIPEWAIT "(3), "
.BR RFC 7540
share/man/man3/CURLOPT_FOLLOWLOCATION.3 0000644 00000006720 14751150677 0012730 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_FOLLOWLOCATION 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_FOLLOWLOCATION \- follow HTTP 3xx redirects
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FOLLOWLOCATION, long enable);
.fi
.SH DESCRIPTION
A long parameter set to 1 tells the library to follow any Location: header
that the server sends as part of an HTTP header in a 3xx response. The
Location: header can specify a relative or an absolute URL to follow.
libcurl will issue another request for the new URL and follow new Location:
headers all the way until no more such headers are returned.
\fICURLOPT_MAXREDIRS(3)\fP can be used to limit the number of redirects
libcurl will follow.
libcurl limits what protocols it automatically follows to. The accepted
protocols are set with \fICURLOPT_REDIR_PROTOCOLS(3)\fP. By default libcurl
will allow HTTP, HTTPS, FTP and FTPS on redirect (7.65.2). Older versions of
libcurl allowed all protocols on redirect except those disabled for security
reasons: Since 7.19.4 FILE and SCP are disabled, and since 7.40.0 SMB and SMBS
are also disabled.
When following a Location:, the 3xx response code that redirected it also
dictates which request method it will use in the subsequent request: For 301,
302 and 303 responses libcurl will switch method from POST to GET unless
\fICURLOPT_POSTREDIR(3)\fP instructs libcurl otherwise. All other 3xx codes
will make libcurl send the same method again.
For users who think the existing location following is too naive, too simple
or just lacks features, it is easy to instead implement your own redirect
follow logic with the use of \fIcurl_easy_getinfo(3)\fP's
\fICURLINFO_REDIRECT_URL(3)\fP option instead of using
\fICURLOPT_FOLLOWLOCATION(3)\fP.
.SH DEFAULT
0, disabled
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* example.com is redirected, so we tell libcurl to follow redirection */
curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Along with HTTP
.SH RETURN VALUE
Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_REDIR_PROTOCOLS "(3), " CURLOPT_PROTOCOLS "(3), "
.BR CURLOPT_POSTREDIR "(3), "
.BR CURLINFO_REDIRECT_URL "(3), " CURLINFO_REDIRECT_COUNT "(3), "
share/man/man3/CURLINFO_RTSP_CLIENT_CSEQ.3 0000644 00000004032 14751150677 0013321 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_RTSP_CLIENT_CSEQ 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_RTSP_CLIENT_CSEQ \- get the next RTSP client CSeq
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_RTSP_CLIENT_CSEQ,
long *cseq);
.fi
.SH DESCRIPTION
Pass a pointer to a long to receive the next CSeq that will be used by the
application.
.SH PROTOCOLS
RTSP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res;
curl_easy_setopt(curl, CURLOPT_URL, "rtsp://rtsp.example.com");
res = curl_easy_perform(curl);
if(res == CURLE_OK) {
long cseq;
curl_easy_getinfo(curl, CURLINFO_RTSP_CLIENT_CSEQ, &cseq);
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.20.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
share/man/man3/CURLOPT_MAXCONNECTS.3 0000644 00000005322 14751150677 0012354 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_MAXCONNECTS 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_MAXCONNECTS \- maximum connection cache size
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXCONNECTS, long amount);
.fi
.SH DESCRIPTION
Pass a long. The set \fIamount\fP will be the maximum number of simultaneously
open persistent connections that libcurl may cache in the pool associated with
this handle. The default is 5, and there is not much point in changing this
value unless you are perfectly aware of how this works and changes libcurl's
behavior. This concerns connections using any of the protocols that support
persistent connections.
When reaching the maximum limit, curl closes the oldest one in the cache to
prevent increasing the number of open connections.
If you already have performed transfers with this curl handle, setting a
smaller \fICURLOPT_MAXCONNECTS(3)\fP than before may cause open connections to
get closed unnecessarily.
If you add this easy handle to a multi handle, this setting is not
acknowledged, and you must instead use \fIcurl_multi_setopt(3)\fP and the
\fICURLMOPT_MAXCONNECTS(3)\fP option.
.SH DEFAULT
5
.SH PROTOCOLS
Most
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode ret;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
/* limit the connection cache for this handle to no more than 3 */
curl_easy_setopt(curl, CURLOPT_MAXCONNECTS, 3L);
ret = curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLMOPT_MAXCONNECTS "(3), " CURLOPT_MAXREDIRS "(3), "
share/man/man3/CURLOPT_PROXY_TLSAUTH_PASSWORD.3 0000644 00000005202 14751150677 0014236 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXY_TLSAUTH_PASSWORD 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXY_TLSAUTH_PASSWORD \- password to use for proxy TLS authentication
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_TLSAUTH_PASSWORD,
char *pwd);
.fi
.SH DESCRIPTION
Pass a char * as parameter, which should point to the null-terminated password
to use for the TLS authentication method specified with the
\fICURLOPT_PROXY_TLSAUTH_TYPE(3)\fP option. Requires that the
\fICURLOPT_PROXY_TLSAUTH_USERNAME(3)\fP option also be set.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy");
curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_TYPE, "SRP");
curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_USERNAME, "user");
curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_PASSWORD, "secret");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.52.0, with the OpenSSL and GnuTLS backends only
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_PROXY_TLSAUTH_TYPE "(3), " CURLOPT_PROXY_TLSAUTH_USERNAME "(3), "
.BR CURLOPT_TLSAUTH_TYPE "(3), " CURLOPT_TLSAUTH_USERNAME "(3), "
share/man/man3/CURLOPT_HEADER.3 0000644 00000005234 14751150677 0011524 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_HEADER 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_HEADER \- pass headers to the data stream
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HEADER, long onoff);
.fi
.SH DESCRIPTION
Pass the long value \fIonoff\fP set to 1 to ask libcurl to include the headers
in the write callback (\fICURLOPT_WRITEFUNCTION(3)\fP). This option is
relevant for protocols that actually have headers or other meta-data (like
HTTP and FTP).
When asking to get the headers passed to the same callback as the body, it is
not possible to accurately separate them again without detailed knowledge
about the protocol in use.
Further: the \fICURLOPT_WRITEFUNCTION(3)\fP callback is limited to only ever
get a maximum of \fICURL_MAX_WRITE_SIZE\fP bytes passed to it (16KB), while a
header can be longer and the \fICURLOPT_HEADERFUNCTION(3)\fP supports getting
called with headers up to \fICURL_MAX_HTTP_HEADER\fP bytes big (100KB).
It is often better to use \fICURLOPT_HEADERFUNCTION(3)\fP to get the header
data separately.
While named confusingly similar, \fICURLOPT_HTTPHEADER(3)\fP is used to set
custom HTTP headers!
.SH DEFAULT
0
.SH PROTOCOLS
Most
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_HEADER, 1L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Provided in all libcurl versions.
.SH RETURN VALUE
Returns CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_HEADERFUNCTION "(3), "
.BR CURLOPT_HTTPHEADER "(3), "
share/man/man3/libcurl-env.3 0000644 00000011475 14751150677 0011612 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 2018 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH libcurl-env 3 "September 20, 2022" "libcurl 7.86.0" "libcurl environment variables"
.SH NAME
libcurl-env \- environment variables libcurl understands
.SH DESCRIPTION
libcurl reads and understands a set of environment variables that if set will
control and change behaviors. This is the full list of variables to set and
description of what they do. Also note that curl, the command line tool,
supports a set of additional environment variables independently of this.
.IP "[scheme]_proxy"
When libcurl is given a URL to use in a transfer, it first extracts the
"scheme" part from the URL and checks if there is a given proxy set for that
in its corresponding environment variable. A URL like "https://example.com"
will hence use the "http_proxy" variable, while a URL like "ftp://example.com"
will use the "ftp_proxy" variable.
These proxy variables are also checked for in their uppercase versions, except
the "http_proxy" one which is only used lowercase. Note also that some systems
actually have a case insensitive handling of environment variables and then of
course "HTTP_PROXY" will still work...
.IP ALL_PROXY
This is a setting to set proxy for all URLs, independently of what scheme is
being used. Note that the scheme specific variables will override this one if
set.
.IP CURL_SSL_BACKEND
When libcurl is built to support multiple SSL backends, it will select a
specific backend at first use. If no selection is done by the program using
libcurl, this variable's selection will be used. Setting a name that is not a
built-in alternative will make libcurl stay with the default.
SSL backend names (case-insensitive): BearSSL, GnuTLS, gskit, mbedTLS,
nss, OpenSSL, rustls, Schannel, Secure-Transport, wolfSSL
.IP HOME
When the netrc feature is used (\fICURLOPT_NETRC(3)\fP), this variable is
checked as the primary way to find the "current" home directory in which
the .netrc file is likely to exist.
.IP USERPROFILE
When the netrc feature is used (\fICURLOPT_NETRC(3)\fP), this variable is
checked as the secondary way to find the "current" home directory (on Windows
only) in which the .netrc file is likely to exist.
.IP LOGNAME
User name to use when invoking the \fIntlm-wb\fP tool, if \fINTLMUSER\fP was
not set.
.IP NO_PROXY
This has the same functionality as the \fICURLOPT_NOPROXY(3)\fP option: it
gives libcurl a comma-separated list of host name patterns for which libcurl
should not use a proxy.
.IP NTLMUSER
User name to use when invoking the \fIntlm-wb\fP tool.
.IP SSLKEYLOGFILE
When set and libcurl runs with a SSL backend that supports this feature,
libcurl will save SSL secrets into the given file name. Using those SSL
secrets, other tools (such as Wireshark) can decrypt the SSL communication and
analyze/view the traffic.
.IP SSL_DIR
When libcurl runs with the NSS backends for TLS features, this variable is
used to find the directory for NSS PKI database instead of the built-in.
.IP USER
User name to use when invoking the \fIntlm-wb\fP tool, if \fINTLMUSER\fP and
\fILOGNAME\fP were not set.
.SH "Debug Variables"
There's a set of variables only recognized and used if libcurl was built
"debug enabled", which should never be true for a library used in production.
.IP "CURL_GETHOSTNAME"
Debug-only variable.
.IP "CURL_FORCETIME"
Debug-only variable.
.IP "CURL_ENTROPY"
Debug-only variable. Used to set a fixed faked value to use instead of a
proper random number so that functions in libcurl that are otherwise getting
random outputs can be tested for what they generate.
.IP "CURL_TRACE"
Debug-only variable. Used for debugging the lib/ldap implementation.
.IP "CURL_NTLM_WB_FILE"
Debug-only variable. Used to set to a debug-version of the \fIntlm-wb\fP
executable.
.IP "CURL_OPENLDAP_TRACE"
Debug-only variable. Used for debugging the OpenLDAP implementation.
share/man/man3/CURLOPT_BUFFERSIZE.3 0000644 00000005330 14751150677 0012235 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_BUFFERSIZE 3 "August 23, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_BUFFERSIZE \- receive buffer size
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_BUFFERSIZE, long size);
.fi
.SH DESCRIPTION
Pass a long specifying your preferred \fIsize\fP (in bytes) for the receive
buffer in libcurl. The main point of this would be that the write callback
gets called more often and with smaller chunks. Secondly, for some protocols,
there's a benefit of having a larger buffer for performance.
This is just treated as a request, not an order. You cannot be guaranteed to
actually get the given size.
This buffer size is by default \fICURL_MAX_WRITE_SIZE\fP (16kB). The maximum
buffer size allowed to be set is \fICURL_MAX_READ_SIZE\fP (512kB). The minimum
buffer size allowed to be set is 1024.
DO NOT set this option on a handle that is currently used for an active
transfer as that may lead to unintended consequences.
.SH DEFAULT
CURL_MAX_WRITE_SIZE (16kB)
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/foo.bin");
/* ask libcurl to allocate a larger receive buffer */
curl_easy_setopt(curl, CURLOPT_BUFFERSIZE, 120000L);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.10. Growing the buffer was added in 7.53.0.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_MAX_RECV_SPEED_LARGE "(3), " CURLOPT_WRITEFUNCTION "(3), "
.BR CURLOPT_UPLOAD_BUFFERSIZE "(3), "
share/man/man3/CURLOPT_TCP_KEEPALIVE.3 0000644 00000004562 14751150677 0012612 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_TCP_KEEPALIVE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_TCP_KEEPALIVE \- TCP keep-alive probing
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_KEEPALIVE, long probe);
.fi
.SH DESCRIPTION
Pass a long. If set to 1, TCP keepalive probes will be sent. The delay and
frequency of these probes can be controlled by the
\fICURLOPT_TCP_KEEPIDLE(3)\fP and \fICURLOPT_TCP_KEEPINTVL(3)\fP options,
provided the operating system supports them. Set to 0 (default behavior) to
disable keepalive probes
.SH DEFAULT
0
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* enable TCP keep-alive for this transfer */
curl_easy_setopt(curl, CURLOPT_TCP_KEEPALIVE, 1L);
/* keep-alive idle time to 120 seconds */
curl_easy_setopt(curl, CURLOPT_TCP_KEEPIDLE, 120L);
/* interval time between keep-alive probes: 60 seconds */
curl_easy_setopt(curl, CURLOPT_TCP_KEEPINTVL, 60L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.25.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_TCP_KEEPIDLE "(3), " CURLOPT_TCP_KEEPINTVL "(3), "
share/man/man3/CURLOPT_RANGE.3 0000644 00000005677 14751150677 0011443 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_RANGE 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_RANGE \- byte range to request
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RANGE, char *range);
.fi
.SH DESCRIPTION
Pass a char * as parameter, which should contain the specified range you want
to retrieve. It should be in the format "X-Y", where either X or Y may be left
out and X and Y are byte indexes.
HTTP transfers also support several intervals, separated with commas as in
\fI"X-Y,N-M"\fP. Using this kind of multiple intervals will cause the HTTP
server to send the response document in pieces (using standard MIME separation
techniques). Unfortunately, the HTTP standard (RFC 7233 section 3.1) allows
servers to ignore range requests so even when you set \fICURLOPT_RANGE(3)\fP
for a request, you may end up getting the full response sent back.
For RTSP, the formatting of a range should follow RFC2326 Section 12.29. For
RTSP, byte ranges are \fBnot\fP permitted. Instead, ranges should be given in
\fBnpt\fP, \fButc\fP, or \fBsmpte\fP formats.
For HTTP PUT uploads this option should not be used, since it may conflict with
other options.
Pass a NULL to this option to disable the use of ranges.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
HTTP, FTP, FILE, RTSP and SFTP.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* get the first 200 bytes */
curl_easy_setopt(curl, CURLOPT_RANGE, "0-199");
/* Perform the request */
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
FILE since 7.18.0, RTSP since 7.20.0
.SH RETURN VALUE
Returns CURLE_OK on success or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_RESUME_FROM "(3), "
share/man/man3/CURLOPT_HTTP200ALIASES.3 0000644 00000005445 14751150677 0012603 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_HTTP200ALIASES 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_HTTP200ALIASES \- alternative matches for HTTP 200 OK
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP200ALIASES,
struct curl_slist *aliases);
.SH DESCRIPTION
Pass a pointer to a linked list of \fIaliases\fP to be treated as valid HTTP
200 responses. Some servers respond with a custom header response line. For
example, SHOUTcast servers respond with "ICY 200 OK". Also some old Icecast
1.3.x servers will respond like that for certain user agent headers or in
absence of such. By including this string in your list of aliases, the
response will be treated as a valid HTTP header line such as "HTTP/1.0 200
OK".
The linked list should be a fully valid list of struct curl_slist structs, and
be properly filled in. Use \fIcurl_slist_append(3)\fP to create the list and
\fIcurl_slist_free_all(3)\fP to clean up an entire list.
The alias itself is not parsed for any version strings. The protocol is
assumed to match HTTP 1.0 when an alias match.
.SH DEFAULT
NULL
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
struct curl_slist *list;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
list = curl_slist_append(NULL, "ICY 200 OK");
list = curl_slist_append(list, "WEIRDO 99 FINE");
curl_easy_setopt(curl, CURLOPT_HTTP200ALIASES, list);
curl_easy_perform(curl);
curl_slist_free_all(list); /* free the list again */
}
.fi
.SH AVAILABILITY
Added in 7.10.3
.SH RETURN VALUE
Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_HTTP_VERSION "(3), "
share/man/man3/CURLOPT_CRLFILE.3 0000644 00000006133 14751150677 0011653 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_CRLFILE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_CRLFILE \- Certificate Revocation List file
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CRLFILE, char *file);
.fi
.SH DESCRIPTION
Pass a char * to a null-terminated string naming a \fIfile\fP with the
concatenation of CRL (in PEM format) to use in the certificate validation that
occurs during the SSL exchange.
When curl is built to use NSS or GnuTLS, there is no way to influence the use
of CRL passed to help in the verification process.
When libcurl is built with OpenSSL support, X509_V_FLAG_CRL_CHECK and
X509_V_FLAG_CRL_CHECK_ALL are both set, requiring CRL check against all the
elements of the certificate chain if a CRL file is passed. Also note that
\fICURLOPT_CRLFILE(3)\fP will imply \fBCURLSSLOPT_NO_PARTIALCHAIN\fP (see
\fICURLOPT_SSL_OPTIONS(3)\fP) since curl 7.71.0 due to an OpenSSL bug.
This option makes sense only when used in combination with the
\fICURLOPT_SSL_VERIFYPEER(3)\fP option.
A specific error code (\fICURLE_SSL_CRL_BADFILE\fP) is defined with the
option. It is returned when the SSL exchange fails because the CRL file cannot
be loaded. A failure in certificate verification due to a revocation
information found in the CRL does not trigger this specific error.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
All TLS-based protocols
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_CRLFILE, "/etc/certs/crl.pem");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.19.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_SSL_VERIFYPEER "(3), " CURLOPT_SSL_VERIFYHOST "(3), "
.BR CURLOPT_PROXY_CRLFILE "(3), "
share/man/man3/libcurl-share.3 0000644 00000006021 14751150677 0012113 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH libcurl-share 3 "May 17, 2022" "libcurl 7.86.0" "libcurl share interface"
.SH NAME
libcurl-share \- how to use the share interface
.SH DESCRIPTION
This is an overview on how to use the libcurl share interface in your C
programs. There are specific man pages for each function mentioned in
here.
All functions in the share interface are prefixed with curl_share.
.SH "OBJECTIVES"
The share interface was added to enable sharing of data between curl
\&"handles".
.SH "ONE SET OF DATA - MANY TRANSFERS"
You can have multiple easy handles share data between them. Have them update
and use the \fBsame\fP cookie database, DNS cache, TLS session cache and/or
connection cache! This way, each single transfer will take advantage from data
updates made by the other transfer(s).
.SH "SHARE OBJECT"
You create a shared object with \fIcurl_share_init(3)\fP. It returns a handle
for a newly created one.
You tell the shared object what data you want it to share by using
\fIcurl_share_setopt(3)\fP.
Since you can use this share from multiple threads, and libcurl has no
internal thread synchronization, you must provide mutex callbacks if you are
using this multi-threaded. You set lock and unlock functions with
\fIcurl_share_setopt(3)\fP too.
Then, you make an easy handle to use this share, you set the
\fICURLOPT_SHARE(3)\fP option with \fIcurl_easy_setopt(3)\fP, and pass in
share handle. You can make any number of easy handles share the same share
handle.
To make an easy handle stop using that particular share, you set
\fICURLOPT_SHARE(3)\fP to NULL for that easy handle. To make a handle stop
sharing a particular data, you can \fICURLSHOPT_UNSHARE\fP it.
When you are done using the share, make sure that no easy handle is still using
it, and call \fIcurl_share_cleanup(3)\fP on the handle.
.SH "SEE ALSO"
.BR curl_share_init "(3), " curl_share_setopt "(3), " curl_share_cleanup "(3)"
.BR libcurl-errors "(3), " libcurl-easy "(3), " libcurl-multi "(3) "
share/man/man3/CURLINFO_LASTSOCKET.3 0000644 00000005400 14751150677 0012334 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_LASTSOCKET 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_LASTSOCKET \- get the last socket used
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_LASTSOCKET, long *socket);
.fi
.SH DESCRIPTION
Deprecated since 7.45.0. Use \fICURLINFO_ACTIVESOCKET(3)\fP instead.
Pass a pointer to a long to receive the last socket used by this curl
session. If the socket is no longer valid, -1 is returned. When you finish
working with the socket, you must call curl_easy_cleanup() as usual and let
libcurl close the socket and cleanup other resources associated with the
handle. This is typically used in combination with
\fICURLOPT_CONNECT_ONLY(3)\fP.
NOTE: this API is deprecated since it is not working on win64 where the SOCKET
type is 64 bits large while its 'long' is 32 bits. Use the
\fICURLINFO_ACTIVESOCKET(3)\fP instead, if possible.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
long sockfd; /* does not work on win64! */
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);
/* Extract the socket from the curl handle */
res = curl_easy_getinfo(curl, CURLINFO_LASTSOCKET, &sockfd);
if(res != CURLE_OK) {
printf("Error: %s\\n", curl_easy_strerror(res));
return 1;
}
}
.fi
.SH AVAILABILITY
Added in 7.15.2
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
.BR CURLINFO_ACTIVESOCKET "(3), "
share/man/man3/CURLOPT_XFERINFOFUNCTION.3 0000644 00000010372 14751150677 0013161 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_XFERINFOFUNCTION 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_XFERINFOFUNCTION \- progress meter callback
.SH SYNOPSIS
.nf
#include <curl/curl.h>
int progress_callback(void *clientp,
curl_off_t dltotal,
curl_off_t dlnow,
curl_off_t ultotal,
curl_off_t ulnow);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_XFERINFOFUNCTION,
progress_callback);
.fi
.SH DESCRIPTION
Pass a pointer to your callback function, which should match the prototype
shown above.
This function gets called by libcurl instead of its internal equivalent with a
frequent interval. While data is being transferred it will be called
frequently, and during slow periods like when nothing is being transferred it
can slow down to about one call per second.
\fIclientp\fP is the pointer set with \fICURLOPT_XFERINFODATA(3)\fP, it is not
used by libcurl but is only passed along from the application to the callback.
The callback gets told how much data libcurl will transfer and has
transferred, in number of bytes. \fIdltotal\fP is the total number of bytes
libcurl expects to download in this transfer. \fIdlnow\fP is the number of
bytes downloaded so far. \fIultotal\fP is the total number of bytes libcurl
expects to upload in this transfer. \fIulnow\fP is the number of bytes
uploaded so far.
Unknown/unused argument values passed to the callback will be set to zero
(like if you only download data, the upload size will remain 0). Many times
the callback will be called one or more times first, before it knows the data
sizes so a program must be made to handle that.
If your callback function returns CURL_PROGRESSFUNC_CONTINUE it will cause
libcurl to continue executing the default progress function.
Returning any other non-zero value from this callback will cause libcurl to
abort the transfer and return \fICURLE_ABORTED_BY_CALLBACK\fP.
If you transfer data with the multi interface, this function will not be
called during periods of idleness unless you call the appropriate libcurl
function that performs transfers.
\fICURLOPT_NOPROGRESS(3)\fP must be set to 0 to make this function actually
get called.
.SH DEFAULT
By default, libcurl has an internal progress meter. That is rarely wanted by
users.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
struct progress {
char *private;
size_t size;
};
static size_t progress_callback(void *clientp,
curl_off_t dltotal,
curl_off_t dlnow,
curl_off_t ultotal,
curl_off_t ulnow)
{
struct progress *memory = (struct progress *)clientp;
/* use the values */
return 0; /* all is good */
}
struct progress data;
/* pass struct to callback */
curl_easy_setopt(curl_handle, CURLOPT_XFERINFODATA, &data);
curl_easy_setopt(curl_handle, CURLOPT_XFERINFOFUNCTION, progress_callback);
.fi
.SH AVAILABILITY
Added in 7.32.0. This callback replaces \fICURLOPT_PROGRESSFUNCTION(3)\fP
.SH RETURN VALUE
Returns CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_XFERINFODATA "(3), " CURLOPT_NOPROGRESS "(3), "
share/man/man3/CURLOPT_AUTOREFERER.3 0000644 00000004605 14751150677 0012360 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_AUTOREFERER 3 "October 18, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_AUTOREFERER \- automatically update the referer header
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_AUTOREFERER, long autorefer);
.fi
.SH DESCRIPTION
Pass a long parameter set to 1 to enable this. When enabled, libcurl will
automatically set the Referer: header field in HTTP requests to the full URL
where it follows a Location: redirect.
The automatic referer is set to the full previous URL even when redirects are
done cross-origin or following redirects to insecure protocols. This is
considered a minor privacy leak by some.
.SH DEFAULT
0, disabled
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
/* follow redirects */
curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
/* set Referer: automatically when following redirects */
curl_easy_setopt(curl, CURLOPT_AUTOREFERER, 1L);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Along with HTTP
.SH RETURN VALUE
Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_REFERER "(3), " CURLOPT_FOLLOWLOCATION "(3), "
share/man/man3/CURLINFO_COOKIELIST.3 0000644 00000005555 14751150677 0012340 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_COOKIELIST 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_COOKIELIST \- get all known cookies
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_COOKIELIST,
struct curl_slist **cookies);
.fi
.SH DESCRIPTION
Pass a pointer to a 'struct curl_slist *' to receive a linked-list of all
cookies curl knows (expired ones, too). do not forget to call
\fIcurl_slist_free_all(3)\fP on the list after it has been used. If there are
no cookies (cookies for the handle have not been enabled or simply none have
been received) 'struct curl_slist *' will be set to point to NULL.
Since 7.43.0 cookies that were imported in the Set-Cookie format without a
domain name are not exported by this option.
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* enable the cookie engine */
curl_easy_setopt(curl, CURLOPT_COOKIEFILE, "");
res = curl_easy_perform(curl);
if(!res) {
/* extract all known cookies */
struct curl_slist *cookies = NULL;
res = curl_easy_getinfo(curl, CURLINFO_COOKIELIST, &cookies);
if(!res && cookies) {
/* a linked list of cookies in cookie file format */
struct curl_slist *each = cookies;
while(each) {
printf("%s\\n", each->data);
each = each->next;
}
/* we must free these cookies when we are done */
curl_slist_free_all(cookies);
}
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.14.1
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
.BR CURLOPT_COOKIELIST "(3), "
share/man/man3/CURLINFO_TLS_SSL_PTR.3 0000644 00000014517 14751150677 0012601 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_TLS_SSL_PTR 3 "September 22, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_TLS_SESSION, CURLINFO_TLS_SSL_PTR \- get TLS session info
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TLS_SSL_PTR,
struct curl_tlssessioninfo **session);
/* if you need compatibility with libcurl < 7.48.0 use
CURLINFO_TLS_SESSION instead: */
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TLS_SESSION,
struct curl_tlssessioninfo **session);
.SH DESCRIPTION
Pass a pointer to a \fIstruct curl_tlssessioninfo *\fP. The pointer will be
initialized to refer to a \fIstruct curl_tlssessioninfo *\fP that will contain
an enum indicating the SSL library used for the handshake and a pointer to the
respective internal TLS session structure of this underlying SSL library.
This option may be useful for example to extract certificate information in a
format convenient for further processing, such as manual validation. Refer to
the \fBLIMITATIONS\fP section.
.nf
struct curl_tlssessioninfo {
curl_sslbackend backend;
void *internals;
};
.fi
The \fIbackend\fP struct member is one of the defines in the CURLSSLBACKEND_*
series: CURLSSLBACKEND_NONE (when built without TLS support),
CURLSSLBACKEND_WOLFSSL, CURLSSLBACKEND_SECURETRANSPORT, CURLSSLBACKEND_GNUTLS,
CURLSSLBACKEND_GSKIT, CURLSSLBACKEND_MBEDTLS, CURLSSLBACKEND_NSS,
CURLSSLBACKEND_OPENSSL, CURLSSLBACKEND_SCHANNEL or
CURLSSLBACKEND_MESALINK. (Note that the OpenSSL forks are all reported as just
OpenSSL here.)
The \fIinternals\fP struct member will point to a TLS library specific pointer
for the active ("in use") SSL connection, with the following underlying types:
.RS
.IP GnuTLS
\fBgnutls_session_t\fP
.IP gskit
\fBgsk_handle\fP
.IP NSS
\fBPRFileDesc *\fP
.IP OpenSSL
\fICURLINFO_TLS_SESSION(3)\fP: \fBSSL_CTX *\fP
\fICURLINFO_TLS_SSL_PTR(3)\fP: \fBSSL *\fP
.RE
Since 7.48.0 the \fIinternals\fP member can point to these other SSL backends
as well:
.RS
.IP mbedTLS
\fBmbedTLS_ssl_context *\fP
.IP "Secure Channel"
\fBCtxtHandle *\fP
.IP "Secure Transport"
\fBSSLContext *\fP
.IP "wolfSSL"
\fBSSL *\fP
.RE
If the \fIinternals\fP pointer is NULL then either the SSL backend is not
supported, an SSL session has not yet been established or the connection is no
longer associated with the easy handle (e.g. curl_easy_perform has returned).
.SH LIMITATIONS
This option has some limitations that could make it unsafe when it comes to
the manual verification of certificates.
This option only retrieves the first in-use SSL session pointer for your easy
handle, however your easy handle may have more than one in-use SSL session if
using FTP over SSL. That is because the FTP protocol has a control channel and
a data channel and one or both may be over SSL. Currently there is no way to
retrieve a second in-use SSL session associated with an easy handle.
This option has not been thoroughly tested with clear text protocols that can
be upgraded/downgraded to/from SSL: FTP, SMTP, POP3, IMAP when used with
\fICURLOPT_USE_SSL(3)\fP. Though you will be able to retrieve the SSL pointer,
it's possible that before you can do that data (including auth) may have
already been sent over a connection after it was upgraded.
Renegotiation. If unsafe renegotiation or renegotiation in a way that the
certificate is allowed to change is allowed by your SSL library this may occur
and the certificate may change, and data may continue to be sent or received
after renegotiation but before you are able to get the (possibly) changed SSL
pointer, with the (possibly) changed certificate information.
If you are using OpenSSL or wolfSSL then \fICURLOPT_SSL_CTX_FUNCTION(3)\fP can
be used to set a certificate verification callback. That is safer than using
this option to poll for certificate changes and does not suffer from any of
the problems above. There is currently no way in libcurl to set a verification
callback for the other SSL backends.
How are you using this option? Are you affected by any of these limitations?
Please let us know by making a comment at
https://github.com/curl/curl/issues/685
.SH PROTOCOLS
All TLS-based
.SH EXAMPLE
.nf
#include <curl/curl.h>
#include <openssl/ssl.h>
CURL *curl;
static size_t wf(void *ptr, size_t size, size_t nmemb, void *stream)
{
const struct curl_tlssessioninfo *info = NULL;
CURLcode res = curl_easy_getinfo(curl, CURLINFO_TLS_SSL_PTR, &info);
if(info && !res) {
if(CURLSSLBACKEND_OPENSSL == info->backend) {
printf("OpenSSL ver. %s\\n", SSL_get_version((SSL*)info->internals));
}
}
return size * nmemb;
}
int main(int argc, char** argv)
{
CURLcode res;
curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, wf);
res = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
return res;
}
.fi
.SH AVAILABILITY
Added in 7.48.0.
This option supersedes \fICURLINFO_TLS_SESSION(3)\fP which was added in 7.34.0.
This option is exactly the same as that option except in the case of OpenSSL.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
.BR CURLINFO_TLS_SESSION "(3), "
share/man/man3/CURLOPT_PORT.3 0000644 00000004767 14751150677 0011372 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PORT 3 "July 04, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PORT \- remote port number to connect to
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PORT, long number);
.fi
.SH DESCRIPTION
We discourage using this option since its scope is not obvious and hard to
predict. Set the preferred port number in the URL instead.
This option sets \fInumber\fP to be the remote port number to connect to,
instead of the one specified in the URL or the default port for the used
protocol.
Usually, you just let the URL decide which port to use but this allows the
application to override that.
While this option accepts a 'long', a port number is an unsigned 16 bit number
and therefore using a port number lower than zero or over 65535 will cause a
\fBCURLE_BAD_FUNCTION_ARGUMENT\fP error.
.SH DEFAULT
By default this is 0 which makes it not used. This also makes port number zero
impossible to set with this API.
.SH PROTOCOLS
Used for all protocols that speak to a port number.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
curl_easy_setopt(curl, CURLOPT_PORT, 8080L);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_STDERR "(3), " CURLOPT_DEBUGFUNCTION "(3), "
share/man/man3/CURLOPT_PROXY_SSLCERT_BLOB.3 0000644 00000006033 14751150677 0013510 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXY_SSLCERT_BLOB 3 "September 06, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXY_SSLCERT_BLOB \- SSL proxy client certificate from memory blob
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSLCERT_BLOB,
struct curl_blob *blob);
.fi
.SH DESCRIPTION
Pass a pointer to a curl_blob structure, which contains information (pointer
and size) about a memory block with binary data of the certificate used to
connect to the HTTPS proxy. The format must be "P12" on Secure Transport or
Schannel. The format must be "P12" or "PEM" on OpenSSL. The string "P12" or
"PEM" must be specified with \fICURLOPT_PROXY_SSLCERTTYPE(3)\fP.
If the blob is initialized with the flags member of struct curl_blob set to
CURL_BLOB_COPY, the application does not have to keep the buffer around after
setting this.
This option is an alternative to \fICURLOPT_PROXY_SSLCERT(3)\fP which instead
expects a file name as input.
.SH DEFAULT
NULL
.SH PROTOCOLS
Used with HTTPS proxy
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
struct curl_blob blob;
blob.data = certificateData;
blob.len = filesize;
blob.flags = CURL_BLOB_COPY;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy");
curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEY, "key.pem");
curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "s3cret");
curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERT_BLOB, &blob);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.71.0. This option is supported by the OpenSSL, Secure Transport and
Schannel backends.
.SH RETURN VALUE
Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_PROXY_SSLCERTTYPE "(3), " CURLOPT_PROXY_SSLKEY "(3), "
.BR CURLOPT_PROXY_SSLCERT "(3), "
share/man/man3/curl_mime_init.3 0000644 00000005040 14751150677 0012356 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_mime_init 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_mime_init - create a mime handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
curl_mime *curl_mime_init(CURL *easy_handle);
.fi
.SH DESCRIPTION
\fIcurl_mime_init(3)\fP creates a handle to a new empty mime structure
intended to be used with \fIeasy_handle\fP. This mime structure can be
subsequently filled using the mime API, then attached to \fIeasy_handle\fP
using option \fICURLOPT_MIMEPOST(3)\fP within a \fIcurl_easy_setopt(3)\fP
call.
Using a mime handle is the recommended way to post an HTTP form, format and
send a multi-part email with SMTP or upload such an email to an IMAP server.
.SH EXAMPLE
.nf
CURL *easy = curl_easy_init();
curl_mime *mime;
curl_mimepart *part;
/* Build an HTTP form with a single field named "data", */
mime = curl_mime_init(easy);
part = curl_mime_addpart(mime);
curl_mime_data(part, "This is the field data", CURL_ZERO_TERMINATED);
curl_mime_name(part, "data");
/* Post and send it. */
curl_easy_setopt(easy, CURLOPT_MIMEPOST, mime);
curl_easy_setopt(easy, CURLOPT_URL, "https://example.com");
curl_easy_perform(easy);
/* 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),"
.BR CURLOPT_MIMEPOST "(3)"
share/man/man3/CURLOPT_MIMEPOST.3 0000644 00000004733 14751150677 0012034 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_MIMEPOST 3 "October 12, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_MIMEPOST \- send data from mime structure
.SH SYNOPSIS
.nf
#include <curl/curl.h>
curl_mime *mime;
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MIMEPOST, mime);
.SH DESCRIPTION
Pass a mime handle previously obtained from \fIcurl_mime_init(3)\fP.
This setting is supported by the HTTP protocol to post forms and by the
SMTP and IMAP protocols to provide the email data to send/upload.
This option is the preferred way of posting an HTTP form, replacing and
extending the \fICURLOPT_HTTPPOST(3)\fP option.
.SH PROTOCOLS
HTTP, SMTP, IMAP.
.SH EXAMPLE
.nf
curl_mime *multipart = curl_mime_init(handle);
curl_mimepart *part = curl_mime_addpart(multipart);
curl_mime_name(part, "name");
curl_mime_data(part, "daniel", CURL_ZERO_TERMINATED);
part = curl_mime_addpart(multipart);
curl_mime_name(part, "project");
curl_mime_data(part, "curl", CURL_ZERO_TERMINATED);
part = curl_mime_addpart(multipart);
curl_mime_name(part, "logotype-image");
curl_mime_filedata(part, "curl.png");
/* Set the form info */
curl_easy_setopt(handle, CURLOPT_MIMEPOST, multipart);
curl_easy_perform(handle); /* post away! */
curl_mime_free(multipart); /* free the post data */
.fi
.SH AVAILABILITY
Added in 7.56.0
.SH RETURN VALUE
This will return CURLE_OK.
.SH "SEE ALSO"
.BR curl_mime_init "(3)"
share/man/man3/CURLINFO_STARTTRANSFER_TIME.3 0000644 00000004667 14751150677 0013556 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_STARTTRANSFER_TIME 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_STARTTRANSFER_TIME \- get the time until the first byte is received
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_STARTTRANSFER_TIME,
double *timep);
.fi
.SH DESCRIPTION
Pass a pointer to a double to receive the time, in seconds, it took from the
start until the first byte is received by libcurl. This includes
\fICURLINFO_PRETRANSFER_TIME(3)\fP and also the time the server needs to
calculate the result.
When a redirect is followed, the time from each request is added together.
See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
double start;
curl_easy_setopt(curl, CURLOPT_URL, url);
res = curl_easy_perform(curl);
if(CURLE_OK == res) {
res = curl_easy_getinfo(curl, CURLINFO_STARTTRANSFER_TIME, &start);
if(CURLE_OK == res) {
printf("Time: %.1f", start);
}
}
/* always cleanup */
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.9.2
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), " CURLINFO_STARTTRANSFER_TIME_T "(3)"
share/man/man3/curl_mime_encoder.3 0000644 00000007314 14751150677 0013040 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_mime_encoder 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_mime_encoder - set a mime part's encoder and content transfer encoding
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_mime_encoder(curl_mimepart *part, const char *encoding);
.fi
.SH DESCRIPTION
curl_mime_encoder() requests a mime part's content to be encoded before being
transmitted.
\fIpart\fP is the part's handle to assign an encoder.
\fIencoding\fP is a pointer to a null-terminated encoding scheme. It may be
set to NULL to disable an encoder previously attached to the part. The encoding
scheme storage may safely be reused after this function returns.
Setting a part's encoder multiple times 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 \fI"Content-Transfer-Encoding"\fP header
is added to the part.
Supported encoding schemes are:
.br
"\fIbinary\fP": the data is left unchanged, the header is added.
.br
"\fI8bit\fP": header added, no data change.
.br
"\fI7bit\fP": the data is unchanged, but is each byte is checked
to be a 7-bit value; if not, a read error occurs.
.br
"\fIbase64\fP": Data is converted to base64 encoding, then split in
CRLF-terminated lines of at most 76 characters.
.br
"\fIquoted-printable\fP": data is encoded in quoted printable lines of
at most 76 characters. Since the resulting size of the final data cannot be
determined prior to reading the original data, it is left as unknown, causing
chunked transfer in HTTP. For the same reason, this encoder may not be used
with IMAP. This encoder targets text data that is mostly ASCII and should
not be used with other types of data.
If the original data is already encoded in such a scheme, a custom
\fIContent-Transfer-Encoding\fP header should be added with
\fIcurl_mime_headers\fP() instead of setting a part encoder.
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 EXAMPLE
.nf
curl_mime *mime;
curl_mimepart *part;
/* create a mime handle */
mime = curl_mime_init(easy);
/* add a part */
part = curl_mime_addpart(mime);
/* send a file */
curl_mime_filedata(part, "image.png");
/* 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),"
.BR curl_mime_subparts "(3)"
share/man/man3/CURLOPT_PATH_AS_IS.3 0000644 00000004624 14751150677 0012310 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PATH_AS_IS 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PATH_AS_IS \- do not handle dot dot sequences
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PATH_AS_IS, long leaveit);
.fi
.SH DESCRIPTION
Set the long \fIleaveit\fP to 1, to explicitly tell libcurl to not alter the
given path before passing it on to the server.
This instructs libcurl to NOT squash sequences of "/../" or "/./" that may
exist in the URL's path part and that is supposed to be removed according to
RFC 3986 section 5.2.4.
Some server implementations are known to (erroneously) require the dot dot
sequences to remain in the path and some clients want to pass these on in
order to try out server implementations.
By default libcurl will merge such sequences before using the path.
.SH DEFAULT
0
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/../../etc/password");
curl_easy_setopt(curl, CURLOPT_PATH_AS_IS, 1L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.42.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_STDERR "(3), " CURLOPT_DEBUGFUNCTION "(3), "
.BR CURLOPT_URL "(3), "
share/man/man3/curl_easy_getinfo.3 0000644 00000026612 14751150677 0013070 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH curl_easy_getinfo 3 "October 12, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_easy_getinfo - extract information from a curl handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *curl, CURLINFO info, ... );
.fi
.SH DESCRIPTION
Request internal information from the curl session with this function. The
third argument \fBMUST\fP be a pointer to a long, a pointer to a char *, a
pointer to a struct curl_slist * or a pointer to a double (as this
documentation describes further down). The data pointed-to will be filled in
accordingly and can be relied upon only if the function returns CURLE_OK. Use
this function AFTER a performed transfer if you want to get transfer related
data.
You should not free the memory returned by this function unless it is
explicitly mentioned below.
.SH AVAILABLE INFORMATION
The following information can be extracted:
.IP CURLINFO_EFFECTIVE_METHOD
Last used HTTP method.
See \fICURLINFO_EFFECTIVE_METHOD(3)\fP
.IP CURLINFO_EFFECTIVE_URL
Last used URL.
See \fICURLINFO_EFFECTIVE_URL(3)\fP
.IP CURLINFO_RESPONSE_CODE
Last received response code.
See \fICURLINFO_RESPONSE_CODE(3)\fP
.IP CURLINFO_REFERER
Referrer header.
See \fICURLINFO_REFERER(3)\fP
.IP CURLINFO_HTTP_CONNECTCODE
Last proxy CONNECT response code.
See \fICURLINFO_HTTP_CONNECTCODE(3)\fP
.IP CURLINFO_HTTP_VERSION
The http version used in the connection.
See \fICURLINFO_HTTP_VERSION(3)\fP
.IP CURLINFO_FILETIME
Remote time of the retrieved document. See \fICURLINFO_FILETIME(3)\fP
.IP CURLINFO_FILETIME_T
Remote time of the retrieved document. See \fICURLINFO_FILETIME_T(3)\fP
.IP CURLINFO_TOTAL_TIME
Total time of previous transfer.
See \fICURLINFO_TOTAL_TIME(3)\fP
.IP CURLINFO_TOTAL_TIME_T
Total time of previous transfer.
See \fICURLINFO_TOTAL_TIME_T(3)\fP
.IP CURLINFO_NAMELOOKUP_TIME
Time from start until name resolving completed.
See \fICURLINFO_NAMELOOKUP_TIME(3)\fP
.IP CURLINFO_NAMELOOKUP_TIME_T
Time from start until name resolving completed.
See \fICURLINFO_NAMELOOKUP_TIME_T(3)\fP
.IP CURLINFO_CONNECT_TIME
Time from start until remote host or proxy completed.
See \fICURLINFO_CONNECT_TIME(3)\fP
.IP CURLINFO_CONNECT_TIME_T
Time from start until remote host or proxy completed.
See \fICURLINFO_CONNECT_TIME_T(3)\fP
.IP CURLINFO_APPCONNECT_TIME
Time from start until SSL/SSH handshake completed.
See \fICURLINFO_APPCONNECT_TIME(3)\fP
.IP CURLINFO_APPCONNECT_TIME_T
Time from start until SSL/SSH handshake completed.
See \fICURLINFO_APPCONNECT_TIME_T(3)\fP
.IP CURLINFO_PRETRANSFER_TIME
Time from start until just before the transfer begins.
See \fICURLINFO_PRETRANSFER_TIME(3)\fP
.IP CURLINFO_PRETRANSFER_TIME_T
Time from start until just before the transfer begins.
See \fICURLINFO_PRETRANSFER_TIME_T(3)\fP
.IP CURLINFO_STARTTRANSFER_TIME
Time from start until just when the first byte is received.
See \fICURLINFO_STARTTRANSFER_TIME(3)\fP
.IP CURLINFO_STARTTRANSFER_TIME_T
Time from start until just when the first byte is received.
See \fICURLINFO_STARTTRANSFER_TIME_T(3)\fP
.IP CURLINFO_REDIRECT_TIME
Time taken for all redirect steps before the final transfer.
See \fICURLINFO_REDIRECT_TIME(3)\fP
.IP CURLINFO_REDIRECT_TIME_T
Time taken for all redirect steps before the final transfer.
See \fICURLINFO_REDIRECT_TIME_T(3)\fP
.IP CURLINFO_REDIRECT_COUNT
Total number of redirects that were followed.
See \fICURLINFO_REDIRECT_COUNT(3)\fP
.IP CURLINFO_REDIRECT_URL
URL a redirect would take you to, had you enabled redirects.
See \fICURLINFO_REDIRECT_URL(3)\fP
.IP CURLINFO_SIZE_UPLOAD
(Deprecated) Number of bytes uploaded.
See \fICURLINFO_SIZE_UPLOAD(3)\fP
.IP CURLINFO_SIZE_UPLOAD_T
Number of bytes uploaded.
See \fICURLINFO_SIZE_UPLOAD_T(3)\fP
.IP CURLINFO_SIZE_DOWNLOAD
(Deprecated) Number of bytes downloaded.
See \fICURLINFO_SIZE_DOWNLOAD(3)\fP
.IP CURLINFO_SIZE_DOWNLOAD_T
Number of bytes downloaded.
See \fICURLINFO_SIZE_DOWNLOAD_T(3)\fP
.IP CURLINFO_SPEED_DOWNLOAD
(Deprecated) Average download speed.
See \fICURLINFO_SPEED_DOWNLOAD(3)\fP
.IP CURLINFO_SPEED_DOWNLOAD_T
Average download speed.
See \fICURLINFO_SPEED_DOWNLOAD_T(3)\fP
.IP CURLINFO_SPEED_UPLOAD
(Deprecated) Average upload speed.
See \fICURLINFO_SPEED_UPLOAD(3)\fP
.IP CURLINFO_SPEED_UPLOAD_T
Average upload speed.
See \fICURLINFO_SPEED_UPLOAD_T(3)\fP
.IP CURLINFO_HEADER_SIZE
Number of bytes of all headers received.
See \fICURLINFO_HEADER_SIZE(3)\fP
.IP CURLINFO_REQUEST_SIZE
Number of bytes sent in the issued HTTP requests.
See \fICURLINFO_REQUEST_SIZE(3)\fP
.IP CURLINFO_SSL_VERIFYRESULT
Certificate verification result.
See \fICURLINFO_SSL_VERIFYRESULT(3)\fP
.IP CURLINFO_PROXY_ERROR
Detailed proxy error.
See \fICURLINFO_PROXY_ERROR(3)\fP
.IP CURLINFO_PROXY_SSL_VERIFYRESULT
Proxy certificate verification result.
See \fICURLINFO_PROXY_SSL_VERIFYRESULT(3)\fP
.IP CURLINFO_SSL_ENGINES
A list of OpenSSL crypto engines.
See \fICURLINFO_SSL_ENGINES(3)\fP
.IP CURLINFO_CONTENT_LENGTH_DOWNLOAD
(Deprecated) Content length from the Content-Length header.
See \fICURLINFO_CONTENT_LENGTH_DOWNLOAD(3)\fP
.IP CURLINFO_CONTENT_LENGTH_DOWNLOAD_T
Content length from the Content-Length header.
See \fICURLINFO_CONTENT_LENGTH_DOWNLOAD_T(3)\fP
.IP CURLINFO_CONTENT_LENGTH_UPLOAD
(Deprecated) Upload size. See \fICURLINFO_CONTENT_LENGTH_UPLOAD(3)\fP
.IP CURLINFO_CONTENT_LENGTH_UPLOAD_T
Upload size. See \fICURLINFO_CONTENT_LENGTH_UPLOAD_T(3)\fP
.IP CURLINFO_CONTENT_TYPE
Content type from the Content-Type header.
See \fICURLINFO_CONTENT_TYPE(3)\fP
.IP CURLINFO_RETRY_AFTER
The value from the from the Retry-After header.
See \fICURLINFO_RETRY_AFTER(3)\fP
.IP CURLINFO_PRIVATE
User's private data pointer.
See \fICURLINFO_PRIVATE(3)\fP
.IP CURLINFO_HTTPAUTH_AVAIL
Available HTTP authentication methods.
See \fICURLINFO_HTTPAUTH_AVAIL(3)\fP
.IP CURLINFO_PROXYAUTH_AVAIL
Available HTTP proxy authentication methods.
See \fICURLINFO_PROXYAUTH_AVAIL(3)\fP
.IP CURLINFO_OS_ERRNO
The errno from the last failure to connect.
See \fICURLINFO_OS_ERRNO(3)\fP
.IP CURLINFO_NUM_CONNECTS
Number of new successful connections used for previous transfer.
See \fICURLINFO_NUM_CONNECTS(3)\fP
.IP CURLINFO_PRIMARY_IP
IP address of the last connection.
See \fICURLINFO_PRIMARY_IP(3)\fP
.IP CURLINFO_PRIMARY_PORT
Port of the last connection.
See \fICURLINFO_PRIMARY_PORT(3)\fP
.IP CURLINFO_LOCAL_IP
Local-end IP address of last connection.
See \fICURLINFO_LOCAL_IP(3)\fP
.IP CURLINFO_LOCAL_PORT
Local-end port of last connection.
See \fICURLINFO_LOCAL_PORT(3)\fP
.IP CURLINFO_COOKIELIST
List of all known cookies.
See \fICURLINFO_COOKIELIST(3)\fP
.IP CURLINFO_LASTSOCKET
(Deprecated) Last socket used.
See \fICURLINFO_LASTSOCKET(3)\fP
.IP CURLINFO_ACTIVESOCKET
The session's active socket.
See \fICURLINFO_ACTIVESOCKET(3)\fP
.IP CURLINFO_FTP_ENTRY_PATH
The entry path after logging in to an FTP server.
See \fICURLINFO_FTP_ENTRY_PATH(3)\fP
.IP CURLINFO_CAPATH
Get the default value for \fICURLOPT_CAPATH(3)\fP.
See \fICURLINFO_CAPATH(3)\fP
.IP CURLINFO_CAINFO
Get the default value for \fICURLOPT_CAINFO(3)\fP.
See \fICURLINFO_CAINFO(3)\fP
.IP CURLINFO_CERTINFO
Certificate chain.
See \fICURLINFO_CERTINFO(3)\fP
.IP CURLINFO_TLS_SSL_PTR
TLS session info that can be used for further processing.
See \fICURLINFO_TLS_SSL_PTR(3)\fP
.IP CURLINFO_TLS_SESSION
TLS session info that can be used for further processing. See
\fICURLINFO_TLS_SESSION(3)\fP. Deprecated option, use
\fICURLINFO_TLS_SSL_PTR(3)\fP instead!
.IP CURLINFO_CONDITION_UNMET
Whether or not a time conditional was met or 304 HTTP response.
See \fICURLINFO_CONDITION_UNMET(3)\fP
.IP CURLINFO_RTSP_SESSION_ID
RTSP session ID.
See \fICURLINFO_RTSP_SESSION_ID(3)\fP
.IP CURLINFO_RTSP_CLIENT_CSEQ
RTSP CSeq that will next be used.
See \fICURLINFO_RTSP_CLIENT_CSEQ(3)\fP
.IP CURLINFO_RTSP_SERVER_CSEQ
RTSP CSeq that will next be expected.
See \fICURLINFO_RTSP_SERVER_CSEQ(3)\fP
.IP CURLINFO_RTSP_CSEQ_RECV
RTSP CSeq last received.
See \fICURLINFO_RTSP_CSEQ_RECV(3)\fP
.IP CURLINFO_PROTOCOL
(Deprecated) The protocol used for the connection. (Added in 7.52.0)
See \fICURLINFO_PROTOCOL(3)\fP
.IP CURLINFO_SCHEME
The scheme used for the connection. (Added in 7.52.0)
See \fICURLINFO_SCHEME(3)\fP
.SH TIMES
.nf
An overview of the six time values available from curl_easy_getinfo()
curl_easy_perform()
|
|--NAMELOOKUP
|--|--CONNECT
|--|--|--APPCONNECT
|--|--|--|--PRETRANSFER
|--|--|--|--|--STARTTRANSFER
|--|--|--|--|--|--TOTAL
|--|--|--|--|--|--REDIRECT
.fi
.IP NAMELOOKUP
\fICURLINFO_NAMELOOKUP_TIME\fP and \fICURLINFO_NAMELOOKUP_TIME_T\fP.
The time it took from the start until the name resolving was completed.
.IP CONNECT
\fICURLINFO_CONNECT_TIME\fP and \fICURLINFO_CONNECT_TIME_T\fP.
The time it took from the start until the connect
to the remote host (or proxy) was completed.
.IP APPCONNECT
\fICURLINFO_APPCONNECT_TIME\fP and \fICURLINFO_APPCONNECT_TIME_T\fP.
The time it took from the start until the SSL
connect/handshake with the remote host was completed. (Added in 7.19.0)
The latter is the integer version (measuring microseconds). (Added in 7.60.0)
.IP PRETRANSFER
\fICURLINFO_PRETRANSFER_TIME\fP and \fICURLINFO_PRETRANSFER_TIME_T\fP.
The time it took from the start until the
file transfer is just about to begin. This includes all pre-transfer commands
and negotiations that are specific to the particular protocol(s) involved.
.IP STARTTRANSFER
\fICURLINFO_STARTTRANSFER_TIME\fP and \fICURLINFO_STARTTRANSFER_TIME_T\fP.
The time it took from the start until the
first byte is received by libcurl.
.IP TOTAL
\fICURLINFO_TOTAL_TIME\fP and \fICURLINFO_TOTAL_TIME_T\fP.
Total time of the previous request.
.IP REDIRECT
\fICURLINFO_REDIRECT_TIME\fP and \fICURLINFO_REDIRECT_TIME_T\fP.
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 7.4.1
.SH RETURN VALUE
If the operation was successful, CURLE_OK is returned. Otherwise an
appropriate error code will be returned.
.SH "SEE ALSO"
.BR curl_easy_setopt "(3)"
share/man/man3/CURLOPT_LOW_SPEED_TIME.3 0000644 00000004302 14751150677 0012766 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_LOW_SPEED_TIME 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_LOW_SPEED_TIME \- low speed limit time period
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_LOW_SPEED_TIME,
long speedtime);
.fi
.SH DESCRIPTION
Pass a long as parameter. It contains the time in number seconds that the
transfer speed should be below the \fICURLOPT_LOW_SPEED_LIMIT(3)\fP for the
library to consider it too slow and abort.
.SH DEFAULT
0, disabled
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, url);
/* abort if slower than 30 bytes/sec during 60 seconds */
curl_easy_setopt(curl, CURLOPT_LOW_SPEED_TIME, 60L);
curl_easy_setopt(curl, CURLOPT_LOW_SPEED_LIMIT, 30L);
res = curl_easy_perform(curl);
if(CURLE_OPERATION_TIMEDOUT == res) {
printf("Timeout!\\n");
}
/* always cleanup */
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_LOW_SPEED_LIMIT "(3), " CURLOPT_TIMEOUT "(3), "
share/man/man3/CURLOPT_POSTREDIR.3 0000644 00000006107 14751150677 0012147 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_POSTREDIR 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_POSTREDIR \- how to act on an HTTP POST redirect
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTREDIR,
long bitmask);
.SH DESCRIPTION
Pass a bitmask to control how libcurl acts on redirects after POSTs that get a
301, 302 or 303 response back. A parameter with bit 0 set (value
\fBCURL_REDIR_POST_301\fP) tells the library to respect RFC 7231 (section
6.4.2 to 6.4.4) and not convert POST requests into GET requests when following
a 301 redirection. Setting bit 1 (value \fBCURL_REDIR_POST_302\fP) makes
libcurl maintain the request method after a 302 redirect whilst setting bit 2
(value \fBCURL_REDIR_POST_303\fP) makes libcurl maintain the request method
after a 303 redirect. The value \fBCURL_REDIR_POST_ALL\fP is a convenience
define that sets all three bits.
The non-RFC behavior is ubiquitous in web browsers, so the library does the
conversion by default to maintain consistency. However, a server may require a
POST to remain a POST after such a redirection. This option is meaningful only
when setting \fICURLOPT_FOLLOWLOCATION(3)\fP.
.SH DEFAULT
0
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* a silly POST example */
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "data=true");
/* example.com is redirected, so we tell libcurl to send POST on 301, 302 and
303 HTTP response codes */
curl_easy_setopt(curl, CURLOPT_POSTREDIR, CURL_REDIR_POST_ALL);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.17.1. This option was known as CURLOPT_POST301 up to 7.19.0 as it
only supported the 301 then. CURL_REDIR_POST_303 was added in 7.26.0.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_FOLLOWLOCATION "(3), " CURLOPT_POSTFIELDS "(3), "
share/man/man3/libcurl-thread.3 0000644 00000013077 14751150677 0012271 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 2015 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH libcurl-thread 3 "September 20, 2022" "libcurl 7.86.0" "libcurl thread safety"
.SH NAME
libcurl-thread \- libcurl thread safety
.SH "Multi-threading with libcurl"
libcurl is thread safe but has no internal thread synchronization. You may have
to provide your own locking should you meet any of the thread safety exceptions
below.
\fBHandles.\fP You must \fBnever\fP share the same handle in multiple threads.
You can pass the handles around among threads, but you must never use a single
handle from more than one thread at any given time.
\fBShared objects.\fP You can share certain data between multiple handles by
using the share interface but you must provide your own locking and set
\fIcurl_share_setopt(3)\fP CURLSHOPT_LOCKFUNC and CURLSHOPT_UNLOCKFUNC.
.SH TLS
If you are accessing HTTPS or FTPS URLs in a multi-threaded manner, you are
then of course using the underlying SSL library multi-threaded and those libs
might have their own requirements on this issue. You may need to provide one
or two functions to allow it to function properly:
.IP OpenSSL
OpenSSL 1.1.0+ "can be safely used in multi-threaded applications provided that
support for the underlying OS threading API is built-in." In that case the
engine is used by libcurl in a way that is fully thread-safe.
https://www.openssl.org/docs/man1.1.0/man3/CRYPTO_THREAD_run_once.html#DESCRIPTION
OpenSSL <= 1.0.2 the user must set callbacks.
https://www.openssl.org/docs/man1.0.2/man3/CRYPTO_set_locking_callback.html#DESCRIPTION
https://curl.se/libcurl/c/opensslthreadlock.html
.IP GnuTLS
https://gnutls.org/manual/html_node/Thread-safety.html
.IP NSS
thread-safe already without anything required.
.IP Secure-Transport
The engine is used by libcurl in a way that is fully thread-safe.
.IP Schannel
The engine is used by libcurl in a way that is fully thread-safe.
.IP wolfSSL
The engine is used by libcurl in a way that is fully thread-safe.
.IP BoringSSL
The engine is used by libcurl in a way that is fully thread-safe.
.SH "Other areas of caution"
.IP Signals
Signals are used for timing out name resolves (during DNS lookup) - when built
without using either the c-ares or threaded resolver backends. When using
multiple threads you should set the \fICURLOPT_NOSIGNAL(3)\fP option to 1L for
all handles. Everything will or might work fine except that timeouts are not
honored during the DNS lookup - which you can work around by building libcurl
with c-ares or threaded-resolver support. c-ares is a library that provides
asynchronous name resolves. On some platforms, libcurl simply will not
function properly multi-threaded unless the \fICURLOPT_NOSIGNAL(3)\fP option
is set.
When \fICURLOPT_NOSIGNAL(3)\fP is set to 1L, your application needs to deal
with the risk of a SIGPIPE (that at least the OpenSSL backend can
trigger). Note that setting \fICURLOPT_NOSIGNAL(3)\fP to 0L will not work in a
threaded situation as there will be race where libcurl risks restoring the
former signal handler while another thread should still ignore it.
.IP "Name resolving"
\fBgethostby* functions and other system calls.\fP These functions, provided
by your operating system, must be thread safe. It is important that libcurl
can find and use thread safe versions of these and other system calls, as
otherwise it cannot function fully thread safe. Some operating systems are
known to have faulty thread implementations. We have previously received
problem reports on *BSD (at least in the past, they may be working fine these
days). Some operating systems that are known to have solid and working thread
support are Linux, Solaris and Windows.
.IP "curl_global_* functions"
These functions are thread-safe since libcurl 7.84.0 if
\fIcurl_version_info(3)\fP has the \fBCURL_VERSION_THREADSAFE\fP feature bit
set (most platforms).
If these functions are not thread-safe and you are using libcurl with multiple
threads it is especially important that before use you call
\fIcurl_global_init(3)\fP or \fIcurl_global_init_mem(3)\fP to explicitly
initialize the library and its dependents, rather than rely on the "lazy"
fail-safe initialization that takes place the first time
\fIcurl_easy_init(3)\fP is called. For an in-depth explanation refer to
\fIlibcurl(3)\fP section \fBGLOBAL CONSTANTS\fP.
.IP "Memory functions"
These functions, provided either by your operating system or your own
replacements, must be thread safe. You can use \fIcurl_global_init_mem(3)\fP
to set your own replacement memory functions.
.IP "Non-safe functions"
\fICURLOPT_DNS_USE_GLOBAL_CACHE(3)\fP is not thread-safe.
share/man/man3/CURLOPT_POST.3 0000644 00000007500 14751150677 0011357 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_POST 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_POST \- make an HTTP POST
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POST, long post);
.fi
.SH DESCRIPTION
A parameter set to 1 tells libcurl to do a regular HTTP post. This will also
make the library use a "Content-Type: application/x-www-form-urlencoded"
header. (This is by far the most commonly used POST method).
Use one of \fICURLOPT_POSTFIELDS(3)\fP or \fICURLOPT_COPYPOSTFIELDS(3)\fP
options to specify what data to post and \fICURLOPT_POSTFIELDSIZE(3)\fP or
\fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP to set the data size.
Optionally, you can provide data to POST using the
\fICURLOPT_READFUNCTION(3)\fP and \fICURLOPT_READDATA(3)\fP options but then
you must make sure to not set \fICURLOPT_POSTFIELDS(3)\fP to anything but
NULL. When providing data with a callback, you must transmit it using chunked
transfer-encoding or you must set the size of the data with the
\fICURLOPT_POSTFIELDSIZE(3)\fP or \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP
options. To enable chunked encoding, you simply pass in the appropriate
Transfer-Encoding header, see the post-callback.c example.
You can override the default POST Content-Type: header by setting your own
with \fICURLOPT_HTTPHEADER(3)\fP.
Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header.
You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP as usual.
If you use POST to an HTTP 1.1 server, you can send data without knowing the
size before starting the POST if you use chunked encoding. You enable this by
adding a header like "Transfer-Encoding: chunked" with
\fICURLOPT_HTTPHEADER(3)\fP. With HTTP 1.0 or without chunked transfer, you
must specify the size in the request. (Since 7.66.0, libcurl will
automatically use chunked encoding for POSTs if the size is unknown.)
When setting \fICURLOPT_POST(3)\fP to 1, libcurl will automatically set
\fICURLOPT_NOBODY(3)\fP and \fICURLOPT_HTTPGET(3)\fP to 0.
If you issue a POST request and then want to make a HEAD or GET using the same
re-used handle, you must explicitly set the new request type using
\fICURLOPT_NOBODY(3)\fP or \fICURLOPT_HTTPGET(3)\fP or similar.
.SH DEFAULT
0, disabled
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
curl_easy_setopt(curl, CURLOPT_POST, 1L);
/* set up the read callback with CURLOPT_READFUNCTION */
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Along with HTTP
.SH RETURN VALUE
Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_POSTFIELDS "(3), " CURLOPT_HTTPPOST "(3), "
share/man/man3/CURLOPT_QUOTE.3 0000644 00000011733 14751150677 0011472 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_QUOTE 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_QUOTE \- (S)FTP commands to run before transfer
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_QUOTE,
struct curl_slist *cmds);
.fi
.SH DESCRIPTION
Pass a pointer to a linked list of FTP or SFTP commands to pass to the server
prior to your request. This will be done before any other commands are issued
(even before the CWD command for FTP). The linked list should be a fully valid
list of 'struct curl_slist' structs properly filled in with text strings. Use
\fIcurl_slist_append(3)\fP to append strings (commands) to the list, and clear
the entire list afterwards with \fIcurl_slist_free_all(3)\fP.
Disable this operation again by setting a NULL to this option.
When speaking to an FTP server, prefix the command with an asterisk (*) to
make libcurl continue even if the command fails as by default libcurl will
stop at first failure.
The set of valid FTP commands depends on the server (see RFC959 for a list of
mandatory commands).
libcurl does not inspect, parse or "understand" the commands passed to the
server using this option. If you change connection state, working directory or
similar using quote commands, libcurl will not know about it.
The valid SFTP commands are:
.RS
.IP "atime date file"
The atime command sets the last access time of the file named by the file
operand. The <date expression> can be all sorts of date strings, see the
\fIcurl_getdate(3)\fP man page for date expression details. (Added in 7.73.0)
.IP "chgrp group file"
The chgrp command sets the group ID of the file named by the file operand to
the group ID specified by the group operand. The group operand is a decimal
integer group ID.
.IP "chmod mode file"
The chmod command modifies the file mode bits of the specified file. The
mode operand is an octal integer mode number.
.IP "chown user file"
The chown command sets the owner of the file named by the file operand to the
user ID specified by the user operand. The user operand is a decimal
integer user ID.
.IP "ln source_file target_file"
The \fBln\fP and \fBsymlink\fP commands create a symbolic link at the
target_file location pointing to the source_file location.
.IP "mkdir directory_name"
The mkdir command creates the directory named by the directory_name operand.
.IP "mtime date file"
The mtime command sets the last modification time of the file named by the
file operand. The <date expression> can be all sorts of date strings, see the
\fIcurl_getdate(3)\fP man page for date expression details. (Added in 7.73.0)
.IP "pwd"
The \fBpwd\fP command returns the absolute path of the current working
directory.
.IP "rename source target"
The rename command renames the file or directory named by the source
operand to the destination path named by the target operand.
.IP "rm file"
The rm command removes the file specified by the file operand.
.IP "rmdir directory"
The rmdir command removes the directory entry specified by the directory
operand, provided it is empty.
.IP "statvfs file"
The statvfs command returns statistics on the file system in which specified
file resides. (Added in 7.49.0)
.IP "symlink source_file target_file"
See ln.
.RE
.SH DEFAULT
NULL
.SH PROTOCOLS
SFTP and FTP
.SH EXAMPLE
.nf
struct curl_slist *cmdlist = NULL;
cmdlist = curl_slist_append(cmdlist, "RNFR source-name");
cmdlist = curl_slist_append(cmdlist, "RNTO new-name");
curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/foo.bin");
/* pass in the FTP commands to run before the transfer */
curl_easy_setopt(curl, CURLOPT_QUOTE, cmdlist);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
SFTP support added in 7.16.3. *-prefix for SFTP added in 7.24.0
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_POSTQUOTE "(3), " CURLOPT_PREQUOTE "(3), "
share/man/man3/CURLOPT_MAXLIFETIME_CONN.3 0000644 00000005376 14751150677 0013164 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_MAXLIFETIME_CONN 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_MAXLIFETIME_CONN \- max lifetime (since creation) allowed for reusing a connection
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXLIFETIME_CONN,
long maxlifetime);
.fi
.SH DESCRIPTION
Pass a long as parameter containing \fImaxlifetime\fP - the maximum time in
seconds, since the creation of the connection, that you allow an existing
connection to have to be considered for reuse for this request.
libcurl features a connection cache that holds previously used connections.
When a new request is to be done, it will consider any connection that matches
for reuse. The \fICURLOPT_MAXLIFETIME_CONN(3)\fP limit prevents libcurl from
trying too old connections for reuse. This can be used for client-side load
balancing. If a connection is found in the cache that is older than this set
\fImaxlifetime\fP, it will instead be closed once any in-progress transfers
complete.
If set to 0, this behavior is disabled: all connections are eligible for reuse.
.SH DEFAULT
Default \fImaxlifetime\fP is 0 seconds (i.e., disabled).
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* only allow each connection to be reused for 30 seconds */
curl_easy_setopt(curl, CURLOPT_MAXLIFETIME_CONN, 30L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.80.0
.SH RETURN VALUE
Returns CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_TIMEOUT "(3), " CURLOPT_FORBID_REUSE "(3), "
.BR CURLOPT_FRESH_CONNECT "(3), " CURLOPT_MAXAGE_CONN "(3), "
share/man/man3/curl_strnequal.3 0000644 00000000031 14751150677 0012415 0 ustar 00 .so man3/curl_strequal.3
share/man/man3/CURLOPT_FTP_USE_EPRT.3 0000644 00000004454 14751150677 0012576 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_FTP_USE_EPRT 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_FTP_USE_EPRT \- use EPRT for FTP
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_USE_EPRT, long enabled);
.fi
.SH DESCRIPTION
Pass a long. If the value is 1, it tells curl to use the EPRT command when
doing active FTP downloads (which is enabled by
\fICURLOPT_FTPPORT(3)\fP). Using EPRT means that it will first attempt to use
EPRT before using PORT, but if you pass zero to this option, it will not try
using EPRT, only plain PORT.
If the server is an IPv6 host, this option will have no effect as EPRT is
necessary then.
.SH DEFAULT
.SH PROTOCOLS
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/file.txt");
/* contact us back, aka "active" FTP */
curl_easy_setopt(curl, CURLOPT_FTPPORT, "-");
/* FTP the way the neanderthals did it */
curl_easy_setopt(curl, CURLOPT_FTP_USE_EPRT, 0L);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.10.5
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_FTP_USE_EPSV "(3), " CURLOPT_FTPPORT "(3), "
share/man/man3/CURLOPT_FTP_CREATE_MISSING_DIRS.3 0000644 00000006270 14751150677 0014263 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2014, 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_FTP_CREATE_MISSING_DIRS 3 "October 22, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_FTP_CREATE_MISSING_DIRS \- create missing directories for FTP and SFTP
.SH SYNOPSIS
.nf
#include <curl/curl.h>
typedef enum {
CURLFTP_CREATE_DIR_NONE,
CURLFTP_CREATE_DIR,
CURLFTP_CREATE_DIR_RETRY
} curl_ftpcreatedir;
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_CREATE_MISSING_DIRS,
long create);
.SH DESCRIPTION
Pass a long telling libcurl to \fIcreate\fP the dir. If the value is
\fICURLFTP_CREATE_DIR\fP (1), libcurl will attempt to create any remote
directory that it fails to "move" into.
For FTP requests, that means a CWD command fails. CWD being the command that
changes working directory.
For SFTP requests, libcurl will attempt to create the remote directory if it
cannot obtain a handle to the target-location. The creation will fail if a file
of the same name as the directory to create already exists or lack of
permissions prevents creation.
Setting \fIcreate\fP to \fICURLFTP_CREATE_DIR_RETRY\fP (2), tells libcurl to
retry the CWD command again if the subsequent \fBMKD\fP command fails. This is
especially useful if you are doing many simultaneous connections against the
same server and they all have this option enabled, as then CWD may first fail
but then another connection does \fBMKD\fP before this connection and thus
\fBMKD\fP fails but trying CWD works!
.SH DEFAULT
CURLFTP_CREATE_DIR_NONE (0)
.SH PROTOCOLS
FTP and SFTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/non-existing/new.txt");
curl_easy_setopt(curl, CURLOPT_FTP_CREATE_MISSING_DIRS,
(long)CURLFTP_CREATE_DIR_RETRY);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.10.7. SFTP support added in 7.16.3. The retry option was added in
7.19.4.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if the
create value is not.
.SH "SEE ALSO"
.BR CURLOPT_FTP_FILEMETHOD "(3), " CURLOPT_FTP_USE_EPSV "(3), "
share/man/man3/curl_easy_header.3 0000644 00000015035 14751150677 0012662 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_easy_header 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_easy_header - get an HTTP header
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLHcode curl_easy_header(CURL *easy,
const char *name,
size_t index,
unsigned int origin,
int request,
struct curl_header **hout);
.SH DESCRIPTION
\fIcurl_easy_header(3)\fP returns a pointer to a "curl_header" struct in
\fBhout\fP with data for the HTTP response header \fIname\fP. The case
insensitive null-terminated header name should be specified without colon.
\fIindex\fP 0 means asking for the first instance of the header. If the
returned header struct has \fBamount\fP set larger than 1, it means there are
more instances of the same header name available to get. Asking for a too big
index makes \fBCURLHE_BADINDEX\fP get returned.
The \fIorigin\fP argument is for specifying which headers to receive, as a
single HTTP transfer might provide headers from several different places and
they may then have different importance to the user and headers using the same
name might be used. The \fIorigin\fP is a bitmask for what header sources you
want. See the descriptions below.
The \fIrequest\fP argument tells libcurl from which request you want headers
from. A single transfer might consist of a series of HTTP requests and this
argument lets you specify which particular individual request you want the
headers from. 0 being the first request and then the number increases for
further redirects or when multi-state authentication is used. Passing in -1 is
a shortcut to "the last" request in the series, independently of the actual
amount of requests used.
libcurl stores and provides the actually used "correct" headers. If for
example two headers with the same name arrive and the latter overrides the
former, then only the latter will be provided. If the first header survives
the second, then only the first one will be provided. An application using
this API does not have to bother about multiple headers used wrongly.
The memory for the returned struct is associated with the easy handle and
subsequent calls to \fIcurl_easy_header(3)\fP will clobber the struct used in
the previous calls for the same easy handle. Applications need to copy the
data if it wants to keep it around. The memory used for the struct gets freed
with calling \fIcurl_easy_cleanup(3)\fP of the easy handle.
The first line in an HTTP response is called the status line. It is not
considered a header by this function. Headers are the "name: value" lines
following the status.
This function can be used before (all) headers have been received and is fine
to call from within libcurl callbacks. It will always return the state of the
headers at the time it is called.
.SH "The header struct"
.nf
struct curl_header {
char *name;
char *value;
size_t amount;
size_t index;
unsigned int origin;
void *anchor;
};
.fi
The data \fBname\fP field points to, will be the same as the requested name
but it might have a different case.
The data \fBvalue\fP field points to, comes exactly as delivered over the
network but with leading and trailing whitespace and newlines stripped
off. The `value` data is null-terminated. For legacy HTTP/1 "folded headers",
this API provides the full single value in an unfolded manner with a single
whitespace between the lines.
\fBamount\fP is how many headers using this name that exist, within the origin
and request scope asked for.
\fBindex\fP is the zero based entry number of this particular header, which in
case this header was used more than once in the requested scope can be larger
than 0 but is always less than \fBamount\fP.
The \fBorigin\fP field in the "curl_header" struct has one of the origin bits
set, indicating where from the header originates. At the time of this writing,
there are 5 bits with defined use. The undocumented 27 remaining bits are
reserved for future use and must not be assumed to have any particular value.
\fBanchor\fP is a private handle used by libcurl internals. Do not modify.
.SH ORIGINS
.IP CURLH_HEADER
The header arrived as a header from the server.
.IP CURLH_TRAILER
The header arrived as a trailer. A header that arrives after the body.
.IP CURLH_CONNECT
The header arrived in a CONNECT response. A CONNECT request is being done to
setup a transfer "through" an HTTP(S) proxy.
.IP CURLH_1XX
The header arrived in an HTTP 1xx response. A 1xx response is an "intermediate"
response that might happen before the "real" response.
.IP CURLH_PSEUDO
The header is an HTTP/2 or HTTP/3 pseudo header
.SH EXAMPLE
.nf
struct curl_header *type;
CURLHcode h =
curl_easy_header(easy, "Content-Type", 0, CURLH_HEADER, -1, &type);
.fi
.SH AVAILABILITY
Added in 7.83.0. Officially supported since 7.84.0.
.SH RETURN VALUE
This function returns a CURLHcode indicating success or error.
.IP "CURLHE_BADINDEX (1)"
There is no header with the requested index.
.IP "CURLHE_MISSING (2)"
No such header exists.
.IP "CURLHE_NOHEADERS (3)"
No headers at all have been recorded.
.IP "CURLHE_NOREQUEST (4)"
There was no such request number.
.IP "CURLHE_OUT_OF_MEMORY (5)"
Out of resources
.IP "CURLHE_BAD_ARGUMENT (6)"
One or more of the given arguments are bad.
.IP "CURLHE_NOT_BUILT_IN (7)"
HTTP or the header API has been disabled in the build.
.SH "SEE ALSO"
.BR curl_easy_nextheader "(3), " curl_easy_perform "(3), "
.BR CURLOPT_HEADERFUNCTION "(3), " CURLINFO_CONTENT_TYPE "(3) "
share/man/man3/CURLMOPT_PIPELINING_SITE_BL.3 0000644 00000004340 14751150677 0013545 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLMOPT_PIPELINING_SITE_BL 3 "May 17, 2022" "libcurl 7.86.0" "curl_multi_setopt options"
.SH NAME
CURLMOPT_PIPELINING_SITE_BL \- pipelining host block list
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PIPELINING_SITE_BL,
char **hosts);
.fi
.SH DESCRIPTION
No function since pipelining was removed in 7.62.0.
Pass a \fBhosts\fP array of char *, ending with a NULL entry. This is a list
of sites that are blocked from pipelining, i.e sites that are known to not
support HTTP pipelining. The array is copied by libcurl.
Pass a NULL pointer to clear the block list.
.SH DEFAULT
The default value is NULL, which means that there is no block list.
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
.nf
char *site_block_list[] =
{
"www.haxx.se",
"www.example.com:1234",
NULL
};
curl_multi_setopt(m, CURLMOPT_PIPELINING_SITE_BL, site_block_list);
.fi
.SH AVAILABILITY
Added in 7.30.0
.SH RETURN VALUE
Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLMOPT_PIPELINING "(3), " CURLMOPT_PIPELINING_SERVER_BL "(3), "
share/man/man3/CURLOPT_PROXY_SSLCERTTYPE.3 0000644 00000005272 14751150677 0013420 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXY_SSLCERTTYPE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXY_SSLCERTTYPE \- type of the proxy client SSL certificate
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSLCERTTYPE, char *type);
.fi
.SH DESCRIPTION
Pass a pointer to a null-terminated string as parameter. The string should be
the format of your client certificate used when connecting to an HTTPS proxy.
Supported formats are "PEM" and "DER", except with Secure Transport or
Schannel. OpenSSL (versions 0.9.3 and later), Secure Transport (on iOS 5 or
later, or OS X 10.7 or later) and Schannel support "P12" for PKCS#12-encoded
files.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
"PEM"
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy");
curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERT, "client.pem");
curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERTTYPE, "PEM");
curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEY, "key.pem");
curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "s3cret");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.52.0
If built TLS enabled.
.SH RETURN VALUE
Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_PROXY_SSLCERT "(3), " CURLOPT_PROXY_SSLKEY "(3), "
.BR CURLOPT_SSLCERTTYPE "(3), "
share/man/man3/CURLOPT_SSLCERT.3 0000644 00000006752 14751150677 0011721 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SSLCERT 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSLCERT \- SSL client certificate
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLCERT, char *cert);
.fi
.SH DESCRIPTION
Pass a pointer to a null-terminated string as parameter. The string should be
the file name of your client certificate. The default format is "P12" on
Secure Transport and "PEM" on other engines, and can be changed with
\fICURLOPT_SSLCERTTYPE(3)\fP.
With NSS or Secure Transport, this can also be the nickname of the certificate
you wish to authenticate with as it is named in the security database. If you
want to use a file from the current directory, please precede it with "./"
prefix, in order to avoid confusion with a nickname.
(Schannel only) Client certificates can be specified by a path expression to a
certificate store. (You can import \fIPFX\fP to a store first). You can use
"<store location>\\<store name>\\<thumbprint>" to refer to a certificate in
the system certificates store, for example,
\fB"CurrentUser\\MY\\934a7ac6f8a5d579285a74fa"\fP. The thumbprint is usually a
SHA-1 hex string which you can see in certificate details. Following store
locations are supported: \fBCurrentUser\fP, \fBLocalMachine\fP,
\fBCurrentService\fP, \fBServices\fP, \fBCurrentUserGroupPolicy\fP,
\fBLocalMachineGroupPolicy\fP, \fBLocalMachineEnterprise\fP. Schannel also
support P12 certificate file, with the string "P12" specified with
\fICURLOPT_SSLCERTTYPE(3)\fP.
When using a client certificate, you most likely also need to provide a
private key with \fICURLOPT_SSLKEY(3)\fP.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_SSLCERT, "client.pem");
curl_easy_setopt(curl, CURLOPT_SSLKEY, "key.pem");
curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "s3cret");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
If built TLS enabled.
.SH RETURN VALUE
Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_SSLCERTTYPE "(3), " CURLOPT_SSLKEY "(3), "
share/man/man3/CURLOPT_PROXYUSERNAME.3 0000644 00000004771 14751150677 0012662 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXYUSERNAME 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXYUSERNAME \- user name to use for proxy authentication
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYUSERNAME,
char *username);
.SH DESCRIPTION
Pass a char * as parameter, which should be pointing to the null-terminated
user name to use for the transfer.
\fICURLOPT_PROXYUSERNAME(3)\fP sets the user name to be used in protocol
authentication with the proxy.
To specify the proxy password use the \fICURLOPT_PROXYPASSWORD(3)\fP.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
blank
.SH PROTOCOLS
Most
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
curl_easy_setopt(curl, CURLOPT_PROXY, "http://localhost:8080");
curl_easy_setopt(curl, CURLOPT_PROXYUSERNAME, "mrsmith");
curl_easy_setopt(curl, CURLOPT_PROXYPASSWORD, "qwerty");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.19.1
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_PROXYPASSWORD "(3), " CURLOPT_USERNAME "(3), "
.BR CURLOPT_HTTPAUTH "(3), " CURLOPT_PROXYAUTH "(3)"
share/man/man3/CURLINFO_RESPONSE_CODE.3 0000644 00000004714 14751150677 0012717 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_RESPONSE_CODE 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_RESPONSE_CODE \- get the last response code
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_RESPONSE_CODE, long *codep);
.fi
.SH DESCRIPTION
Pass a pointer to a long to receive the last received HTTP, FTP, SMTP or
LDAP (OpenLDAP only) response code. This option was previously known as
CURLINFO_HTTP_CODE in libcurl 7.10.7 and earlier.
The stored value will be zero if no server response code has been received.
Note that a proxy's CONNECT response should
be read with \fICURLINFO_HTTP_CONNECTCODE(3)\fP and not this.
.SH PROTOCOLS
HTTP, FTP, SMTP and LDAP
.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);
if(res == CURLE_OK) {
long response_code;
curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE, &response_code);
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.10.8. CURLINFO_HTTP_CODE was added in 7.4.1.
Support for SMTP responses added in 7.25.0, for OpenLDAP in 7.81.0.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
.BR CURLINFO_HTTP_CONNECTCODE "(3), "
share/man/man3/curl_easy_option_by_name.3 0000644 00000004210 14751150677 0014425 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_easy_option_by_name 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_easy_option_by_name - find an easy setopt option by name
.SH SYNOPSIS
.nf
#include <curl/curl.h>
const struct curl_easyoption *curl_easy_option_by_name(const char *name);
.fi
.SH DESCRIPTION
Given a \fBname\fP, this function returns a pointer to the
\fIcurl_easyoption\fP struct, holding information about the
\fIcurl_easy_setopt(3)\fP option using 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
A pointer to the \fIcurl_easyoption\fP struct for the option or NULL.
.SH "SEE ALSO"
.BR curl_easy_option_next "(3)," curl_easy_option_by_id "(3),"
.BR curl_easy_setopt "(3),"
share/man/man3/CURLOPT_POSTFIELDSIZE_LARGE.3 0000644 00000004557 14751150677 0013541 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_POSTFIELDSIZE_LARGE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_POSTFIELDSIZE_LARGE \- size of POST data pointed to
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTFIELDSIZE_LARGE,
curl_off_t size);
.SH DESCRIPTION
If you want to post data to the server without having libcurl do a strlen() to
measure the data size, this option must be used. When this option is used you
can post fully binary data, which otherwise is likely to fail. If this size is
set to -1, the library will use strlen() to get the size.
.SH DEFAULT
-1
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
const char *data = large_chunk;
curl_off_t length_of_data; /* set somehow */
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* size of the POST data */
curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE_LARGE, length_of_data);
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Along with HTTP
.SH RETURN VALUE
Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_POSTFIELDS "(3), " CURLOPT_COPYPOSTFIELDS "(3), "
.BR CURLOPT_POSTFIELDSIZE "(3), "
share/man/man3/curl_easy_recv.3 0000644 00000010112 14751150677 0012360 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH curl_easy_recv 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_easy_recv - receives raw data on an "easy" connection
.SH SYNOPSIS
.nf
#include <curl/easy.h>
CURLcode curl_easy_recv(CURL *curl, void *buffer, size_t buflen, size_t *n);
.fi
.SH DESCRIPTION
This function receives raw data from the established connection. You may use
it together with \fIcurl_easy_send(3)\fP to implement custom protocols using
libcurl. This functionality can be particularly useful if you use proxies
and/or SSL encryption: libcurl will take care of proxy negotiation and
connection setup.
\fBbuffer\fP is a pointer to your buffer that will get the received
data. \fBbuflen\fP is the maximum amount of data you can get in that
buffer. The variable \fBn\fP points to will receive the number of received
bytes.
To establish the connection, set \fICURLOPT_CONNECT_ONLY(3)\fP option before
calling \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP. Note that
\fIcurl_easy_recv(3)\fP does not work on connections that were created without
this option.
The call will return \fBCURLE_AGAIN\fP if there is no data to read - the
socket is used in non-blocking mode internally. When \fBCURLE_AGAIN\fP is
returned, use your operating system facilities like \fIselect(2)\fP to wait
for data. The socket may be obtained using \fIcurl_easy_getinfo(3)\fP with
\fICURLINFO_ACTIVESOCKET(3)\fP.
Wait on the socket only if \fIcurl_easy_recv(3)\fP returns \fBCURLE_AGAIN\fP.
The reason for this is libcurl or the SSL library may internally cache some
data, therefore you should call \fIcurl_easy_recv(3)\fP until all data is
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 will 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
On success, returns \fBCURLE_OK\fP, stores the received data into
\fBbuffer\fP, and the number of bytes it actually read into \fB*n\fP.
On failure, returns the appropriate error code.
The function may return \fBCURLE_AGAIN\fP. In this case, use your operating
system facilities to wait until data can be read, and retry.
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 "SEE ALSO"
.BR curl_easy_setopt "(3), " curl_easy_perform "(3), "
.BR curl_easy_getinfo "(3), "
.BR curl_easy_send "(3) "
share/man/man3/curl_ws_meta.3 0000644 00000010331 14751150677 0012042 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH curl_ws_meta 3 "October 03, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_ws_meta - meta data WebSocket information
.SH SYNOPSIS
.nf
#include <curl/easy.h>
struct curl_ws_frame {
int age; /* zero */
int flags; /* See the CURLWS_* defines */
curl_off_t offset; /* the offset of this data into the frame */
curl_off_t bytesleft; /* number of pending bytes left of the payload */
};
struct curl_ws_frame *curl_ws_meta(CURL *curl);
.fi
.SH DESCRIPTION
This function call is EXPERIMENTAL.
When the write callback (\fICURLOPT_WRITEFUNCTION(3)\fP) is invoked on
received WebSocket traffic, \fIcurl_ws_meta(3)\fP can be called from within
the callback to provide additional information about the current frame.
This function only works from within the callback, and only when receiving
WebSocket data.
This function requires an easy handle as input argument for libcurl to know
what transfer the question is about, but as there is no such pointer provided
to the callback by libcurl itself, applications that want to use
\fIcurl_ws_meta(3)\fP need to pass it on to the callback on its own.
.SH "struct fields"
.IP age
This field specify the age of this struct. It is always zero for now.
.IP flags
This is a bitmask with individual bits set that describes the WebSocket
data. See the list below.
.IP offset
When this frame is a continuation of fragment data already delivered, this is
the offset into the final fragment where this piece belongs.
.IP bytesleft
If this is not a complete fragment, the \fIbytesleft\fP field informs about
how many additional bytes are expected to arrive before this fragment is
complete.
.SH FLAGS
.IP CURLWS_TEXT
The buffer contains text data. Note that this makes a difference to WebSocket
but libcurl itself will not make any verification of the content or
precautions that you actually receive valid UTF-8 content.
.IP CURLWS_BINARY
This is binary data.
.IP CURLWS_CONT
This is not the final fragment of the message, it implies that there will be
another fragment coming as part of the same message.
.IP CURLWS_CLOSE
This transfer is now closed.
.IP CURLWS_PING
This as an incoming ping message, that expects a pong response.
.SH EXAMPLE
.nf
/* we pass a pointer to this struct to the callback */
struct customdata {
CURL *easy;
void *ptr;
};
static size_t writecb(unsigned char *buffer,
size_t size, size_t nitems, void *p)
{
struct customdata *c = (struct customdata *)p;
struct curl_ws_frame *m = curl_ws_meta(c->easy);
/* m->flags tells us about the traffic */
}
{
struct customdata custom;
custom.easy = easy;
custom.ptr = NULL;
curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, writecb);
curl_easy_setopt(curl, CURLOPT_WRITEDATA, &custom);
}
.fi
.SH AVAILABILITY
Added in 7.86.0.
.SH RETURN VALUE
This function returns a pointer to a \fIcurl_ws_frame\fP struct with
information that is valid for this specific callback invocation. If it cannot
return this information, or if the function is called in the wrong context, it
returns NULL.
.SH "SEE ALSO"
.BR curl_easy_setopt "(3), "
.BR curl_easy_getinfo "(3), "
.BR curl_ws_send "(3), " curl_ws_recv "(3), "
share/man/man3/CURLOPT_HEADERFUNCTION.3 0000644 00000012274 14751150677 0012674 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_HEADERFUNCTION 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_HEADERFUNCTION \- callback that receives header data
.SH SYNOPSIS
.nf
#include <curl/curl.h>
size_t header_callback(char *buffer,
size_t size,
size_t nitems,
void *userdata);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HEADERFUNCTION,
header_callback);
.fi
.SH DESCRIPTION
Pass a pointer to your callback function, which should match the prototype
shown above.
This function gets called by libcurl as soon as it has received header
data. The header callback will be called once for each header and only
complete header lines are passed on to the callback. Parsing headers is easy
to do using this callback. \fIbuffer\fP points to the delivered data, and the
size of that data is \fInitems\fP; \fIsize\fP is always 1. Do not assume that
the header line is null-terminated!
The pointer named \fIuserdata\fP is the one you set with the
\fICURLOPT_HEADERDATA(3)\fP option.
This callback function must return the number of bytes actually taken care of.
If that amount differs from the amount passed in to your function, it will signal
an error to the library. This will cause the transfer to get aborted and the
libcurl function in progress will return \fICURLE_WRITE_ERROR\fP.
A complete HTTP header that is passed to this function can be up to
\fICURL_MAX_HTTP_HEADER\fP (100K) bytes and includes the final line terminator.
If this option is not set, or if it is set to NULL, but
\fICURLOPT_HEADERDATA(3)\fP is set to anything but NULL, the function used to
accept response data will be used instead. That is, it will be the function
specified with \fICURLOPT_WRITEFUNCTION(3)\fP, or if it is not specified or
NULL - the default, stream-writing function.
It's important to note that the callback will be invoked for the headers of
all responses received after initiating a request and not just the final
response. This includes all responses which occur during authentication
negotiation. If you need to operate on only the headers from the final
response, you will need to collect headers in the callback yourself and use
HTTP status lines, for example, to delimit response boundaries.
For an HTTP transfer, the status line and the blank line preceding the response
body are both included as headers and passed to this function.
When a server sends a chunked encoded transfer, it may contain a trailer. That
trailer is identical to an HTTP header and if such a trailer is received it is
passed to the application using this callback as well. There are several ways
to detect it being a trailer and not an ordinary header: 1) it comes after the
response-body. 2) it comes after the final header line (CR LF) 3) a Trailer:
header among the regular response-headers mention what header(s) to expect in
the trailer.
For non-HTTP protocols like FTP, POP3, IMAP and SMTP this function will get
called with the server responses to the commands that libcurl sends.
.SH LIMITATIONS
libcurl does not unfold HTTP "folded headers" (deprecated since RFC 7230). A
folded header is a header that continues on a subsequent line and starts with
a whitespace. Such folds will be passed to the header callback as a separate
one, although strictly it is just a continuation of the previous line.
.SH DEFAULT
Nothing.
.SH PROTOCOLS
Used for all protocols with headers or meta-data concept: HTTP, FTP, POP3,
IMAP, SMTP and more.
.SH EXAMPLE
.nf
static size_t header_callback(char *buffer, size_t size,
size_t nitems, void *userdata)
{
/* received header is nitems * size long in 'buffer' NOT ZERO TERMINATED */
/* 'userdata' is set with CURLOPT_HEADERDATA */
return nitems * size;
}
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_HEADERFUNCTION, header_callback);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR curl_easy_header "(3), "
.BR CURLOPT_HEADERDATA "(3), " CURLOPT_WRITEFUNCTION "(3), "
share/man/man3/CURLOPT_NOSIGNAL.3 0000644 00000005647 14751150677 0012016 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_NOSIGNAL 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_NOSIGNAL \- skip all signal handling
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NOSIGNAL, long onoff);
.fi
.SH DESCRIPTION
If \fIonoff\fP is 1, libcurl will not use any functions that install signal
handlers or any functions that cause signals to be sent to the process. This
option is here to allow multi-threaded unix applications to still set/use all
timeout options etc, without risking getting signals.
If this option is set and libcurl has been built with the standard name
resolver, timeouts will not occur while the name resolve takes place.
Consider building libcurl with the c-ares or threaded resolver backends to
enable asynchronous DNS lookups, to enable timeouts for name resolves without
the use of signals.
Setting \fICURLOPT_NOSIGNAL(3)\fP to 1 makes libcurl NOT ask the system to
ignore SIGPIPE signals, which otherwise are sent by the system when trying to
send data to a socket which is closed in the other end. libcurl makes an
effort to never cause such SIGPIPE signals to trigger, but some operating
systems have no way to avoid them and even on those that have there are some
corner cases when they may still happen, contrary to our desire. In addition,
using \fICURLAUTH_NTLM_WB\fP authentication could cause a SIGCHLD signal to be
raised.
.SH DEFAULT
0
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_NOSIGNAL, 1L);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.10
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH SEE ALSO
.BR CURLOPT_TIMEOUT "(3), "
share/man/man3/CURLOPT_PROXY_SSLKEY.3 0000644 00000005332 14751150677 0012606 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXY_SSLKEY 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXY_SSLKEY \- private key file for HTTPS proxy client cert
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSLKEY, char *keyfile);
.fi
.SH DESCRIPTION
Pass a pointer to a null-terminated string as parameter. The string should be
the file name of your private key used for connecting to the HTTPS proxy. The
default format is "PEM" and can be changed with
\fICURLOPT_PROXY_SSLKEYTYPE(3)\fP.
(Windows, iOS and Mac OS X) This option is ignored by Secure Transport and
Schannel SSL backends because they expect the private key to be already
present in the key chain or PKCS#12 file containing the certificate.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy");
curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERT, "client.pem");
curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEY, "key.pem");
curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "s3cret");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.52.0
If built TLS enabled.
.SH RETURN VALUE
Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_PROXY_SSLKEYTYPE "(3), " CURLOPT_PROXY_SSLCERT "(3), "
.BR CURLOPT_SSLKEYTYPE "(3), " CURLOPT_SSLCERT "(3), "
share/man/man3/CURLOPT_CONNECTTIMEOUT_MS.3 0000644 00000004665 14751150677 0013342 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_CONNECTTIMEOUT_MS 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_CONNECTTIMEOUT_MS \- timeout for the connect phase
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECTTIMEOUT_MS,
long timeout);
.fi
.SH DESCRIPTION
Pass a long. It should contain the maximum time in milliseconds that you allow
the connection phase to the server to take. This only limits the connection
phase, it has no impact once it has connected. Set to zero to switch to the
default built-in connection timeout - 300 seconds. See also the
\fICURLOPT_TIMEOUT_MS(3)\fP option.
In unix-like systems, this might cause signals to be used unless
\fICURLOPT_NOSIGNAL(3)\fP is set.
If both \fICURLOPT_CONNECTTIMEOUT(3)\fP and \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP
are set, the value set last will be used.
.SH DEFAULT
300000
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* complete connection within 10000 milliseconds */
curl_easy_setopt(curl, CURLOPT_CONNECTTIMEOUT_MS, 10000L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_CONNECTTIMEOUT "(3), "
.BR CURLOPT_TIMEOUT "(3), " CURLOPT_LOW_SPEED_LIMIT "(3), "
share/man/man3/CURLINFO_CONTENT_LENGTH_DOWNLOAD.3 0000644 00000004630 14751150677 0014326 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_CONTENT_LENGTH_DOWNLOAD 3 "October 12, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_CONTENT_LENGTH_DOWNLOAD \- get content-length of download
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONTENT_LENGTH_DOWNLOAD,
double *content_length);
.fi
.SH DESCRIPTION
Pass a pointer to a double to receive the content-length of the download. This
is the value read from the Content-Length: field. Since 7.19.4, this returns
-1 if the size is not known.
\fICURLINFO_CONTENT_LENGTH_DOWNLOAD_T(3)\fP is a newer replacement that returns a more
sensible variable type.
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* Perform the request */
res = curl_easy_perform(curl);
if(!res) {
/* check the size */
double cl;
res = curl_easy_getinfo(curl, CURLINFO_CONTENT_LENGTH_DOWNLOAD, &cl);
if(!res) {
printf("Size: %.0f\\n", cl);
}
}
}
.fi
.SH AVAILABILITY
Added in 7.6.1. Deprecated since 7.55.0.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
.BR CURLINFO_CONTENT_LENGTH_UPLOAD "(3), "
share/man/man3/CURLOPT_TCP_NODELAY.3 0000644 00000005131 14751150677 0012371 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_TCP_NODELAY 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_TCP_NODELAY \- the TCP_NODELAY option
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_NODELAY, long nodelay);
.fi
.SH DESCRIPTION
Pass a long specifying whether the \fITCP_NODELAY\fP option is to be set or
cleared (1L = set, 0 = clear). The option is set by default. This will have no
effect after the connection has been established.
Setting this option to 1L will disable TCP's Nagle algorithm on this
connection. The purpose of this algorithm is to try to minimize the number of
small packets on the network (where "small packets" means TCP segments less
than the Maximum Segment Size for the network).
Maximizing the amount of data sent per TCP segment is good because it
amortizes the overhead of the send. However, in some cases small segments may
need to be sent without delay. This is less efficient than sending larger
amounts of data at a time, and can contribute to congestion on the network if
overdone.
.SH DEFAULT
1
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* leave Nagle enabled */
curl_easy_setopt(curl, CURLOPT_TCP_NODELAY, 0);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Always. The default was changed to 1 from 0 in 7.50.2.
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_SOCKOPTFUNCTION "(3), " CURLOPT_TCP_KEEPALIVE "(3), "
share/man/man3/CURLOPT_PROXY_SSL_OPTIONS.3 0000644 00000010311 14751150677 0013441 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXY_SSL_OPTIONS 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXY_SSL_OPTIONS \- HTTPS proxy SSL behavior options
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSL_OPTIONS,
long bitmask);
.fi
.SH DESCRIPTION
Pass a long with a bitmask to tell libcurl about specific SSL
behaviors. Available bits:
.IP CURLSSLOPT_ALLOW_BEAST
Tells libcurl to not attempt to use any workarounds for a security flaw in the
SSL3 and TLS1.0 protocols. If this option is not used or this bit is set to 0,
the SSL layer libcurl uses may use a work-around for this flaw although it
might cause interoperability problems with some (older) SSL
implementations. WARNING: avoiding this work-around lessens the security, and
by setting this option to 1 you ask for exactly that. This option is only
supported for Secure Transport, NSS and OpenSSL.
.IP CURLSSLOPT_NO_REVOKE
Tells libcurl to disable certificate revocation checks for those SSL backends
where such behavior is present. This option is only supported for Schannel
(the native Windows SSL library), with an exception in the case of Windows'
Untrusted Publishers block list which it seems cannot be bypassed. (Added in
7.44.0)
.IP CURLSSLOPT_NO_PARTIALCHAIN
Tells libcurl to not accept "partial" certificate chains, which it otherwise
does by default. This option is only supported for OpenSSL and will fail the
certificate verification if the chain ends with an intermediate certificate
and not with a root cert. (Added in 7.68.0)
.IP CURLSSLOPT_REVOKE_BEST_EFFORT
Tells libcurl to ignore certificate revocation checks in case of missing or
offline distribution points for those SSL backends where such behavior is
present. This option is only supported for Schannel (the native Windows SSL
library). If combined with \fICURLSSLOPT_NO_REVOKE\fP, the latter takes
precedence. (Added in 7.70.0)
.IP CURLSSLOPT_AUTO_CLIENT_CERT
Tell libcurl to automatically locate and use a client certificate for
authentication, when requested by the server. This option is only supported
for Schannel (the native Windows SSL library). Prior to 7.77.0 this was the
default behavior in libcurl with Schannel. Since the server can request any
certificate that supports client authentication in the OS certificate store it
could be a privacy violation and unexpected.
(Added in 7.77.0)
.SH DEFAULT
0
.SH PROTOCOLS
All TLS-based protocols
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy");
/* weaken TLS only for use with silly proxies */
curl_easy_setopt(curl, CURLOPT_PROXY_SSL_OPTIONS, CURLSSLOPT_ALLOW_BEAST |
CURLSSLOPT_NO_REVOKE);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.52.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_PROXY_SSLVERSION "(3), " CURLOPT_PROXY_SSL_CIPHER_LIST "(3), "
.BR CURLOPT_SSLVERSION "(3), " CURLOPT_SSL_CIPHER_LIST "(3), "
share/man/man3/CURLOPT_HSTSREADDATA.3 0000644 00000004373 14751150677 0012446 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_HSTSREADDATA 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_HSTSREADDATA \- pointer passed to the HSTS read callback
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTSREADDATA, void *pointer);
.fi
.SH DESCRIPTION
Data \fIpointer\fP to pass to the HSTS read function. If you use the
\fICURLOPT_HSTSREADFUNCTION(3)\fP option, this is the pointer you will get as
input in the 3rd argument to the callback.
This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to
do that.
.SH DEFAULT
NULL
.SH PROTOCOLS
This feature is only used for HTTP(S) transfer.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
struct MyData this;
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
/* pass pointer that gets passed in to the
CURLOPT_HSTSREADFUNCTION callback */
curl_easy_setopt(curl, CURLOPT_HSTSREADDATA, &this);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.74.0
.SH RETURN VALUE
This will return CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_HSTSREADFUNCTION "(3), " CURLOPT_HSTSWRITEDATA "(3), "
.BR CURLOPT_HSTSWRITEFUNCTION "(3), "
share/man/man3/CURLOPT_UNIX_SOCKET_PATH.3 0000644 00000006702 14751150677 0013244 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_UNIX_SOCKET_PATH 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_UNIX_SOCKET_PATH \- Unix domain socket
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UNIX_SOCKET_PATH, char *path);
.fi
.SH DESCRIPTION
Enables the use of Unix domain sockets as connection endpoint and sets the path
to \fIpath\fP. If \fIpath\fP is NULL, then Unix domain sockets are disabled. An
empty string will result in an error at some point, it will not disable use of
Unix domain sockets.
When enabled, curl will connect to the Unix domain socket instead of
establishing a TCP connection to a host. Since no TCP connection is created,
curl does not need to resolve the DNS hostname in the URL.
The maximum path length on Cygwin, Linux and Solaris is 107. On other platforms
it might be even less.
Proxy and TCP options such as \fICURLOPT_TCP_NODELAY(3)\fP are not
supported. Proxy options such as \fICURLOPT_PROXY(3)\fP have no effect either
as these are TCP-oriented, and asking a proxy server to connect to a certain
Unix domain socket is not possible.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
Default is NULL, meaning that no Unix domain sockets are used.
.SH PROTOCOLS
All protocols except for FILE and FTP are supported in theory. HTTP, IMAP,
POP3 and SMTP should in particular work (including their SSL/TLS variants).
.SH EXAMPLE
Given that you have an HTTP server running listening on /tmp/httpd.sock, you
can request an HTTP resource with:
.nf
curl_easy_setopt(curl_handle, CURLOPT_UNIX_SOCKET_PATH, "/tmp/httpd.sock");
curl_easy_setopt(curl_handle, CURLOPT_URL, "http://localhost/");
.fi
If you are on Linux and somehow have a need for paths larger than 107 bytes,
you could use the proc filesystem to bypass the limitation:
.nf
int dirfd = open(long_directory_path_to_socket, O_DIRECTORY | O_RDONLY);
char path[108];
snprintf(path, sizeof(path), "/proc/self/fd/%d/httpd.sock", dirfd);
curl_easy_setopt(curl_handle, CURLOPT_UNIX_SOCKET_PATH, path);
/* Be sure to keep dirfd valid until you discard the handle */
.fi
.SH AVAILABILITY
Added in 7.40.0.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_ABSTRACT_UNIX_SOCKET "(3), "
.BR CURLOPT_OPENSOCKETFUNCTION "(3), " unix "(7), "
share/man/man3/curl_share_init.3 0000644 00000004350 14751150677 0012534 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_share_init 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_share_init - Create a shared object
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLSH *curl_share_init();
.fi
.SH DESCRIPTION
This function returns a pointer to a \fICURLSH\fP handle to be used as input
to all the other share-functions, sometimes referred to as a share handle in
some places in the documentation. This init call MUST have a corresponding
call to \fIcurl_share_cleanup(3)\fP when all operations using the share are
complete.
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 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.
.SH "SEE ALSO"
.BR curl_share_cleanup "(3), " curl_share_setopt "(3)"
share/man/man3/CURLOPT_SHARE.3 0000644 00000006251 14751150677 0011436 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SHARE 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SHARE \- share handle to use
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SHARE, CURLSH *share);
.fi
.SH DESCRIPTION
Pass a \fIshare\fP handle as a parameter. The share handle must have been
created by a previous call to \fIcurl_share_init(3)\fP. Setting this option,
will make this curl handle use the data from the shared handle instead of
keeping the data to itself. This enables several curl handles to share
data. If the curl handles are used simultaneously in multiple threads, you
\fBMUST\fP use the locking methods in the share handle. See
\fIcurl_share_setopt(3)\fP for details.
If you add a share that is set to share cookies, your easy handle will use
that cookie cache and get the cookie engine enabled. If you stop sharing an
object that was using cookies (or change to another object that does not share
cookies), the easy handle will get its cookie engine disabled.
Data that the share object is not set to share will be dealt with the usual
way, as if no share was used.
Set this option to NULL again to stop using that share object.
.SH DEFAULT
NULL
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
CURL *curl2 = curl_easy_init(); /* a second handle */
if(curl) {
CURLSH *shobject = curl_share_init();
curl_share_setopt(shobject, CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE);
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_COOKIEFILE, "");
curl_easy_setopt(curl, CURLOPT_SHARE, shobject);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
/* the second handle shares cookies from the first */
curl_easy_setopt(curl2, CURLOPT_URL, "https://example.com/second");
curl_easy_setopt(curl2, CURLOPT_COOKIEFILE, "");
curl_easy_setopt(curl2, CURLOPT_SHARE, shobject);
ret = curl_easy_perform(curl2);
curl_easy_cleanup(curl2);
curl_share_cleanup(shobject);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_COOKIE "(3), "
share/man/man3/CURLOPT_DNS_SERVERS.3 0000644 00000004776 14751150677 0012443 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_DNS_SERVERS 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_DNS_SERVERS \- DNS servers to use
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_SERVERS, char *servers);
.fi
.SH DESCRIPTION
Pass a char * that is the list of DNS servers to be used instead of the system
default. The format of the dns servers option is:
host[:port][,host[:port]]...
For example:
192.168.1.100,192.168.1.101,3.4.5.6
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL - use system default
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
curl_easy_setopt(curl, CURLOPT_DNS_SERVERS, "192.168.1.100:53,192.168.1.101");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
This option requires that libcurl was built with a resolver backend that
supports this operation. The c-ares backend is the only such one.
Added in 7.24.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not,
CURLE_NOT_BUILT_IN if support was disabled at compile-time,
CURLE_BAD_FUNCTION_ARGUMENT when given an invalid server list, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_DNS_LOCAL_IP4 "(3), " CURLOPT_DNS_CACHE_TIMEOUT "(3), "
share/man/man3/CURLOPT_SOCKS5_GSSAPI_SERVICE.3 0000644 00000004655 14751150677 0013777 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SOCKS5_GSSAPI_SERVICE 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SOCKS5_GSSAPI_SERVICE \- SOCKS5 proxy authentication service name
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKS5_GSSAPI_SERVICE,
char *name);
.fi
.SH DESCRIPTION
Deprecated since 7.49.0. Use \fICURLOPT_PROXY_SERVICE_NAME(3)\fP instead.
Pass a \fBchar *\fP as parameter to a string holding the \fIname\fP of the
service. The default service name for a SOCKS5 server is \fI"rcmd"\fP. This
option allows you to change it.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
See above
.SH PROTOCOLS
All network protocols
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_PROXY, "socks5://proxy");
curl_easy_setopt(curl, CURLOPT_SOCKS5_GSSAPI_SERVICE, "rcmd-special");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.19.4, deprecated in 7.49.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_PROXY "(3), " CURLOPT_PROXYTYPE "(3), "
share/man/man3/CURLOPT_SSH_PUBLIC_KEYFILE.3 0000644 00000005060 14751150677 0013434 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SSH_PUBLIC_KEYFILE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSH_PUBLIC_KEYFILE \- public key file for SSH auth
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_PUBLIC_KEYFILE,
char *filename);
.SH DESCRIPTION
Pass a char * pointing to a \fIfilename\fP for your public key. If not used,
libcurl defaults to \fB$HOME/.ssh/id_dsa.pub\fP if the HOME environment
variable is set, and just "id_dsa.pub" in the current directory if HOME is not
set.
If NULL (or an empty string) is passed, libcurl will pass no public key to
libssh2, which then tries to compute it from the private key. This is known
to work with libssh2 1.4.0+ linked against OpenSSL.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
SFTP and SCP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file");
curl_easy_setopt(curl, CURLOPT_SSH_PUBLIC_KEYFILE,
"/home/clarkkent/.ssh/id_rsa.pub");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
The "" trick was added in 7.26.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_SSH_PRIVATE_KEYFILE "(3), " CURLOPT_SSH_AUTH_TYPES "(3), "
share/man/man3/CURLOPT_FNMATCH_DATA.3 0000644 00000004537 14751150677 0012452 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_FNMATCH_DATA 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_FNMATCH_DATA \- pointer passed to the fnmatch callback
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FNMATCH_DATA,
void *pointer);
.SH DESCRIPTION
Pass a pointer that will be untouched by libcurl and passed as the ptr
argument to the \fICURLOPT_FNMATCH_FUNCTION(3)\fP.
.SH DEFAULT
NULL
.SH PROTOCOLS
FTP
.SH EXAMPLE
.nf
static int my_fnmatch(void *clientp,
const char *pattern, const char *string)
{
struct local_stuff *data = (struct local_stuff *)clientp;
if(string_match(pattern, string))
return CURL_FNMATCHFUNC_MATCH;
else
return CURL_FNMATCHFUNC_NOMATCH;
}
{
struct local_stuff local_data;
curl_easy_setopt(curl, CURLOPT_URL, "ftp://ftp.example.com/file*");
curl_easy_setopt(curl, CURLOPT_WILDCARDMATCH, 1L);
curl_easy_setopt(curl, CURLOPT_FNMATCH_FUNCTION, my_fnmatch);
curl_easy_setopt(curl, CURLOPT_FNMATCH_DATA, &local_data);
}
.fi
.SH AVAILABILITY
Added in 7.21.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_FNMATCH_FUNCTION "(3), " CURLOPT_WILDCARDMATCH "(3), "
share/man/man3/CURLOPT_MAXFILESIZE.3 0000644 00000004521 14751150677 0012352 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_MAXFILESIZE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_MAXFILESIZE \- maximum file size allowed to download
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXFILESIZE, long size);
.fi
.SH DESCRIPTION
Pass a long as parameter. This allows you to specify the maximum \fIsize\fP
(in bytes) of a file to download. If the file requested is found larger than
this value, the transfer will not start and \fICURLE_FILESIZE_EXCEEDED\fP will
be returned.
The file size is not always known prior to download, and for such files this
option has no effect even if the file transfer ends up being larger than this
given limit.
If you want a limit above 2GB, use \fICURLOPT_MAXFILESIZE_LARGE(3)\fP.
.SH DEFAULT
None
.SH PROTOCOLS
FTP, HTTP and MQTT
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode ret;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
/* refuse to download if larger than 1000 bytes! */
curl_easy_setopt(curl, CURLOPT_MAXFILESIZE, 1000L);
ret = curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_MAXFILESIZE_LARGE "(3), " CURLOPT_MAX_RECV_SPEED_LARGE "(3), "
share/man/man3/CURLOPT_DIRLISTONLY.3 0000644 00000005620 14751150677 0012407 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_DIRLISTONLY 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_DIRLISTONLY \- ask for names only in a directory listing
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DIRLISTONLY, long listonly);
.fi
.SH DESCRIPTION
For FTP and SFTP based URLs a parameter set to 1 tells the library to list the
names of files in a directory, rather than performing a full directory listing
that would normally include file sizes, dates etc.
For POP3 a parameter of 1 tells the library to list the email message or
messages on the POP3 server. This can be used to change the default behavior
of libcurl, when combined with a URL that contains a message ID, to perform a
"scan listing" which can then be used to determine the size of an email.
Note: For FTP this causes a NLST command to be sent to the FTP server. Beware
that some FTP servers list only files in their response to NLST; they might not
include subdirectories and symbolic links.
Setting this option to 1 also implies a directory listing even if the URL
does not end with a slash, which otherwise is necessary.
Do NOT use this option if you also use \fICURLOPT_WILDCARDMATCH(3)\fP as it
will effectively break that feature then.
.SH DEFAULT
0, disabled
.SH PROTOCOLS
FTP, SFTP and POP3
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/");
/* list only */
curl_easy_setopt(curl, CURLOPT_DIRLISTONLY, 1L);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
This option was known as CURLOPT_FTPLISTONLY up to 7.16.4. POP3 is supported
since 7.21.5.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_CUSTOMREQUEST "(3), "
share/man/man3/CURLOPT_SSLCERT_BLOB.3 0000644 00000005620 14751150677 0012510 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SSLCERT_BLOB 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSLCERT_BLOB \- SSL client certificate from memory blob
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLCERT_BLOB,
struct curl_blob *stblob);
.fi
.SH DESCRIPTION
Pass a pointer to a curl_blob structure, which contains (pointer and size) a
client certificate. The format must be "P12" on Secure Transport or
Schannel. The format must be "P12" or "PEM" on OpenSSL. The format must be
"DER" or "PEM" on mbedTLS. The format must be specified with
\fICURLOPT_SSLCERTTYPE(3)\fP.
If the blob is initialized with the flags member of struct curl_blob set to
CURL_BLOB_COPY, the application does not have to keep the buffer around after
setting this.
This option is an alternative to \fICURLOPT_SSLCERT(3)\fP which instead
expects a file name as input.
.SH DEFAULT
NULL
.SH PROTOCOLS
All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
struct curl_blob stblob;
stblob.data = certificateData;
stblob.len = filesize;
stblob.flags = CURL_BLOB_COPY;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_SSLCERT_BLOB, &stblob);
curl_easy_setopt(curl, CURLOPT_SSLCERTTYPE, "P12");
curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "s3cret");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.71.0. This option is supported by the OpenSSL, Secure Transport,
Schannel and mbedTLS (since 7.78.0) backends.
.SH RETURN VALUE
Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_SSLCERTTYPE "(3), " CURLOPT_SSLKEY "(3), "
share/man/man3/CURLOPT_PREQUOTE.3 0000644 00000004772 14751150677 0012046 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PREQUOTE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PREQUOTE \- commands to run before an FTP transfer
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PREQUOTE,
struct curl_slist *cmds);
.fi
.SH DESCRIPTION
Pass a pointer to a linked list of FTP commands to pass to the server after
the transfer type is set. The linked list should be a fully valid list of
struct curl_slist structs properly filled in as described for
\fICURLOPT_QUOTE(3)\fP. Disable this operation again by setting a NULL to this
option.
These commands are not performed when a directory listing is performed, only
for file transfers.
While \fICURLOPT_QUOTE(3)\fP and \fICURLOPT_POSTQUOTE(3)\fP work for SFTP,
this option does not.
.SH DEFAULT
NULL
.SH PROTOCOLS
FTP
.SH EXAMPLE
.nf
struct curl_slist *cmdlist = NULL;
cmdlist = curl_slist_append(cmdlist, "SYST");
curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/foo.bin");
/* pass in the FTP commands to run */
curl_easy_setopt(curl, CURLOPT_PREQUOTE, cmdlist);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Along with the protocol support
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_QUOTE "(3), " CURLOPT_POSTQUOTE "(3), "
share/man/man3/CURLOPT_VERBOSE.3 0000644 00000004525 14751150677 0011703 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_VERBOSE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_VERBOSE \- verbose mode
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_VERBOSE, long onoff);
.fi
.SH DESCRIPTION
Set the \fIonoff\fP parameter to 1 to make the library display a lot of
verbose information about its operations on this \fIhandle\fP. Useful for
libcurl and/or protocol debugging and understanding. The verbose information
will be sent to stderr, or the stream set with \fICURLOPT_STDERR(3)\fP.
You hardly ever want this set in production use, you will almost always want
this when you debug/report problems.
To also get all the protocol data sent and received, consider using the
\fICURLOPT_DEBUGFUNCTION(3)\fP.
.SH DEFAULT
0, meaning disabled.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* ask libcurl to show us the verbose output */
curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L);
/* Perform the request */
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_STDERR "(3), " CURLOPT_DEBUGFUNCTION "(3), "
.BR CURLOPT_ERRORBUFFER "(3), "
share/man/man3/CURLOPT_MAXFILESIZE_LARGE.3 0000644 00000004652 14751150677 0013271 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_MAXFILESIZE_LARGE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_MAXFILESIZE_LARGE \- maximum file size allowed to download
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXFILESIZE_LARGE,
curl_off_t size);
.SH DESCRIPTION
Pass a curl_off_t as parameter. This allows you to specify the maximum
\fIsize\fP (in bytes) of a file to download. If the file requested is found
larger than this value, the transfer will not start and
\fICURLE_FILESIZE_EXCEEDED\fP will be returned.
The file size is not always known prior to download, and for such files this
option has no effect even if the file transfer ends up being larger than this
given limit.
.SH DEFAULT
None
.SH PROTOCOLS
FTP, HTTP and MQTT
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode ret;
curl_off_t ridiculous = 1 << 48;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
/* refuse to download if larger than ridiculous */
curl_easy_setopt(curl, CURLOPT_MAXFILESIZE_LARGE, ridiculous);
ret = curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.11.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_MAXFILESIZE "(3), " CURLOPT_MAX_RECV_SPEED_LARGE "(3), "
share/man/man3/curl_url_strerror.3 0000644 00000003705 14751150677 0013156 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_url_strerror 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_url_strerror - return string describing error code
.SH SYNOPSIS
.nf
.B #include <curl/curl.h>
.BI "const char *curl_url_strerror(CURLUcode " errornum ");"
.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
Added in 7.80.0
.SH RETURN VALUE
A pointer to a null-terminated string.
.SH "SEE ALSO"
.BR libcurl-errors "(3), " curl_url_get "(3), " curl_url_set "(3), "
.BR curl_easy_strerror "(3), " curl_multi_strerror "(3), "
.BR curl_share_strerror "(3)"
share/man/man3/CURLINFO_EFFECTIVE_URL.3 0000644 00000004565 14751150677 0012715 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_EFFECTIVE_URL 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_EFFECTIVE_URL \- get the last used URL
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_EFFECTIVE_URL, char **urlp);
.fi
.SH DESCRIPTION
Pass in a pointer to a char pointer and get the last used effective URL.
In cases when you have asked libcurl to follow redirects, it may not be the same
value you set with \fICURLOPT_URL(3)\fP.
The \fBurlp\fP pointer will be NULL or pointing to private memory you MUST NOT
free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the
corresponding CURL handle.
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
res = curl_easy_perform(curl);
if(res == CURLE_OK) {
char *url = NULL;
curl_easy_getinfo(curl, CURLINFO_EFFECTIVE_URL, &url);
if(url)
printf("Redirect to: %s\\n", url);
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.4
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
share/man/man3/CURLOPT_KEEP_SENDING_ON_ERROR.3 0000644 00000004737 14751150677 0014043 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_KEEP_SENDING_ON_ERROR 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_KEEP_SENDING_ON_ERROR \- keep sending on early HTTP response >= 300
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_KEEP_SENDING_ON_ERROR,
long keep_sending);
.fi
.SH DESCRIPTION
A long parameter set to 1 tells the library to keep sending the request body
if the HTTP code returned is equal to or larger than 300. The default action
would be to stop sending and close the stream or connection.
This option is suitable for manual NTLM authentication, i.e. if an application
does not use \fICURLOPT_HTTPAUTH(3)\fP, but instead sets "Authorization: NTLM ..."
headers manually using \fICURLOPT_HTTPHEADER(3)\fP.
Most applications do not need this option.
.SH DEFAULT
0, stop sending on error
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode ret;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "sending data");
curl_easy_setopt(curl, CURLOPT_KEEP_SENDING_ON_ERROR, 1L);
ret = curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Along with HTTP. Added in 7.51.0.
.SH RETURN VALUE
Returns CURLE_OK if HTTP is enabled, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_FAILONERROR "(3), " CURLOPT_HTTPHEADER "(3), "
share/man/man3/CURLOPT_CAINFO_BLOB.3 0000644 00000005422 14751150677 0012330 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_CAINFO_BLOB 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_CAINFO_BLOB \- Certificate Authority (CA) bundle in PEM format
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CAINFO_BLOB,
struct curl_blob *stblob);
.fi
.SH DESCRIPTION
Pass a pointer to a curl_blob structure, which contains information (pointer
and size) about a memory block with binary data of PEM encoded content holding
one or more certificates to verify the HTTPS server with.
If \fICURLOPT_SSL_VERIFYPEER(3)\fP is zero and you avoid verifying the
server's certificate, \fICURLOPT_CAINFO_BLOB(3)\fP is not needed.
This option overrides \fICURLOPT_CAINFO(3)\fP.
.SH DEFAULT
NULL
.SH PROTOCOLS
All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
.SH EXAMPLE
.nf
char *strpem; /* strpem must point to a PEM string */
CURL *curl = curl_easy_init();
if(curl) {
struct curl_blob blob;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
blob.data = strpem;
blob.len = strlen(strpem);
blob.flags = CURL_BLOB_COPY;
curl_easy_setopt(curl, CURLOPT_CAINFO_BLOB, &blob);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.77.0.
This option is supported by the BearSSL (since 7.79.0), mbedTLS (since 7.81.0),
rustls (since 7.82.0), OpenSSL, Secure Transport and Schannel backends.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_CAINFO "(3), " CURLOPT_CAPATH "(3), "
.BR CURLOPT_SSL_VERIFYPEER "(3), " CURLOPT_SSL_VERIFYHOST "(3), "
share/man/man3/CURLOPT_PROXYPASSWORD.3 0000644 00000004667 14751150677 0012711 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXYPASSWORD 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXYPASSWORD \- password to use with proxy authentication
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYPASSWORD, char *pwd);
.fi
.SH DESCRIPTION
Pass a char * as parameter, which should be pointing to the null-terminated
password to use for authentication with the proxy.
The \fICURLOPT_PROXYPASSWORD(3)\fP option should be used in conjunction with
the \fICURLOPT_PROXYUSERNAME(3)\fP option.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
blank
.SH PROTOCOLS
Most
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
curl_easy_setopt(curl, CURLOPT_PROXY, "http://localhost:8080");
curl_easy_setopt(curl, CURLOPT_PROXYUSERNAME, "mrsmith");
curl_easy_setopt(curl, CURLOPT_PROXYPASSWORD, "qwerty");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.19.1
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_PASSWORD "(3), " CURLOPT_PROXYUSERNAME "(3), "
.BR CURLOPT_HTTPAUTH "(3), " CURLOPT_PROXYAUTH "(3)"
share/man/man3/CURLOPT_NETRC.3 0000644 00000012322 14751150677 0011443 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_NETRC 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_NETRC \- enable use of .netrc
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NETRC, long level);
.fi
.SH DESCRIPTION
This parameter controls the preference \fIlevel\fP of libcurl between using
user names and passwords from your \fI~/.netrc\fP file, relative to user names
and passwords in the URL supplied with \fICURLOPT_URL(3)\fP.
On Windows, libcurl will use the file as \fI%HOME%/_netrc\fP. If \fI%HOME%\fP
is not set on Windows, libcurl falls back to \fI%USERPROFILE%\fP.
You can also tell libcurl a different file name to use with
\fICURLOPT_NETRC_FILE(3)\fP.
libcurl uses a user name (and supplied or prompted password) supplied with
\fICURLOPT_USERPWD(3)\fP or \fICURLOPT_USERNAME(3)\fP in preference to any of
the options controlled by this parameter.
Only machine name, user name and password are taken into account (init macros
and similar things are not supported).
libcurl does not verify that the file has the correct properties set (as the
standard Unix ftp client does). It should only be readable by user.
\fIlevel\fP is a long that should be set to one of the values described below.
.IP "CURL_NETRC_IGNORED (0)"
The library will ignore the \fI.netrc\fP file. This is the default.
.IP "CURL_NETRC_OPTIONAL (1)"
The use of the \fI.netrc\fP file is optional, and information in the URL is to
be preferred. The file will be scanned for the host and user name (to find
the password only) or for the host only, to find the first user name and
password after that \fImachine\fP, which ever information is not specified.
.IP "CURL_NETRC_REQUIRED (2)"
The use of the \fI.netrc\fP file is required, and any credential information
present in the URL is ignored. The file will be scanned for the host and user
name (to find the password only) or for the host only, to find the first user
name and password after that \fImachine\fP, which ever information is not
specified.
.SH FILE FORMAT
The \fB.netrc\fP file format is simple: you specify lines with a machine name
and follow the login and password that are associated with that machine.
Each field is provided as a sequence of letters that ends with a space or
newline. Starting in 7.84.0, libcurl also supports quoted strings. They start
and end with double quotes and support the escaped special letters \\\", \\n,
\\r, and \\t. Quoted strings are the only way a space character can be used in
a user name or password.
.IP "machine <name>"
Provides credentials for a host called \fBname\fP. libcurl searches the .netrc
file for a machine token that matches the host name specified in the URL. Once
a match is made, the subsequent tokens are processed, stopping when the end of
file is reached or another "machine" is encountered.
.IP default
This is the same as "machine" name except that default matches any name. There
can be only one default token, and it must be after all machine tokens. To
provide a default anonymous login for hosts that are not otherwise matched,
add a line similar to this in the end:
default login anonymous password user@domain
.IP "login <name>"
The user name string for the remote machine.
.IP "password <secret>"
Supply a password. If this token is present, curl will supply the specified
string if the remote server requires a password as part of the login process.
Note that if this token is present in the .netrc file you really should make
sure the file is not readable by anyone besides the user.
.IP "macdef <name>"
Define a macro. This feature is not supported by libcurl. In order for the
rest of the .netrc to still work fine, libcurl will properly skip every
definition done with "macdef" that it finds.
.SH DEFAULT
CURL_NETRC_IGNORED
.SH PROTOCOLS
Most
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode ret;
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/");
curl_easy_setopt(curl, CURLOPT_NETRC, CURL_NETRC_OPTIONAL);
ret = curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_USERPWD "(3), " CURLOPT_USERNAME "(3), " CURLOPT_NETRC_FILE "(3), "
share/man/man3/CURLOPT_SOCKOPTFUNCTION.3 0000644 00000011677 14751150677 0013074 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SOCKOPTFUNCTION 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SOCKOPTFUNCTION \- callback for setting socket options
.SH SYNOPSIS
.nf
#include <curl/curl.h>
typedef enum {
CURLSOCKTYPE_IPCXN, /* socket created for a specific IP connection */
CURLSOCKTYPE_ACCEPT, /* socket created by accept() call */
CURLSOCKTYPE_LAST /* never use */
} curlsocktype;
#define CURL_SOCKOPT_OK 0
#define CURL_SOCKOPT_ERROR 1 /* causes libcurl to abort and return
CURLE_ABORTED_BY_CALLBACK */
#define CURL_SOCKOPT_ALREADY_CONNECTED 2
int sockopt_callback(void *clientp,
curl_socket_t curlfd,
curlsocktype purpose);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKOPTFUNCTION, sockopt_callback);
.SH DESCRIPTION
Pass a pointer to your callback function, which should match the prototype
shown above.
When set, this callback function gets called by libcurl when the socket has
been created, but before the connect call to allow applications to change
specific socket options. The callback's \fIpurpose\fP argument identifies the
exact purpose for this particular socket:
\fICURLSOCKTYPE_IPCXN\fP for actively created connections or since 7.28.0
\fICURLSOCKTYPE_ACCEPT\fP for FTP when the connection was setup with PORT/EPSV
(in earlier versions these sockets were not passed to this callback).
Future versions of libcurl may support more purposes. libcurl passes the newly
created socket descriptor to the callback in the \fIcurlfd\fP parameter so
additional setsockopt() calls can be done at the user's discretion.
The \fIclientp\fP pointer contains whatever user-defined value set using the
\fICURLOPT_SOCKOPTDATA(3)\fP function.
Return \fICURL_SOCKOPT_OK\fP from the callback on success. Return
\fICURL_SOCKOPT_ERROR\fP from the callback function to signal an unrecoverable
error to the library and it will close the socket and return
\fICURLE_COULDNT_CONNECT\fP.
Alternatively, the callback function can return
\fICURL_SOCKOPT_ALREADY_CONNECTED\fP, to tell libcurl that the socket is
already connected and then libcurl will not attempt to connect it. This allows
an application to pass in an already connected socket with
\fICURLOPT_OPENSOCKETFUNCTION(3)\fP and then have this function make libcurl
not attempt to connect (again).
.SH DEFAULT
By default, this callback is NULL and unused.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
/* make libcurl use the already established socket 'sockfd' */
static curl_socket_t opensocket(void *clientp,
curlsocktype purpose,
struct curl_sockaddr *address)
{
curl_socket_t sockfd;
sockfd = *(curl_socket_t *)clientp;
/* the actual externally set socket is passed in via the OPENSOCKETDATA
option */
return sockfd;
}
static int sockopt_callback(void *clientp, curl_socket_t curlfd,
curlsocktype purpose)
{
/* This return code was added in libcurl 7.21.5 */
return CURL_SOCKOPT_ALREADY_CONNECTED;
}
curl = curl_easy_init();
if(curl) {
/* libcurl will internally think that you connect to the host
* and port that you specify in the URL option. */
curl_easy_setopt(curl, CURLOPT_URL, "http://99.99.99.99:9999");
/* call this function to get a socket */
curl_easy_setopt(curl, CURLOPT_OPENSOCKETFUNCTION, opensocket);
curl_easy_setopt(curl, CURLOPT_OPENSOCKETDATA, &sockfd);
/* call this function to set options for the socket */
curl_easy_setopt(curl, CURLOPT_SOCKOPTFUNCTION, sockopt_callback);
res = curl_easy_perform(curl);
curl_easy_cleanup(curl);
.fi
.SH AVAILABILITY
Added in 7.16.0. The \fICURL_SOCKOPT_ALREADY_CONNECTED\fP return code was
added in 7.21.5.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_SOCKOPTDATA "(3), " CURLOPT_OPENSOCKETFUNCTION "(3), "
share/man/man3/CURLOPT_PROXY_SSLKEY_BLOB.3 0000644 00000005576 14751150677 0013416 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXY_SSLKEY_BLOB 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXY_SSLKEY_BLOB \- private key for proxy cert from memory blob
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSLKEY_BLOB,
struct curl_blob *blob);
.fi
.SH DESCRIPTION
Pass a pointer to a curl_blob structure that contains information (pointer and
size) about the private key for connecting to the HTTPS proxy. Compatible with
OpenSSL. The format (like "PEM") must be specified with
\fICURLOPT_PROXY_SSLKEYTYPE(3)\fP.
If the blob is initialized with the flags member of struct curl_blob set to
CURL_BLOB_COPY, the application does not have to keep the buffer around after
setting this.
.SH DEFAULT
NULL
.SH PROTOCOLS
All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
struct curl_blob blob;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy");
blob.data = certificateData;
blob.len = filesize;
blob.flags = CURL_BLOB_COPY;
curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERT_BLOB, &blob);
curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERTTYPE, "PEM");
blob.data = privateKeyData;
blob.len = privateKeySize;
curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEY_BLOB, &blob);
curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "s3cret");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.71.0. This option is supported by the OpenSSL backends.
.SH RETURN VALUE
Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_SSLKEYTYPE "(3), " CURLOPT_SSLKEY "(3), "
share/man/man3/CURLINFO_ACTIVESOCKET.3 0000644 00000005552 14751150677 0012554 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_ACTIVESOCKET 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_ACTIVESOCKET \- get the active socket
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_ACTIVESOCKET,
curl_socket_t *socket);
.fi
.SH DESCRIPTION
Pass a pointer to a curl_socket_t to receive the most recently active socket
used for the transfer connection by this curl session. If the socket is no
longer valid, \fICURL_SOCKET_BAD\fP is returned. When you are finished working
with the socket, you must call \fIcurl_easy_cleanup(3)\fP as usual on the easy
handle and let libcurl close the socket and cleanup other resources associated
with the handle. This option returns the active socket only after the transfer
is complete, and is typically used in combination with
\fICURLOPT_CONNECT_ONLY(3)\fP, which skips the transfer phase.
\fICURLINFO_ACTIVESOCKET(3)\fP was added as a replacement for
\fICURLINFO_LASTSOCKET(3)\fP since that one is not working on all platforms.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_socket_t sockfd;
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);
/* Extract the socket from the curl handle */
res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd);
if(res != CURLE_OK) {
printf("Error: %s\\n", curl_easy_strerror(res));
return 1;
}
}
.fi
.SH AVAILABILITY
Added in 7.45.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
.BR CURLINFO_LASTSOCKET "(3), "
share/man/man3/CURLINFO_HTTP_CONNECTCODE.3 0000644 00000004504 14751150677 0013247 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_HTTP_CONNECTCODE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_HTTP_CONNECTCODE \- get the CONNECT response code
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_HTTP_CONNECTCODE, long *p);
.fi
.SH DESCRIPTION
Pass a pointer to a long to receive the last received HTTP proxy response code
to a CONNECT request. The returned value will be zero if no such response code
was available.
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* typically CONNECT is used to do HTTPS over HTTP proxies */
curl_easy_setopt(curl, CURLOPT_PROXY, "http://127.0.0.1");
res = curl_easy_perform(curl);
if(res == CURLE_OK) {
long code;
res = curl_easy_getinfo(curl, CURLINFO_HTTP_CONNECTCODE, &code);
if(!res && code)
printf("The CONNECT response code: %03ld\\n", code);
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.10.7
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLINFO_RESPONSE_CODE "(3), "
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
share/man/man3/CURLINFO_TLS_SESSION.3 0000644 00000005643 14751150677 0012536 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_TLS_SESSION 3 "October 12, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_TLS_SESSION \- get TLS session info
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TLS_SESSION,
struct curl_tlssessioninfo **session);
.SH DESCRIPTION
\fBThis option has been superseded\fP by \fICURLINFO_TLS_SSL_PTR(3)\fP which
was added in 7.48.0. The only reason you would use this option instead is if
you could be using a version of libcurl earlier than 7.48.0.
This option is exactly the same as \fICURLINFO_TLS_SSL_PTR(3)\fP except in the
case of OpenSSL. If the session \fIbackend\fP is CURLSSLBACKEND_OPENSSL the
session \fIinternals\fP pointer varies depending on the option:
\fICURLINFO_TLS_SESSION(3)\fP OpenSSL session \fIinternals\fP is \fBSSL_CTX *\fP.
\fICURLINFO_TLS_SSL_PTR(3)\fP OpenSSL session \fIinternals\fP is \fBSSL *\fP.
You can obtain an \fBSSL_CTX\fP pointer from an SSL pointer using OpenSSL
function \fISSL_get_SSL_CTX(3)\fP. Therefore unless you need compatibility
with older versions of libcurl use \fICURLINFO_TLS_SSL_PTR(3)\fP. Refer to
that document for more information.
.SH PROTOCOLS
All TLS-based
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res;
struct curl_tlssessioninfo *tls;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
res = curl_easy_perform(curl);
curl_easy_getinfo(curl, CURLINFO_TLS_SESSION, &tls);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.34.0. Deprecated since 7.48.0 and supported OpenSSL, GnuTLS,
NSS and gskit only up until this version was released.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
.BR CURLINFO_TLS_SSL_PTR "(3), "
share/man/man3/CURLOPT_HEADERDATA.3 0000644 00000005114 14751150677 0012153 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_HEADERDATA 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_HEADERDATA \- pointer to pass to header callback
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HEADERDATA, void *pointer);
.fi
.SH DESCRIPTION
Pass a \fIpointer\fP to be used to write the header part of the received data
to.
If \fICURLOPT_WRITEFUNCTION(3)\fP or \fICURLOPT_HEADERFUNCTION(3)\fP is used,
\fIpointer\fP will be passed in to the respective callback.
If neither of those options are set, \fIpointer\fP must be a valid FILE * and
it will be used by a plain fwrite() to write headers to.
.SH DEFAULT
NULL
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
struct my_info {
int shoesize;
char *secret;
};
static size_t header_callback(char *buffer, size_t size,
size_t nitems, void *userdata)
{
struct my_info *i = (struct my_info *)userdata;
/* now this callback can access the my_info struct */
return nitems * size;
}
CURL *curl = curl_easy_init();
if(curl) {
struct my_info my = { 10, "the cookies are in the cupboard" };
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_HEADERFUNCTION, header_callback);
/* pass in custom data to the callback */
curl_easy_setopt(curl, CURLOPT_HEADERDATA, &my);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_HEADERFUNCTION "(3), " CURLOPT_WRITEFUNCTION "(3), "
share/man/man3/CURLOPT_SSL_FALSESTART.3 0000644 00000004502 14751150677 0012762 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SSL_FALSESTART 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSL_FALSESTART \- TLS false start
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_FALSESTART, long enable);
.fi
.SH DESCRIPTION
Pass a long as parameter set to 1L to enable or 0 to disable.
This option determines whether libcurl should use false start during the TLS
handshake. False start is a mode where a TLS client will start sending
application data before verifying the server's Finished message, thus saving a
round trip when performing a full handshake.
.SH DEFAULT
0
.SH PROTOCOLS
All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_SSL_FALSESTART, 1L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.42.0. This option is currently only supported by the NSS and
Secure Transport (on iOS 7.0 or later, or OS X 10.9 or later) TLS backends.
.SH RETURN VALUE
Returns CURLE_OK if false start is supported by the SSL backend, otherwise
returns CURLE_NOT_BUILT_IN.
.SH SEE ALSO
.BR CURLOPT_TCP_FASTOPEN "(3), "
share/man/man3/CURLOPT_SASL_AUTHZID.3 0000644 00000005343 14751150677 0012527 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SASL_AUTHZID 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SASL_AUTHZID \- authorization identity (identity to act as)
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SASL_AUTHZID, char *authzid);
.fi
.SH DESCRIPTION
Pass a char * as parameter, which should be pointing to the null-terminated
authorization identity (\fIauthzid\fP) for the transfer. Only applicable to
the PLAIN SASL authentication mechanism where it is optional.
When not specified only the authentication identity (\fIauthcid\fP) as
specified by the username will be sent to the server, along with the
password. The server will derive a \fIauthzid\fP from the \fIauthcid\fP when
not provided, which it will then uses internally.
When the \fIauthzid\fP is specified, the use of which is server dependent, it
can be used to access another user's inbox, that the user has been granted
access to, or a shared mailbox for example.
.SH DEFAULT
blank
.SH PROTOCOLS
IMAP, LDAP, POP3 and SMTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "imap://example.com/");
curl_easy_setopt(curl, CURLOPT_USERNAME, "Kurt");
curl_easy_setopt(curl, CURLOPT_PASSWORD, "xipj3plmq");
curl_easy_setopt(curl, CURLOPT_SASL_AUTHZID, "Ursel");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.66.0. Support for OpenLDAP added in 7.82.0.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_USERNAME "(3), " CURLOPT_PASSWORD "(3), ".BR CURLOPT_USERPWD "(3)"
share/man/man3/CURLOPT_KRBLEVEL.3 0000644 00000004561 14751150677 0012004 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_KRBLEVEL 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_KRBLEVEL \- FTP kerberos security level
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_KRBLEVEL, char *level);
.fi
.SH DESCRIPTION
Pass a char * as parameter. Set the kerberos security level for FTP; this also
enables kerberos awareness. This is a string that should match one of the
following: \&'clear', \&'safe', \&'confidential' or \&'private'. If the
string is set but does not match one of these, 'private' will be used. Set the
string to NULL to disable kerberos support for FTP.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
FTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/foo.bin");
curl_easy_setopt(curl, CURLOPT_KRBLEVEL, "private");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
This option was known as CURLOPT_KRB4LEVEL up to 7.16.3
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_KRBLEVEL "(3), " CURLOPT_USE_SSL "(3), "
share/man/man3/CURLINFO_PRIVATE.3 0000644 00000004426 14751150677 0012001 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_PRIVATE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_PRIVATE \- get the private pointer
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PRIVATE, char **private);
.fi
.SH DESCRIPTION
Pass a pointer to a char pointer to receive the pointer to the private data
associated with the curl handle (set with the \fICURLOPT_PRIVATE(3)\fP).
Please note that for internal reasons, the value is returned as a char
pointer, although effectively being a 'void *'.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
void *pointer = 0x2345454;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
/* set the private pointer */
curl_easy_setopt(curl, CURLOPT_PRIVATE, pointer);
ret = curl_easy_perform(curl);
/* extract the private pointer again */
ret = curl_easy_getinfo(curl, CURLINFO_PRIVATE, &pointer);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.10.3
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
.BR CURLOPT_PRIVATE "(3), "
share/man/man3/curl_easy_pause.3 0000644 00000012726 14751150677 0012553 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_easy_pause 3 "September 05, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_easy_pause - pause and unpause a connection
.SH SYNOPSIS
.nf
.B #include <curl/curl.h>
.BI "CURLcode curl_easy_pause(CURL *"handle ", int "bitmask ");"
.fi
.SH DESCRIPTION
Using this function, you can explicitly mark a running connection to get
paused, and you can unpause a connection that was previously paused.
A connection can be paused by using this function or by letting the read or
the write callbacks return the proper magic return code
(\fICURL_READFUNC_PAUSE\fP and \fICURL_WRITEFUNC_PAUSE\fP). A write callback
that returns pause signals to the library that it could not take care of any
data at all, and that data will then be delivered again to the callback when
the transfer is unpaused.
While it may feel tempting, take care and notice that you cannot call this
function from another thread. To unpause, you may for example call it from the
progress callback (\fICURLOPT_PROGRESSFUNCTION(3)\fP).
When this function is called to unpause receiving, the write callback might
get called before this function returns to deliver cached content. When
libcurl delivers such cached data to the write callback, it will be delivered
as fast as possible, which may overstep the boundary set in
\fICURLOPT_MAX_RECV_SPEED_LARGE(3)\fP etc.
The \fBhandle\fP argument identifies the transfer you want to pause or
unpause.
A paused transfer is excluded from low speed cancels via the
\fICURLOPT_LOW_SPEED_LIMIT(3)\fP option and unpausing a transfer will reset
the time period required for the low speed limit to be met.
The \fBbitmask\fP argument is a set of bits that sets the new state of the
connection. The following bits can be used:
.IP CURLPAUSE_RECV
Pause receiving data. There will be no data received on this connection until
this function is called again without this bit set. Thus, the write callback
(\fICURLOPT_WRITEFUNCTION(3)\fP) will not be called.
.IP CURLPAUSE_SEND
Pause sending data. There will be no data sent on this connection until this
function is called again without this bit set. Thus, the read callback
(\fICURLOPT_READFUNCTION(3)\fP) will not be called.
.IP CURLPAUSE_ALL
Convenience define that pauses both directions.
.IP CURLPAUSE_CONT
Convenience define that unpauses both directions.
.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
direction, will cause problems in the worst case or an error in the best case.
.SH MULTIPLEXED
When a connection is used multiplexed, like for HTTP/2, and one of the
transfers over the connection is paused and the others continue flowing,
libcurl might end up buffering contents for the paused transfer. It has to do
this because it needs to drain the socket for the other transfers and the
already announced window size for the paused transfer will allow the server to
continue sending data up to that window size amount. By default, libcurl
announces a 32 megabyte window size, which thus can make libcurl end up
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 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 will have to keep
it in an allocated buffer until the receiving is again unpaused using this
function.
If the downloaded data is compressed and is asked to get uncompressed
automatically on download, libcurl will continue to uncompress the entire
downloaded chunk and it will cache the data uncompressed. This has the side-
effect that if you download something that is compressed a lot, it can result
in a 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 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)"
share/man/man3/CURLOPT_RTSP_STREAM_URI.3 0000644 00000005450 14751150677 0013156 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_RTSP_STREAM_URI 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_RTSP_STREAM_URI \- RTSP stream URI
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_STREAM_URI, char *URI);
.fi
.SH DESCRIPTION
Set the stream \fIURI\fP to operate on by passing a char * . For example, a
single session may be controlling \fIrtsp://foo/twister/audio\fP and
\fIrtsp://foo/twister/video\fP and the application can switch to the
appropriate stream using this option. If unset, libcurl will default to
operating on generic server options by passing '*' in the place of the RTSP
Stream URI. This option is distinct from \fICURLOPT_URL(3)\fP. When working
with RTSP, the \fICURLOPT_RTSP_STREAM_URI(3)\fP indicates what URL to send to
the server in the request header while the \fICURLOPT_URL(3)\fP indicates
where to make the connection to. (e.g. the \fICURLOPT_URL(3)\fP for the above
examples might be set to \fIrtsp://foo/twister\fP
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
\&'*'
.SH PROTOCOLS
RTSP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
char *prev_id; /* saved from before somehow */
curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/");
curl_easy_setopt(curl, CURLOPT_RTSP_STREAM_URI,
"rtsp://foo.example.com/twister/video");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.20.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_RTSP_REQUEST "(3), " CURLOPT_RTSP_TRANSPORT "(3), "
share/man/man3/CURLOPT_PROTOCOLS.3 0000644 00000006025 14751150677 0012157 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROTOCOLS 3 "October 12, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROTOCOLS \- allowed protocols
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROTOCOLS, long bitmask);
.fi
.SH DESCRIPTION
This option is deprecated. We strongly recommend using
\fICURLOPT_PROTOCOLS_STR(3)\fP instead because this option cannot control all
available protocols!
Pass a long that holds a bitmask of CURLPROTO_* defines. If used, this bitmask
limits what protocols libcurl may use in the transfer. This allows you to have
a libcurl built to support a wide range of protocols but still limit specific
transfers to only be allowed to use a subset of them. By default libcurl will
accept all protocols it supports (\fICURLPROTO_ALL\fP). See also
\fICURLOPT_REDIR_PROTOCOLS(3)\fP.
These are the available protocol defines:
.nf
CURLPROTO_DICT
CURLPROTO_FILE
CURLPROTO_FTP
CURLPROTO_FTPS
CURLPROTO_GOPHER
CURLPROTO_HTTP
CURLPROTO_HTTPS
CURLPROTO_IMAP
CURLPROTO_IMAPS
CURLPROTO_LDAP
CURLPROTO_LDAPS
CURLPROTO_POP3
CURLPROTO_POP3S
CURLPROTO_RTMP
CURLPROTO_RTMPE
CURLPROTO_RTMPS
CURLPROTO_RTMPT
CURLPROTO_RTMPTE
CURLPROTO_RTMPTS
CURLPROTO_RTSP
CURLPROTO_SCP
CURLPROTO_SFTP
CURLPROTO_SMB
CURLPROTO_SMBS
CURLPROTO_SMTP
CURLPROTO_SMTPS
CURLPROTO_TELNET
CURLPROTO_TFTP
.fi
.SH DEFAULT
All protocols built-in.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
/* pass in the URL from an external source */
curl_easy_setopt(curl, CURLOPT_URL, argv[1]);
/* only allow HTTP, TFTP and SFTP */
curl_easy_setopt(curl, CURLOPT_PROTOCOLS,
CURLPROTO_HTTP | CURLPROTO_TFTP | CURLPROTO_SFTP);
/* Perform the request */
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.19.4. Deprecated since 7.85.0.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_REDIR_PROTOCOLS "(3), " CURLOPT_URL "(3), "
share/man/man3/CURLINFO_NUM_CONNECTS.3 0000644 00000004710 14751150677 0012616 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_NUM_CONNECTS 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_NUM_CONNECTS \- get number of created connections
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_NUM_CONNECTS, long *nump);
.fi
.SH DESCRIPTION
Pass a pointer to a long to receive how many new connections libcurl had to
create to achieve the previous transfer (only the successful connects are
counted). Combined with \fICURLINFO_REDIRECT_COUNT(3)\fP you are able to know
how many times libcurl successfully reused existing connection(s) or not. See
the connection options of \fIcurl_easy_setopt(3)\fP to see how libcurl tries
to make persistent connections to save time.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
res = curl_easy_perform(curl);
if(res == CURLE_OK) {
long connects;
res = curl_easy_getinfo(curl, CURLINFO_NUM_CONNECTS, &connects);
if(res)
printf("It needed %d connects\\n", connects);
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.12.3
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
share/man/man3/CURLMOPT_TIMERFUNCTION.3 0000644 00000007516 14751150677 0012744 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLMOPT_TIMERFUNCTION 3 "May 17, 2022" "libcurl 7.86.0" "curl_multi_setopt options"
.SH NAME
CURLMOPT_TIMERFUNCTION \- callback to receive timeout values
.SH SYNOPSIS
.nf
#include <curl/curl.h>
int timer_callback(CURLM *multi, /* multi handle */
long timeout_ms, /* timeout in number of ms */
void *userp); /* private callback pointer */
CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_TIMERFUNCTION, timer_callback);
.SH DESCRIPTION
Pass a pointer to your callback function, which should match the prototype
shown above.
Certain features, such as timeouts and retries, require you to call libcurl
even when there is no activity on the file descriptors.
Your callback function \fBtimer_callback\fP should install a non-repeating
timer with an expire time of \fBtimeout_ms\fP milliseconds. When that timer
fires, call either \fIcurl_multi_socket_action(3)\fP or
\fIcurl_multi_perform(3)\fP, depending on which interface you use.
A \fBtimeout_ms\fP value of -1 passed to this callback means you should delete
the timer. All other values are valid expire times in number of milliseconds.
The \fBtimer_callback\fP will only be called when the timeout expire time is
changed.
The \fBuserp\fP pointer is set with \fICURLMOPT_TIMERDATA(3)\fP.
The timer callback should return 0 on success, and -1 on error. If this
callback returns error, \fBall\fP transfers currently in progress in this
multi handle will be aborted and fail.
This callback can be used instead of, or in addition to,
\fIcurl_multi_timeout(3)\fP.
\fBWARNING:\fP do not call libcurl directly from within the callback itself
when the \fBtimeout_ms\fP value is zero, since it risks triggering an
unpleasant recursive behavior that immediately calls another call to the
callback with a zero timeout...
.SH DEFAULT
NULL
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
static gboolean timeout_cb(gpointer user_data)
{
int running;
if(user_data) {
g_free(user_data);
curl_multi_setopt(curl_handle, CURLMOPT_TIMERDATA, NULL);
}
curl_multi_socket_action(multi, CURL_SOCKET_TIMEOUT, 0, &running);
return G_SOURCE_REMOVE;
}
static int timerfunc(CURLM *multi, long timeout_ms, void *userp)
{
guint *id = userp;
if(id)
g_source_remove(*id);
/* -1 means we should just delete our timer. */
if(timeout_ms == -1) {
g_free(id);
id = NULL;
}
else {
if(!id)
id = g_new(guint, 1);
*id = g_timeout_add(timeout_ms, timeout_cb, id);
}
current_timer = id;
return 0;
}
curl_multi_setopt(multi, CURLMOPT_TIMERFUNCTION, timerfunc);
.fi
.SH AVAILABILITY
Added in 7.16.0
.SH RETURN VALUE
Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLMOPT_TIMERDATA "(3), " CURLMOPT_SOCKETFUNCTION "(3), "
share/man/man3/CURLOPT_WILDCARDMATCH.3 0000644 00000007445 14751150677 0012550 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_WILDCARDMATCH 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_WILDCARDMATCH \- directory wildcard transfers
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WILDCARDMATCH, long onoff);
.fi
.SH DESCRIPTION
Set \fIonoff\fP to 1 if you want to transfer multiple files according to a
file name pattern. The pattern can be specified as part of the
\fICURLOPT_URL(3)\fP option, using an \fBfnmatch\fP-like pattern (Shell
Pattern Matching) in the last part of URL (file name).
By default, libcurl uses its internal wildcard matching implementation. You
can provide your own matching function by the
\fICURLOPT_FNMATCH_FUNCTION(3)\fP option.
A brief introduction of its syntax follows:
.RS
.IP "* - ASTERISK"
.nf
ftp://example.com/some/path/*.txt
.fi
for all txt's from the root directory. Only two asterisks are allowed within
the same pattern string.
.RE
.RS
.IP "? - QUESTION MARK"
Question mark matches any (exactly one) character.
.nf
ftp://example.com/some/path/photo?.jpg
.fi
.RE
.RS
.IP "[ - BRACKET EXPRESSION"
The left bracket opens a bracket expression. The question mark and asterisk have
no special meaning in a bracket expression. Each bracket expression ends by the
right bracket and matches exactly one character. Some examples follow:
\fB[a-zA-Z0\-9]\fP or \fB[f\-gF\-G]\fP \- character interval
\fB[abc]\fP - character enumeration
\fB[^abc]\fP or \fB[!abc]\fP - negation
\fB[[:name:]]\fP class expression. Supported classes are
\fBalnum\fP,\fBlower\fP, \fBspace\fP, \fBalpha\fP, \fBdigit\fP, \fBprint\fP,
\fBupper\fP, \fBblank\fP, \fBgraph\fP, \fBxdigit\fP.
\fB[][-!^]\fP - special case \- matches only '\-', ']', '[', '!' or '^'. These
characters have no special purpose.
\fB[\\[\\]\\\\]\fP - escape syntax. Matches '[', ']' or '\e'.
Using the rules above, a file name pattern can be constructed:
.nf
ftp://example.com/some/path/[a-z[:upper:]\\\\].jpg
.fi
.SH PROTOCOLS
This feature is only supported for FTP download.
.SH EXAMPLE
.nf
/* initialization of easy handle */
handle = curl_easy_init();
/* turn on wildcard matching */
curl_easy_setopt(handle, CURLOPT_WILDCARDMATCH, 1L);
/* callback is called before download of concrete file started */
curl_easy_setopt(handle, CURLOPT_CHUNK_BGN_FUNCTION, file_is_coming);
/* callback is called after data from the file have been transferred */
curl_easy_setopt(handle, CURLOPT_CHUNK_END_FUNCTION, file_is_downloaded);
/* See more on https://curl.se/libcurl/c/ftp-wildcard.html */
.fi
.SH AVAILABILITY
Added in 7.21.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_FNMATCH_FUNCTION "(3), " CURLOPT_URL "(3), "
share/man/man3/CURLOPT_PROXY_SSLKEYTYPE.3 0000644 00000004767 14751150677 0013323 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXY_SSLKEYTYPE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXY_SSLKEYTYPE \- type of the proxy private key file
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSLKEYTYPE, char *type);
.fi
.SH DESCRIPTION
This option is for connecting to an HTTPS proxy, not an HTTPS server.
Pass a pointer to a null-terminated string as parameter. The string should be
the format of your private key. Supported formats are "PEM", "DER" and "ENG".
The application does not have to keep the string around after setting this
option.
.SH PROTOCOLS
Used with HTTPS proxy
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy");
curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERT, "client.pem");
curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEY, "key.pem");
curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEYTYPE, "PEM");
curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "s3cret");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.52.0
.SH RETURN VALUE
Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_PROXY_SSLKEY "(3), " CURLOPT_PROXY_SSLCERT "(3), "
.BR CURLOPT_SSLKEYTYPE "(3), "
share/man/man3/CURLOPT_POSTFIELDS.3 0000644 00000007671 14751150677 0012257 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_POSTFIELDS 3 "October 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_POSTFIELDS \- data to POST to server
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTFIELDS, char *postdata);
.fi
.SH DESCRIPTION
Pass a char * as parameter, pointing to the full data to send in an HTTP POST
operation. You must make sure that the data is formatted the way you want the
server to receive it. libcurl will not convert or encode it for you in any
way. For example, the web server may assume that this data is URL encoded.
The data pointed to is NOT copied by the library: as a consequence, it must be
preserved by the calling application until the associated transfer finishes.
This behavior can be changed (so libcurl does copy the data) by setting the
\fICURLOPT_COPYPOSTFIELDS(3)\fP option.
This POST is a normal \fBapplication/x-www-form-urlencoded\fP kind (and
libcurl will set that Content-Type by default when this option is used), which
is commonly used by HTML forms. Change Content-Type with
\fICURLOPT_HTTPHEADER(3)\fP.
You can use \fIcurl_easy_escape(3)\fP to URL encode your data, if
necessary. It returns a pointer to an encoded string that can be passed as
\fIpostdata\fP.
Using \fICURLOPT_POSTFIELDS(3)\fP implies setting \fICURLOPT_POST(3)\fP to 1.
If \fICURLOPT_POSTFIELDS(3)\fP is explicitly set to NULL then libcurl will get
the POST data from the read callback. If you want to send a zero-byte POST set
\fICURLOPT_POSTFIELDS(3)\fP to an empty string, or set \fICURLOPT_POST(3)\fP to
1 and \fICURLOPT_POSTFIELDSIZE(3)\fP to 0.
libcurl will use assume this option points to a null-terminated string unless
you also set \fICURLOPT_POSTFIELDSIZE(3)\fP to specify the length of the
provided data, which then is strictly required if you want to send off null
bytes included in the data.
Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header,
and libcurl will add that header automatically if the POST is either known to
be larger than 1MB or if the expected size is unknown. You can disable this
header with \fICURLOPT_HTTPHEADER(3)\fP as usual.
To make \fBmultipart/formdata\fP posts, check out the
\fICURLOPT_MIMEPOST(3)\fP option combined with \fIcurl_mime_init(3)\fP.
.SH DEFAULT
NULL
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
const char *data = "data to send";
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* size of the POST data */
curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, 12L);
/* pass in a pointer to the data - libcurl will not copy */
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_POSTFIELDSIZE "(3), " CURLOPT_READFUNCTION "(3), "
.BR CURLOPT_MIMEPOST "(3), " CURLOPT_UPLOAD "(3), "
share/man/man3/CURLOPT_FTP_USE_EPSV.3 0000644 00000004401 14751150677 0012571 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_FTP_USE_EPSV 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_FTP_USE_EPSV \- use EPSV for FTP
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_USE_EPSV, long epsv);
.fi
.SH DESCRIPTION
Pass \fIepsv\fP as a long. If the value is 1, it tells curl to use the EPSV
command when doing passive FTP downloads (which it does by default). Using
EPSV means that it will first attempt to use EPSV before using PASV, but if
you pass zero to this option, it will not try using EPSV, only plain PASV.
If the server is an IPv6 host, this option will have no effect as of 7.12.3.
.SH DEFAULT
1
.SH PROTOCOLS
FTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/old-server/file.txt");
/* let's shut off this modern feature */
curl_easy_setopt(curl, CURLOPT_FTP_USE_EPSV, 0L);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Along with FTP
.SH RETURN VALUE
Returns CURLE_OK if FTP is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_FTP_USE_EPRT "(3), " CURLOPT_FTPPORT "(3), "
share/man/man3/curl_multi_socket_all.3 0000644 00000000035 14751150677 0013735 0 ustar 00 .so man3/curl_multi_socket.3
share/man/man3/curl_version.3 0000644 00000003410 14751150677 0012070 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_version 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_version - returns the libcurl version string
.SH SYNOPSIS
.nf
#include <curl/curl.h>
char *curl_version();
.fi
.SH DESCRIPTION
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.
.SH "SEE ALSO"
.BR curl_version_info "(3)"
share/man/man3/curl_formget.3 0000644 00000005435 14751150677 0012057 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_formget 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_formget - serialize a previously built multipart form POST chain
.SH SYNOPSIS
.nf
.B #include <curl/curl.h>
int curl_formget(struct curl_httppost * form, void *userp,
curl_formget_callback append );
.SH DESCRIPTION
curl_formget() is used to serialize data previously built/appended with
\fIcurl_formadd(3)\fP. Accepts a void pointer as second argument named
\fIuserp\fP which will be passed as the first argument to the
curl_formget_callback function.
.BI "typedef size_t (*curl_formget_callback)(void *" userp, " const char *" buf,
.BI " size_t " len ");"
The curl_formget_callback will be executed for each part of the HTTP POST
chain. The character buffer passed to the callback must not be freed. The
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 have performed the actual HTTP
request as only then will libcurl get the actual read callback to use!
.SH EXAMPLE
.nf
size_t print_httppost_callback(void *arg, const char *buf, size_t len)
{
fwrite(buf, len, 1, stdout);
(*(size_t *) arg) += len;
return len;
}
size_t print_httppost(struct curl_httppost *post)
{
size_t total_size = 0;
if(curl_formget(post, &total_size, print_httppost_callback)) {
return (size_t) -1;
}
return total_size;
}
.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)"
share/man/man3/CURLOPT_INTERLEAVEDATA.3 0000644 00000004341 14751150677 0012662 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_INTERLEAVEDATA 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_INTERLEAVEDATA \- pointer passed to RTSP interleave callback
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_INTERLEAVEDATA, void *pointer);
.fi
.SH DESCRIPTION
This is the userdata \fIpointer\fP that will be passed to
\fICURLOPT_INTERLEAVEFUNCTION(3)\fP when interleaved RTP data is received. If
the interleave function callback is not set, this pointer is not used
anywhere.
.SH DEFAULT
NULL
.SH PROTOCOLS
RTSP
.SH EXAMPLE
.nf
static size_t rtp_write(void *ptr, size_t size, size_t nmemb, void *user)
{
struct local *l = (struct local *)user;
/* take care of the packet in 'ptr', then return... */
return size * nmemb;
}
{
struct local rtp_data;
curl_easy_setopt(curl, CURLOPT_INTERLEAVEFUNCTION, rtp_write);
curl_easy_setopt(curl, CURLOPT_INTERLEAVEDATA, &rtp_data);
}
.fi
.SH AVAILABILITY
Added in 7.20.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_INTERLEAVEFUNCTION "(3), " CURLOPT_RTSP_REQUEST "(3), "
share/man/man3/CURLOPT_CAINFO.3 0000644 00000007432 14751150677 0011535 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_CAINFO 3 "September 22, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_CAINFO \- path to Certificate Authority (CA) bundle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CAINFO, char *path);
.fi
.SH DESCRIPTION
Pass a char * to a null-terminated string naming a file holding one or more
certificates to verify the peer with.
If \fICURLOPT_SSL_VERIFYPEER(3)\fP is zero and you avoid verifying the
server's certificate, \fICURLOPT_CAINFO(3)\fP need not even indicate an
accessible file.
This option is by default set to the system path where libcurl's CA
certificate bundle is assumed to be stored, as established at build time.
If curl is built against the NSS SSL library, the NSS PEM PKCS#11 module
(libnsspem.so) needs to be available for this option to work properly.
Starting with curl-7.55.0, if both \fICURLOPT_CAINFO(3)\fP and
\fICURLOPT_CAPATH(3)\fP are unset, NSS-linked libcurl tries to load
libnssckbi.so, which contains a more comprehensive set of trust information
than supported by nss-pem, because libnssckbi.so also includes information
about distrusted certificates.
(iOS and macOS) When curl uses Secure Transport this option is supported. If
the option is not set, then curl will use the certificates in the system and
user Keychain to verify the peer.
(Schannel) This option is supported for Schannel in Windows 7 or later but we
recommend not using it until Windows 8 since it works better starting then.
If the option is not set, then curl will use the certificates in the Windows'
store of root certificates (the default for Schannel).
The application does not have to keep the string around after setting this
option.
The default value for this can be figured out with \fICURLINFO_CAINFO(3)\fP.
.SH DEFAULT
Built-in system specific. When curl is built with Secure Transport or
Schannel, this option is not set by default.
.SH PROTOCOLS
All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_CAINFO, "/etc/certs/cabundle.pem");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
For the SSL engines that do not support certificate files the
\fICURLOPT_CAINFO(3)\fP option is ignored. Schannel support added in libcurl
7.60.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_CAINFO_BLOB "(3), " CURLOPT_CAPATH "(3), "
.BR CURLOPT_SSL_VERIFYPEER "(3), " CURLOPT_SSL_VERIFYHOST "(3), "
.BR CURLINFO_CAINFO "(3), "
share/man/man3/curl_mime_name.3 0000644 00000004451 14751150677 0012340 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_mime_name 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_mime_name - set a mime part's name
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_mime_name(curl_mimepart *part, const char *name);
.fi
.SH DESCRIPTION
\fIcurl_mime_name(3)\fP sets a mime part's name. This is the way HTTP form
fields are named.
\fIpart\fP is the part's handle to assign a name to.
\fIname\fP points to the null-terminated name string.
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 multiple times
is valid: only the value set by the last call is retained. It is possible to
reset the name of a part by setting \fIname\fP to NULL.
.SH EXAMPLE
.nf
curl_mime *mime;
curl_mimepart *part;
/* create a mime handle */
mime = curl_mime_init(easy);
/* add a part */
part = curl_mime_addpart(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),"
.BR curl_mime_type "(3)"
share/man/man3/CURLOPT_TCP_KEEPIDLE.3 0000644 00000004556 14751150677 0012472 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_TCP_KEEPIDLE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_TCP_KEEPIDLE \- TCP keep-alive idle time wait
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_KEEPIDLE, long delay);
.fi
.SH DESCRIPTION
Pass a long. Sets the \fIdelay\fP, in seconds, that the operating system will
wait while the connection is idle before sending keepalive probes. Not all
operating systems support this option.
The maximum value this accepts is 2147483648. Any larger value will be capped
to this amount.
.SH DEFAULT
60
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* enable TCP keep-alive for this transfer */
curl_easy_setopt(curl, CURLOPT_TCP_KEEPALIVE, 1L);
/* set keep-alive idle time to 120 seconds */
curl_easy_setopt(curl, CURLOPT_TCP_KEEPIDLE, 120L);
/* interval time between keep-alive probes: 60 seconds */
curl_easy_setopt(curl, CURLOPT_TCP_KEEPINTVL, 60L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.25.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_TCP_KEEPALIVE "(3), " CURLOPT_TCP_KEEPINTVL "(3), "
share/man/man3/CURLOPT_SSL_CTX_DATA.3 0000644 00000010444 14751150677 0012543 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SSL_CTX_DATA 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSL_CTX_DATA \- pointer passed to SSL context callback
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_CTX_DATA, void *pointer);
.fi
.SH DESCRIPTION
Data \fIpointer\fP to pass to the ssl context callback set by the option
\fICURLOPT_SSL_CTX_FUNCTION(3)\fP, this is the pointer you will get as third
parameter.
.SH DEFAULT
NULL
.SH PROTOCOLS
All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
.SH EXAMPLE
.nf
/* OpenSSL specific */
#include <openssl/ssl.h>
#include <curl/curl.h>
#include <stdio.h>
static CURLcode sslctx_function(CURL *curl, void *sslctx, void *parm)
{
X509_STORE *store;
X509 *cert = NULL;
BIO *bio;
char *mypem = parm;
/* get a BIO */
bio = BIO_new_mem_buf(mypem, -1);
/* use it to read the PEM formatted certificate from memory into an
* X509 structure that SSL can use
*/
PEM_read_bio_X509(bio, &cert, 0, NULL);
if(cert == NULL)
printf("PEM_read_bio_X509 failed...\\n");
/* get a pointer to the X509 certificate store (which may be empty) */
store = SSL_CTX_get_cert_store((SSL_CTX *)sslctx);
/* add our certificate to this store */
if(X509_STORE_add_cert(store, cert) == 0)
printf("error adding certificate\\n");
/* decrease reference counts */
X509_free(cert);
BIO_free(bio);
/* all set to go */
return CURLE_OK;
}
int main(void)
{
CURL * ch;
CURLcode rv;
char *mypem = /* example CA cert PEM - shortened */
"-----BEGIN CERTIFICATE-----\\n"
"MIIHPTCCBSWgAwIBAgIBADANBgkqhkiG9w0BAQQFADB5MRAwDgYDVQQKEwdSb290\\n"
"IENBMR4wHAYDVQQLExVodHRwOi8vd3d3LmNhY2VydC5vcmcxIjAgBgNVBAMTGUNB\\n"
"IENlcnQgU2lnbmluZyBBdXRob3JpdHkxITAfBgkqhkiG9w0BCQEWEnN1cHBvcnRA\\n"
"Y2FjZXJ0Lm9yZzAeFw0wMzAzMzAxMjI5NDlaFw0zMzAzMjkxMjI5NDlaMHkxEDAO\\n"
"GCSNe9FINSkYQKyTYOGWhlC0elnYjyELn8+CkcY7v2vcB5G5l1YjqrZslMZIBjzk\\n"
"zk6q5PYvCdxTby78dOs6Y5nCpqyJvKeyRKANihDjbPIky/qbn3BHLt4Ui9SyIAmW\\n"
"omTxJBzcoTWcFbLUvFUufQb1nA5V9FrWk9p2rSVzTMVD\\n"
"-----END CERTIFICATE-----\\n";
curl_global_init(CURL_GLOBAL_ALL);
ch = curl_easy_init();
curl_easy_setopt(ch, CURLOPT_SSLCERTTYPE, "PEM");
curl_easy_setopt(ch, CURLOPT_SSL_VERIFYPEER, 1L);
curl_easy_setopt(ch, CURLOPT_URL, "https://www.example.com/");
/* Retrieve page using cacerts' certificate -> will succeed
* load the certificate by installing a function doing the necessary
* "modifications" to the SSL CONTEXT just before link init
*/
curl_easy_setopt(ch, CURLOPT_SSL_CTX_FUNCTION, *sslctx_function);
curl_easy_setopt(ch, CURLOPT_SSL_CTX_DATA, mypem);
rv = curl_easy_perform(ch);
if(!rv)
printf("*** transfer succeeded ***\\n");
else
printf("*** transfer failed ***\\n");
curl_easy_cleanup(ch);
curl_global_cleanup();
return rv;
}
.fi
.SH AVAILABILITY
Added in 7.11.0 for OpenSSL, in 7.42.0 for wolfSSL, in 7.54.0 for mbedTLS,
in 7.83.0 in BearSSL. Other SSL backends are not supported.
.SH RETURN VALUE
CURLE_OK if supported; or an error such as:
CURLE_NOT_BUILT_IN - Not supported by the SSL backend
CURLE_UNKNOWN_OPTION
.SH "SEE ALSO"
.BR CURLOPT_SSL_CTX_FUNCTION "(3), " CURLOPT_SSLVERSION "(3), "
share/man/man3/CURLOPT_TIMECONDITION.3 0000644 00000005031 14751150677 0012574 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_TIMECONDITION 3 "October 22, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_TIMECONDITION \- select condition for a time request
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMECONDITION, long cond);
.fi
.SH DESCRIPTION
Pass a long as parameter. This defines how the \fICURLOPT_TIMEVALUE(3)\fP time
value is treated. You can set this parameter to \fICURL_TIMECOND_IFMODSINCE\fP
or \fICURL_TIMECOND_IFUNMODSINCE\fP.
The last modification time of a file is not always known and in such instances
this feature will have no effect even if the given time condition would not
have been met. \fIcurl_easy_getinfo(3)\fP with the
\fICURLINFO_CONDITION_UNMET\fP option can be used after a transfer to learn if
a zero-byte successful "transfer" was due to this condition not matching.
.SH DEFAULT
CURL_TIMECOND_NONE (0)
.SH PROTOCOLS
HTTP, FTP, RTSP, and FILE
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* January 1, 2020 is 1577833200 */
curl_easy_setopt(curl, CURLOPT_TIMEVALUE, 1577833200L);
/* If-Modified-Since the above time stamp */
curl_easy_setopt(curl, CURLOPT_TIMECONDITION,
(long)CURL_TIMECOND_IFMODSINCE);
/* Perform the request */
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_TIMEVALUE "(3), "
share/man/man3/CURLOPT_PROXY_TLSAUTH_USERNAME.3 0000644 00000005221 14751150677 0014214 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXY_TLSAUTH_USERNAME 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXY_TLSAUTH_USERNAME \- user name to use for proxy TLS authentication
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_TLSAUTH_USERNAME,
char *user);
.fi
.SH DESCRIPTION
Pass a char * as parameter, which should point to the null-terminated username
to use for the HTTPS proxy TLS authentication method specified with the
\fICURLOPT_PROXY_TLSAUTH_TYPE(3)\fP option. Requires that the
\fICURLOPT_PROXY_TLSAUTH_PASSWORD(3)\fP option also be set.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy");
curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_TYPE, "SRP");
curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_USERNAME, "user");
curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_PASSWORD, "secret");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.52.0, with the OpenSSL and GnuTLS backends only.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_PROXY_TLSAUTH_TYPE "(3), " CURLOPT_PROXY_TLSAUTH_PASSWORD "(3), "
.BR CURLOPT_TLSAUTH_TYPE "(3), " CURLOPT_TLSAUTH_PASSWORD "(3), "
share/man/man3/CURLINFO_RTSP_SESSION_ID.3 0000644 00000004464 14751150677 0013240 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_RTSP_SESSION_ID 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_RTSP_SESSION_ID \- get RTSP session ID
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_RTSP_SESSION_ID, char **id);
.fi
.SH DESCRIPTION
Pass a pointer to a char pointer to receive a pointer to a string holding the
most recent RTSP Session ID.
Applications wishing to resume an RTSP session on another connection should
retrieve this info before closing the active connection.
The \fBid\fP pointer will be NULL or pointing to private memory you MUST NOT
free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the
corresponding CURL handle.
.SH PROTOCOLS
RTSP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res;
curl_easy_setopt(curl, CURLOPT_URL, "rtsp://rtsp.example.com");
res = curl_easy_perform(curl);
if(res == CURLE_OK) {
char *id;
curl_easy_getinfo(curl, CURLINFO_RTSP_SESSION_ID, &id);
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.20.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
share/man/man3/CURLOPT_INFILESIZE_LARGE.3 0000644 00000005153 14751150677 0013147 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_INFILESIZE_LARGE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_INFILESIZE_LARGE \- size of the input file to send off
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_INFILESIZE_LARGE,
curl_off_t filesize);
.SH DESCRIPTION
When uploading a file to a remote site, \fIfilesize\fP should be used to tell
libcurl what the expected size of the input file is. This value must be passed
as a \fBcurl_off_t\fP.
For uploading using SCP, this option or \fICURLOPT_INFILESIZE(3)\fP is
mandatory.
To unset this value again, set it to -1.
When sending emails using SMTP, this command can be used to specify the
optional SIZE parameter for the MAIL FROM command.
This option does not limit how much data libcurl will actually send, as that
is controlled entirely by what the read callback returns, but telling one
value and sending a different amount may lead to errors.
.SH DEFAULT
Unset
.SH PROTOCOLS
Many
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_off_t uploadsize = FILE_SIZE;
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/destination.tar.gz");
curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L);
curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, uploadsize);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
SMTP support added in 7.23.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_INFILESIZE "(3), " CURLOPT_UPLOAD "(3), "
share/man/man3/CURLMOPT_MAXCONNECTS.3 0000644 00000005035 14751150677 0012472 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLMOPT_MAXCONNECTS 3 "May 17, 2022" "libcurl 7.86.0" "curl_multi_setopt options"
.SH NAME
CURLMOPT_MAXCONNECTS \- size of connection cache
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAXCONNECTS, long max);
.fi
.SH DESCRIPTION
Pass a long indicating the \fBmax\fP. The set number will be used as the
maximum amount of simultaneously open connections that libcurl may keep in its
connection cache after completed use. By default libcurl will enlarge the size
for each added easy handle to make it fit 4 times the number of added easy
handles.
By setting this option, you can prevent the cache size from growing beyond the
limit set by you.
When the cache is full, curl closes the oldest one in the cache to prevent the
number of open connections from increasing.
This option is for the multi handle's use only, when using the easy interface
you should instead use the \fICURLOPT_MAXCONNECTS(3)\fP option.
See \fICURLMOPT_MAX_TOTAL_CONNECTIONS(3)\fP for limiting the number of active
connections.
.SH DEFAULT
See DESCRIPTION
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURLM *m = curl_multi_init();
/* only keep 10 connections in the cache */
curl_multi_setopt(m, CURLMOPT_MAXCONNECTS, 10L);
.fi
.SH AVAILABILITY
Added in 7.16.3
.SH RETURN VALUE
Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLMOPT_MAX_HOST_CONNECTIONS "(3), "
.BR CURLOPT_MAXCONNECTS "(3), "
share/man/man3/CURLINFO_CONTENT_TYPE.3 0000644 00000004733 14751150677 0012643 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_CONTENT_TYPE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_CONTENT_TYPE \- get Content-Type
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONTENT_TYPE, char **ct);
.fi
.SH DESCRIPTION
Pass a pointer to a char pointer to receive the content-type of the downloaded
object. This is the value read from the Content-Type: field. If you get NULL,
it means that the server did not send a valid Content-Type header or that the
protocol used does not support this.
The \fBct\fP pointer will be NULL or pointing to private memory you MUST NOT
free it - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the
corresponding CURL handle.
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
res = curl_easy_perform(curl);
if(!res) {
/* extract the content-type */
char *ct = NULL;
res = curl_easy_getinfo(curl, CURLINFO_CONTENT_TYPE, &ct);
if(!res && ct) {
printf("Content-Type: %s\\n", ct);
}
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.9.4
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
.BR CURLOPT_HEADERFUNCTION "(3), " curl_easy_header "(3) "
share/man/man3/CURLINFO_STARTTRANSFER_TIME_T.3 0000644 00000005036 14751150677 0014030 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 2022 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_STARTTRANSFER_TIME_T 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_STARTTRANSFER_TIME_T \- get the time until the first byte is received
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_STARTTRANSFER_TIME_T,
curl_off_t *timep);
.fi
.SH DESCRIPTION
Pass a pointer to a curl_off_t to receive the time, in microseconds,
it took from the
start until the first byte is received by libcurl. This includes
\fICURLINFO_PRETRANSFER_TIME_T(3)\fP and also the time the server needs to
calculate the result.
When a redirect is followed, the time from each request is added together.
See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
curl_off_t start;
curl_easy_setopt(curl, CURLOPT_URL, url);
res = curl_easy_perform(curl);
if(CURLE_OK == res) {
res = curl_easy_getinfo(curl, CURLINFO_STARTTRANSFER_TIME_T, &start);
if(CURLE_OK == res) {
printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", start / 1000000,
(long)(start % 1000000));
}
}
/* always cleanup */
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.61.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), " CURLINFO_STARTTRANSFER_TIME "(3)"
share/man/man3/CURLOPT_SSL_EC_CURVES.3 0000644 00000004240 14751150677 0012667 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SSL_EC_CURVES 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSL_EC_CURVES \- key exchange curves
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_EC_CURVES, char *alg_list);
.fi
.SH DESCRIPTION
Pass a string as parameter with a colon delimited list of (EC) algorithms. This
option defines the client's key exchange algorithms in the SSL handshake (if
the SSL backend libcurl is built to use supports it).
.SH DEFAULT
"", embedded in SSL backend
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_SSL_EC_CURVES, "X25519:P-521");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.73.0. Supported by the OpenSSL backend.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_SSL_OPTIONS "(3), " CURLOPT_SSL_CIPHER_LIST "(3), "
.BR CURLOPT_TLS13_CIPHERS "(3), "
share/man/man3/curl_global_init_mem.3 0000644 00000006341 14751150677 0013532 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_global_init_mem 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_global_init_mem - Global libcurl initialization with memory callbacks
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_global_init_mem(long flags,
curl_malloc_callback m,
curl_free_callback f,
curl_realloc_callback r,
curl_strdup_callback s,
curl_calloc_callback c);
.fi
.SH DESCRIPTION
This function works exactly as \fIcurl_global_init(3)\fP with one addition: it
allows the application to set callbacks to replace the otherwise used internal
memory functions.
If you are using libcurl from multiple threads or libcurl was built with the
threaded resolver option then the callback functions must be thread safe. The
threaded resolver is a common build option to enable (and in some cases the
default) so we strongly urge you to make your callback functions thread safe.
All callback arguments must be set to valid function pointers. The
prototypes for the given callbacks must match these:
.IP "void *malloc_callback(size_t size);"
To replace malloc()
.IP "void free_callback(void *ptr);"
To replace free()
.IP "void *realloc_callback(void *ptr, size_t size);"
To replace realloc()
.IP "char *strdup_callback(const char *str);"
To replace strdup()
.IP "void *calloc_callback(size_t nmemb, size_t size);"
To replace calloc()
.PP
This function is otherwise the same as \fIcurl_global_init(3)\fP, please refer
to that man page for documentation.
.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 "SEE ALSO"
.BR curl_global_init "(3), "
.BR curl_global_cleanup "(3), "
share/man/man3/curl_easy_escape.3 0000644 00000006007 14751150677 0012671 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH curl_easy_escape 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_easy_escape - URL encodes the given string
.SH SYNOPSIS
.nf
#include <curl/curl.h>
char *curl_easy_escape(CURL *curl, const char *string, int length);
.fi
.SH DESCRIPTION
This function converts the given input \fIstring\fP to a URL encoded string
and returns that as a new allocated string. All input characters that are not
a-z, A-Z, 0-9, '-', '.', '_' or '~' are converted to their "URL escaped"
version (\fB%NN\fP where \fBNN\fP is a two-digit hexadecimal number).
If \fIlength\fP is set to 0 (zero), \fIcurl_easy_escape(3)\fP uses strlen() on
the input \fIstring\fP to find out the size. This function does not accept
input strings longer than \fBCURL_MAX_INPUT_LENGTH\fP (8 MB).
Since 7.82.0, the \fBcurl\fP parameter is ignored. Prior to that there was
per-handle character conversion support for some very old operating systems
such as TPF, but it was otherwise ignored.
You must \fIcurl_free(3)\fP the returned string when you are done with it.
.SH ENCODING
libcurl is typically not aware of, nor does it care about, character
encodings. \fIcurl_easy_escape(3)\fP encodes the data byte-by-byte into the
URL encoded version without knowledge or care for what particular character
encoding the application or the receiving server may assume that the data
uses.
The caller of \fIcurl_easy_escape(3)\fP must make sure that the data passed in
to the function is encoded correctly.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
char *output = curl_easy_escape(curl, "data to convert", 15);
if(output) {
printf("Encoded: %s\\n", output);
curl_free(output);
}
curl_easy_cleanup(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
share/man/man3/CURLOPT_SSL_ENABLE_ALPN.3 0000644 00000004140 14751150677 0013050 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SSL_ENABLE_ALPN 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSL_ENABLE_ALPN \- Application Layer Protocol Negotiation
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_ENABLE_ALPN, long npn);
.fi
.SH DESCRIPTION
Pass a long as parameter, 0 or 1 where 1 is for enable and 0 for disable. This
option enables/disables ALPN in the SSL handshake (if the SSL backend libcurl
is built to use supports it), which can be used to negotiate http2.
.SH DEFAULT
1, enabled
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_SSL_ENABLE_ALPN, 0L);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.36.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_SSL_ENABLE_NPN "(3), " CURLOPT_SSL_OPTIONS "(3), "
share/man/man3/CURLOPT_PROXYTYPE.3 0000644 00000005162 14751150677 0012217 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXYTYPE 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXYTYPE \- proxy protocol type
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYTYPE, long type);
.fi
.SH DESCRIPTION
Pass one of the values below to set the type of the proxy.
.RS
.IP CURLPROXY_HTTP
HTTP Proxy. Default.
.IP CURLPROXY_HTTPS
HTTPS Proxy. (Added in 7.52.0 for OpenSSL, GnuTLS and NSS)
.IP CURLPROXY_HTTP_1_0
HTTP 1.0 Proxy. This is similar to CURLPROXY_HTTP except it uses HTTP/1.0 for
any CONNECT tunneling. It does not change the HTTP version of the actual HTTP
requests, controlled by \fICURLOPT_HTTP_VERSION(3)\fP.
.IP CURLPROXY_SOCKS4
SOCKS4 Proxy.
.IP CURLPROXY_SOCKS4A
SOCKS4a Proxy. Proxy resolves URL hostname.
.IP CURLPROXY_SOCKS5
SOCKS5 Proxy.
.IP CURLPROXY_SOCKS5_HOSTNAME
SOCKS5 Proxy. Proxy resolves URL hostname.
.RE
Often it is more convenient to specify the proxy type with the scheme part of
the \fICURLOPT_PROXY(3)\fP string.
.SH DEFAULT
CURLPROXY_HTTP
.SH PROTOCOLS
Most
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode ret;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_PROXY, "local.example.com:1080");
/* set the proxy type */
curl_easy_setopt(curl, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS5);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_PROXY "(3), " CURLOPT_PROXYPORT "(3), "
share/man/man3/CURLOPT_RESOLVER_START_FUNCTION.3 0000644 00000005665 14751150677 0014327 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_RESOLVER_START_FUNCTION 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_RESOLVER_START_FUNCTION \- callback called before a new name resolve is started
.SH SYNOPSIS
.nf
#include <curl/curl.h>
int resolver_start_cb(void *resolver_state, void *reserved, void *userdata);
CURLcode curl_easy_setopt(CURL *handle,
CURLOPT_RESOLVER_START_FUNCTION,
resolver_start_cb);
.SH DESCRIPTION
Pass a pointer to your callback function, which should match the prototype
shown above.
This callback function gets called by libcurl every time before a new resolve
request is started.
\fIresolver_state\fP points to a backend-specific resolver state. Currently
only the ares resolver backend has a resolver state. It can be used to set up
any desired option on the ares channel before it's used, for example setting up
socket callback options.
\fIreserved\fP is reserved.
\fIuserdata\fP is the user pointer set with the
\fICURLOPT_RESOLVER_START_DATA(3)\fP option.
The callback must return 0 on success. Returning a non-zero value will cause
the resolve to fail.
.SH DEFAULT
NULL (No callback)
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
static int resolver_start_cb(void *resolver_state, void *reserved,
void *userdata)
{
(void)reserved;
printf("Received resolver_state=%p userdata=%p\\n",
resolver_state, userdata);
return 0;
}
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_RESOLVER_START_FUNCTION, resolver_start_cb);
curl_easy_setopt(curl, CURLOPT_RESOLVER_START_DATA, curl);
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.59.0
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_RESOLVER_START_DATA "(3) "
share/man/man3/CURLOPT_MAIL_FROM.3 0000644 00000004621 14751150677 0012140 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_MAIL_FROM 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_MAIL_FROM \- SMTP sender address
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAIL_FROM, char *from);
.fi
.SH DESCRIPTION
Pass a pointer to a null-terminated string as parameter. This should be used
to specify the sender's email address when sending SMTP mail with libcurl.
An originator email address should be specified with angled brackets (<>)
around it, which if not specified will be added automatically.
If this parameter is not specified then an empty address will be sent to the
mail server which may cause the email to be rejected.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
blank
.SH PROTOCOLS
SMTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "smtp://example.com/");
curl_easy_setopt(curl, CURLOPT_MAIL_FROM, "president@example.com");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.20.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_MAIL_RCPT "(3), " CURLOPT_MAIL_AUTH "(3), "
share/man/man3/CURLOPT_PIPEWAIT.3 0000644 00000006051 14751150677 0012014 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PIPEWAIT 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PIPEWAIT \- wait for pipelining/multiplexing
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PIPEWAIT, long wait);
.fi
.SH DESCRIPTION
Set \fIwait\fP to 1L to tell libcurl to prefer to wait for a connection to
confirm or deny that it can do pipelining or multiplexing before continuing.
When about to perform a new transfer that allows pipelining or multiplexing,
libcurl will check for existing connections to re-use and pipeline on. If no
such connection exists it will immediately continue and create a fresh new
connection to use.
By setting this option to 1 - and having \fICURLMOPT_PIPELINING(3)\fP enabled
for the multi handle this transfer is associated with - libcurl will instead
wait for the connection to reveal if it is possible to pipeline/multiplex on
before it continues. This enables libcurl to much better keep the number of
connections to a minimum when using pipelining or multiplexing protocols.
The effect thus becomes that with this option set, libcurl prefers to wait and
re-use an existing connection for pipelining rather than the opposite: prefer
to open a new connection rather than waiting.
The waiting time is as long as it takes for the connection to get up and for
libcurl to get the necessary response back that informs it about its protocol
and support level.
.SH DEFAULT
0 (off)
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_PIPEWAIT, 1L);
/* now add this easy handle to the multi handle */
}
.fi
.SH AVAILABILITY
Added in 7.43.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_FORBID_REUSE "(3), " CURLOPT_FRESH_CONNECT "(3), "
.BR CURLMOPT_PIPELINING "(3), " CURLMOPT_MAX_HOST_CONNECTIONS "(3), "
share/man/man3/CURLOPT_STDERR.3 0000644 00000004266 14751150677 0011603 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_STDERR 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_STDERR \- redirect stderr to another stream
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_STDERR, FILE *stream);
.fi
.SH DESCRIPTION
Pass a FILE * as parameter. Tell libcurl to use this \fIstream\fP instead of
stderr when showing the progress meter and displaying \fICURLOPT_VERBOSE(3)\fP
data.
If you are using libcurl as a win32 DLL, this option will cause an exception
and crash in the library since it cannot access a FILE * passed on from the
application. A work-around is to instead use \fICURLOPT_DEBUGFUNCTION(3)\fP.
.SH DEFAULT
stderr
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
FILE *filep = fopen("dump", "wb");
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_STDERR, filep);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_VERBOSE "(3), " CURLOPT_NOPROGRESS "(3), "
.BR CURLOPT_DEBUGFUNCTION "(3) "
share/man/man3/curl_multi_remove_handle.3 0000644 00000004762 14751150677 0014440 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_multi_remove_handle 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_multi_remove_handle - remove an easy handle from a multi session
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_remove_handle(CURLM *multi_handle, CURL *easy_handle);
.fi
.SH DESCRIPTION
Removes a given \fIeasy_handle\fP from the \fImulti_handle\fP. This will make
the specified easy handle be removed from this multi handle's control.
When the easy handle has been removed from a multi stack, it is again
perfectly legal to invoke \fIcurl_easy_perform(3)\fP on this easy handle.
Removing an easy handle while being used is perfectly legal and will
effectively halt the transfer in progress involving that easy handle. All
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"
.BR curl_multi_cleanup "(3)," curl_multi_init "(3), "
.BR curl_multi_add_handle "(3) "
share/man/man3/CURLOPT_COOKIELIST.3 0000644 00000011305 14751150677 0012235 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_COOKIELIST 3 "October 04, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_COOKIELIST \- add to or manipulate cookies held in memory
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIELIST,
char *cookie);
.SH DESCRIPTION
Pass a char * to a \fIcookie\fP string.
Such a cookie can be either a single line in Netscape / Mozilla format or just
regular HTTP-style header (Set-Cookie: ...) format. This will also enable the
cookie engine. This adds that single cookie to the internal cookie store.
Exercise caution if you are using this option and multiple transfers may occur.
If you use the Set-Cookie format and do not specify a domain then the cookie is
sent for any domain (even after redirects are followed) and cannot be modified
by a server-set cookie. If a server sets a cookie of the same name (or maybe
you have imported one) then both will be sent on a future transfer to that
server, likely not what you intended. To address these issues set a domain in
Set-Cookie (doing that will include sub-domains) or use the Netscape format as
shown in EXAMPLE.
Additionally, there are commands available that perform actions if you pass in
these exact strings:
.IP ALL
erases all cookies held in memory
.IP SESS
erases all session cookies held in memory
.IP FLUSH
writes all known cookies to the file specified by \fICURLOPT_COOKIEJAR(3)\fP
.IP RELOAD
loads all cookies from the files specified by \fICURLOPT_COOKIEFILE(3)\fP
.SH DEFAULT
NULL
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
/* This example shows an inline import of a cookie in Netscape format.
You can set the cookie as HttpOnly to prevent XSS attacks by prepending
#HttpOnly_ to the hostname. That may be useful if the cookie will later
be imported by a browser.
*/
#define SEP "\\t" /* Tab separates the fields */
char *my_cookie =
"example.com" /* Hostname */
SEP "FALSE" /* Include subdomains */
SEP "/" /* Path */
SEP "FALSE" /* Secure */
SEP "0" /* Expiry in epoch time format. 0 == Session */
SEP "foo" /* Name */
SEP "bar"; /* Value */
/* my_cookie is imported immediately via CURLOPT_COOKIELIST.
*/
curl_easy_setopt(curl, CURLOPT_COOKIELIST, my_cookie);
/* The list of cookies in cookies.txt will not be imported until right
before a transfer is performed. Cookies in the list that have the same
hostname, path and name as in my_cookie are skipped. That is because
libcurl has already imported my_cookie and it's considered a "live"
cookie. A live cookie will not be replaced by one read from a file.
*/
curl_easy_setopt(curl, CURLOPT_COOKIEFILE, "cookies.txt"); /* import */
/* Cookies are exported after curl_easy_cleanup is called. The server
may have added, deleted or modified cookies by then. The cookies that
were skipped on import are not exported.
*/
curl_easy_setopt(curl, CURLOPT_COOKIEJAR, "cookies.txt"); /* export */
curl_easy_perform(curl); /* cookies imported from cookies.txt */
curl_easy_cleanup(curl); /* cookies exported to cookies.txt */
.fi
.SH "Cookie file format"
The cookie file format and general cookie concepts in curl are described
online here: https://curl.se/docs/http-cookies.html
.SH AVAILABILITY
\fBALL\fP was added in 7.14.1
\fBSESS\fP was added in 7.15.4
\fBFLUSH\fP was added in 7.17.1
\fBRELOAD\fP was added in 7.39.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_COOKIEFILE "(3), " CURLOPT_COOKIEJAR "(3), " CURLOPT_COOKIE "(3), "
.BR CURLINFO_COOKIELIST "(3), "
share/man/man3/CURLOPT_USE_SSL.3 0000644 00000005502 14751150677 0011747 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_USE_SSL 3 "October 22, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_USE_SSL \- request using SSL / TLS for the transfer
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_USE_SSL, long level);
.fi
.SH DESCRIPTION
Pass a long using one of the values from below, to make libcurl use your
desired \fIlevel\fP of SSL for the transfer.
These are all protocols that start out plain text and get "upgraded" to SSL
using the STARTTLS command.
This is for enabling SSL/TLS when you use FTP, SMTP, POP3, IMAP etc.
.IP CURLUSESSL_NONE
do not attempt to use SSL.
.IP CURLUSESSL_TRY
Try using SSL, proceed as normal otherwise. Note that server may close the
connection if the negotiation does not succeed.
.IP CURLUSESSL_CONTROL
Require SSL for the control connection or fail with \fICURLE_USE_SSL_FAILED\fP.
.IP CURLUSESSL_ALL
Require SSL for all communication or fail with \fICURLE_USE_SSL_FAILED\fP.
.SH DEFAULT
CURLUSESSL_NONE
.SH PROTOCOLS
FTP, SMTP, POP3, IMAP, LDAP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/file.ext");
/* require use of SSL for this, or fail */
curl_easy_setopt(curl, CURLOPT_USE_SSL, (long)CURLUSESSL_ALL);
/* Perform the request */
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.11.0. This option was known as CURLOPT_FTP_SSL up to 7.16.4, and
the constants were known as CURLFTPSSL_*
Handled by LDAP since 7.81.0. Fully supported by the OpenLDAP backend only.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_SSLVERSION "(3), " CURLOPT_PROXY_SSLVERSION "(3), "
.BR CURLOPT_SSL_OPTIONS "(3), "
share/man/man3/curl_multi_assign.3 0000644 00000006162 14751150677 0013110 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_multi_assign 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_multi_assign \- set data to associate with an internal socket
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_assign(CURLM *multi_handle, curl_socket_t sockfd,
void *sockptr);
.fi
.SH DESCRIPTION
This function creates an association in the multi handle between the given
socket and a private pointer of the application. This is designed for
\fIcurl_multi_socket_action(3)\fP uses.
When set, the \fIsockptr\fP pointer will be passed to all future socket
callbacks for the specific \fIsockfd\fP socket.
If the given \fIsockfd\fP is not already in use by libcurl, this function will
return an error.
libcurl only keeps one single pointer associated with a socket, so calling
this function several times for the same socket will make the last set pointer
get used.
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.
It is acceptable to call this function from your multi callback functions.
.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
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.
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 do not have to find the struct associated with this socket by ourselves.
.SH "SEE ALSO"
.BR curl_multi_setopt "(3), " curl_multi_socket_action "(3) "
share/man/man3/curl_slist_free_all.3 0000644 00000003634 14751150677 0013402 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_slist_free_all 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_slist_free_all - free an entire curl_slist list
.SH SYNOPSIS
.nf
#include <curl/curl.h>
void curl_slist_free_all(struct curl_slist *list);
.fi
.SH DESCRIPTION
curl_slist_free_all() removes all traces of a previously built curl_slist
linked list.
Passing in a NULL pointer in \fIlist\fP will make this function return
immediately with no action.
.SH EXAMPLE
.nf
CURL *handle;
struct curl_slist *slist=NULL;
slist = curl_slist_append(slist, "X-libcurl: coolness");
if (slist == NULL)
return -1;
curl_easy_setopt(handle, CURLOPT_HTTPHEADER, slist);
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), "
share/man/man3/CURLSHOPT_UNLOCKFUNC.3 0000644 00000005133 14751150677 0012474 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH CURLSHOPT_UNLOCKFUNC 3 "September 28, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
CURLSHOPT_UNLOCKFUNC - mutex unlock callback
.SH SYNOPSIS
.nf
#include <curl/curl.h>
void unlockcb(CURL *handle, curl_lock_data data, void *userptr);
CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_UNLOCKFUNC, unlockcb);
.fi
.SH DESCRIPTION
Set a mutex unlock callback for the share object. There's a corresponding
\fICURLSHOPT_LOCKFUNC(3)\fP callback called when the mutex is first locked.
The \fIunlockcb\fP argument must be a pointer to a function matching the
prototype shown above. The arguments to the callback are:
\fIhandle\fP is the currently active easy handle in use when the share object
is released.
The \fIdata\fP argument tells what kind of data libcurl wants to unlock. Make
sure that the callback uses a different lock for each kind of data.
\fIuserptr\fP is the private pointer you set with \fICURLSHOPT_USERDATA\fP.
This pointer is not used by libcurl itself.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURLSHcode sh;
share = curl_share_init();
sh = curl_share_setopt(share, CURLSHOPT_UNLOCKFUNC, mutex_unlock);
if(sh)
printf("Error: %s\\n", curl_share_strerror(sh));
.fi
.SH AVAILABILITY
Added in 7.10
.SH RETURN VALUE
CURLSHE_OK (zero) means that the option was set properly, non-zero means an
error occurred. See \fIlibcurl-errors(3)\fP for the full list with
descriptions.
.SH "SEE ALSO"
.BR CURLSHOPT_LOCKFUNC "(3), "
.BR curl_share_setopt "(3), " curl_share_cleanup "(3), " curl_share_init "(3)"
share/man/man3/CURLOPT_FILETIME.3 0000644 00000004662 14751150677 0011776 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_FILETIME 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_FILETIME \- get the modification time of the remote resource
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FILETIME, long gettime);
.fi
.SH DESCRIPTION
Pass a long. If it is 1, libcurl will attempt to get the modification time of
the remote document in this operation. This requires that the remote server
sends the time or replies to a time querying command. The
\fIcurl_easy_getinfo(3)\fP function with the \fICURLINFO_FILETIME(3)\fP
argument can be used after a transfer to extract the received time (if any).
.SH DEFAULT
0
.SH PROTOCOLS
HTTP(S), FTP(S), SFTP, FILE, SMB(S)
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, url);
/* Ask for filetime */
curl_easy_setopt(curl, CURLOPT_FILETIME, 1L);
res = curl_easy_perform(curl);
if(CURLE_OK == res) {
res = curl_easy_getinfo(curl, CURLINFO_FILETIME, &filetime);
if((CURLE_OK == res) && (filetime >= 0)) {
time_t file_time = (time_t)filetime;
printf("filetime %s: %s", filename, ctime(&file_time));
}
}
/* always cleanup */
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Always, for SFTP since 7.49.0
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), "
share/man/man3/CURLOPT_SSH_PRIVATE_KEYFILE.3 0000644 00000004750 14751150677 0013575 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SSH_PRIVATE_KEYFILE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSH_PRIVATE_KEYFILE \- private key file for SSH auth
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_PRIVATE_KEYFILE,
char *filename);
.SH DESCRIPTION
Pass a char * pointing to a \fIfilename\fP for your private key. If not used,
libcurl defaults to \fB$HOME/.ssh/id_dsa\fP if the HOME environment variable
is set, and just "id_dsa" in the current directory if HOME is not set.
If the file is password-protected, set the password with
\fICURLOPT_KEYPASSWD(3)\fP.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
As explained above
.SH PROTOCOLS
SFTP and SCP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file");
curl_easy_setopt(curl, CURLOPT_SSH_PRIVATE_KEYFILE,
"/home/clarkkent/.ssh/id_rsa");
curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "password");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.16.1
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_SSH_PUBLIC_KEYFILE "(3), " CURLOPT_SSH_AUTH_TYPES "(3), "
share/man/man3/CURLOPT_MAIL_RCPT_ALLLOWFAILS.3 0000644 00000005315 14751150677 0013777 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_MAIL_RCPT_ALLLOWFAILS 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_MAIL_RCPT_ALLLOWFAILS \- allow RCPT TO command to fail for some recipients
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAIL_RCPT_ALLLOWFAILS,
long allow);
.SH DESCRIPTION
If \fIallow\fP is set to 1L, allow RCPT TO command to fail for some recipients.
When sending data to multiple recipients, by default curl will abort SMTP
conversation if at least one of the recipients causes RCPT TO command to
return an error.
The default behavior can be changed by setting \fIignore\fP to 1L which will
make curl ignore errors and proceed with the remaining valid recipients.
If all recipients trigger RCPT TO failures and this flag is specified, curl
will still abort the SMTP conversation and return the error received from to
the last RCPT TO command.
.SH DEFAULT
0
.SH PROTOCOLS
SMTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
struct curl_slist *list;
/* Adding one valid and one invalid email address */
list = curl_slist_append(NULL, "person@example.com");
list = curl_slist_append(list, "invalidemailaddress");
curl_easy_setopt(curl, CURLOPT_URL, "smtp://example.com/");
curl_easy_setopt(curl, CURLOPT_MAIL_RCPT_ALLLOWFAILS, 1L);
ret = curl_easy_perform(curl);
curl_slist_free_all(list);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.69.0.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_MAIL_FROM "(3), " CURLOPT_MAIL_RCPT "(3), "
share/man/man3/CURLOPT_FTPPORT.3 0000644 00000006316 14751150677 0011734 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_FTPPORT 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_FTPPORT \- make FTP transfer active
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTPPORT, char *spec);
.fi
.SH DESCRIPTION
Pass a pointer to a null-terminated string as parameter. It specifies that the
FTP transfer will be made actively and the given string will be used to get
the IP address to use for the FTP PORT instruction.
The PORT instruction tells the remote server to connect to our specified IP
address. The string may be a plain IP address, a host name, a network
interface name (under Unix) or just a '-' symbol to let the library use your
system's default IP address. Default FTP operations are passive, and thus
will not use PORT.
The address can be followed by a ':' to specify a port, optionally followed by
a '-' to specify a port range. If the port specified is 0, the operating
system will pick a free port. If a range is provided and all ports in the
range are not available, libcurl will report CURLE_FTP_PORT_FAILED for the
handle. Invalid port/range settings are ignored. IPv6 addresses followed by
a port or port range have to be in brackets. IPv6 addresses without
port/range specifier can be in brackets.
Examples with specified ports:
.nf
eth0:0
192.168.1.2:32000-33000
curl.se:32123
[::1]:1234-4567
.fi
You disable PORT again and go back to using the passive version by setting
this option to NULL.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
FTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/old-server/file.txt");
curl_easy_setopt(curl, CURLOPT_FTPPORT, "-");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Port range support was added in 7.19.5
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_FTP_USE_EPRT "(3), " CURLOPT_FTP_USE_EPSV "(3), "
share/man/man3/CURLINFO_FILETIME.3 0000644 00000005440 14751150677 0012062 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_FILETIME 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_FILETIME \- get the remote time of the retrieved document
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_FILETIME, long *timep);
.fi
.SH DESCRIPTION
Pass a pointer to a long to receive the remote time of the retrieved document
in number of seconds since January 1 1970 in the GMT/UTC time zone. If you get
-1, it can be because of many reasons (it might be unknown, the server might
hide it or the server does not support the command that tells document time
etc) and the time of the document is unknown.
You must tell libcurl to collect this information before the transfer is made,
by using the \fICURLOPT_FILETIME(3)\fP option to \fIcurl_easy_setopt(3)\fP or
you will unconditionally get a -1 back.
Consider using \fICURLINFO_FILETIME_T(3)\fP to be able to extract dates beyond
the year 2038 on systems using 32 bit longs.
.SH PROTOCOLS
HTTP(S), FTP(S), SFTP
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, url);
/* Ask for filetime */
curl_easy_setopt(curl, CURLOPT_FILETIME, 1L);
res = curl_easy_perform(curl);
if(CURLE_OK == res) {
res = curl_easy_getinfo(curl, CURLINFO_FILETIME, &filetime);
if((CURLE_OK == res) && (filetime >= 0)) {
time_t file_time = (time_t)filetime;
printf("filetime %s: %s", filename, ctime(&file_time));
}
}
/* always cleanup */
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.5
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
share/man/man3/CURLMOPT_MAX_PIPELINE_LENGTH.3 0000644 00000004662 14751150677 0013670 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLMOPT_MAX_PIPELINE_LENGTH 3 "September 20, 2022" "libcurl 7.86.0" "curl_multi_setopt options"
.SH NAME
CURLMOPT_MAX_PIPELINE_LENGTH \- maximum number of requests in a pipeline
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_PIPELINE_LENGTH,
long max);
.fi
.SH DESCRIPTION
No function since pipelining was removed in 7.62.0.
Pass a long. The set \fBmax\fP number will be used as the maximum amount of
outstanding requests in an HTTP/1.1 pipeline. This option is only used for
HTTP/1.1 pipelining, not for HTTP/2 multiplexing.
When this limit is reached, libcurl will use another connection to the same
host (see \fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP), or queue the request until
one of the pipelines to the host is ready to accept a request. Thus, the
total number of requests in-flight is \fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP *
\fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP.
.SH DEFAULT
5
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
.nf
CURLM *m = curl_multi_init();
/* set a more conservative pipe length */
curl_multi_setopt(m, CURLMOPT_MAX_PIPELINE_LENGTH, 3L);
.fi
.SH AVAILABILITY
Added in 7.30.0
.SH RETURN VALUE
Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLMOPT_PIPELINING "(3), " CURLMOPT_MAX_HOST_CONNECTIONS "(3), "
share/man/man3/CURLOPT_POSTFIELDSIZE.3 0000644 00000004472 14751150677 0012623 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_POSTFIELDSIZE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_POSTFIELDSIZE \- size of POST data pointed to
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTFIELDSIZE, long size);
.fi
.SH DESCRIPTION
If you want to post data to the server without having libcurl do a strlen() to
measure the data size, this option must be used. When this option is used you
can post fully binary data, which otherwise is likely to fail. If this size is
set to -1, the library will use strlen() to get the size.
If you post more than 2GB, use \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP.
.SH DEFAULT
-1
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
const char *data = "data to send";
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* size of the POST data */
curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, (long) strlen(data));
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Along with HTTP
.SH RETURN VALUE
Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_POSTFIELDS "(3), " CURLOPT_POSTFIELDSIZE_LARGE "(3), "
share/man/man3/CURLOPT_HTTP_CONTENT_DECODING.3 0000644 00000004246 14751150677 0014003 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_HTTP_CONTENT_DECODING 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_HTTP_CONTENT_DECODING \- HTTP content decoding control
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP_CONTENT_DECODING,
long enabled);
.SH DESCRIPTION
Pass a long to tell libcurl how to act on content decoding. If set to zero,
content decoding will be disabled. If set to 1 it is enabled. Libcurl has no
default content decoding but requires you to use
\fICURLOPT_ACCEPT_ENCODING(3)\fP for that.
.SH DEFAULT
1
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode ret;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_HTTP_CONTENT_DECODING, 0L);
ret = curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.16.2
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_STDERR "(3), " CURLOPT_DEBUGFUNCTION "(3), "
.BR CURLOPT_ACCEPT_ENCODING "(3) "
share/man/man3/CURLINFO_PRIMARY_PORT.3 0000644 00000004526 14751150677 0012657 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_PRIMARY_PORT 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_PRIMARY_PORT \- get the latest destination port number
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PRIMARY_PORT, long *portp);
.fi
.SH DESCRIPTION
Pass a pointer to a long to receive the destination port of the most recent
connection done with this \fBcurl\fP handle.
This is the destination port of the actual TCP or UDP connection libcurl used.
If a proxy was used for the most recent transfer, this is the port number of
the proxy, if no proxy was used it is the port number of the most recently
accessed URL.
.SH PROTOCOLS
All
.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);
if(res == CURLE_OK) {
long port;
res = curl_easy_getinfo(curl, CURLINFO_PRIMARY_PORT, &port);
if(!res)
printf("Connected to remote port: %ld\\n", port);
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.21.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
share/man/man3/CURLOPT_RTSP_SESSION_ID.3 0000644 00000004661 14751150677 0013146 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_RTSP_SESSION_ID 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_RTSP_SESSION_ID \- RTSP session ID
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_SESSION_ID, char *id);
.fi
.SH DESCRIPTION
Pass a char * as a parameter to set the value of the current RTSP Session ID
for the handle. Useful for resuming an in-progress session. Once this value is
set to any non-NULL value, libcurl will return \fICURLE_RTSP_SESSION_ERROR\fP
if ID received from the server does not match. If unset (or set to NULL),
libcurl will automatically set the ID the first time the server sets it in a
response.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
RTSP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
char *prev_id; /* saved from before somehow */
curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/");
curl_easy_setopt(curl, CURLOPT_RTSP_SESSION_ID, prev_id);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.20.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_RTSP_REQUEST "(3), " CURLOPT_RTSP_STREAM_URI "(3), "
share/man/man3/CURLOPT_INFILESIZE.3 0000644 00000005177 14751150677 0012243 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_INFILESIZE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_INFILESIZE \- size of the input file to send off
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_INFILESIZE, long filesize);
.fi
.SH DESCRIPTION
When uploading a file to a remote site, \fIfilesize\fP should be used to tell
libcurl what the expected size of the input file is. This value must be passed
as a long. See also \fICURLOPT_INFILESIZE_LARGE(3)\fP for sending files larger
than 2GB.
For uploading using SCP, this option or \fICURLOPT_INFILESIZE_LARGE(3)\fP is
mandatory.
To unset this value again, set it to -1.
When sending emails using SMTP, this command can be used to specify the
optional SIZE parameter for the MAIL FROM command.
This option does not limit how much data libcurl will actually send, as that
is controlled entirely by what the read callback returns, but telling one
value and sending a different amount may lead to errors.
.SH DEFAULT
Unset
.SH PROTOCOLS
Many
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
long uploadsize = FILE_SIZE;
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/destination.tar.gz");
curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L);
curl_easy_setopt(curl, CURLOPT_INFILESIZE, uploadsize);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
SMTP support added in 7.23.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_INFILESIZE_LARGE "(3), " CURLOPT_UPLOAD "(3), "
share/man/man3/CURLOPT_FTPSSLAUTH.3 0000644 00000004653 14751150677 0012275 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_FTPSSLAUTH 3 "October 22, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_FTPSSLAUTH \- order in which to attempt TLS vs SSL
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTPSSLAUTH, long order);
.fi
.SH DESCRIPTION
Pass a long using one of the values from below, to alter how libcurl issues
\&"AUTH TLS" or "AUTH SSL" when FTP over SSL is activated. This is only
interesting if \fICURLOPT_USE_SSL(3)\fP is also set.
Possible \fIorder\fP values:
.IP CURLFTPAUTH_DEFAULT
Allow libcurl to decide.
.IP CURLFTPAUTH_SSL
Try "AUTH SSL" first, and only if that fails try "AUTH TLS".
.IP CURLFTPAUTH_TLS
Try "AUTH TLS" first, and only if that fails try "AUTH SSL".
.SH DEFAULT
CURLFTPAUTH_DEFAULT
.SH PROTOCOLS
FTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/file.txt");
curl_easy_setopt(curl, CURLOPT_USE_SSL, CURLUSESSL_TRY);
/* funny server, ask for SSL before TLS */
curl_easy_setopt(curl, CURLOPT_FTPSSLAUTH, (long)CURLFTPAUTH_SSL);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.12.2
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_USE_SSL "(3), " CURLOPT_FTP_SSL_CCC "(3), "
share/man/man3/CURLOPT_PINNEDPUBLICKEY.3 0000644 00000010775 14751150677 0013027 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PINNEDPUBLICKEY 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PINNEDPUBLICKEY \- pinned public key
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PINNEDPUBLICKEY,
char *pinnedpubkey);
.fi
.SH DESCRIPTION
Pass a pointer to a null-terminated string as parameter. The string can be the
file name of your pinned public key. The file format expected is "PEM" or "DER".
The string can also be any number of base64 encoded sha256 hashes preceded by
"sha256//" and separated by ";"
When negotiating a TLS or SSL connection, the server sends a certificate
indicating its identity. A public key is extracted from this certificate and
if it does not exactly match the public key provided to this option, curl will
abort the connection before sending or receiving any data.
On mismatch, \fICURLE_SSL_PINNEDPUBKEYNOTMATCH\fP is returned.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_PINNEDPUBLICKEY, "/etc/publickey.der");
/* OR
curl_easy_setopt(curl, CURLOPT_PINNEDPUBLICKEY, "sha256//YhKJKSzoTt2b5FP18fvpHo7fJYqQCjAa3HWY3tvRMwE=;sha256//t62CeU2tQiqkexU74Gxa2eg7fRbEgoChTociMee9wno=");
*/
/* Perform the request */
curl_easy_perform(curl);
}
.fi
.SH PUBLIC KEY EXTRACTION
If you do not have the server's public key file you can extract it from the
server's certificate.
.nf
# retrieve the server's certificate if you do not already have it
#
# be sure to examine the certificate to see if it is what you expected
#
# Windows-specific:
# - Use NUL instead of /dev/null.
# - OpenSSL may wait for input instead of disconnecting. Hit enter.
# - If you do not have sed, then just copy the certificate into a file:
# Lines from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE-----.
#
openssl s_client -servername www.example.com -connect www.example.com:443 < /dev/null | sed -n "/-----BEGIN/,/-----END/p" > www.example.com.pem
# extract public key in pem format from certificate
openssl x509 -in www.example.com.pem -pubkey -noout > www.example.com.pubkey.pem
# convert public key from pem to der
openssl asn1parse -noout -inform pem -in www.example.com.pubkey.pem -out www.example.com.pubkey.der
# sha256 hash and base64 encode der to string for use
openssl dgst -sha256 -binary www.example.com.pubkey.der | openssl base64
.fi
The public key in PEM format contains a header, base64 data and a
footer:
.nf
-----BEGIN PUBLIC KEY-----
[BASE 64 DATA]
-----END PUBLIC KEY-----
.fi
.SH AVAILABILITY
PEM/DER support:
7.39.0: OpenSSL, GnuTLS
7.39.0-7.48.0,7.58.1+: GSKit
7.43.0: NSS and wolfSSL
7.47.0: mbedTLS
7.54.1: Secure Transport on macOS 10.7+/iOS 10+
7.58.1: Schannel
sha256 support:
7.44.0: OpenSSL, GnuTLS, NSS and wolfSSL
7.47.0: mbedTLS
7.54.1: Secure Transport on macOS 10.7+/iOS 10+
7.58.1: Schannel Windows XP SP3+
Other SSL backends not supported.
.SH RETURN VALUE
Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_SSL_VERIFYPEER "(3), "
.BR CURLOPT_SSL_VERIFYHOST "(3), "
.BR CURLOPT_CAINFO "(3), "
.BR CURLOPT_CAPATH "(3), "
share/man/man3/CURLOPT_HTTPGET.3 0000644 00000004634 14751150677 0011716 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_HTTPGET 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_HTTPGET \- ask for an HTTP GET request
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPGET, long useget);
.fi
.SH DESCRIPTION
Pass a long. If \fIuseget\fP is 1, this forces the HTTP request to get back to
using GET. Usable if a POST, HEAD, PUT, etc has been used previously using the
same curl \fIhandle\fP.
When setting \fICURLOPT_HTTPGET(3)\fP to 1, it will automatically set
\fICURLOPT_NOBODY(3)\fP to 0 and \fICURLOPT_UPLOAD(3)\fP to 0.
Setting this option to zero has no effect. Applications need to explicitly
select which HTTP request method to use, they cannot deselect a method. To
reset a handle to default method, consider \fIcurl_easy_reset(3)\fP.
.SH DEFAULT
0
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* use a GET to fetch this */
curl_easy_setopt(curl, CURLOPT_HTTPGET, 1L);
/* Perform the request */
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Along with HTTP
.SH RETURN VALUE
Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_NOBODY "(3), " CURLOPT_UPLOAD "(3), " CURLOPT_POST "(3), "
.BR curl_easy_reset "(3) "
share/man/man3/CURLOPT_CONNECT_TO.3 0000644 00000011170 14751150677 0012263 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_CONNECT_TO 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_CONNECT_TO \- connect to a specific host and port instead of the URL's host and port
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECT_TO,
struct curl_slist *connect_to);
.fi
.SH DESCRIPTION
Pass a pointer to a linked list of strings with "connect to" information to
use for establishing network connections with this handle. The linked list
should be a fully valid list of \fBstruct curl_slist\fP structs properly
filled in. Use \fIcurl_slist_append(3)\fP to create the list and
\fIcurl_slist_free_all(3)\fP to clean up an entire list.
Each single string should be written using the format
HOST:PORT:CONNECT-TO-HOST:CONNECT-TO-PORT where HOST is the host of the
request, PORT is the port of the request, CONNECT-TO-HOST is the host name to
connect to, and CONNECT-TO-PORT is the port to connect to.
The first string that matches the request's host and port is used.
Dotted numerical IP addresses are supported for HOST and CONNECT-TO-HOST.
A numerical IPv6 address must be written within [brackets].
Any of the four values may be empty. When the HOST or PORT is empty, the host
or port will always match (the request's host or port is ignored).
When CONNECT-TO-HOST or CONNECT-TO-PORT is empty, the "connect to" feature
will be disabled for the host or port, and the request's host or port will be
used to establish the network connection.
This option is suitable to direct the request at a specific server, e.g. at a
specific cluster node in a cluster of servers.
The "connect to" host and port are only used to establish the network
connection. They do NOT affect the host and port that are used for TLS/SSL
(e.g. SNI, certificate verification) or for the application protocols.
In contrast to \fICURLOPT_RESOLVE(3)\fP, the option
\fICURLOPT_CONNECT_TO(3)\fP does not pre-populate the DNS cache and therefore
it does not affect future transfers of other easy handles that have been added
to the same multi handle.
The "connect to" host and port are ignored if they are equal to the host and
the port in the request URL, because connecting to the host and the port in
the request URL is the default behavior.
If an HTTP proxy is used for a request having a special "connect to" host or
port, and the "connect to" host or port differs from the request's host and
port, the HTTP proxy is automatically switched to tunnel mode for this
specific request. This is necessary because it is not possible to connect to a
specific host or port in normal (non-tunnel) mode.
When this option is passed to \fIcurl_easy_setopt(3)\fP, libcurl will not copy
the entire list so you \fBmust\fP keep it around until you no longer use this
\fIhandle\fP for a transfer before you call \fIcurl_slist_free_all(3)\fP on
the list.
.SH DEFAULT
NULL
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl;
struct curl_slist *connect_to = NULL;
connect_to = curl_slist_append(NULL, "example.com::server1.example.com:");
curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_CONNECT_TO, connect_to);
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_perform(curl);
/* always cleanup */
curl_easy_cleanup(curl);
}
curl_slist_free_all(connect_to);
.fi
.SH AVAILABILITY
Added in 7.49.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_URL "(3), " CURLOPT_RESOLVE "(3), " CURLOPT_FOLLOWLOCATION "(3), " CURLOPT_HTTPPROXYTUNNEL "(3), "
share/man/man3/curl_easy_duphandle.3 0000644 00000005347 14751150677 0013403 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_easy_duphandle 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_easy_duphandle - Clone a libcurl session handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURL *curl_easy_duphandle(CURL *handle);
.fi
.SH DESCRIPTION
This function will return a new curl handle, a duplicate, using all the
options previously set in the input curl \fIhandle\fP. Both handles can
subsequently be used independently and they must both be freed with
\fIcurl_easy_cleanup(3)\fP.
All strings that the input handle has been told to point to (as opposed to
copy) with previous calls to \fIcurl_easy_setopt(3)\fP using char * inputs,
will be pointed to by the new handle as well. You must therefore make sure to
keep the data around until both handles have been cleaned up.
The new handle will \fBnot\fP inherit any state information, no connections,
no SSL sessions and no cookies. It also will not inherit any share object
states or options (it will be made as if \fICURLOPT_SHARE(3)\fP was set to
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 7.9
.SH RETURN VALUE
If this function returns NULL, something went wrong and no valid handle was
returned.
.SH "SEE ALSO"
.BR curl_easy_init "(3)," curl_easy_cleanup "(3)," curl_easy_reset "(3),"
.BR curl_global_init "(3)"
share/man/man3/CURLOPT_EXPECT_100_TIMEOUT_MS.3 0000644 00000004375 14751150677 0013756 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_EXPECT_100_TIMEOUT_MS 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_EXPECT_100_TIMEOUT_MS \- timeout for Expect: 100-continue response
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_EXPECT_100_TIMEOUT_MS,
long milliseconds);
.SH DESCRIPTION
Pass a long to tell libcurl the number of \fImilliseconds\fP to wait for a
server response with the HTTP status 100 (Continue), 417 (Expectation Failed)
or similar after sending an HTTP request containing an Expect: 100-continue
header. If this times out before a response is received, the request body is
sent anyway.
.SH DEFAULT
1000 milliseconds
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* wait 3 seconds for 100-continue */
curl_easy_setopt(curl, CURLOPT_EXPECT_100_TIMEOUT_MS, 3000L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.36.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_POST "(3), " CURLOPT_HTTPPOST "(3), "
share/man/man3/CURLOPT_PROXY_SSL_VERIFYHOST.3 0000644 00000006723 14751150677 0014024 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXY_SSL_VERIFYHOST 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXY_SSL_VERIFYHOST \- verify the proxy certificate's name against host
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSL_VERIFYHOST,
long verify);
.fi
.SH DESCRIPTION
Pass a long set to 2L as asking curl to \fIverify\fP in the HTTPS proxy's
certificate name fields against the proxy name.
This option determines whether libcurl verifies that the proxy cert contains
the correct name for the name it is known as.
When \fICURLOPT_PROXY_SSL_VERIFYHOST(3)\fP is 2, the proxy certificate must
indicate that the server is the proxy to which you meant to connect to, or the
connection fails.
Curl considers the proxy the intended one when the Common Name field or a
Subject Alternate Name field in the certificate matches the host name in the
proxy string which you told curl to use.
If \fIverify\fP value is set to 1:
In 7.28.0 and earlier: treated as a debug option of some sorts, not supported
anymore due to frequently leading to programmer mistakes.
From 7.28.1 to 7.65.3: setting it to 1 made curl_easy_setopt() return an error
and leaving the flag untouched.
From 7.66.0: treats 1 and 2 the same.
When the \fIverify\fP value is 0L, the connection succeeds regardless of the
names used in the certificate. Use that ability with caution!
See also \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP to verify the digital signature
of the proxy certificate. If libcurl is built against NSS and
\fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP is zero,
\fICURLOPT_PROXY_SSL_VERIFYHOST(3)\fP is also set to zero and cannot be
overridden.
.SH DEFAULT
2
.SH PROTOCOLS
All protocols when used over an HTTPS proxy.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* Set the default value: strict name check please */
curl_easy_setopt(curl, CURLOPT_PROXY_SSL_VERIFYHOST, 2L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.52.0.
If built TLS enabled.
.SH RETURN VALUE
Returns CURLE_OK if TLS is supported, and CURLE_UNKNOWN_OPTION if not.
If 1 is set as argument, \fICURLE_BAD_FUNCTION_ARGUMENT\fP is returned.
.SH "SEE ALSO"
.BR CURLOPT_PROXY_SSL_VERIFYPEER "(3), " CURLOPT_PROXY_CAINFO "(3), "
.BR CURLOPT_SSL_VERIFYPEER "(3), " CURLOPT_CAINFO "(3), "
share/man/man3/curl_multi_poll.3 0000644 00000010637 14751150677 0012574 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_multi_poll 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_multi_poll - polls on all easy handles in a multi handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_poll(CURLM *multi_handle,
struct curl_waitfd extra_fds[],
unsigned int extra_nfds,
int timeout_ms,
int *numfds);
.ad
.SH DESCRIPTION
\fIcurl_multi_poll(3)\fP polls all file descriptors used by the curl easy
handles contained in the given multi handle set. It will block until activity
is detected on at least one of the handles or \fItimeout_ms\fP has passed.
Alternatively, if the multi handle has a pending internal timeout that has a
shorter expiry time than \fItimeout_ms\fP, that shorter time will be used
instead to make sure timeout accuracy is reasonably kept.
The calling application may pass additional curl_waitfd structures which are
similar to \fIpoll(2)\fP's \fIpollfd\fP structure to be waited on in the same
call.
On completion, if \fInumfds\fP is non-NULL, it will be populated with the
total number of file descriptors on which interesting events occurred. This
number can include both libcurl internal descriptors as well as descriptors
provided in \fIextra_fds\fP.
The \fIcurl_multi_wakeup(3)\fP function can be used from another thread to
wake up this function and return faster. This is one of the details
that makes this function different than \fIcurl_multi_wait(3)\fP which cannot
be woken up this way.
If no extra file descriptors are provided and libcurl has no file descriptor
to offer to wait for, this function will instead wait during \fItimeout_ms\fP
milliseconds (or shorter if an internal timer indicates so). This is the
other detail that makes this function different than
\fIcurl_multi_wait(3)\fP.
This function is encouraged to be used instead of select(3) when using the
multi interface to allow applications to easier circumvent the common problem
with 1024 maximum file descriptors.
.SH curl_waitfd
.nf
struct curl_waitfd {
curl_socket_t fd;
short events;
short revents;
};
.fi
.IP CURL_WAIT_POLLIN
Bit flag to curl_waitfd.events indicating the socket should poll on read
events such as new data received.
.IP CURL_WAIT_POLLPRI
Bit flag to curl_waitfd.events indicating the socket should poll on high
priority read events such as out of band data.
.IP CURL_WAIT_POLLOUT
Bit flag to curl_waitfd.events indicating the socket should poll on write
events such as the socket being clear to write without blocking.
.SH EXAMPLE
.nf
CURL *easy_handle;
CURLM *multi_handle;
/* add the individual easy handle */
curl_multi_add_handle(multi_handle, easy_handle);
do {
CURLMcode mc;
int numfds;
mc = curl_multi_perform(multi_handle, &still_running);
if(mc == CURLM_OK) {
/* wait for activity or timeout */
mc = curl_multi_poll(multi_handle, NULL, 0, 1000, &numfds);
}
if(mc != CURLM_OK) {
fprintf(stderr, "curl_multi failed, code %d.\\n", mc);
break;
}
} while(still_running);
curl_multi_remove_handle(multi_handle, easy_handle);
.fi
.SH AVAILABILITY
Added in 7.66.0.
.SH RETURN VALUE
CURLMcode type, general libcurl multi interface error code. See
\fIlibcurl-errors(3)\fP
.SH "SEE ALSO"
.BR curl_multi_fdset "(3), " curl_multi_perform "(3), "
.BR curl_multi_wait "(3), " curl_multi_wakeup "(3)"
share/man/man3/curl_multi_strerror.3 0000644 00000003612 14751150677 0013503 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_multi_strerror 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_multi_strerror - return string describing error code
.SH SYNOPSIS
.nf
.B #include <curl/curl.h>
.BI "const char *curl_multi_strerror(CURLMcode " errornum ");"
.SH DESCRIPTION
The curl_multi_strerror() function returns a string describing the
\fICURLMcode\fP 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
A pointer to a null-terminated string.
.SH "SEE ALSO"
.BR libcurl-errors "(3), " curl_easy_strerror "(3), "
.BR curl_share_strerror "(3), " curl_url_strerror "(3)"
share/man/man3/CURLINFO_LOCAL_IP.3 0000644 00000005064 14751150677 0012110 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_LOCAL_IP 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_LOCAL_IP \- get local IP address of last connection
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_LOCAL_IP, char **ip);
.fi
.SH DESCRIPTION
Pass a pointer to a char pointer to receive the pointer to a null-terminated
string holding the IP address of the local end of most recent connection done
with this \fBcurl\fP handle. This string may be IPv6 when that is
enabled. Note that you get a pointer to a memory area that will be re-used at
next request so you need to copy the string if you want to keep the
information.
The \fBip\fP pointer will be NULL or pointing to private memory you MUST NOT
free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the
corresponding CURL handle.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
{
char *ip;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* Perform the request, res will get the return code */
res = curl_easy_perform(curl);
/* Check for errors */
if((res == CURLE_OK) &&
!curl_easy_getinfo(curl, CURLINFO_LOCAL_IP, &ip) && ip) {
printf("Local IP: %s\\n", ip);
}
/* always cleanup */
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.21.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
.BR CURLINFO_PRIMARY_IP "(3), "
share/man/man3/CURLINFO_FTP_ENTRY_PATH.3 0000644 00000004673 14751150677 0013121 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_FTP_ENTRY_PATH 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_FTP_ENTRY_PATH \- get entry path in FTP server
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_FTP_ENTRY_PATH, char **path);
.fi
.SH DESCRIPTION
Pass a pointer to a char pointer to receive a pointer to a string holding the
path of the entry path. That is the initial path libcurl ended up in when
logging on to the remote FTP server. This stores a NULL as pointer if
something is wrong.
The \fBpath\fP pointer will be NULL or pointing to private memory you MUST NOT
free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the
corresponding CURL handle.
.SH PROTOCOLS
FTP(S) and SFTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com");
res = curl_easy_perform(curl);
if(!res) {
/* extract the entry path */
char *ep = NULL;
res = curl_easy_getinfo(curl, CURLINFO_FTP_ENTRY_PATH, &ep);
if(!res && ep) {
printf("Entry path was: %s\\n", ep);
}
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.15.4. Works for SFTP since 7.21.4
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
share/man/man3/CURLOPT_TLS13_CIPHERS.3 0000644 00000005516 14751150677 0012562 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_TLS13_CIPHERS 3 "September 22, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_TLS13_CIPHERS \- ciphers suites to use for TLS 1.3
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TLS13_CIPHERS, char *list);
.fi
.SH DESCRIPTION
Pass a char *, pointing to a null-terminated string holding the list of cipher
suites to use for the TLS 1.3 connection. The list must be syntactically
correct, it consists of one or more cipher suite strings separated by colons.
you will find more details about cipher lists on this URL:
https://curl.se/docs/ssl-ciphers.html
This option is currently used only when curl is built to use OpenSSL 1.1.1 or
later or Schannel. If you are using a different SSL backend you can try
setting TLS 1.3 cipher suites by using the \fICURLOPT_SSL_CIPHER_LIST(3)\fP
option.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL, use internal default
.SH PROTOCOLS
All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_TLS13_CIPHERS,
"TLS_CHACHA20_POLY1305_SHA256");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.61.0 for OpenSSL. Available when built with OpenSSL >= 1.1.1.
Added in 7.85.0 for Schannel.
.SH RETURN VALUE
Returns CURLE_OK if supported, CURLE_NOT_BUILT_IN otherwise.
.SH "SEE ALSO"
.BR CURLOPT_SSL_CIPHER_LIST "(3), " CURLOPT_SSLVERSION "(3), "
.BR CURLOPT_PROXY_SSL_CIPHER_LIST "(3), " CURLOPT_PROXY_TLS13_CIPHERS "(3), "
.BR CURLOPT_PROXY_SSLVERSION "(3), " CURLOPT_USE_SSL "(3), "
share/man/man3/CURLINFO_PROXYAUTH_AVAIL.3 0000644 00000005271 14751150677 0013205 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_PROXYAUTH_AVAIL 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_PROXYAUTH_AVAIL \- get available HTTP proxy authentication methods
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PROXYAUTH_AVAIL,
long *authp);
.fi
.SH DESCRIPTION
Pass a pointer to a long to receive a bitmask indicating the authentication
method(s) available according to the previous response. The meaning of the
bits is explained in the \fICURLOPT_PROXYAUTH(3)\fP option for
\fIcurl_easy_setopt(3)\fP.
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_PROXY, "http://127.0.0.1:80");
res = curl_easy_perform(curl);
if(!res) {
/* extract the available proxy authentication types */
long auth;
res = curl_easy_getinfo(curl, CURLINFO_PROXYAUTH_AVAIL, &auth);
if(!res) {
if(!auth)
printf("No proxy auth available, perhaps no 407?\\n");
else {
printf("%s%s%s%s\\n",
auth & CURLAUTH_BASIC ? "Basic ":"",
auth & CURLAUTH_DIGEST ? "Digest ":"",
auth & CURLAUTH_NEGOTIATE ? "Negotiate ":"",
auth % CURLAUTH_NTLM ? "NTLM ":"");
}
}
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added RFC2617 in 7.10.8
Added RFC7616 in 7.57.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
share/man/man3/curl_multi_socket.3 0000644 00000010137 14751150677 0013111 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_multi_socket 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_multi_socket \- reads/writes available data
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_socket(CURLM *multi_handle, curl_socket_t sockfd,
int *running_handles);
CURLMcode curl_multi_socket_all(CURLM *multi_handle,
int *running_handles);
.fi
.SH DESCRIPTION
These functions are deprecated. Do not use. See
\fIcurl_multi_socket_action(3)\fP instead.
At return, the integer \fBrunning_handles\fP points to will contain the number
of still running easy handles within the multi handle. When this number
reaches zero, all transfers are complete/done. Note that when you call
\fIcurl_multi_socket_action(3)\fP on a specific socket and the counter
decreases by one, it DOES NOT necessarily mean that this exact socket/transfer
is the one that completed. Use \fIcurl_multi_info_read(3)\fP to figure out
which easy handle that completed.
The \fIcurl_multi_socket_action(3)\fP functions inform the application about
updates in the socket (file descriptor) status by doing none, one, or multiple
calls to the socket callback function set with the
\fICURLMOPT_SOCKETFUNCTION(3)\fP option to \fIcurl_multi_setopt(3)\fP. They
update the status with changes since the previous time the callback was
called.
Get the timeout time by setting the \fICURLMOPT_TIMERFUNCTION(3)\fP option
with \fIcurl_multi_setopt(3)\fP. Your application will then get called with
information on how long to wait for socket actions at most before doing the
timeout action: call the \fIcurl_multi_socket_action(3)\fP function with the
\fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT. You can also use the
\fIcurl_multi_timeout(3)\fP function to poll the value at any given time, but
for an event-based system using the callback is far better than relying on
polling the timeout value.
Usage of \fIcurl_multi_socket(3)\fP is deprecated, whereas the function is
equivalent to \fIcurl_multi_socket_action(3)\fP with \fBev_bitmask\fP set to
0.
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 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), "
.BR "the hiperfifo.c example"
share/man/man3/CURLOPT_SSL_ENABLE_NPN.3 0000644 00000004226 14751150677 0012756 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SSL_ENABLE_NPN 3 "September 01, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSL_ENABLE_NPN \- use NPN
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_ENABLE_NPN, long npn);
.fi
.SH DESCRIPTION
Deprecated in 7.86.0. Setting this option has no function.
Pass a long as parameter, 0 or 1 where 1 is for enable and 0 for disable. This
option enables/disables NPN in the SSL handshake (if the SSL backend libcurl
is built to use supports it), which can be used to negotiate http2.
.SH DEFAULT
1, enabled
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_SSL_ENABLE_NPN, 1L);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.36.0. Deprecated in 7.86.0.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_SSL_ENABLE_ALPN "(3), " CURLOPT_SSL_OPTIONS "(3), "
share/man/man3/CURLSHOPT_LOCKFUNC.3 0000644 00000005370 14751150677 0012234 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH CURLSHOPT_LOCKFUNC 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
CURLSHOPT_LOCKFUNC - mutex lock callback
.SH SYNOPSIS
.nf
#include <curl/curl.h>
void lockcb(CURL *handle, curl_lock_data data, curl_lock_access access,
void *userptr);
CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_LOCKFUNC, lockcb);
.fi
.SH DESCRIPTION
Set a mutex lock callback for the share object, to allow it to get used by
multiple threads concurrently. There's a corresponding
\fICURLSHOPT_UNLOCKFUNC(3)\fP callback called when the mutex is again released.
The \fIlockcb\fP argument must be a pointer to a function matching the
prototype shown above. The arguments to the callback are:
\fIhandle\fP is the currently active easy handle in use when the share object
is intended to get used.
The \fIdata\fP argument tells what kind of data libcurl wants to lock. Make
sure that the callback uses a different lock for each kind of data.
\fIaccess\fP defines what access type libcurl wants, shared or single.
\fIuserptr\fP is the private pointer you set with \fICURLSHOPT_USERDATA\fP.
This pointer is not used by libcurl itself.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURLSHcode sh;
share = curl_share_init();
sh = curl_share_setopt(share, CURLSHOPT_LOCKFUNC, mutex_lock);
if(sh)
printf("Error: %s\\n", curl_share_strerror(sh));
.fi
.SH AVAILABILITY
Added in 7.10
.SH RETURN VALUE
CURLSHE_OK (zero) means that the option was set properly, non-zero means an
error occurred. See \fIlibcurl-errors(3)\fP for the full list with
descriptions.
.SH "SEE ALSO"
.BR CURLSHOPT_UNLOCKFUNC "(3), "
.BR curl_share_setopt "(3), " curl_share_cleanup "(3), " curl_share_init "(3)"
share/man/man3/CURLOPT_PROXYPORT.3 0000644 00000004232 14751150677 0012217 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXYPORT 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXYPORT \- port number the proxy listens on
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYPORT, long port);
.fi
.SH DESCRIPTION
Pass a long with this option to set the proxy port to connect to unless it is
specified in the proxy string \fICURLOPT_PROXY(3)\fP or uses 443 for https
proxies and 1080 for all others as default.
While this accepts a 'long', the port number is 16 bit so it cannot be larger
than 65535.
.SH DEFAULT
0, not specified which makes it use the default port
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
curl_easy_setopt(curl, CURLOPT_PROXY, "localhost");
curl_easy_setopt(curl, CURLOPT_PROXYPORT, 8080L);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_PROXY "(3), " CURLOPT_PROXYTYPE "(3), "
share/man/man3/CURLOPT_CHUNK_BGN_FUNCTION.3 0000644 00000010644 14751150677 0013440 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_CHUNK_BGN_FUNCTION 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_CHUNK_BGN_FUNCTION \- callback before a transfer with FTP wildcard match
.SH SYNOPSIS
.nf
#include <curl/curl.h>
struct curl_fileinfo {
char *filename;
curlfiletype filetype;
time_t time; /* always zero! */
unsigned int perm;
int uid;
int gid;
curl_off_t size;
long int hardlinks;
struct {
/* If some of these fields is not NULL, it is a pointer to b_data. */
char *time;
char *perm;
char *user;
char *group;
char *target; /* pointer to the target filename of a symlink */
} strings;
unsigned int flags;
/* used internally */
char *b_data;
size_t b_size;
size_t b_used;
};
long chunk_bgn_callback(const void *transfer_info, void *ptr,
int remains);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CHUNK_BGN_FUNCTION,
chunk_bgn_callback);
.SH DESCRIPTION
Pass a pointer to your callback function, which should match the prototype
shown above.
This callback function gets called by libcurl before a part of the stream is
going to be transferred (if the transfer supports chunks).
The \fItransfer_info\fP pointer will point to a \fBcurl_fileinfo\fP struct
with details about the file that is about to get transferred.
This callback makes sense only when using the \fICURLOPT_WILDCARDMATCH(3)\fP
option for now.
The target of transfer_info parameter is a "feature depended" structure. For
the FTP wildcard download, the target is \fBcurl_fileinfo\fP structure (see
\fIcurl/curl.h\fP). The parameter \fIptr\fP is a pointer given by
\fICURLOPT_CHUNK_DATA(3)\fP. The parameter remains contains number of chunks
remaining per the transfer. If the feature is not available, the parameter has
zero value.
Return \fICURL_CHUNK_BGN_FUNC_OK\fP if everything is fine,
\fICURL_CHUNK_BGN_FUNC_SKIP\fP if you want to skip the concrete chunk or
\fICURL_CHUNK_BGN_FUNC_FAIL\fP to tell libcurl to stop if some error occurred.
.SH DEFAULT
NULL
.SH PROTOCOLS
FTP
.SH EXAMPLE
.nf
static long file_is_coming(struct curl_fileinfo *finfo,
struct callback_data *data,
int remains)
{
printf("%3d %40s %10luB ", remains, finfo->filename,
(unsigned long)finfo->size);
switch(finfo->filetype) {
case CURLFILETYPE_DIRECTORY:
printf(" DIR\\n");
break;
case CURLFILETYPE_FILE:
printf("FILE ");
break;
default:
printf("OTHER\\n");
break;
}
if(finfo->filetype == CURLFILETYPE_FILE) {
/* do not transfer files >= 50B */
if(finfo->size > 50) {
printf("SKIPPED\\n");
return CURL_CHUNK_BGN_FUNC_SKIP;
}
data->output = fopen(finfo->filename, "wb");
if(!data->output) {
return CURL_CHUNK_BGN_FUNC_FAIL;
}
}
return CURL_CHUNK_BGN_FUNC_OK;
}
int main()
{
/* data for callback */
struct callback_data callback_info;
/* callback is called before download of concrete file started */
curl_easy_setopt(curl, CURLOPT_CHUNK_BGN_FUNCTION, file_is_coming);
curl_easy_setopt(curl, CURLOPT_CHUNK_DATA, &callback_info);
}
.fi
.SH AVAILABILITY
This was added in 7.21.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_CHUNK_END_FUNCTION "(3), " CURLOPT_WILDCARDMATCH "(3), "
share/man/man3/curl_easy_upkeep.3 0000644 00000005446 14751150677 0012730 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH curl_easy_upkeep 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_easy_upkeep - Perform any connection upkeep checks.
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_upkeep(CURL *handle);
.fi
.SH DESCRIPTION
Some protocols have "connection upkeep" mechanisms. These mechanisms usually
send some traffic on existing connections in order to keep them alive; this
can prevent connections from being closed due to overzealous firewalls, for
example.
Currently the only protocol with a connection upkeep mechanism is HTTP/2: when
the connection upkeep interval is exceeded and \fIcurl_easy_upkeep(3)\fP
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 EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
/* Make a connection to an HTTP/2 server. */
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* Set the interval to 30000ms / 30s */
curl_easy_setopt(curl, CURLOPT_UPKEEP_INTERVAL_MS, 30000L);
curl_easy_perform(curl);
/* Perform more work here. */
/* While the connection is being held open, curl_easy_upkeep() can be
called. If curl_easy_upkeep() is called and the time since the last
upkeep exceeds the interval, then an HTTP/2 PING is sent. */
curl_easy_upkeep(curl);
/* Perform more work here. */
/* 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), "
share/man/man3/curl_mime_filedata.3 0000644 00000006452 14751150677 0013174 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_mime_filedata 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_mime_filedata - set a mime part's body data from a file contents
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_mime_filedata(curl_mimepart *part,
const char *filename);
.fi
.SH DESCRIPTION
\fIcurl_mime_filedata(3)\fP sets a mime part's body content from the named
file's contents. This is an alternative to \fIcurl_mime_data(3)\fP for setting
data to a mime part.
\fIpart\fP is the part's to assign contents to.
\fIfilename\fP points to the null-terminated file's path name. The pointer can
be NULL to detach the previous part contents settings. Filename storage can
be safely be reused after this call.
As a side effect, the part's remote file name is set to the base name of the
given \fIfilename\fP if it is a valid named file. This can be undone or
overridden by a subsequent call to \fIcurl_mime_filename(3)\fP.
The contents of the file is read during the file transfer in a streaming
manner to allow huge files to get transferred without using much memory. It
therefore requires that the file is kept intact during the entire request.
If the file size cannot be determined before actually reading it (such as for
a device or named pipe), the whole mime structure containing the part
will be transferred as chunks by HTTP and rejected by IMAP.
Setting a part's contents multiple times is valid: only the value set by the
last call is retained.
.SH EXAMPLE
.nf
curl_mime *mime;
curl_mimepart *part;
/* create a mime handle */
mime = curl_mime_init(easy);
/* add a part */
part = curl_mime_addpart(mime);
/* send data from this file */
curl_mime_filedata(part, "image.png");
/* 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),"
.BR curl_mime_filename "(3),"
.BR curl_mime_name "(3)"
share/man/man3/CURLOPT_COOKIESESSION.3 0000644 00000004712 14751150677 0012611 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_COOKIESESSION 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_COOKIESESSION \- start a new cookie session
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIESESSION, long init);
.fi
.SH DESCRIPTION
Pass a long set to 1 to mark this as a new cookie "session". It will force
libcurl to ignore all cookies it is about to load that are "session cookies"
from the previous session. By default, libcurl always stores and loads all
cookies, independent if they are session cookies or not. Session cookies are
cookies without expiry date and they are meant to be alive and existing for
this "session" only.
A "session" is usually defined in browser land for as long as you have your
browser up, more or less.
.SH DEFAULT
0
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
/* new "session", do not load session cookies */
curl_easy_setopt(curl, CURLOPT_COOKIESESSION, 1L);
/* get the (non session) cookies from this file */
curl_easy_setopt(curl, CURLOPT_COOKIEFILE, "/tmp/cookies.txt");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Along with HTTP
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_COOKIEFILE "(3), " CURLOPT_COOKIE "(3), "
share/man/man3/curl_global_cleanup.3 0000644 00000005563 14751150677 0013365 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_global_cleanup 3 "June 15, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_global_cleanup - global libcurl cleanup
.SH SYNOPSIS
.nf
#include <curl/curl.h>
void curl_global_cleanup(void);
.fi
.SH DESCRIPTION
This function releases resources acquired by \fIcurl_global_init(3)\fP.
You should call \fIcurl_global_cleanup(3)\fP once for each call you make to
\fIcurl_global_init(3)\fP, after you are done using libcurl.
This function is thread-safe since libcurl 7.84.0 if
\fIcurl_version_info(3)\fP has the CURL_VERSION_THREADSAFE feature bit set
(most platforms).
If this is not thread-safe, you must not call this function when any other
thread in the program (i.e. a thread sharing the same memory) is running.
This does not just mean no other thread that is using libcurl. Because
\fIcurl_global_cleanup(3)\fP calls functions of other libraries that are
similarly thread unsafe, it could conflict with any other thread that uses
these other libraries.
See the description in \fIlibcurl(3)\fP of global environment requirements for
details of how to use this function.
.SH CAUTION
\fIcurl_global_cleanup(3)\fP does not block waiting for any libcurl-created
threads to terminate (such as threads used for name resolving). If a module
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"
.BR curl_global_init "(3), "
.BR libcurl "(3), "
.BR libcurl-thread "(3), "
share/man/man3/CURLOPT_XOAUTH2_BEARER.3 0000644 00000004643 14751150677 0012711 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_XOAUTH2_BEARER 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_XOAUTH2_BEARER \- OAuth 2.0 access token
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_XOAUTH2_BEARER, char *token);
.fi
.SH DESCRIPTION
Pass a char * as parameter, which should point to the null-terminated OAuth
2.0 Bearer Access Token for use with HTTP, IMAP, LDAP, POP3 and SMTP servers
that support the OAuth 2.0 Authorization Framework.
Note: For IMAP, LDAP, POP3 and SMTP, the user name used to generate the
Bearer Token should be supplied via the \fICURLOPT_USERNAME(3)\fP option.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
HTTP, IMAP, LDAP, POP3 and SMTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "pop3://example.com/");
curl_easy_setopt(curl, CURLOPT_XOAUTH2_BEARER, "1ab9cb22ba269a7");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.33.0. Support for OpenLDAP added in 7.82.0.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_MAIL_AUTH "(3), " CURLOPT_USERNAME "(3), "
share/man/man3/CURLOPT_TFTP_BLKSIZE.3 0000644 00000004403 14751150677 0012531 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_TFTP_BLKSIZE 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_TFTP_BLKSIZE \- TFTP block size
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TFTP_BLKSIZE, long blocksize);
.fi
.SH DESCRIPTION
Specify \fIblocksize\fP to use for TFTP data transmission. Valid range as per
RFC2348 is 8-65464 bytes. The default of 512 bytes will be used if this option
is not specified. The specified block size will only be used pending support
by the remote server. If the server does not return an option acknowledgment
or returns an option acknowledgment with no block size, the default of 512
bytes will be used.
.SH DEFAULT
512
.SH PROTOCOLS
TFTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "tftp://example.com/bootimage");
/* try using larger blocks */
curl_easy_setopt(curl, CURLOPT_TFTP_BLKSIZE, 2048L);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.19.4
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_MAXFILESIZE "(3), "
share/man/man3/CURLOPT_TELNETOPTIONS.3 0000644 00000004461 14751150677 0012644 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_TELNETOPTIONS 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_TELNETOPTIONS \- set of telnet options
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TELNETOPTIONS,
struct curl_slist *cmds);
.fi
.SH DESCRIPTION
Provide a pointer to a curl_slist with variables to pass to the telnet
negotiations. The variables should be in the format <option=value>. libcurl
supports the options \fBTTYPE\fP, \fBXDISPLOC\fP and \fBNEW_ENV\fP. See the
TELNET standard for details.
.SH DEFAULT
NULL
.SH PROTOCOLS
TELNET
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
struct curl_slist *options;
options = curl_slist_append(NULL, "TTTYPE=vt100");
options = curl_slist_append(options, "USER=foobar");
curl_easy_setopt(curl, CURLOPT_URL, "telnet://example.com/");
curl_easy_setopt(curl, CURLOPT_TELNETOPTIONS, options);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
curl_slist_free_all(options);
}
.fi
.SH AVAILABILITY
Along with TELNET
.SH RETURN VALUE
Returns CURLE_OK if TELNET is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_HTTPHEADER "(3), " CURLOPT_QUOTE "(3), "
share/man/man3/CURLOPT_TCP_KEEPINTVL.3 0000644 00000004527 14751150677 0012647 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_TCP_KEEPINTVL 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_TCP_KEEPINTVL \- TCP keep-alive interval
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_KEEPINTVL, long interval);
.fi
.SH DESCRIPTION
Pass a long. Sets the interval, in seconds, that the operating system will
wait between sending keepalive probes. Not all operating systems support this
option. (Added in 7.25.0)
The maximum value this accepts is 2147483648. Any larger value will be capped
to this amount.
.SH DEFAULT
60
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* enable TCP keep-alive for this transfer */
curl_easy_setopt(curl, CURLOPT_TCP_KEEPALIVE, 1L);
/* set keep-alive idle time to 120 seconds */
curl_easy_setopt(curl, CURLOPT_TCP_KEEPIDLE, 120L);
/* interval time between keep-alive probes: 60 seconds */
curl_easy_setopt(curl, CURLOPT_TCP_KEEPINTVL, 60L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_TCP_KEEPALIVE "(3), " CURLOPT_TCP_KEEPIDLE "(3), "
share/man/man3/CURLINFO_REDIRECT_URL.3 0000644 00000004622 14751150677 0012610 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_REDIRECT_URL 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_REDIRECT_URL \- get the URL a redirect would go to
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_REDIRECT_URL, char **urlp);
.fi
.SH DESCRIPTION
Pass a pointer to a char pointer to receive the URL a redirect \fIwould\fP
take you to if you would enable \fICURLOPT_FOLLOWLOCATION(3)\fP. This can come
handy if you think using the built-in libcurl redirect logic is not good enough
for you but you would still prefer to avoid implementing all the magic of
figuring out the new URL.
This URL is also set if the \fICURLOPT_MAXREDIRS(3)\fP limit prevented a
redirect to happen (since 7.54.1).
.SH PROTOCOLS
HTTP(S)
.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);
if(res == CURLE_OK) {
char *url = NULL;
curl_easy_getinfo(curl, CURLINFO_REDIRECT_URL, &url);
if(url)
printf("Redirect to: %s\\n", url);
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.18.2
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
share/man/man3/CURLINFO_PRETRANSFER_TIME_T.3 0000644 00000005222 14751150677 0013556 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 2022 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_PRETRANSFER_TIME_T 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_PRETRANSFER_TIME_T \- get the time until the file transfer start
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PRETRANSFER_TIME_T,
curl_off_t *timep);
.fi
.SH DESCRIPTION
Pass a pointer to a curl_off_t to receive the time, in microseconds,
it took from the
start until the file transfer is just about to begin. This includes all
pre-transfer commands and negotiations that are specific to the particular
protocol(s) involved. It does \fInot\fP involve the sending of the protocol-
specific request that triggers a transfer.
When a redirect is followed, the time from each request is added together.
See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
curl_off_t pretransfer;
curl_easy_setopt(curl, CURLOPT_URL, url);
res = curl_easy_perform(curl);
if(CURLE_OK == res) {
res = curl_easy_getinfo(curl, CURLINFO_PRETRANSFER_TIME_T, &pretransfer);
if(CURLE_OK == res) {
printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", pretransfer / 1000000,
(long)(pretransfer % 1000000));
}
}
/* always cleanup */
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.61.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), " CURLINFO_PRETRANSFER_TIME "(3)"
share/man/man3/CURLSHOPT_USERDATA.3 0000644 00000004216 14751150677 0012236 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH CURLSHOPT_USERDATA 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
CURLSHOPT_USERDATA - pointer passed to the lock and unlock mutex callbacks
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_USERDATA, void *ptr);
.fi
.SH DESCRIPTION
The \fIptr\fP parameter is held verbatim by libcurl and is passed on as the
\fIuserptr\fP argument to the callbacks set with \fICURLSHOPT_LOCKFUNC(3)\fP
and \fICURLSHOPT_UNLOCKFUNC(3)\fP.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURLSHcode sh;
struct secrets private_stuff;
share = curl_share_init();
sh = curl_share_setopt(share, CURLSHOPT_USERDATA, &private_stuff);
if(sh)
printf("Error: %s\\n", curl_share_strerror(sh));
.fi
.SH AVAILABILITY
Added in 7.10
.SH RETURN VALUE
CURLSHE_OK (zero) means that the option was set properly, non-zero means an
error occurred. See \fIlibcurl-errors(3)\fP for the full list with
descriptions.
.SH "SEE ALSO"
.BR CURLSHOPT_LOCKFUNC "(3), "
.BR curl_share_setopt "(3), " curl_share_cleanup "(3), " curl_share_init "(3)"
share/man/man3/CURLINFO_REDIRECT_COUNT.3 0000644 00000004132 14751150677 0013032 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_REDIRECT_COUNT 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_REDIRECT_COUNT \- get the number of redirects
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_REDIRECT_COUNT,
long *countp);
.fi
.SH DESCRIPTION
Pass a pointer to a long to receive the total number of redirections that were
actually followed.
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
res = curl_easy_perform(curl);
if(res == CURLE_OK) {
long redirects;
curl_easy_getinfo(curl, CURLINFO_REDIRECT_COUNT, &redirects);
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.9.7
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
share/man/man3/curl_multi_socket_action.3 0000644 00000012611 14751150677 0014445 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_multi_socket_action 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_multi_socket_action \- reads/writes available data given an action
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_socket_action(CURLM *multi_handle,
curl_socket_t sockfd,
int ev_bitmask,
int *running_handles);
.fi
.SH DESCRIPTION
When the application has detected action on a socket handled by libcurl, it
should call \fIcurl_multi_socket_action(3)\fP with the \fBsockfd\fP argument
set to the socket with the action. When the events on a socket are known, they
can be passed as an events bitmask \fBev_bitmask\fP by first setting
\fBev_bitmask\fP to 0, and then adding using bitwise OR (|) any combination of
events to be chosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or
CURL_CSELECT_ERR. When the events on a socket are unknown, pass 0 instead, and
libcurl will test the descriptor internally. It is also permissible to pass
CURL_SOCKET_TIMEOUT to the \fBsockfd\fP parameter in order to initiate the
whole process or when a timeout occurs.
At return, \fBrunning_handles\fP points to the number of running easy handles
within the multi handle. When this number reaches zero, all transfers are
complete/done. When you call \fIcurl_multi_socket_action(3)\fP on a specific
socket and the counter decreases by one, it DOES NOT necessarily mean that
this exact socket/transfer is the one that completed. Use
\fIcurl_multi_info_read(3)\fP to figure out which easy handle that completed.
The \fIcurl_multi_socket_action(3)\fP function informs the application about
updates in the socket (file descriptor) status by doing none, one, or multiple
calls to the socket callback function set with the
\fICURLMOPT_SOCKETFUNCTION(3)\fP option to \fIcurl_multi_setopt(3)\fP. They
update the status with changes since the previous time the callback was
called.
Get the timeout time by setting the \fICURLMOPT_TIMERFUNCTION(3)\fP option
with \fIcurl_multi_setopt(3)\fP. Your application will then get called with
information on how long to wait for socket actions at most before doing the
timeout action: call the \fIcurl_multi_socket_action(3)\fP function with the
\fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT. You can also use the
\fIcurl_multi_timeout(3)\fP function to poll the value at any given time, but
for an event-based system using the callback is far better than relying on
polling the timeout value.
When this function returns error, the state of all transfers are uncertain and
they cannot be continued. \fIcurl_multi_socket_action(3)\fP should not be
called again on the same multi handle after an error has been returned, unless
first removing all the handles and adding new ones.
.SH "TYPICAL USAGE"
1. Create a multi handle
2. Set the socket callback with \fICURLMOPT_SOCKETFUNCTION(3)\fP
3. Set the timeout callback with \fICURLMOPT_TIMERFUNCTION(3)\fP, to get to
know what timeout value to use when waiting for socket activities.
4. Add easy handles with curl_multi_add_handle()
5. Provide some means to manage the sockets libcurl is using, so you can check
them for activity. This can be done through your application code, or by way
of an external library such as libevent or glib.
6. Call curl_multi_socket_action(..., CURL_SOCKET_TIMEOUT, 0, ...)
to kickstart everything. To get one or more callbacks called.
7. Wait for activity on any of libcurl's sockets, use the timeout value your
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 "SEE ALSO"
.BR curl_multi_cleanup "(3), " curl_multi_init "(3), "
.BR curl_multi_fdset "(3), " curl_multi_info_read "(3), "
.BR "the hiperfifo.c example"
share/man/man3/CURLOPT_SSL_CIPHER_LIST.3 0000644 00000007036 14751150677 0013124 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SSL_CIPHER_LIST 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSL_CIPHER_LIST \- ciphers to use for TLS
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_CIPHER_LIST, char *list);
.fi
.SH DESCRIPTION
Pass a char *, pointing to a null-terminated string holding the list of
ciphers to use for the SSL connection. The list must be syntactically correct,
it consists of one or more cipher strings separated by colons. Commas or
spaces are also acceptable separators but colons are normally used, \&!, \&-
and \&+ can be used as operators.
For OpenSSL and GnuTLS valid examples of cipher lists include \fBRC4-SHA\fP,
\fBSHA1+DES\fP, \fBTLSv1\fP and \fBDEFAULT\fP. The default list is normally
set when you compile OpenSSL.
For NSS, valid examples of cipher lists include \fBrsa_rc4_128_md5\fP,
\fBrsa_aes_128_sha\fP, etc. With NSS you do not add/remove ciphers. If one uses
this option then all known ciphers are disabled and only those passed in are
enabled.
For WolfSSL, valid examples of cipher lists include \fBECDHE-RSA-RC4-SHA\fP,
\fBAES256-SHA:AES256-SHA256\fP, etc.
For BearSSL, valid examples of cipher lists include
\fBECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256\fP, or when using IANA names
\fBTLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256:TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256\fP,
etc.
With BearSSL you do not add/remove ciphers. If one uses this option then all
known ciphers are disabled and only those passed in are enabled.
you will find more details about cipher lists on this URL:
https://curl.se/docs/ssl-ciphers.html
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL, use internal default
.SH PROTOCOLS
All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_SSL_CIPHER_LIST, "TLSv1");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.9, in 7.83.0 for BearSSL
If built TLS enabled.
.SH RETURN VALUE
Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_TLS13_CIPHERS "(3), " CURLOPT_SSLVERSION "(3), "
.BR CURLOPT_PROXY_SSL_CIPHER_LIST "(3), " CURLOPT_PROXY_TLS13_CIPHERS "(3), "
.BR CURLOPT_USE_SSL "(3), "
share/man/man3/CURLOPT_REDIR_PROTOCOLS.3 0000644 00000007050 14751150677 0013103 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_REDIR_PROTOCOLS 3 "October 12, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_REDIR_PROTOCOLS \- protocols allowed to redirect to
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_REDIR_PROTOCOLS, long bitmask);
.fi
.SH DESCRIPTION
This option is deprecated. We strongly recommend using
\fICURLOPT_REDIR_PROTOCOLS_STR(3)\fP instead because this option cannot
control all available protocols!
Pass a long that holds a bitmask of CURLPROTO_* defines. If used, this bitmask
limits what protocols libcurl may use in a transfer that it follows to in a
redirect when \fICURLOPT_FOLLOWLOCATION(3)\fP is enabled. This allows you to
limit specific transfers to only be allowed to use a subset of protocols in
redirections.
Protocols denied by \fICURLOPT_PROTOCOLS(3)\fP are not overridden by this
option.
By default libcurl will allow HTTP, HTTPS, FTP and FTPS on redirect (7.65.2).
Older versions of libcurl allowed all protocols on redirect except several
disabled for security reasons: Since 7.19.4 FILE and SCP are disabled, and
since 7.40.0 SMB and SMBS are also disabled. \fICURLPROTO_ALL\fP enables all
protocols on redirect, including those disabled for security.
These are the available protocol defines:
.nf
CURLPROTO_DICT
CURLPROTO_FILE
CURLPROTO_FTP
CURLPROTO_FTPS
CURLPROTO_GOPHER
CURLPROTO_HTTP
CURLPROTO_HTTPS
CURLPROTO_IMAP
CURLPROTO_IMAPS
CURLPROTO_LDAP
CURLPROTO_LDAPS
CURLPROTO_POP3
CURLPROTO_POP3S
CURLPROTO_RTMP
CURLPROTO_RTMPE
CURLPROTO_RTMPS
CURLPROTO_RTMPT
CURLPROTO_RTMPTE
CURLPROTO_RTMPTS
CURLPROTO_RTSP
CURLPROTO_SCP
CURLPROTO_SFTP
CURLPROTO_SMB
CURLPROTO_SMBS
CURLPROTO_SMTP
CURLPROTO_SMTPS
CURLPROTO_TELNET
CURLPROTO_TFTP
.fi
.SH DEFAULT
HTTP, HTTPS, FTP and FTPS (Added in 7.65.2).
Older versions defaulted to all protocols except FILE, SCP and since 7.40.0
SMB and SMBS.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
/* pass in the URL from an external source */
curl_easy_setopt(curl, CURLOPT_URL, argv[1]);
/* only allow redirects to HTTP and HTTPS URLs */
curl_easy_setopt(curl, CURLOPT_REDIR_PROTOCOLS,
CURLPROTO_HTTP | CURLPROTO_HTTPS);
/* Perform the request */
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.19.4, before then it would follow all protocols. Deprecated
since 7.85.0.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_PROTOCOLS "(3), "
share/man/man3/CURLOPT_DNS_LOCAL_IP6.3 0000644 00000004724 14751150677 0012613 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_DNS_LOCAL_IP6 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_DNS_LOCAL_IP6 \- IPv6 address to bind DNS resolves to
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_LOCAL_IP6, char *address);
.fi
.SH DESCRIPTION
Set the local IPv6 \fIaddress\fP that the resolver should bind to. The
argument should be of type char * and contain a single IPv6 address as a
string. Set this option to NULL to use the default setting (do not bind to a
specific IP address).
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
curl_easy_setopt(curl, CURLOPT_DNS_LOCAL_IP6, "fe80::a9ff:fe46:b619");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
This option requires that libcurl was built with a resolver backend that
supports this operation. The c-ares backend is the only such one.
Added in 7.33.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not,
CURLE_NOT_BUILT_IN if support was disabled at compile-time, or
CURLE_BAD_FUNCTION_ARGUMENT when given a bad address.
.SH "SEE ALSO"
.BR CURLOPT_DNS_INTERFACE "(3), " CURLOPT_DNS_LOCAL_IP4 "(3), "
share/man/man3/CURLOPT_HTTPHEADER.3 0000644 00000016552 14751150677 0012231 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_HTTPHEADER 3 "September 28, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_HTTPHEADER \- set of HTTP headers
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPHEADER,
struct curl_slist *headers);
.fi
.SH DESCRIPTION
Pass a pointer to a linked list of HTTP headers to pass to the server and/or
proxy in your HTTP request. The same list can be used for both host and proxy
requests!
When used within an IMAP or SMTP request to upload a MIME mail, the given
header list establishes the document-level MIME headers to prepend to the
uploaded document described by \fICURLOPT_MIMEPOST(3)\fP. This does not affect
raw mail uploads.
The linked list should be a fully valid list of \fBstruct curl_slist\fP
structs properly filled in. Use \fIcurl_slist_append(3)\fP to create the list
and \fIcurl_slist_free_all(3)\fP to clean up an entire list. If you add a
header that is otherwise generated and used by libcurl internally, your added
one will be used instead. If you add a header with no content as in 'Accept:'
(no data on the right side of the colon), the internally used header will get
disabled. With this option you can add new headers, replace internal headers
and remove internal headers. To add a header with no content (nothing to the
right side of the colon), use the form 'name;' (note the ending semicolon).
The headers included in the linked list \fBmust not\fP be CRLF-terminated,
because libcurl adds CRLF after each header item. Failure to comply with this
will result in strange bugs because the server will most likely ignore part of
the headers you specified.
The first line in an HTTP request (containing the method, usually a GET or
POST) is not a header and cannot be replaced using this option. Only the lines
following the request-line are headers. Adding this method line in this list
of headers will only cause your request to send an invalid header. Use
\fICURLOPT_CUSTOMREQUEST(3)\fP to change the method.
When this option is passed to \fIcurl_easy_setopt(3)\fP, libcurl will not copy
the entire list so you \fBmust\fP keep it around until you no longer use this
\fIhandle\fP for a transfer before you call \fIcurl_slist_free_all(3)\fP on
the list.
Pass a NULL to this option to reset back to no custom headers.
The most commonly replaced HTTP headers have "shortcuts" in the options
\fICURLOPT_COOKIE(3)\fP, \fICURLOPT_USERAGENT(3)\fP and
\fICURLOPT_REFERER(3)\fP. We recommend using those.
There's an alternative option that sets or replaces headers only for requests
that are sent with CONNECT to a proxy: \fICURLOPT_PROXYHEADER(3)\fP. Use
\fICURLOPT_HEADEROPT(3)\fP to control the behavior.
.SH SPECIFIC HTTP HEADERS
Setting some specific headers will cause libcurl to act differently.
.IP "Host:"
The specified host name will be used for cookie matching if the cookie engine
is also enabled for this transfer. If the request is done over HTTP/2 or
HTTP/3, the custom host name will instead be used in the ":authority" header
field and Host: will not be sent at all over the wire.
.IP "Transfer-Encoding: chunked"
Tells libcurl the upload is to be done using this chunked encoding instead of
providing the Content-Length: field in the request.
.SH SPECIFIC MIME HEADERS
When used to build a MIME e-mail for IMAP or SMTP, the following
document-level headers can be set to override libcurl-generated values:
.IP "Mime-Version:"
Tells the parser at the receiving site how to interpret the MIME framing.
It defaults to "1.0" and should normally not be altered.
.IP "Content-Type:"
Indicates the document's global structure type. By default, libcurl sets it
to "multipart/mixed", describing a document made of independent parts. When a
MIME mail is only composed of alternative representations of the same data
(i.e.: HTML and plain text), this header must be set to "multipart/alternative".
In all cases the value must be of the form "multipart/*" to respect the
document structure and may not include the "boundary=" parameter.
.P
Other specific headers that do not have a libcurl default value but are
strongly desired by mail delivery and user agents should also be included.
These are "From:", "To:", "Date:" and "Subject:" among others and their
presence and value is generally checked by anti-spam utilities.
.SH SECURITY CONCERNS
By default, this option makes libcurl send the given headers in all HTTP
requests done by this handle. You should therefore use this option with
caution if you for example connect to the remote site using a proxy and a
CONNECT request, you should to consider if that proxy is supposed to also get
the headers. They may be private or otherwise sensitive to leak.
Use \fICURLOPT_HEADEROPT(3)\fP to make the headers only get sent to where you
intend them to get sent.
Custom headers are sent in all requests done by the easy handles, which
implies that if you tell libcurl to follow redirects
(\fICURLOPT_FOLLOWLOCATION(3)\fP), the same set of custom headers will be sent
in the subsequent request. Redirects can of course go to other hosts and thus
those servers will get all the contents of your custom headers too.
Starting in 7.58.0, libcurl will specifically prevent "Authorization:" headers
from being sent to other hosts than the first used one, unless specifically
permitted with the \fICURLOPT_UNRESTRICTED_AUTH(3)\fP option.
Starting in 7.64.0, libcurl will specifically prevent "Cookie:" headers
from being sent to other hosts than the first used one, unless specifically
permitted with the \fICURLOPT_UNRESTRICTED_AUTH(3)\fP option.
.SH DEFAULT
NULL
.SH PROTOCOLS
HTTP, IMAP and SMTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
struct curl_slist *list = NULL;
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
list = curl_slist_append(list, "Shoesize: 10");
list = curl_slist_append(list, "Accept:");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, list);
curl_easy_perform(curl);
curl_slist_free_all(list); /* free the list */
}
.fi
.SH AVAILABILITY
As long as HTTP is enabled. Use in MIME mail added in 7.56.0.
.SH RETURN VALUE
Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_CUSTOMREQUEST "(3), " CURLOPT_HEADEROPT "(3), "
.BR CURLOPT_PROXYHEADER "(3), " CURLOPT_HEADER "(3), "
.BR CURLOPT_MIMEPOST "(3), " curl_mime_init "(3)"
share/man/man3/CURLOPT_HTTPAUTH.3 0000644 00000013650 14751150677 0012036 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_HTTPAUTH 3 "October 22, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_HTTPAUTH \- HTTP server authentication methods to try
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPAUTH, long bitmask);
.SH DESCRIPTION
Pass a long as parameter, which is set to a bitmask, to tell libcurl which
authentication method(s) you want it to use speaking to the remote server.
The available bits are listed below. If more than one bit is set, libcurl will
first query the site to see which authentication methods it supports and then
pick the best one you allow it to use. For some methods, this will induce an
extra network round-trip. Set the actual name and password with the
\fICURLOPT_USERPWD(3)\fP option or with the \fICURLOPT_USERNAME(3)\fP and the
\fICURLOPT_PASSWORD(3)\fP options.
For authentication with a proxy, see \fICURLOPT_PROXYAUTH(3)\fP.
.IP CURLAUTH_BASIC
HTTP Basic authentication. This is the default choice, and the only method
that is in wide-spread use and supported virtually everywhere. This sends
the user name and password over the network in plain text, easily captured by
others.
.IP CURLAUTH_DIGEST
HTTP Digest authentication. Digest authentication is defined in RFC2617 and
is a more secure way to do authentication over public networks than the
regular old-fashioned Basic method.
.IP CURLAUTH_DIGEST_IE
HTTP Digest authentication with an IE flavor. Digest authentication is
defined in RFC2617 and is a more secure way to do authentication over public
networks than the regular old-fashioned Basic method. The IE flavor is simply
that libcurl will use a special "quirk" that IE is known to have used before
version 7 and that some servers require the client to use.
.IP CURLAUTH_BEARER
HTTP Bearer token authentication, used primarily in OAuth 2.0 protocol.
You can set the Bearer token to use with \fICURLOPT_XOAUTH2_BEARER(3)\fP.
.IP CURLAUTH_NEGOTIATE
HTTP Negotiate (SPNEGO) authentication. Negotiate authentication is defined
in RFC 4559 and is the most secure way to perform authentication over HTTP.
You need to build libcurl with a suitable GSS-API library or SSPI on Windows
for this to work.
.IP CURLAUTH_NTLM
HTTP NTLM authentication. A proprietary protocol invented and used by
Microsoft. It uses a challenge-response and hash concept similar to Digest, to
prevent the password from being eavesdropped.
You need to build libcurl with either OpenSSL, GnuTLS or NSS support for this
option to work, or build libcurl on Windows with SSPI support.
.IP CURLAUTH_NTLM_WB
NTLM delegating to winbind helper. Authentication is performed by a separate
binary application that is executed when needed. The name of the application
is specified at compile time but is typically \fB/usr/bin/ntlm_auth\fP.
Note that libcurl will fork when necessary to run the winbind application and
kill it when complete, calling \fBwaitpid()\fP to await its exit when done. On
POSIX operating systems, killing the process will cause a SIGCHLD signal to be
raised (regardless of whether \fICURLOPT_NOSIGNAL(3)\fP is set), which must be
handled intelligently by the application. In particular, the application must
not unconditionally call wait() in its SIGCHLD signal handler to avoid being
subject to a race condition. This behavior is subject to change in future
versions of libcurl.
.IP CURLAUTH_ANY
This is a convenience macro that sets all bits and thus makes libcurl pick any
it finds suitable. libcurl will automatically select the one it finds most
secure.
.IP CURLAUTH_ANYSAFE
This is a convenience macro that sets all bits except Basic and thus makes
libcurl pick any it finds suitable. libcurl will automatically select the one
it finds most secure.
.IP CURLAUTH_ONLY
This is a meta symbol. OR this value together with a single specific auth
value to force libcurl to probe for unrestricted auth and if not, only that
single auth algorithm is acceptable.
.IP CURLAUTH_AWS_SIGV4
provides AWS V4 signature authentication on HTTPS header
see \fICURLOPT_AWS_SIGV4(3)\fP.
.SH DEFAULT
CURLAUTH_BASIC
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode ret;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
/* allow whatever auth the server speaks */
curl_easy_setopt(curl, CURLOPT_HTTPAUTH, (long)CURLAUTH_ANY);
curl_easy_setopt(curl, CURLOPT_USERPWD, "james:bond");
ret = curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Option Added in 7.10.6.
CURLAUTH_DIGEST_IE was added in 7.19.3
CURLAUTH_ONLY was added in 7.21.3
CURLAUTH_NTLM_WB was added in 7.22.0
CURLAUTH_BEARER was added in 7.61.0
CURLAUTH_AWS_SIGV4 was added in 7.74.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_NOT_BUILT_IN if the bitmask specified no supported authentication
methods.
.SH "SEE ALSO"
.BR CURLOPT_PROXYAUTH "(3), " CURLOPT_USERPWD "(3), "
share/man/man3/CURLINFO_PRETRANSFER_TIME.3 0000644 00000005063 14751150677 0013276 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_PRETRANSFER_TIME 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_PRETRANSFER_TIME \- get the time until the file transfer start
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PRETRANSFER_TIME,
double *timep);
.fi
.SH DESCRIPTION
Pass a pointer to a double to receive the time, in seconds, it took from the
start until the file transfer is just about to begin.
This time-stamp includes all pre-transfer commands and negotiations that are
specific to the particular protocol(s) involved. It includes the sending of
the protocol- specific protocol instructions that triggers a transfer.
When a redirect is followed, the time from each request is added together.
See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
double pretransfer;
curl_easy_setopt(curl, CURLOPT_URL, url);
res = curl_easy_perform(curl);
if(CURLE_OK == res) {
res = curl_easy_getinfo(curl, CURLINFO_PRETRANSFER_TIME, &pretransfer);
if(CURLE_OK == res) {
printf("Time: %.1f", pretransfer);
}
}
/* always cleanup */
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.4.1
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), " CURLINFO_PRETRANSFER_TIME_T "(3)"
share/man/man3/CURLINFO_OS_ERRNO.3 0000644 00000004252 14751150677 0012152 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_OS_ERRNO 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_OS_ERRNO \- get errno number from last connect failure
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_OS_ERRNO, long *errnop);
.fi
.SH DESCRIPTION
Pass a pointer to a long to receive the errno variable from a connect failure.
Note that the value is only set on failure, it is not reset upon a successful
operation. The number is OS and system specific.
.SH PROTOCOLS
All
.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);
if(res != CURLE_OK) {
long error;
res = curl_easy_getinfo(curl, CURLINFO_OS_ERRNO, &error);
if(res && error) {
printf("Errno: %ld\\n", error);
}
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.12.2
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
share/man/man3/CURLOPT_STREAM_WEIGHT.3 0000644 00000006112 14751150677 0012632 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_STREAM_WEIGHT 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_STREAM_WEIGHT \- numerical stream weight
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_STREAM_WEIGHT, long weight);
.fi
.SH DESCRIPTION
Set the long \fIweight\fP to a number between 1 and 256.
When using HTTP/2, this option sets the individual weight for this particular
stream used by the easy \fIhandle\fP. Setting and using weights only makes
sense and is only usable when doing multiple streams over the same
connections, which thus implies that you use \fICURLMOPT_PIPELINING(3)\fP.
This option can be set during transfer and will then cause the updated weight
info get sent to the server the next time an HTTP/2 frame is sent to the
server.
See section 5.3 of RFC 7540 for protocol details.
Streams with the same parent should be allocated resources proportionally
based on their weight. So if you have two streams going, stream A with weight
16 and stream B with weight 32, stream B will get two thirds (32/48) of the
available bandwidth (assuming the server can send off the data equally for
both streams).
.SH DEFAULT
If nothing is set, the HTTP/2 protocol itself will use its own default which
is 16.
.SH PROTOCOLS
HTTP/2
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
CURL *curl2 = curl_easy_init(); /* a second handle */
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/one");
curl_easy_setopt(curl, CURLOPT_STREAM_WEIGHT, 10L);
/* the second has twice the weight */
curl_easy_setopt(curl2, CURLOPT_URL, "https://example.com/two");
curl_easy_setopt(curl2, CURLOPT_STREAM_WEIGHT, 20L);
/* then add both to a multi handle and transfer them! */
}
.fi
.SH AVAILABILITY
Added in 7.46.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_STREAM_DEPENDS "(3), " CURLOPT_STREAM_DEPENDS_E "(3), "
.BR CURLOPT_PIPEWAIT "(3), " CURLMOPT_PIPELINING "(3), "
share/man/man3/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.3 0000644 00000004455 14751150677 0014570 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 \- SHA256 hash of SSH server public key
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256,
char *sha256);
.SH DESCRIPTION
Pass a char * pointing to a string containing a Base64-encoded SHA256
hash of the remote host's public key.
The transfer will fail if the given hash does not match the hash the
remote host provides.
.SH DEFAULT
NULL
.SH PROTOCOLS
SCP and SFTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file");
curl_easy_setopt(curl, CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256,
"NDVkMTQxMGQ1ODdmMjQ3MjczYjAyOTY5MmRkMjVmNDQ=");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.80.0
Requires the libssh2 backend.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_SSH_PUBLIC_KEYFILE "(3), " CURLOPT_SSH_AUTH_TYPES "(3), "
share/man/man3/CURLOPT_FORBID_REUSE.3 0000644 00000004454 14751150677 0012507 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_FORBID_REUSE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_FORBID_REUSE \- make connection get closed at once after use
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FORBID_REUSE, long close);
.fi
.SH DESCRIPTION
Pass a long. Set \fIclose\fP to 1 to make libcurl explicitly close the
connection when done with the transfer. Normally, libcurl keeps all
connections alive when done with one transfer in case a succeeding one follows
that can re-use them. This option should be used with caution and only if you
understand what it does as it can seriously impact performance.
Set to 0 to have libcurl keep the connection open for possible later re-use
(default behavior).
.SH DEFAULT
0
.SH PROTOCOLS
Most
.SH EXAMPLE
.nf
{
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_FORBID_REUSE, 1L);
curl_easy_perform(curl);
/* this second transfer may not reuse the same connection */
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_FRESH_CONNECT "(3), " CURLOPT_MAXCONNECTS "(3), "
.BR CURLOPT_MAXLIFETIME_CONN "(3), "
share/man/man3/CURLOPT_ACCEPTTIMEOUT_MS.3 0000644 00000004111 14751150677 0013172 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_ACCEPTTIMEOUT_MS 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_ACCEPTTIMEOUT_MS \- timeout waiting for FTP server to connect back
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ACCEPTTIMEOUT_MS, long ms);
.fi
.SH DESCRIPTION
Pass a long telling libcurl the maximum number of milliseconds to wait for a
server to connect back to libcurl when an active FTP connection is used.
.SH DEFAULT
60000 milliseconds
.SH PROTOCOLS
FTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/path/file");
/* wait no more than 5 seconds for FTP server responses */
curl_easy_setopt(curl, CURLOPT_ACCEPTTIMEOUT_MS, 5000L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.24.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_STDERR "(3), " CURLOPT_DEBUGFUNCTION "(3), "
share/man/man3/CURLOPT_UPLOAD.3 0000644 00000005743 14751150677 0011565 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_UPLOAD 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_UPLOAD \- data upload
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UPLOAD, long upload);
.fi
.SH DESCRIPTION
The long parameter \fIupload\fP set to 1 tells the library to prepare for and
perform an upload. The \fICURLOPT_READDATA(3)\fP and
\fICURLOPT_INFILESIZE(3)\fP or \fICURLOPT_INFILESIZE_LARGE(3)\fP options are
also interesting for uploads. If the protocol is HTTP, uploading means using
the PUT request unless you tell libcurl otherwise.
Using PUT with HTTP 1.1 implies the use of a "Expect: 100-continue" header.
You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP as usual.
If you use PUT to an HTTP 1.1 server, you can upload data without knowing the
size before starting the transfer if you use chunked encoding. You enable this
by adding a header like "Transfer-Encoding: chunked" with
\fICURLOPT_HTTPHEADER(3)\fP. With HTTP 1.0 or without chunked transfer, you
must specify the size.
.SH DEFAULT
0, default is download
.SH PROTOCOLS
Most
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
/* we want to use our own read function */
curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_callback);
/* enable uploading */
curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L);
/* specify target */
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/to/newfile");
/* now specify which pointer to pass to our callback */
curl_easy_setopt(curl, CURLOPT_READDATA, hd_src);
/* Set the size of the file to upload */
curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, (curl_off_t)fsize);
/* Now run off and do what you have been told! */
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_PUT "(3), " CURLOPT_READFUNCTION "(3), "
.BR CURLOPT_INFILESIZE_LARGE "(3), "
share/man/man3/CURLINFO_PRIMARY_IP.3 0000644 00000005122 14751150677 0012374 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_PRIMARY_IP 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_PRIMARY_IP \- get IP address of last connection
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PRIMARY_IP, char **ip);
.fi
.SH DESCRIPTION
Pass a pointer to a char pointer to receive the pointer to a null-terminated
string holding the IP address of the most recent connection done with this
\fBcurl\fP handle. This string may be IPv6 when that is enabled. Note that you
get a pointer to a memory area that will be re-used at next request so you
need to copy the string if you want to keep the information.
The \fBip\fP pointer will be NULL or pointing to private memory you MUST NOT
free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the
corresponding CURL handle.
.SH PROTOCOLS
All network based ones
.SH EXAMPLE
.nf
{
char *ip;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* Perform the request, res will get the return code */
res = curl_easy_perform(curl);
/* Check for errors */
if((res == CURLE_OK) &&
!curl_easy_getinfo(curl, CURLINFO_PRIMARY_IP, &ip) && ip) {
printf("IP: %s\\n", ip);
}
/* always cleanup */
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.19.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
.BR CURLINFO_PRIMARY_PORT "(3), " CURLINFO_LOCAL_IP "(3), "
share/man/man3/curl_easy_send.3 0000644 00000007416 14751150677 0012367 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH curl_easy_send 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_easy_send - sends raw data over an "easy" connection
.SH SYNOPSIS
.nf
#include <curl/easy.h>
CURLcode curl_easy_send(CURL *curl, const void *buffer,
size_t buflen, size_t *n);
.fi
.SH DESCRIPTION
This function sends arbitrary data over the established connection. You may
use it together with \fIcurl_easy_recv(3)\fP to implement custom protocols
using libcurl. This functionality can be particularly useful if you use
proxies and/or SSL encryption: libcurl will take care of proxy negotiation and
connection setup.
\fBbuffer\fP is a pointer to the data of length \fBbuflen\fP that you want sent.
The variable \fBn\fP points to will receive the number of sent bytes.
To establish the connection, set \fICURLOPT_CONNECT_ONLY(3)\fP option before
calling \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP. Note that
\fIcurl_easy_send(3)\fP will not work on connections that were created without
this option.
The call will return \fBCURLE_AGAIN\fP if it's not possible to send data right
now - the socket is used in non-blocking mode internally. When
\fBCURLE_AGAIN\fP is returned, use your operating system facilities like
\fIselect(2)\fP to wait until the socket is writable. The socket may be
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 will 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
On success, returns \fBCURLE_OK\fP and stores the number of bytes actually
sent into \fB*n\fP. Note that this may be less than the amount you wanted to
send.
On failure, returns the appropriate error code.
This function may return \fBCURLE_AGAIN\fP. In this case, use your operating
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 "SEE ALSO"
.BR curl_easy_setopt "(3), " curl_easy_perform "(3), " curl_easy_getinfo "(3), "
.BR curl_easy_recv "(3) "
share/man/man3/CURLOPT_HTTP_VERSION.3 0000644 00000007777 14751150677 0012576 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_HTTP_VERSION 3 "October 22, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_HTTP_VERSION \- HTTP protocol version to use
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP_VERSION, long version);
.fi
.SH DESCRIPTION
Pass \fIversion\fP a long, set to one of the values described below. They ask
libcurl to use the specific HTTP versions.
Note that the HTTP version is just a request. libcurl will still prioritize to
re-use an existing connection so it might then re-use a connection using a
HTTP version you have not asked for.
.IP CURL_HTTP_VERSION_NONE
We do not care about what version the library uses. libcurl will use whatever
it thinks fit.
.IP CURL_HTTP_VERSION_1_0
Enforce HTTP 1.0 requests.
.IP CURL_HTTP_VERSION_1_1
Enforce HTTP 1.1 requests.
.IP CURL_HTTP_VERSION_2_0
Attempt HTTP 2 requests. libcurl will fall back to HTTP 1.1 if HTTP 2 cannot be
negotiated with the server. (Added in 7.33.0)
When libcurl uses HTTP/2 over HTTPS, it does not itself insist on TLS 1.2 or
higher even though that is required by the specification. A user can add this
version requirement with \fICURLOPT_SSLVERSION(3)\fP.
The alias \fICURL_HTTP_VERSION_2\fP was added in 7.43.0 to better reflect the
actual protocol name.
.IP CURL_HTTP_VERSION_2TLS
Attempt HTTP 2 over TLS (HTTPS) only. libcurl will fall back to HTTP 1.1 if
HTTP 2 cannot be negotiated with the HTTPS server. For clear text HTTP servers,
libcurl will use 1.1. (Added in 7.47.0)
.IP CURL_HTTP_VERSION_2_PRIOR_KNOWLEDGE
Issue non-TLS HTTP requests using HTTP/2 without HTTP/1.1 Upgrade. It requires
prior knowledge that the server supports HTTP/2 straight away. HTTPS requests
will still do HTTP/2 the standard way with negotiated protocol version in the
TLS handshake. (Added in 7.49.0)
.IP CURL_HTTP_VERSION_3
(Added in 7.66.0) Setting this value will make libcurl attempt to use HTTP/3
directly to server given in the URL. Note that this cannot gracefully
downgrade to earlier HTTP version if the server does not support HTTP/3.
For more reliably upgrading to HTTP/3, set the preferred version to something
lower and let the server announce its HTTP/3 support via Alt-Svc:. See
\fICURLOPT_ALTSVC(3)\fP.
.SH DEFAULT
Since curl 7.62.0: CURL_HTTP_VERSION_2TLS
Before that: CURL_HTTP_VERSION_1_1
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode ret;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_HTTP_VERSION,
(long)CURL_HTTP_VERSION_2TLS);
ret = curl_easy_perform(curl);
if(ret == CURLE_HTTP_RETURNED_ERROR) {
/* an HTTP response error problem */
}
}
.fi
.SH AVAILABILITY
Along with HTTP
.SH RETURN VALUE
Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_SSLVERSION "(3), " CURLOPT_HTTP200ALIASES "(3), "
.BR CURLOPT_HTTP09_ALLOWED "(3), " CURLOPT_ALTSVC "(3) "
share/man/man3/CURLOPT_AWS_SIGV4.3 0000644 00000007507 14751150677 0012147 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.haxx.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_AWS_SIGV4 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_AWS_SIGV4 \- V4 signature
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_AWS_SIGV4, char *param);
.fi
.SH DESCRIPTION
Provides AWS V4 signature authentication on HTTP(S) header.
.PP
Pass a char * that is the collection of specific arguments are used for
creating outgoing authentication headers. The format of the \fIparam\fP
option is:
.IP provider1[:provider2[:region[:service]]]
.IP provider1,\ provider2
The providers arguments are used for generating some authentication parameters
such as "Algorithm", "date", "request type" and "signed headers".
.IP region
The argument is a geographic area of a resources collection.
It is extracted from the host name specified in the URL if omitted.
.IP service
The argument is a function provided by a cloud.
It is extracted from the host name specified in the URL if omitted.
.PP
NOTE: This call set \fICURLOPT_HTTPAUTH(3)\fP to CURLAUTH_AWS_SIGV4.
Calling \fICURLOPT_HTTPAUTH(3)\fP with CURLAUTH_AWS_SIGV4 is the same
as calling this with \fB"aws:amz"\fP in parameter.
.PP
Example with "Test:Try", when curl will do the algorithm, it will generate
\fB"TEST-HMAC-SHA256"\đP for "Algorithm", \fB"x-try-date"\fP and
\fB"X-Try-Date"\fP for "date", \fB"test4_request"\fP for "request type",
\fB"SignedHeaders=content-type;host;x-try-date"\fP for "signed headers"
.PP
If you use just "test", instead of "test:try",
test will be use for every strings generated
.SH DEFAULT
By default, the value of this parameter is NULL.
Calling \fICURLOPT_HTTPAUTH(3)\fP with CURLAUTH_AWS_SIGV4 is the same
as calling this with \fB"aws:amz"\fP in parameter.
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
struct curl_slist *list = NULL;
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL,
"https://service.region.example.com/uri");
curl_easy_setopt(c, CURLOPT_AWS_SIGV4, "provider1:provider2");
/* service and region also could be set in CURLOPT_AWS_SIGV4 */
/*
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/uri");
curl_easy_setopt(c, CURLOPT_AWS_SIGV4,
"provider1:provider2:region:service");
*/
curl_easy_setopt(c, CURLOPT_USERPWD, "MY_ACCESS_KEY:MY_SECRET_KEY");
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.75.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH NOTES
This option overrides the other auth types you might have set in
\fICURLOPT_HTTPAUTH(3)\fP which should be highlighted as this makes this auth
method special. This method cannot be combined with other auth types.
.SH "SEE ALSO"
.BR CURLOPT_HEADEROPT "(3), " CURLOPT_HTTPHEADER "(3), "
share/man/man3/CURLMOPT_MAX_CONCURRENT_STREAMS.3 0000644 00000004254 14751150677 0014277 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLMOPT_MAX_CONCURRENT_STREAMS 3 "September 20, 2022" "libcurl 7.86.0" "curl_multi_setopt options"
.SH NAME
CURLMOPT_MAX_CONCURRENT_STREAMS \- max concurrent streams for http2
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_CONCURRENT_STREAMS,
long max);
.fi
.SH DESCRIPTION
Pass a long indicating the \fBmax\fP. The set number will be used as the
maximum number of concurrent streams for a connections that libcurl should
support on connections done using HTTP/2.
Valid values range from 1 to 2147483647 (2^31 - 1) and defaults to 100. The
value passed here would be honored based on other system resources properties.
.SH DEFAULT
100
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURLM *m = curl_multi_init();
/* max concurrent streams 200 */
curl_multi_setopt(m, CURLMOPT_MAX_CONCURRENT_STREAMS, 200L);
.fi
.SH AVAILABILITY
Added in 7.67.0
.SH RETURN VALUE
Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_MAXCONNECTS "(3), " CURLMOPT_MAXCONNECTS "(3), "
share/man/man3/CURLINFO_REFERER.3 0000644 00000004424 14751150677 0011757 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_REFERER 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_REFERER \- get the referrer header
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_REFERER, char **hdrp);
.fi
.SH DESCRIPTION
Pass in a pointer to a char pointer and get the referrer header.
The \fBhdrp\fP pointer will be NULL or pointing to private memory you MUST NOT
free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the
corresponding CURL handle.
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_REFERER, "https://example.org/referrer");
res = curl_easy_perform(curl);
if(res == CURLE_OK) {
char *hdr = NULL;
curl_easy_getinfo(curl, CURLINFO_REFERER, &hdr);
if(hdr)
printf("Referrer header: %s\\n", hdr);
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.76.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
.BR CURLOPT_REFERER "(3), "
share/man/man3/CURLOPT_CLOSESOCKETDATA.3 0000644 00000004314 14751150677 0013002 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_CLOSESOCKETDATA 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_CLOSESOCKETDATA \- pointer passed to the socket close callback
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CLOSESOCKETDATA,
void *pointer);
.fi
.SH DESCRIPTION
Pass a \fIpointer\fP that will be untouched by libcurl and passed as the first
argument in the closesocket callback set with
\fICURLOPT_CLOSESOCKETFUNCTION(3)\fP.
.SH DEFAULT
The default value of this parameter is NULL.
.SH PROTOCOLS
All except file:
.SH EXAMPLE
.nf
static int closesocket(void *clientp, curl_socket_t item)
{
printf("libcurl wants to close %d now\\n", (int)item);
return 0;
}
/* call this function to close sockets */
curl_easy_setopt(curl, CURLOPT_CLOSESOCKETFUNCTION, closesocket);
curl_easy_setopt(curl, CURLOPT_CLOSESOCKETDATA, &sockfd);
.fi
.SH AVAILABILITY
Added in 7.21.7
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_CLOSESOCKETFUNCTION "(3), " CURLOPT_OPENSOCKETFUNCTION "(3), "
share/man/man3/CURLINFO_SIZE_DOWNLOAD_T.3 0000644 00000004670 14751150677 0013214 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_SIZE_DOWNLOAD_T 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_SIZE_DOWNLOAD_T \- get the number of downloaded bytes
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SIZE_DOWNLOAD_T,
curl_off_t *dlp);
.fi
.SH DESCRIPTION
Pass a pointer to a \fIcurl_off_t\fP to receive the total amount of bytes that
were downloaded. The amount is only for the latest transfer and will be reset
again for each new transfer. This counts actual payload data, what's also
commonly called body. All meta and header data are excluded and will not be
counted in this number.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* Perform the request */
res = curl_easy_perform(curl);
if(!res) {
/* check the size */
curl_off_t dl;
res = curl_easy_getinfo(curl, CURLINFO_SIZE_DOWNLOAD_T, &dl);
if(!res) {
printf("Downloaded %" CURL_FORMAT_CURL_OFF_T " bytes\\n", dl);
}
}
}
.fi
.SH AVAILABILITY
Added in 7.55.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
.BR CURLINFO_SIZE_DOWNLOAD "(3), "
.BR CURLINFO_SIZE_UPLOAD_T "(3), "
share/man/man3/curl_slist_append.3 0000644 00000005176 14751150677 0013103 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_slist_append 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_slist_append - add a string to an slist
.SH SYNOPSIS
.nf
#include <curl/curl.h>
struct curl_slist *curl_slist_append(struct curl_slist *list,
const char *string);
.fi
.SH DESCRIPTION
\fIcurl_slist_append(3)\fP appends a string to a linked list of strings. The
existing \fBlist\fP should be passed as the first argument and the new list is
returned from this function. Pass in NULL in the \fBlist\fP argument to create
a new list. The specified \fBstring\fP has been appended when this function
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 EXAMPLE
.nf
CURL *handle;
struct curl_slist *slist=NULL;
struct curl_slist *temp=NULL;
slist = curl_slist_append(slist, "pragma:");
if (slist == NULL)
return -1;
temp = curl_slist_append(slist, "Accept:")
if (temp == NULL) {
curl_slist_free_all(slist);
return -1;
}
slist = temp;
curl_easy_setopt(handle, CURLOPT_HTTPHEADER, slist);
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), "
share/man/man3/CURLOPT_FNMATCH_FUNCTION.3 0000644 00000005252 14751150677 0013161 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_FNMATCH_FUNCTION 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_FNMATCH_FUNCTION \- wildcard match callback
.SH SYNOPSIS
.nf
#include <curl/curl.h>
int fnmatch_callback(void *ptr,
const char *pattern,
const char *string);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FNMATCH_FUNCTION,
fnmatch_callback);
.SH DESCRIPTION
Pass a pointer to your callback function, which should match the prototype
shown above.
This callback is used for wildcard matching.
Return \fICURL_FNMATCHFUNC_MATCH\fP if pattern matches the string,
\fICURL_FNMATCHFUNC_NOMATCH\fP if not or \fICURL_FNMATCHFUNC_FAIL\fP if an
error occurred.
.SH DEFAULT
NULL == an internal function for wildcard matching.
.SH PROTOCOLS
FTP
.SH EXAMPLE
.nf
static int my_fnmatch(void *clientp,
const char *pattern, const char *string)
{
struct local_stuff *data = (struct local_stuff *)clientp;
if(string_match(pattern, string))
return CURL_FNMATCHFUNC_MATCH;
else
return CURL_FNMATCHFUNC_NOMATCH;
}
{
struct local_stuff local_data;
curl_easy_setopt(curl, CURLOPT_URL, "ftp://ftp.example.com/file*");
curl_easy_setopt(curl, CURLOPT_WILDCARDMATCH, 1L);
curl_easy_setopt(curl, CURLOPT_FNMATCH_FUNCTION, my_fnmatch);
curl_easy_setopt(curl, CURLOPT_FNMATCH_DATA, &local_data);
}
.fi
.SH AVAILABILITY
Added in 7.21.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_FNMATCH_DATA "(3), " CURLOPT_DEBUGFUNCTION "(3), "
share/man/man3/CURLINFO_PROXY_SSL_VERIFYRESULT.3 0000644 00000004527 14751150677 0014356 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_PROXY_SSL_VERIFYRESULT 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_PROXY_SSL_VERIFYRESULT \- get the result of the proxy certificate verification
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PROXY_SSL_VERIFYRESULT,
long *result);
.fi
.SH DESCRIPTION
Pass a pointer to a long to receive the result of the certificate verification
that was requested (using the \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP
option. This is only used for HTTPS proxies.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res;
long verifyresult;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy:443");
res = curl_easy_perform(curl);
curl_easy_getinfo(curl, CURLINFO_PROXY_SSL_VERIFYRESULT, &verifyresult);
printf("The peer verification said %s\\n", verifyresult?
"fine":"BAAAD");
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.52.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
.BR CURLINFO_SSL_VERIFYRESULT "(3), "
share/man/man3/CURLOPT_PROXY.3 0000644 00000011331 14751150677 0011510 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXY 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXY \- proxy to use
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY, char *proxy);
.fi
.SH DESCRIPTION
Set the \fIproxy\fP to use for the upcoming request. The parameter should be a
char * to a null-terminated string holding the host name or dotted numerical
IP address. A numerical IPv6 address must be written within [brackets].
To specify port number in this string, append :[port] to the end of the host
name. The proxy's port number may optionally be specified with the separate
option \fICURLOPT_PROXYPORT(3)\fP. If not specified, libcurl will default to
using port 1080 for proxies.
The proxy string may be prefixed with [scheme]:// to specify which kind of
proxy is used.
.RS
.IP http://
HTTP Proxy. Default when no scheme or proxy type is specified.
.IP https://
HTTPS Proxy. (Added in 7.52.0 for OpenSSL, GnuTLS and NSS)
.IP socks4://
SOCKS4 Proxy.
.IP socks4a://
SOCKS4a Proxy. Proxy resolves URL hostname.
.IP socks5://
SOCKS5 Proxy.
.IP socks5h://
SOCKS5 Proxy. Proxy resolves URL hostname.
.RE
Without a scheme prefix, \fICURLOPT_PROXYTYPE(3)\fP can be used to specify
which kind of proxy the string identifies.
When you tell the library to use an HTTP proxy, libcurl will transparently
convert operations to HTTP even if you specify an FTP URL etc. This may have
an impact on what other features of the library you can use, such as
\fICURLOPT_QUOTE(3)\fP and similar FTP specifics that do not work unless you
tunnel through the HTTP proxy. Such tunneling is activated with
\fICURLOPT_HTTPPROXYTUNNEL(3)\fP.
Setting the proxy string to "" (an empty string) will explicitly disable the
use of a proxy, even if there is an environment variable set for it.
A proxy host string can also include protocol scheme (http://) and embedded
user + password.
Unix domain sockets are supported for socks proxies since 7.84.0. Set
localhost for the host part. e.g. socks5h://localhost/path/to/socket.sock
The application does not have to keep the string around after setting this
option.
.SH "Environment variables"
libcurl respects the proxy environment variables named \fBhttp_proxy\fP,
\fBftp_proxy\fP, \fBsftp_proxy\fP etc. If set, libcurl will use the specified
proxy for that URL scheme. So for a "FTP://" URL, the \fBftp_proxy\fP is
considered. \fBall_proxy\fP is used if no protocol specific proxy was set.
If \fBno_proxy\fP (or \fBNO_PROXY\fP) is set, it is the exact equivalent of
setting the \fICURLOPT_NOPROXY(3)\fP option.
The \fICURLOPT_PROXY(3)\fP and \fICURLOPT_NOPROXY(3)\fP options override
environment variables.
.SH DEFAULT
Default is NULL, meaning no proxy is used.
When you set a host name to use, do not assume that there's any particular
single port number used widely for proxies. Specify it!
.SH PROTOCOLS
All except file://. Note that some protocols do not work well over proxy.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/file.txt");
curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy:80");
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Since 7.14.1 the proxy environment variable names can include the protocol
scheme.
Since 7.21.7 the proxy string supports the socks protocols as "schemes".
Since 7.50.2, unsupported schemes in proxy strings cause libcurl to return
error.
.SH RETURN VALUE
Returns CURLE_OK if proxies are supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_PROXYPORT "(3), " CURLOPT_HTTPPROXYTUNNEL "(3), "
.BR CURLOPT_PROXYTYPE "(3)"
share/man/man3/CURLOPT_CONNECTTIMEOUT.3 0000644 00000004771 14751150677 0012741 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_CONNECTTIMEOUT 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_CONNECTTIMEOUT \- timeout for the connect phase
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECTTIMEOUT, long timeout);
.fi
.SH DESCRIPTION
Pass a long. It should contain the maximum time in seconds that you allow the
connection phase to the server to take. This only limits the connection
phase, it has no impact once it has connected. Set to zero to switch to the
default built-in connection timeout - 300 seconds. See also the
\fICURLOPT_TIMEOUT(3)\fP option.
In unix-like systems, this might cause signals to be used unless
\fICURLOPT_NOSIGNAL(3)\fP is set.
If both \fICURLOPT_CONNECTTIMEOUT(3)\fP and \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP
are set, the value set last will be used.
.SH DEFAULT
300
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* complete connection within 10 seconds */
curl_easy_setopt(curl, CURLOPT_CONNECTTIMEOUT, 10L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK. Returns CURLE_BAD_FUNCTION_ARGUMENT if set to a negative
value or a value that when converted to milliseconds is too large.
.SH "SEE ALSO"
.BR CURLOPT_CONNECTTIMEOUT_MS "(3), "
.BR CURLOPT_TIMEOUT "(3), " CURLOPT_LOW_SPEED_LIMIT "(3), "
share/man/man3/CURLOPT_NEW_DIRECTORY_PERMS.3 0000644 00000004445 14751150677 0013622 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_NEW_DIRECTORY_PERMS 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_NEW_DIRECTORY_PERMS \- permissions for remotely created directories
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NEW_DIRECTORY_PERMS,
long mode);
.SH DESCRIPTION
Pass a long as a parameter, containing the value of the permissions that will
be assigned to newly created directories on the remote server. The default value is
\fI0755\fP, but any valid value can be used. The only protocols that can use
this are \fIsftp://\fP, \fIscp://\fP, and \fIfile://\fP.
.SH DEFAULT
0755
.SH PROTOCOLS
SFTP, SCP and FILE
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode ret;
curl_easy_setopt(curl, CURLOPT_URL, "sftp://upload.example.com/newdir/file.zip");
curl_easy_setopt(curl, CURLOPT_FTP_CREATE_MISSING_DIRS, 1L);
curl_easy_setopt(curl, CURLOPT_NEW_DIRECTORY_PERMS, 0644L);
ret = curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.16.4
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_NEW_FILE_PERMS "(3), " CURLOPT_UPLOAD "(3), "
share/man/man3/CURLINFO_LOCAL_PORT.3 0000644 00000004322 14751150677 0012360 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_LOCAL_PORT 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_LOCAL_PORT \- get the latest local port number
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_LOCAL_PORT, long *portp);
.fi
.SH DESCRIPTION
Pass a pointer to a long to receive the local port number of the most recent
connection done with this \fBcurl\fP handle.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
{
CURL *curl;
CURLcode res;
curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
res = curl_easy_perform(curl);
if(CURLE_OK == res) {
long port;
res = curl_easy_getinfo(curl, CURLINFO_LOCAL_PORT, &port);
if(CURLE_OK == res) {
printf("We used local port: %ld\\n", port);
}
}
curl_easy_cleanup(curl);
}
return 0;
}
.fi
.SH AVAILABILITY
Added in 7.21.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
.BR CURLINFO_PRIMARY_PORT "(3), " CURLINFO_LOCAL_IP "(3), "
share/man/man3/CURLOPT_HSTSWRITEDATA.3 0000644 00000004413 14751150677 0012620 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_HSTSWRITEDATA 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_HSTSWRITEDATA \- pointer passed to the HSTS write callback
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTSWRITEDATA, void *pointer);
.fi
.SH DESCRIPTION
Data \fIpointer\fP to pass to the HSTS write function. If you use the
\fICURLOPT_HSTSWRITEFUNCTION(3)\fP option, this is the pointer you will get as
input in the fourth argument to the callback.
This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to
do that.
.SH DEFAULT
NULL
.SH PROTOCOLS
This feature is only used for HTTP(S) transfer.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
struct MyData this;
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
/* pass pointer that gets passed in to the
CURLOPT_HSTSWRITEFUNCTION callback */
curl_easy_setopt(curl, CURLOPT_HSTSWRITEDATA, &this);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.74.0
.SH RETURN VALUE
This will return CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_HSTSWRITEFUNCTION "(3), " CURLOPT_HSTSREADDATA "(3), "
.BR CURLOPT_HSTSREADFUNCTION "(3), "
share/man/man3/CURLOPT_PROXY_CAPATH.3 0000644 00000005500 14751150677 0012531 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXY_CAPATH 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXY_CAPATH \- directory holding HTTPS proxy CA certificates
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_CAPATH, char *capath);
.fi
.SH DESCRIPTION
Pass a char * to a null-terminated string naming a directory holding multiple
CA certificates to verify the HTTPS proxy with. If libcurl is built against
OpenSSL, the certificate directory must be prepared using the OpenSSL
\fBc_rehash\fP utility. This makes sense only when
\fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP is enabled (which it is by default).
The application does not have to keep the string around after setting this
option.
The default value for this can be figured out with \fICURLINFO_CAPATH(3)\fP.
.SH DEFAULT
NULL
.SH PROTOCOLS
Everything used over an HTTPS proxy
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
/* using an HTTPS proxy */
curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost:443");
curl_easy_setopt(curl, CURLOPT_PROXY_CAPATH, "/etc/cert-dir");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.52.0
This option is supported by the OpenSSL, GnuTLS, and mbedTLS (since 7.56.0)
backends. The NSS backend provides the option only for backward compatibility.
.SH RETURN VALUE
CURLE_OK if supported; or an error such as:
CURLE_NOT_BUILT_IN - Not supported by the SSL backend
CURLE_UNKNOWN_OPTION
CURLE_OUT_OF_MEMORY
.SH "SEE ALSO"
.BR CURLOPT_PROXY_CAINFO "(3), "
.BR CURLOPT_CAINFO "(3), " CURLOPT_PROXY_SSL_VERIFYHOST "(3), "
.BR CURLOPT_STDERR "(3), " CURLOPT_DEBUGFUNCTION "(3), "
share/man/man3/CURLOPT_PROXY_SSL_VERIFYPEER.3 0000644 00000007451 14751150677 0014001 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXY_SSL_VERIFYPEER 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXY_SSL_VERIFYPEER \- verify the proxy's SSL certificate
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSL_VERIFYPEER,
long verify);
.fi
.SH DESCRIPTION
Pass a long as parameter set to 1L to enable or 0L to disable.
This option tells curl to verifies the authenticity of the HTTPS proxy's
certificate. A value of 1 means curl verifies; 0 (zero) means it does not.
This is the proxy version of \fICURLOPT_SSL_VERIFYPEER(3)\fP that is used for
ordinary HTTPS servers.
When negotiating a TLS or SSL connection, the server sends a certificate
indicating its identity. Curl verifies whether the certificate is authentic,
i.e. that you can trust that the server is who the certificate says it is.
This trust is based on a chain of digital signatures, rooted in certification
authority (CA) certificates you supply. curl uses a default bundle of CA
certificates (the path for that is determined at build time) and you can
specify alternate certificates with the \fICURLOPT_PROXY_CAINFO(3)\fP option
or the \fICURLOPT_PROXY_CAPATH(3)\fP option.
When \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP is enabled, and the verification
fails to prove that the certificate is authentic, the connection fails. When
the option is zero, the peer certificate verification succeeds regardless.
Authenticating the certificate is not enough to be sure about the server. You
typically also want to ensure that the server is the server you mean to be
talking to. Use \fICURLOPT_PROXY_SSL_VERIFYHOST(3)\fP for that. The check
that the host name in the certificate is valid for the host name you are
connecting to is done independently of the
\fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP option.
WARNING: disabling verification of the certificate allows bad guys to
man-in-the-middle the communication without you knowing it. Disabling
verification makes the communication insecure. Just having encryption on a
transfer is not enough as you cannot be sure that you are communicating with
the correct end-point.
.SH DEFAULT
1
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* Set the default value: strict certificate check please */
curl_easy_setopt(curl, CURLOPT_PROXY_SSL_VERIFYPEER, 1L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.52.0
If built TLS enabled.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_PROXY_SSL_VERIFYHOST "(3), "
.BR CURLOPT_SSL_VERIFYPEER "(3), "
.BR CURLOPT_SSL_VERIFYHOST "(3), "
share/man/man3/CURLOPT_SSL_OPTIONS.3 0000644 00000010404 14751150677 0012443 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SSL_OPTIONS 3 "October 22, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSL_OPTIONS \- SSL behavior options
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_OPTIONS, long bitmask);
.fi
.SH DESCRIPTION
Pass a long with a bitmask to tell libcurl about specific SSL
behaviors. Available bits:
.IP CURLSSLOPT_ALLOW_BEAST
Tells libcurl to not attempt to use any workarounds for a security flaw in the
SSL3 and TLS1.0 protocols. If this option is not used or this bit is set to 0,
the SSL layer libcurl uses may use a work-around for this flaw although it
might cause interoperability problems with some (older) SSL
implementations. WARNING: avoiding this work-around lessens the security, and
by setting this option to 1 you ask for exactly that. This option is only
supported for Secure Transport, NSS and OpenSSL.
.IP CURLSSLOPT_NO_REVOKE
Tells libcurl to disable certificate revocation checks for those SSL backends
where such behavior is present. This option is only supported for Schannel
(the native Windows SSL library), with an exception in the case of Windows'
Untrusted Publishers block list which it seems cannot be bypassed. (Added in
7.44.0)
.IP CURLSSLOPT_NO_PARTIALCHAIN
Tells libcurl to not accept "partial" certificate chains, which it otherwise
does by default. This option is only supported for OpenSSL and will fail the
certificate verification if the chain ends with an intermediate certificate
and not with a root cert. (Added in 7.68.0)
.IP CURLSSLOPT_REVOKE_BEST_EFFORT
Tells libcurl to ignore certificate revocation checks in case of missing or
offline distribution points for those SSL backends where such behavior is
present. This option is only supported for Schannel (the native Windows SSL
library). If combined with \fICURLSSLOPT_NO_REVOKE\fP, the latter takes
precedence. (Added in 7.70.0)
.IP CURLSSLOPT_NATIVE_CA
Tell libcurl to use the operating system's native CA store for certificate
verification. Works only on Windows when built to use OpenSSL. This option is
experimental and behavior is subject to change.
(Added in 7.71.0)
.IP CURLSSLOPT_AUTO_CLIENT_CERT
Tell libcurl to automatically locate and use a client certificate for
authentication, when requested by the server. This option is only supported
for Schannel (the native Windows SSL library). Prior to 7.77.0 this was the
default behavior in libcurl with Schannel. Since the server can request any
certificate that supports client authentication in the OS certificate store it
could be a privacy violation and unexpected.
(Added in 7.77.0)
.SH DEFAULT
0
.SH PROTOCOLS
All TLS-based protocols
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
/* weaken TLS only for use with silly servers */
curl_easy_setopt(curl, CURLOPT_SSL_OPTIONS, (long)CURLSSLOPT_ALLOW_BEAST |
CURLSSLOPT_NO_REVOKE);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.25.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_SSLVERSION "(3), " CURLOPT_SSL_CIPHER_LIST "(3), "
share/man/man3/CURLOPT_ABSTRACT_UNIX_SOCKET.3 0000644 00000005126 14751150677 0013712 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_ABSTRACT_UNIX_SOCKET 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_ABSTRACT_UNIX_SOCKET \- abstract Unix domain socket
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ABSTRACT_UNIX_SOCKET,
char *path);
.fi
.SH DESCRIPTION
Enables the use of an abstract Unix domain socket instead of establishing a
TCP connection to a host. The parameter should be a char * to a
null-terminated string holding the path of the socket. The path will be set to
\fIpath\fP prefixed by a NULL byte (this is the convention for abstract
sockets, however it should be stressed that the path passed to this function
should not contain a leading NULL).
On non-supporting platforms, the abstract address will be interpreted as an
empty string and fail gracefully, generating a runtime error.
This option shares the same semantics as \fICURLOPT_UNIX_SOCKET_PATH(3)\fP in
which documentation more details can be found. Internally, these two options
share the same storage and therefore only one of them can be set per handle.
.SH DEFAULT
Default is NULL.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
curl_easy_setopt(curl_handle, CURLOPT_ABSTRACT_UNIX_SOCKET, "/tmp/foo.sock");
curl_easy_setopt(curl_handle, CURLOPT_URL, "http://localhost/");
.fi
.SH AVAILABILITY
Added in 7.53.0.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_UNIX_SOCKET_PATH "(3), " unix "(7), "
share/man/man3/CURLOPT_SSH_KEYFUNCTION.3 0000644 00000012520 14751150677 0013103 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SSH_KEYFUNCTION 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSH_KEYFUNCTION \- callback for known host matching logic
.SH SYNOPSIS
.nf
#include <curl/curl.h>
enum curl_khstat {
CURLKHSTAT_FINE_ADD_TO_FILE,
CURLKHSTAT_FINE,
CURLKHSTAT_REJECT, /* reject the connection, return an error */
CURLKHSTAT_DEFER, /* do not accept it, but we cannot answer right
now. Causes a CURLE_PEER_FAILED_VERIFICATION error but
the connection will be left intact */
CURLKHSTAT_FINE_REPLACE
};
enum curl_khmatch {
CURLKHMATCH_OK, /* match */
CURLKHMATCH_MISMATCH, /* host found, key mismatch! */
CURLKHMATCH_MISSING, /* no matching host/key found */
};
struct curl_khkey {
const char *key; /* points to a null-terminated string encoded with
base64 if len is zero, otherwise to the "raw"
data */
size_t len;
enum curl_khtype keytype;
};
int ssh_keycallback(CURL *easy,
const struct curl_khkey *knownkey,
const struct curl_khkey *foundkey,
enum curl_khmatch,
void *clientp);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_KEYFUNCTION,
ssh_keycallback);
.SH DESCRIPTION
Pass a pointer to your callback function, which should match the prototype
shown above.
It gets called when the known_host matching has been done, to allow the
application to act and decide for libcurl how to proceed. The callback will
only be called if \fICURLOPT_SSH_KNOWNHOSTS(3)\fP is also set.
This callback function gets passed the CURL handle, the key from the
known_hosts file \fIknownkey\fP, the key from the remote site \fIfoundkey\fP,
info from libcurl on the matching status and a custom pointer (set with
\fICURLOPT_SSH_KEYDATA(3)\fP). It MUST return one of the following return
codes to tell libcurl how to act:
.IP CURLKHSTAT_FINE_REPLACE
The new host+key is accepted and libcurl will replace the old host+key into
the known_hosts file before continuing with the connection. This will also
add the new host+key combo to the known_host pool kept in memory if it was not
already present there. The adding of data to the file is done by completely
replacing the file with a new copy, so the permissions of the file must allow
this. (Added in 7.73.0)
.IP CURLKHSTAT_FINE_ADD_TO_FILE
The host+key is accepted and libcurl will append it to the known_hosts file
before continuing with the connection. This will also add the host+key combo
to the known_host pool kept in memory if it was not already present there. The
adding of data to the file is done by completely replacing the file with a new
copy, so the permissions of the file must allow this.
.IP CURLKHSTAT_FINE
The host+key is accepted libcurl will continue with the connection. This will
also add the host+key combo to the known_host pool kept in memory if it was not
already present there.
.IP CURLKHSTAT_REJECT
The host+key is rejected. libcurl will deny the connection to continue and it
will be closed.
.IP CURLKHSTAT_DEFER
The host+key is rejected, but the SSH connection is asked to be kept alive.
This feature could be used when the app wants to somehow return back and act
on the host+key situation and then retry without needing the overhead of
setting it up from scratch again.
.SH DEFAULT
NULL
.SH PROTOCOLS
SFTP and SCP
.SH EXAMPLE
.nf
static int keycb(CURL *easy,
const struct curl_khkey *knownkey,
const struct curl_khkey *foundkey,
enum curl_khmatch,
void *clientp)
{
/* 'clientp' points to the callback_data struct */
/* investigate the situation and return the correct value */
return CURLKHSTAT_FINE_ADD_TO_FILE;
}
{
curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/thisfile.txt");
curl_easy_setopt(curl, CURLOPT_SSH_KEYFUNCTION, keycb);
curl_easy_setopt(curl, CURLOPT_SSH_KEYDATA, &callback_data);
curl_easy_setopt(curl, CURLOPT_SSH_KNOWNHOSTS, "/home/user/known_hosts");
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.19.6
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_SSH_KEYDATA "(3), " CURLOPT_SSH_KNOWNHOSTS "(3), "
share/man/man3/CURLOPT_RTSP_CLIENT_CSEQ.3 0000644 00000004067 14751150677 0013240 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_RTSP_CLIENT_CSEQ 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_RTSP_CLIENT_CSEQ \- RTSP client CSEQ number
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_CLIENT_CSEQ, long cseq);
.fi
.SH DESCRIPTION
Pass a long to set the CSEQ number to issue for the next RTSP
request. Useful if the application is resuming a previously broken
connection. The CSEQ will increment from this new number henceforth.
.SH DEFAULT
0
.SH PROTOCOLS
RTSP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/");
curl_easy_setopt(curl, CURLOPT_RTSP_CLIENT_CSEQ, 1234L);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.20.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_RTSP_SERVER_CSEQ "(3), " CURLOPT_RTSP_REQUEST "(3), "
share/man/man3/libcurl-easy.3 0000644 00000006062 14751150677 0011757 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH libcurl 3 "May 17, 2022" "libcurl 7.86.0" "libcurl easy interface"
.SH NAME
libcurl-easy \- easy interface overview
.SH DESCRIPTION
When using libcurl's "easy" interface you init your session and get a handle
(often referred to as an "easy handle"), which you use as input to the easy
interface functions you use. Use \fIcurl_easy_init(3)\fP to get the handle.
You continue by setting all the options you want in the upcoming transfer, the
most important among them is the URL itself (you cannot transfer anything
without a specified URL as you may have figured out yourself). You might want
to set some callbacks as well that will be called from the library when data
is available etc. \fIcurl_easy_setopt(3)\fP is used for all this.
\fICURLOPT_URL(3)\fP is the only option you really must set, as otherwise
there can be no transfer. Another commonly used option is
\fICURLOPT_VERBOSE(3)\fP that will help you see what libcurl is doing under
the hood, which is useful when debugging for example. The
\fIcurl_easy_setopt(3)\fP man page has a full index of the almost 300
available options.
If you at any point would like to blank all previously set options for a
single easy handle, you can call \fIcurl_easy_reset(3)\fP and you can also
make a clone of an easy handle (with all its set options) using
\fIcurl_easy_duphandle(3)\fP.
When all is setup, you tell libcurl to perform the transfer using
\fIcurl_easy_perform(3)\fP. It will then do the entire operation and will not
return until it is done (successfully or not).
After the transfer has been made, you can set new options and make another
transfer, or if you are done, cleanup the session by calling
\fIcurl_easy_cleanup(3)\fP. If you want persistent connections, you do not
cleanup immediately, but instead run ahead and perform other transfers using
the same easy handle.
.SH "SEE ALSO"
.BR curl_easy_init "(3)," curl_easy_cleanup "(3)," curl_easy_setopt "(3), "
.BR libcurl-errors "(3), " libcurl-multi "(3), " libcurl "(3) "
share/man/man3/CURLSHOPT_SHARE.3 0000644 00000010460 14751150677 0011666 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH CURLSHOPT_SHARE 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
CURLSHOPT_SHARE - add data to share
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_SHARE, long type);
.fi
.SH DESCRIPTION
The \fItype\fP parameter specifies what specific data that should be shared
and kept in the share object that was created with \fIcurl_share_init(3)\fP.
The given \fItype\fP must be be one of the values described below. You can set
\fICURLSHOPT_SHARE(3)\fP multiple times with different data arguments to have
the share object share multiple types of data. Unset a type again by setting
\fICURLSHOPT_UNSHARE(3)\fP.
.IP CURL_LOCK_DATA_COOKIE
Cookie data will be shared across the easy handles using this shared object.
Note that this does not activate an easy handle's cookie handling. You can do
that separately by using \fICURLOPT_COOKIEFILE(3)\fP for example.
.IP CURL_LOCK_DATA_DNS
Cached DNS hosts will be shared across the easy handles using this shared
object. Note that when you use the multi interface, all easy handles added to
the same multi handle will share DNS cache by default without using this
option.
.IP CURL_LOCK_DATA_SSL_SESSION
SSL session IDs will be shared across the easy handles using this shared
object. This will reduce the time spent in the SSL handshake when reconnecting
to the same server. Note SSL session IDs are reused within the same easy
handle by default. Note this symbol was added in 7.10.3 but was not
implemented until 7.23.0.
.IP CURL_LOCK_DATA_CONNECT
Put the connection cache in the share object and make all easy handles using
this share object share the connection cache.
Note that due to a known bug, it is not safe to share connections this way
between multiple concurrent threads.
Connections that are used for HTTP/1.1 Pipelining or HTTP/2 multiplexing only
get additional transfers added to them if the existing connection is held by
the same multi or easy handle. libcurl does not support doing HTTP/2 streams
in different threads using a shared connection.
Support for \fBCURL_LOCK_DATA_CONNECT\fP was added in 7.57.0, but the symbol
existed before this.
Note that when you use the multi interface, all easy handles added to the same
multi handle will share connection cache by default without using this option.
.IP CURL_LOCK_DATA_PSL
The Public Suffix List stored in the share object is made available to all
easy handle bound to the later. Since the Public Suffix List is periodically
refreshed, this avoids updates in too many different contexts.
Added in 7.61.0.
Note that when you use the multi interface, all easy handles added to the same
multi handle will share PSL cache by default without using this option.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURLSHcode sh;
share = curl_share_init();
sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE);
if(sh)
printf("Error: %s\\n", curl_share_strerror(sh));
.fi
.SH AVAILABILITY
Added in 7.10
.SH RETURN VALUE
CURLSHE_OK (zero) means that the option was set properly, non-zero means an
error occurred. See \fIlibcurl-errors(3)\fP for the full list with
descriptions.
.SH "SEE ALSO"
.BR CURLSHOPT_UNSHARE "(3), "
.BR curl_share_setopt "(3), " curl_share_cleanup "(3), " curl_share_init "(3)"
share/man/man3/CURLOPT_HTTP09_ALLOWED.3 0000644 00000004420 14751150677 0012667 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_HTTP09_ALLOWED 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_HTTP09_ALLOWED \- allow HTTP/0.9 response
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP09_ALLOWED, long allowed);
.fi
.SH DESCRIPTION
Pass the long argument \fIallowed\fP set to 1L to allow HTTP/0.9 responses.
An HTTP/0.9 response is a server response entirely without headers and only a
body. You can connect to lots of random TCP services and still get a response
that curl might consider to be HTTP/0.9!
.SH DEFAULT
curl allowed HTTP/0.9 responses by default before 7.66.0
Since 7.66.0, libcurl requires this option set to 1L to allow HTTP/0.9
responses.
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode ret;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_HTTP09_ALLOWED, 1L);
ret = curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Option added in 7.64.0, present along with HTTP.
.SH RETURN VALUE
Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_SSLVERSION "(3), " CURLOPT_HTTP_VERSION "(3), "
share/man/man3/CURLOPT_READDATA.3 0000644 00000005036 14751150677 0011741 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_READDATA 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_READDATA \- pointer passed to the read callback
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_READDATA, void *pointer);
.fi
.SH DESCRIPTION
Data \fIpointer\fP to pass to the file read function. If you use the
\fICURLOPT_READFUNCTION(3)\fP option, this is the pointer you will get as
input in the fourth argument to the callback.
If you do not specify a read callback but instead rely on the default internal
read function, this data must be a valid readable FILE * (cast to 'void *').
If you are using libcurl as a win32 DLL, you \fBMUST\fP use a
\fICURLOPT_READFUNCTION(3)\fP if you set this option or you will experience
crashes.
.SH DEFAULT
By default, this is a FILE * to stdin.
.SH PROTOCOLS
This is used for all protocols when sending data.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
struct MyData this;
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* pass pointer that gets passed in to the
CURLOPT_READFUNCTION callback */
curl_easy_setopt(curl, CURLOPT_READDATA, &this);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
This option was once known by the older name CURLOPT_INFILE, the name
\fICURLOPT_READDATA(3)\fP was introduced in 7.9.7.
.SH RETURN VALUE
This will return CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_READFUNCTION "(3), " CURLOPT_WRITEDATA "(3), "
share/man/man3/CURLOPT_RANDOM_FILE.3 0000644 00000004350 14751150677 0012351 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_RANDOM_FILE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_RANDOM_FILE \- file to read random data from
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RANDOM_FILE, char *path);
.fi
.SH DESCRIPTION
Deprecated option. It serves no purpose anymore.
Pass a char * to a null-terminated file name. The file might be used to read
from to seed the random engine for SSL and more.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL, not used
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_RANDOM_FILE, "junk.txt");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
If built with TLS enabled. Only the OpenSSL backend will use this, and only
with OpenSSL versions before 1.1.0.
This option was deprecated in 7.84.0.
.SH RETURN VALUE
Returns CURLE_OK on success or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_EGDSOCKET "(3), "
share/man/man3/CURLOPT_TLSAUTH_TYPE.3 0000644 00000005176 14751150677 0012566 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_TLSAUTH_TYPE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_TLSAUTH_TYPE \- TLS authentication methods
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TLSAUTH_TYPE, char *type);
.fi
.SH DESCRIPTION
Pass a pointer to a null-terminated string as parameter. The string should be
the method of the TLS authentication. Supported method is "SRP".
.IP SRP
TLS-SRP authentication. Secure Remote Password authentication for TLS is
defined in RFC5054 and provides mutual authentication if both sides have a
shared secret. To use TLS-SRP, you must also set the
\fICURLOPT_TLSAUTH_USERNAME(3)\fP and \fICURLOPT_TLSAUTH_PASSWORD(3)\fP
options.
The application does not have to keep the string around after setting this
option.
TLS SRP does not work with TLS 1.3.
.SH DEFAULT
blank
.SH PROTOCOLS
All TLS-based protocols
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_TLSAUTH_TYPE, "SRP");
curl_easy_setopt(curl, CURLOPT_TLSAUTH_USERNAME, "user");
curl_easy_setopt(curl, CURLOPT_TLSAUTH_PASSWORD, "secret");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
You need to build libcurl with GnuTLS or OpenSSL with TLS-SRP support for this
to work. Added in 7.21.4
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_TLSAUTH_USERNAME "(3), " CURLOPT_TLSAUTH_PASSWORD "(3), "
share/man/man3/CURLINFO_SPEED_DOWNLOAD.3 0000644 00000004473 14751150677 0013020 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_SPEED_DOWNLOAD 3 "October 12, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_SPEED_DOWNLOAD \- get download speed
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SPEED_DOWNLOAD,
double *speed);
.fi
.SH DESCRIPTION
Pass a pointer to a double to receive the average download speed that curl
measured for the complete download. Measured in bytes/second.
\fICURLINFO_SPEED_DOWNLOAD_T(3)\fP is a newer replacement that returns a more
sensible variable type.
.SH PROTOCOLS
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* Perform the request */
res = curl_easy_perform(curl);
if(!res) {
double speed;
res = curl_easy_getinfo(curl, CURLINFO_SPEED_DOWNLOAD, &speed);
if(!res) {
printf("Download speed %.0f bytes/sec\\n", speed);
}
}
}
.fi
.SH AVAILABILITY
Added in 7.4.1. Deprecated since 7.55.0.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
.BR CURLINFO_SPEED_UPLOAD "(3), "
.BR CURLINFO_SIZE_UPLOAD_T "(3), "
share/man/man3/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3 0000644 00000004461 14751150677 0015113 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE 3 "September 20, 2022" "libcurl 7.86.0" "curl_multi_setopt options"
.SH NAME
CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE \- size threshold for pipelining penalty
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE,
long size);
.fi
.SH DESCRIPTION
No function since pipelining was removed in 7.62.0.
Pass a long with a \fBsize\fP in bytes. If a transfer in a pipeline is
currently processing a request with a Content-Length larger than this
\fICURLMOPT_CONTENT_LENGTH_PENALTY_SIZE(3)\fP, that pipeline will then not be
considered for additional requests, even if it is shorter than
\fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP.
.SH DEFAULT
The default value is 0, which means that the size penalization is inactive.
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
.nf
CURLM *m = curl_multi_init();
long maxlength = 10000;
curl_multi_setopt(m, CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE, maxlength);
.fi
.SH AVAILABILITY
Added in 7.30.0
.SH RETURN VALUE
Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLMOPT_PIPELINING "(3), " CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE "(3), "
share/man/man3/CURLOPT_IOCTLFUNCTION.3 0000644 00000006644 14751150677 0012622 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_IOCTLFUNCTION 3 "October 12, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_IOCTLFUNCTION \- callback for I/O operations
.SH SYNOPSIS
.nf
#include <curl/curl.h>
typedef enum {
CURLIOE_OK, /* I/O operation successful */
CURLIOE_UNKNOWNCMD, /* command was unknown to callback */
CURLIOE_FAILRESTART, /* failed to restart the read */
CURLIOE_LAST /* never use */
} curlioerr;
typedef enum {
CURLIOCMD_NOP, /* no operation */
CURLIOCMD_RESTARTREAD, /* restart the read stream from start */
CURLIOCMD_LAST /* never use */
} curliocmd;
curlioerr ioctl_callback(CURL *handle, int cmd, void *clientp);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_IOCTLFUNCTION, ioctl_callback);
.SH DESCRIPTION
Pass a pointer to your callback function, which should match the prototype
shown above.
This callback function gets called by libcurl when something special
I/O-related needs to be done that the library cannot do by itself. For now,
rewinding the read data stream is the only action it can request. The
rewinding of the read data stream may be necessary when doing an HTTP PUT or
POST with a multi-pass authentication method.
The callback MUST return \fICURLIOE_UNKNOWNCMD\fP if the input \fIcmd\fP is
not \fICURLIOCMD_RESTARTREAD\fP.
The \fIclientp\fP argument to the callback is set with the
\fICURLOPT_IOCTLDATA(3)\fP option.
This option is deprecated! Do not use it. Use \fICURLOPT_SEEKFUNCTION(3)\fP
instead to provide seeking! If \fICURLOPT_SEEKFUNCTION(3)\fP is set, this
parameter will be ignored when seeking.
.SH DEFAULT
By default, this parameter is set to NULL. Not used.
.SH PROTOCOLS
Used with HTTP
.SH EXAMPLE
.nf
static curlioerr ioctl_callback(CURL *handle, int cmd, void *clientp)
{
struct data *io = (struct data *)clientp;
if(cmd == CURLIOCMD_RESTARTREAD) {
lseek(fd, 0, SEEK_SET);
current_offset = 0;
return CURLIOE_OK;
}
return CURLIOE_UNKNOWNCMD;
}
{
struct data ioctl_data;
curl_easy_setopt(curl, CURLOPT_IOCTLFUNCTION, ioctl_callback);
curl_easy_setopt(curl, CURLOPT_IOCTLDATA, &ioctl_data);
}
.fi
.SH AVAILABILITY
Added in 7.12.3. Deprecated since 7.18.0.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_IOCTLDATA "(3), " CURLOPT_SEEKFUNCTION "(3), "
share/man/man3/CURLOPT_TLSAUTH_PASSWORD.3 0000644 00000005000 14751150677 0013231 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_TLSAUTH_PASSWORD 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_TLSAUTH_PASSWORD \- password to use for TLS authentication
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TLSAUTH_PASSWORD, char *pwd);
.fi
.SH DESCRIPTION
Pass a char * as parameter, which should point to the null-terminated password
to use for the TLS authentication method specified with the
\fICURLOPT_TLSAUTH_TYPE(3)\fP option. Requires that the
\fICURLOPT_TLSAUTH_USERNAME(3)\fP option also be set.
The application does not have to keep the string around after setting this
option.
This feature relies in TLS SRP which does not work with TLS 1.3.
.SH DEFAULT
NULL
.SH PROTOCOLS
All TLS-based protocols
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_TLSAUTH_TYPE, "SRP");
curl_easy_setopt(curl, CURLOPT_TLSAUTH_USERNAME, "user");
curl_easy_setopt(curl, CURLOPT_TLSAUTH_PASSWORD, "secret");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.21.4, with the OpenSSL and GnuTLS backends only
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_TLSAUTH_TYPE "(3), " CURLOPT_TLSAUTH_USERNAME "(3), "
share/man/man3/CURLMOPT_SOCKETFUNCTION.3 0000644 00000010170 14751150677 0013042 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLMOPT_SOCKETFUNCTION 3 "May 17, 2022" "libcurl 7.86.0" "curl_multi_setopt options"
.SH NAME
CURLMOPT_SOCKETFUNCTION \- callback informed about what to wait for
.SH SYNOPSIS
.nf
#include <curl/curl.h>
int socket_callback(CURL *easy, /* easy handle */
curl_socket_t s, /* socket */
int what, /* describes the socket */
void *userp, /* private callback pointer */
void *socketp); /* private socket pointer */
CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_SOCKETFUNCTION, socket_callback);
.SH DESCRIPTION
Pass a pointer to your callback function, which should match the prototype
shown above.
When the \fIcurl_multi_socket_action(3)\fP function is called, it informs the
application about updates in the socket (file descriptor) status by doing
none, one, or multiple calls to the \fBsocket_callback\fP. The callback
function gets status updates with changes since the previous time the callback
was called. If the given callback pointer is set to NULL, no callback will be
called.
.SH "CALLBACK ARGUMENTS"
\fIeasy\fP identifies the specific transfer for which this update is related.
\fIs\fP is the specific socket this function invocation concerns. If the
\fBwhat\fP argument is not CURL_POLL_REMOVE then it holds information about
what activity on this socket the application is supposed to
monitor. Subsequent calls to this callback might update the \fBwhat\fP bits
for a socket that is already monitored.
The socket callback should return 0 on success, and -1 on error. If this
callback returns error, \fBall\fP transfers currently in progress in this
multi handle will be aborted and fail.
\fBuserp\fP is set with \fICURLMOPT_SOCKETDATA(3)\fP.
\fBsocketp\fP is set with \fIcurl_multi_assign(3)\fP or will be NULL.
The \fBwhat\fP parameter informs the callback on the status of the given
socket. It can hold one of these values:
.IP CURL_POLL_IN
Wait for incoming data. For the socket to become readable.
.IP CURL_POLL_OUT
Wait for outgoing data. For the socket to become writable.
.IP CURL_POLL_INOUT
Wait for incoming and outgoing data. For the socket to become readable or
writable.
.IP CURL_POLL_REMOVE
The specified socket/file descriptor is no longer used by libcurl.
.SH DEFAULT
NULL (no callback)
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
static int sock_cb(CURL *e, curl_socket_t s, int what, void *cbp, void *sockp)
{
GlobalInfo *g = (GlobalInfo*) cbp;
SockInfo *fdp = (SockInfo*) sockp;
if(what == CURL_POLL_REMOVE) {
remsock(fdp);
}
else {
if(!fdp) {
addsock(s, e, what, g);
}
else {
setsock(fdp, s, e, what, g);
}
}
return 0;
}
main()
{
GlobalInfo setup;
/* ... use socket callback and custom pointer */
curl_multi_setopt(multi, CURLMOPT_SOCKETFUNCTION, sock_cb);
curl_multi_setopt(multi, CURLMOPT_SOCKETDATA, &setup);
}
.fi
.SH AVAILABILITY
Added in 7.15.4
.SH RETURN VALUE
Returns CURLM_OK.
.SH "SEE ALSO"
.BR CURLMOPT_SOCKETDATA "(3), " curl_multi_socket_action "(3), "
.BR CURLMOPT_TIMERFUNCTION "(3) "
share/man/man3/CURLOPT_HTTP_TRANSFER_DECODING.3 0000644 00000004344 14751150677 0014114 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_HTTP_TRANSFER_DECODING 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_HTTP_TRANSFER_DECODING \- HTTP transfer decoding control
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP_TRANSFER_DECODING,
long enabled);
.SH DESCRIPTION
Pass a long to tell libcurl how to act on transfer decoding. If set to zero,
transfer decoding will be disabled, if set to 1 it is enabled
(default). libcurl does chunked transfer decoding by default unless this
option is set to zero.
.SH DEFAULT
1
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode ret;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_HTTP_TRANSFER_DECODING, 0L);
ret = curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.16.2 Does not work with the hyper backend (it will always have
transfer decoding enabled).
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_HTTP_CONTENT_DECODING "(3), " CURLOPT_ACCEPT_ENCODING "(3), "
share/man/man3/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.3 0000644 00000004634 14751150677 0014304 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 \- MD5 checksum of SSH server public key
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_HOST_PUBLIC_KEY_MD5,
char *md5);
.SH DESCRIPTION
Pass a char * pointing to a string containing 32 hexadecimal digits. The
string should be the 128 bit MD5 checksum of the remote host's public key, and
libcurl will reject the connection to the host unless the MD5 checksum match.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
SCP and SFTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file");
curl_easy_setopt(curl, CURLOPT_SSH_HOST_PUBLIC_KEY_MD5,
"afe17cd62a0f3b61f1ab9cb22ba269a7");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.17.1
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_SSH_PUBLIC_KEYFILE "(3), " CURLOPT_SSH_AUTH_TYPES "(3), "
.BR CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 "(3), "
share/man/man3/CURLINFO_CAPATH.3 0000644 00000004572 14751150677 0011631 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_CAPATH 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_CAPATH \- get the default built-in CA path string
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CAPATH, char **path);
.fi
.SH DESCRIPTION
Pass a pointer to a char pointer to receive the pointer to a null-terminated
string holding the default built-in path used for the \fICURLOPT_CAPATH(3)\fP
option unless set by the user.
Note that in a situation where libcurl has been built to support multiple TLS
libraries, this option might return a string even if the specific TLS library
currently set to be used does not support \fICURLOPT_CAPATH(3)\fP.
This is a path identifying a directory.
The \fBpath\fP pointer will be NULL if there is no default path.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res;
char *capath = NULL;
curl_easy_getinfo(curl, CURLINFO_CAPATH, &capath);
if(capath)
printf("default ca path: %s\\n", capath);
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.84.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLINFO_CAINFO "(3), "
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
share/man/man3/CURLMOPT_MAX_HOST_CONNECTIONS.3 0000644 00000006314 14751150677 0014035 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLMOPT_MAX_HOST_CONNECTIONS 3 "May 17, 2022" "libcurl 7.86.0" "curl_multi_setopt options"
.SH NAME
CURLMOPT_MAX_HOST_CONNECTIONS \- max number of connections to a single host
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_HOST_CONNECTIONS,
long max);
.fi
.SH DESCRIPTION
Pass a long to indicate \fBmax\fP. The set number will be used as the maximum
amount of simultaneously open connections to a single host (a host being the
same as a host name + port number pair). For each new session to a host,
libcurl will open a new connection up to the limit set by
\fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP. When the limit is reached, the
sessions will be pending until a connection becomes available. If
\fICURLMOPT_PIPELINING(3)\fP is enabled, libcurl will try to pipeline if the
host is capable of it.
The default \fBmax\fP value is 0, unlimited. However, for backwards
compatibility, setting it to 0 when \fICURLMOPT_PIPELINING(3)\fP is 1 will not
be treated as unlimited. Instead it will open only 1 connection and try to
pipeline on it.
This set limit is also used for proxy connections, and then the proxy is
considered to be the host for which this limit counts.
When more transfers are added to the multi handle than what can be performed
due to the set limit, they will be queued up waiting for their chance. When
that happens, the \fICURLOPT_TIMEOUT_MS(3)\fP timeout will be counted
inclusive of the waiting time, meaning that if you set a too narrow timeout in
such a case the transfer might never even start before it times out.
Even in the queued up situation, the \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP
timeout is however treated as a per-connect timeout.
.SH DEFAULT
0
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
.nf
CURLM *m = curl_multi_init();
/* do no more than 2 connections per host */
curl_multi_setopt(m, CURLMOPT_MAX_HOST_CONNECTIONS, 2L);
.fi
.SH AVAILABILITY
Added in 7.30.0
.SH RETURN VALUE
Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLMOPT_MAXCONNECTS "(3), " CURLMOPT_MAX_TOTAL_CONNECTIONS "(3), "
share/man/man3/CURLOPT_PRIVATE.3 0000644 00000004410 14751150677 0011701 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PRIVATE 3 "September 22, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PRIVATE \- store a private pointer
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PRIVATE, void *pointer);
.fi
.SH DESCRIPTION
Pass a void * as parameter, pointing to data that should be associated with
this curl handle. The pointer can subsequently be retrieved using
\fIcurl_easy_getinfo(3)\fP with the \fICURLINFO_PRIVATE(3)\fP option. libcurl
itself never does anything with this data.
.SH DEFAULT
NULL
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
struct private secrets;
if(curl) {
struct private *extracted;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* store a pointer to our private struct */
curl_easy_setopt(curl, CURLOPT_PRIVATE, &secrets);
curl_easy_perform(curl);
/* we can extract the private pointer again too */
curl_easy_getinfo(curl, CURLINFO_PRIVATE, &extracted);
}
.fi
.SH AVAILABILITY
Added in 7.10.3
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_VERBOSE "(3), " CURLOPT_STDERR "(3), "
share/man/man3/CURLOPT_PROXYHEADER.3 0000644 00000005362 14751150677 0012370 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXYHEADER 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXYHEADER \- set of HTTP headers to pass to proxy
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYHEADER,
struct curl_slist *headers);
.SH DESCRIPTION
Pass a pointer to a linked list of HTTP headers to pass in your HTTP request
sent to a proxy. The rules for this list is identical to the
\fICURLOPT_HTTPHEADER(3)\fP option's.
The headers set with this option is only ever used in requests sent to a proxy
- when there's also a request sent to a host.
The first line in a request (containing the method, usually a GET or POST) is
NOT a header and cannot be replaced using this option. Only the lines
following the request-line are headers. Adding this method line in this list
of headers will only cause your request to send an invalid header.
Pass a NULL to this to reset back to no custom headers.
.SH DEFAULT
NULL
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
struct curl_slist *list;
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy.example.com:80");
list = curl_slist_append(NULL, "Shoesize: 10");
list = curl_slist_append(list, "Accept:");
curl_easy_setopt(curl, CURLOPT_PROXYHEADER, list);
curl_easy_perform(curl);
curl_slist_free_all(list); /* free the list again */
}
.fi
.SH AVAILABILITY
Added in 7.37.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_HEADEROPT "(3), " CURLOPT_HTTPHEADER "(3), "
share/man/man3/libcurl-tutorial.3 0000644 00000171431 14751150677 0012664 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH libcurl-tutorial 3 "September 20, 2022" "libcurl 7.86.0" "libcurl programming"
.SH NAME
libcurl-tutorial \- libcurl programming tutorial
.SH "Objective"
This document attempts to describe the general principles and some basic
approaches to consider when programming with libcurl. The text will focus
mainly on the C interface but might apply fairly well on other interfaces as
well as they usually follow the C one pretty closely.
This document will refer to 'the user' as the person writing the source code
that uses libcurl. That would probably be you or someone in your position.
What will be generally referred to as 'the program' will be the collected
source code that you write that is using libcurl for transfers. The program
is outside libcurl and libcurl is outside of the program.
To get more details on all options and functions described herein, please
refer to their respective man pages.
.SH "Building"
There are many different ways to build C programs. This chapter will assume a
Unix style build process. If you use a different build system, you can still
read this to get general information that may apply to your environment as
well.
.IP "Compiling the Program"
Your compiler needs to know where the libcurl headers are located. Therefore
you must set your compiler's include path to point to the directory where you
installed them. The 'curl-config'[3] tool can be used to get this information:
.nf
$ curl-config --cflags
.fi
.IP "Linking the Program with libcurl"
When having compiled the program, you need to link your object files to create
a single executable. For that to succeed, you need to link with libcurl and
possibly also with other libraries that libcurl itself depends on. Like the
OpenSSL libraries, but even some standard OS libraries may be needed on the
command line. To figure out which flags to use, once again the 'curl-config'
tool comes to the rescue:
.nf
$ curl-config --libs
.fi
.IP "SSL or Not"
libcurl can be built and customized in many ways. One of the things that
varies from different libraries and builds is the support for SSL-based
transfers, like HTTPS and FTPS. If a supported SSL library was detected
properly at build-time, libcurl will be built with SSL support. To figure out
if an installed libcurl has been built with SSL support enabled, use
\&'curl-config' like this:
.nf
$ curl-config --feature
.fi
And if SSL is supported, the keyword \fISSL\fP will be written to stdout,
possibly together with a few other features that could be either on or off on
for different libcurls.
See also the "Features libcurl Provides" further down.
.IP "autoconf macro"
When you write your configure script to detect libcurl and setup variables
accordingly, we offer a macro that probably does everything you need in this
area. See docs/libcurl/libcurl.m4 file - it includes docs on how to use it.
.SH "Portable Code in a Portable World"
The people behind libcurl have put a considerable effort to make libcurl work
on a large amount of different operating systems and environments.
You program libcurl the same way on all platforms that libcurl runs on. There
are only a few minor details that differ. If you just make sure to write your
code portable enough, you can create a portable program. libcurl should not
stop you from that.
.SH "Global Preparation"
The program must initialize some of the libcurl functionality globally. That
means it should be done exactly once, no matter how many times you intend to
use the library. Once for your program's entire life time. This is done using
.nf
curl_global_init()
.fi
and it takes one parameter which is a bit pattern that tells libcurl what to
initialize. Using \fICURL_GLOBAL_ALL\fP will make it initialize all known
internal sub modules, and might be a good default option. The current two bits
that are specified are:
.RS
.IP "CURL_GLOBAL_WIN32"
which only does anything on Windows machines. When used on
a Windows machine, it will make libcurl initialize the win32 socket
stuff. Without having that initialized properly, your program cannot use
sockets properly. You should only do this once for each application, so if
your program already does this or of another library in use does it, you
should not tell libcurl to do this as well.
.IP CURL_GLOBAL_SSL
which only does anything on libcurls compiled and built SSL-enabled. On these
systems, this will make libcurl initialize the SSL library properly for this
application. This only needs to be done once for each application so if your
program or another library already does this, this bit should not be needed.
.RE
libcurl has a default protection mechanism that detects if
\fIcurl_global_init(3)\fP has not been called by the time
\fIcurl_easy_perform(3)\fP is called and if that is the case, libcurl runs the
function itself with a guessed bit pattern. Please note that depending solely
on this is not considered nice nor good.
When the program no longer uses libcurl, it should call
\fIcurl_global_cleanup(3)\fP, which is the opposite of the init call. It will
then do the reversed operations to cleanup the resources the
\fIcurl_global_init(3)\fP call initialized.
Repeated calls to \fIcurl_global_init(3)\fP and \fIcurl_global_cleanup(3)\fP
should be avoided. They should only be called once each.
.SH "Features libcurl Provides"
It is considered best-practice to determine libcurl features at runtime rather
than at build-time (if possible of course). By calling
\fIcurl_version_info(3)\fP and checking out the details of the returned
struct, your program can figure out exactly what the currently running libcurl
supports.
.SH "Two Interfaces"
libcurl first introduced the so called easy interface. All operations in the
easy interface are prefixed with 'curl_easy'. The easy interface lets you do
single transfers with a synchronous and blocking function call.
libcurl also offers another interface that allows multiple simultaneous
transfers in a single thread, the so called multi interface. More about that
interface is detailed in a separate chapter further down. You still need to
understand the easy interface first, so please continue reading for better
understanding.
.SH "Handle the Easy libcurl"
To use the easy interface, you must first create yourself an easy handle. You
need one handle for each easy session you want to perform. Basically, you
should use one handle for every thread you plan to use for transferring. You
must never share the same handle in multiple threads.
Get an easy handle with
.nf
handle = curl_easy_init();
.fi
It returns an easy handle. Using that you proceed to the next step: setting
up your preferred actions. A handle is just a logic entity for the upcoming
transfer or series of transfers.
You set properties and options for this handle using
\fIcurl_easy_setopt(3)\fP. They control how the subsequent transfer or
transfers will be made. Options remain set in the handle until set again to
something different. They are sticky. Multiple requests using the same handle
will use the same options.
If you at any point would like to blank all previously set options for a
single easy handle, you can call \fIcurl_easy_reset(3)\fP and you can also
make a clone of an easy handle (with all its set options) using
\fIcurl_easy_duphandle(3)\fP.
Many of the options you set in libcurl are "strings", pointers to data
terminated with a zero byte. When you set strings with
\fIcurl_easy_setopt(3)\fP, libcurl makes its own copy so that they do not need
to be kept around in your application after being set[4].
One of the most basic properties to set in the handle is the URL. You set your
preferred URL to transfer with \fICURLOPT_URL(3)\fP in a manner similar to:
.nf
curl_easy_setopt(handle, CURLOPT_URL, "http://domain.com/");
.fi
Let's assume for a while that you want to receive data as the URL identifies a
remote resource you want to get here. Since you write a sort of application
that needs this transfer, I assume that you would like to get the data passed
to you directly instead of simply getting it passed to stdout. So, you write
your own function that matches this prototype:
.nf
size_t write_data(void *buffer, size_t size, size_t nmemb, void *userp);
.fi
You tell libcurl to pass all data to this function by issuing a function
similar to this:
.nf
curl_easy_setopt(handle, CURLOPT_WRITEFUNCTION, write_data);
.fi
You can control what data your callback function gets in the fourth argument
by setting another property:
.nf
curl_easy_setopt(handle, CURLOPT_WRITEDATA, &internal_struct);
.fi
Using that property, you can easily pass local data between your application
and the function that gets invoked by libcurl. libcurl itself will not touch the
data you pass with \fICURLOPT_WRITEDATA(3)\fP.
libcurl offers its own default internal callback that will take care of the
data if you do not set the callback with \fICURLOPT_WRITEFUNCTION(3)\fP. It
will then simply output the received data to stdout. You can have the default
callback write the data to a different file handle by passing a 'FILE *' to a
file opened for writing with the \fICURLOPT_WRITEDATA(3)\fP option.
Now, we need to take a step back and have a deep breath. Here's one of those
rare platform-dependent nitpicks. Did you spot it? On some platforms[2],
libcurl will not be able to operate on files opened by the program. Thus, if you
use the default callback and pass in an open file with
\fICURLOPT_WRITEDATA(3)\fP, it will crash. You should therefore avoid this to
make your program run fine virtually everywhere.
(\fICURLOPT_WRITEDATA(3)\fP was formerly known as \fICURLOPT_FILE\fP. Both
names still work and do the same thing).
If you are using libcurl as a win32 DLL, you MUST use the
\fICURLOPT_WRITEFUNCTION(3)\fP if you set \fICURLOPT_WRITEDATA(3)\fP - or you
will experience crashes.
There are of course many more options you can set, and we will get back to a few
of them later. Let's instead continue to the actual transfer:
.nf
success = curl_easy_perform(handle);
.fi
\fIcurl_easy_perform(3)\fP will connect to the remote site, do the necessary
commands and receive the transfer. Whenever it receives data, it calls the
callback function we previously set. The function may get one byte at a time,
or it may get many kilobytes at once. libcurl delivers as much as possible as
often as possible. Your callback function should return the number of bytes it
\&"took care of". If that is not the same amount of bytes that was passed to
it, libcurl will abort the operation and return with an error code.
When the transfer is complete, the function returns a return code that informs
you if it succeeded in its mission or not. If a return code is not enough for
you, you can use the \fICURLOPT_ERRORBUFFER(3)\fP to point libcurl to a buffer
of yours where it will store a human readable error message as well.
If you then want to transfer another file, the handle is ready to be used
again. Mind you, it is even preferred that you re-use an existing handle if
you intend to make another transfer. libcurl will then attempt to re-use the
previous connection.
For some protocols, downloading a file can involve a complicated process of
logging in, setting the transfer mode, changing the current directory and
finally transferring the file data. libcurl takes care of all that
complication for you. Given simply the URL to a file, libcurl will take care
of all the details needed to get the file moved from one machine to another.
.SH "Multi-threading Issues"
libcurl is thread safe but there are a few exceptions. Refer to
\fIlibcurl-thread(3)\fP for more information.
.SH "When It does not Work"
There will always be times when the transfer fails for some reason. You might
have set the wrong libcurl option or misunderstood what the libcurl option
actually does, or the remote server might return non-standard replies that
confuse the library which then confuses your program.
There's one golden rule when these things occur: set the
\fICURLOPT_VERBOSE(3)\fP option to 1. it will cause the library to spew out the
entire protocol details it sends, some internal info and some received
protocol data as well (especially when using FTP). If you are using HTTP,
adding the headers in the received output to study is also a clever way to get
a better understanding why the server behaves the way it does. Include headers
in the normal body output with \fICURLOPT_HEADER(3)\fP set 1.
Of course, there are bugs left. We need to know about them to be able to fix
them, so we are quite dependent on your bug reports. When you do report
suspected bugs in libcurl, please include as many details as you possibly can:
a protocol dump that \fICURLOPT_VERBOSE(3)\fP produces, library version, as
much as possible of your code that uses libcurl, operating system name and
version, compiler name and version etc.
If \fICURLOPT_VERBOSE(3)\fP is not enough, you increase the level of debug
data your application receive by using the \fICURLOPT_DEBUGFUNCTION(3)\fP.
Getting some in-depth knowledge about the protocols involved is never wrong,
and if you are trying to do funny things, you might understand libcurl and how
to use it better if you study the appropriate RFC documents at least briefly.
.SH "Upload Data to a Remote Site"
libcurl tries to keep a protocol independent approach to most transfers, thus
uploading to a remote FTP site is similar to uploading data to an HTTP server
with a PUT request.
Of course, first you either create an easy handle or you re-use one existing
one. Then you set the URL to operate on just like before. This is the remote
URL, that we now will upload.
Since we write an application, we most likely want libcurl to get the upload
data by asking us for it. To make it do that, we set the read callback and
the custom pointer libcurl will pass to our read callback. The read callback
should have a prototype similar to:
.nf
size_t function(char *bufptr, size_t size, size_t nitems, void *userp);
.fi
Where \fIbufptr\fP is the pointer to a buffer we fill in with data to upload
and \fIsize*nitems\fP is the size of the buffer and therefore also the maximum
amount of data we can return to libcurl in this call. The \fIuserp\fP pointer
is the custom pointer we set to point to a struct of ours to pass private data
between the application and the callback.
.nf
curl_easy_setopt(handle, CURLOPT_READFUNCTION, read_function);
curl_easy_setopt(handle, CURLOPT_READDATA, &filedata);
.fi
Tell libcurl that we want to upload:
.nf
curl_easy_setopt(handle, CURLOPT_UPLOAD, 1L);
.fi
A few protocols will not behave properly when uploads are done without any prior
knowledge of the expected file size. So, set the upload file size using the
\fICURLOPT_INFILESIZE_LARGE(3)\fP for all known file sizes like this[1]:
.nf
/* in this example, file_size must be an curl_off_t variable */
curl_easy_setopt(handle, CURLOPT_INFILESIZE_LARGE, file_size);
.fi
When you call \fIcurl_easy_perform(3)\fP this time, it will perform all the
necessary operations and when it has invoked the upload it will call your
supplied callback to get the data to upload. The program should return as much
data as possible in every invoke, as that is likely to make the upload perform
as fast as possible. The callback should return the number of bytes it wrote
in the buffer. Returning 0 will signal the end of the upload.
.SH "Passwords"
Many protocols use or even require that user name and password are provided
to be able to download or upload the data of your choice. libcurl offers
several ways to specify them.
Most protocols support that you specify the name and password in the URL
itself. libcurl will detect this and use them accordingly. This is written
like this:
.nf
protocol://user:password@example.com/path/
.fi
If you need any odd letters in your user name or password, you should enter
them URL encoded, as %XX where XX is a two-digit hexadecimal number.
libcurl also provides options to set various passwords. The user name and
password as shown embedded in the URL can instead get set with the
\fICURLOPT_USERPWD(3)\fP option. The argument passed to libcurl should be a
char * to a string in the format "user:password". In a manner like this:
.nf
curl_easy_setopt(handle, CURLOPT_USERPWD, "myname:thesecret");
.fi
Another case where name and password might be needed at times, is for those
users who need to authenticate themselves to a proxy they use. libcurl offers
another option for this, the \fICURLOPT_PROXYUSERPWD(3)\fP. It is used quite
similar to the \fICURLOPT_USERPWD(3)\fP option like this:
.nf
curl_easy_setopt(handle, CURLOPT_PROXYUSERPWD, "myname:thesecret");
.fi
There's a long time Unix "standard" way of storing FTP user names and
passwords, namely in the $HOME/.netrc file (on Windows, libcurl also checks
the \fI%USERPROFILE% environment\fP variable if \fI%HOME%\fP is unset, and
tries "_netrc" as name). The file should be made private so that only the user
may read it (see also the "Security Considerations" chapter), as it might
contain the password in plain text. libcurl has the ability to use this file
to figure out what set of user name and password to use for a particular
host. As an extension to the normal functionality, libcurl also supports this
file for non-FTP protocols such as HTTP. To make curl use this file, use the
\fICURLOPT_NETRC(3)\fP option:
.nf
curl_easy_setopt(handle, CURLOPT_NETRC, 1L);
.fi
And a basic example of how such a .netrc file may look like:
.nf
machine myhost.mydomain.com
login userlogin
password secretword
.fi
All these examples have been cases where the password has been optional, or
at least you could leave it out and have libcurl attempt to do its job
without it. There are times when the password is not optional, like when
you are using an SSL private key for secure transfers.
To pass the known private key password to libcurl:
.nf
curl_easy_setopt(handle, CURLOPT_KEYPASSWD, "keypassword");
.fi
.SH "HTTP Authentication"
The previous chapter showed how to set user name and password for getting
URLs that require authentication. When using the HTTP protocol, there are
many different ways a client can provide those credentials to the server and
you can control which way libcurl will (attempt to) use them. The default HTTP
authentication method is called 'Basic', which is sending the name and
password in clear-text in the HTTP request, base64-encoded. This is insecure.
At the time of this writing, libcurl can be built to use: Basic, Digest, NTLM,
Negotiate (SPNEGO). You can tell libcurl which one to use
with \fICURLOPT_HTTPAUTH(3)\fP as in:
.nf
curl_easy_setopt(handle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST);
.fi
And when you send authentication to a proxy, you can also set authentication
type the same way but instead with \fICURLOPT_PROXYAUTH(3)\fP:
.nf
curl_easy_setopt(handle, CURLOPT_PROXYAUTH, CURLAUTH_NTLM);
.fi
Both these options allow you to set multiple types (by ORing them together),
to make libcurl pick the most secure one out of the types the server/proxy
claims to support. This method does however add a round-trip since libcurl
must first ask the server what it supports:
.nf
curl_easy_setopt(handle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST|CURLAUTH_BASIC);
.fi
For convenience, you can use the \fICURLAUTH_ANY\fP define (instead of a list
with specific types) which allows libcurl to use whatever method it wants.
When asking for multiple types, libcurl will pick the available one it
considers "best" in its own internal order of preference.
.SH "HTTP POSTing"
We get many questions regarding how to issue HTTP POSTs with libcurl the
proper way. This chapter will thus include examples using both different
versions of HTTP POST that libcurl supports.
The first version is the simple POST, the most common version, that most HTML
pages using the <form> tag uses. We provide a pointer to the data and tell
libcurl to post it all to the remote site:
.nf
char *data="name=daniel&project=curl";
curl_easy_setopt(handle, CURLOPT_POSTFIELDS, data);
curl_easy_setopt(handle, CURLOPT_URL, "http://posthere.com/");
curl_easy_perform(handle); /* post away! */
.fi
Simple enough, huh? Since you set the POST options with the
\fICURLOPT_POSTFIELDS(3)\fP, this automatically switches the handle to use
POST in the upcoming request.
What if you want to post binary data that also requires you to set the
Content-Type: header of the post? Well, binary posts prevent libcurl from being
able to do strlen() on the data to figure out the size, so therefore we must
tell libcurl the size of the post data. Setting headers in libcurl requests are
done in a generic way, by building a list of our own headers and then passing
that list to libcurl.
.nf
struct curl_slist *headers=NULL;
headers = curl_slist_append(headers, "Content-Type: text/xml");
/* post binary data */
curl_easy_setopt(handle, CURLOPT_POSTFIELDS, binaryptr);
/* set the size of the postfields data */
curl_easy_setopt(handle, CURLOPT_POSTFIELDSIZE, 23L);
/* pass our list of custom made headers */
curl_easy_setopt(handle, CURLOPT_HTTPHEADER, headers);
curl_easy_perform(handle); /* post away! */
curl_slist_free_all(headers); /* free the header list */
.fi
While the simple examples above cover the majority of all cases where HTTP
POST operations are required, they do not do multi-part formposts. Multi-part
formposts were introduced as a better way to post (possibly large) binary data
and were first documented in the RFC1867 (updated in RFC2388). they are called
multi-part because they are built by a chain of parts, each part being a single
unit of data. Each part has its own name and contents. You can in fact create
and post a multi-part formpost with the regular libcurl POST support described
above, but that would require that you build a formpost yourself and provide
to libcurl. To make that easier, libcurl provides a MIME API consisting in
several functions: using those, you can create and fill a multi-part form.
Function \fIcurl_mime_init(3)\fP creates a multi-part body; you can then
append new parts to a multi-part body using \fIcurl_mime_addpart(3)\fP.
There are three possible data sources for a part: memory using
\fIcurl_mime_data(3)\fP, file using \fIcurl_mime_filedata(3)\fP and
user-defined data read callback using \fIcurl_mime_data_cb(3)\fP.
\fIcurl_mime_name(3)\fP sets a part's (i.e.: form field) name, while
\fIcurl_mime_filename(3)\fP fills in the remote file name. With
\fIcurl_mime_type(3)\fP, you can tell the MIME type of a part,
\fIcurl_mime_headers(3)\fP allows defining the part's headers. When a
multi-part body is no longer needed, you can destroy it using
\fIcurl_mime_free(3)\fP.
The following example sets two simple text parts with plain textual contents,
and then a file with binary contents and uploads the whole thing.
.nf
curl_mime *multipart = curl_mime_init(handle);
curl_mimepart *part = curl_mime_addpart(multipart);
curl_mime_name(part, "name");
curl_mime_data(part, "daniel", CURL_ZERO_TERMINATED);
part = curl_mime_addpart(multipart);
curl_mime_name(part, "project");
curl_mime_data(part, "curl", CURL_ZERO_TERMINATED);
part = curl_mime_addpart(multipart);
curl_mime_name(part, "logotype-image");
curl_mime_filedata(part, "curl.png");
/* Set the form info */
curl_easy_setopt(handle, CURLOPT_MIMEPOST, multipart);
curl_easy_perform(handle); /* post away! */
/* free the post data again */
curl_mime_free(multipart);
.fi
To post multiple files for a single form field, you must supply each file in
a separate part, all with the same field name. Although function
\fIcurl_mime_subparts(3)\fP implements nested multi-parts, this way of
multiple files posting is deprecated by RFC 7578, chapter 4.3.
To set the data source from an already opened FILE pointer, use:
.nf
curl_mime_data_cb(part, filesize, (curl_read_callback) fread,
(curl_seek_callback) fseek, NULL, filepointer);
.fi
A deprecated \fIcurl_formadd(3)\fP function is still supported in libcurl.
It should however not be used anymore for new designs and programs using it
ought to be converted to the MIME API. It is however described here as an
aid to conversion.
Using \fIcurl_formadd\fP, you add parts to the form. When you are done adding
parts, you post the whole form.
The MIME API example above is expressed as follows using this function:
.nf
struct curl_httppost *post=NULL;
struct curl_httppost *last=NULL;
curl_formadd(&post, &last,
CURLFORM_COPYNAME, "name",
CURLFORM_COPYCONTENTS, "daniel", CURLFORM_END);
curl_formadd(&post, &last,
CURLFORM_COPYNAME, "project",
CURLFORM_COPYCONTENTS, "curl", CURLFORM_END);
curl_formadd(&post, &last,
CURLFORM_COPYNAME, "logotype-image",
CURLFORM_FILECONTENT, "curl.png", CURLFORM_END);
/* Set the form info */
curl_easy_setopt(handle, CURLOPT_HTTPPOST, post);
curl_easy_perform(handle); /* post away! */
/* free the post data again */
curl_formfree(post);
.fi
Multipart formposts are chains of parts using MIME-style separators and
headers. It means that each one of these separate parts get a few headers set
that describe the individual content-type, size etc. To enable your
application to handicraft this formpost even more, libcurl allows you to
supply your own set of custom headers to such an individual form part. You can
of course supply headers to as many parts as you like, but this little example
will show how you set headers to one specific part when you add that to the
post handle:
.nf
struct curl_slist *headers=NULL;
headers = curl_slist_append(headers, "Content-Type: text/xml");
curl_formadd(&post, &last,
CURLFORM_COPYNAME, "logotype-image",
CURLFORM_FILECONTENT, "curl.xml",
CURLFORM_CONTENTHEADER, headers,
CURLFORM_END);
curl_easy_perform(handle); /* post away! */
curl_formfree(post); /* free post */
curl_slist_free_all(headers); /* free custom header list */
.fi
Since all options on an easy handle are "sticky", they remain the same until
changed even if you do call \fIcurl_easy_perform(3)\fP, you may need to tell
curl to go back to a plain GET request if you intend to do one as your next
request. You force an easy handle to go back to GET by using the
\fICURLOPT_HTTPGET(3)\fP option:
.nf
curl_easy_setopt(handle, CURLOPT_HTTPGET, 1L);
.fi
Just setting \fICURLOPT_POSTFIELDS(3)\fP to "" or NULL will *not* stop libcurl
from doing a POST. It will just make it POST without any data to send!
.SH "Converting from deprecated form API to MIME API"
Four rules have to be respected in building the multi-part:
.br
- The easy handle must be created before building the multi-part.
.br
- The multi-part is always created by a call to curl_mime_init(handle).
.br
- Each part is created by a call to curl_mime_addpart(multipart).
.br
- When complete, the multi-part must be bound to the easy handle using
\fICURLOPT_MIMEPOST(3)\fP instead of \fICURLOPT_HTTPPOST(3)\fP.
Here are some example of \fIcurl_formadd\fP calls to MIME API sequences:
.nf
curl_formadd(&post, &last,
CURLFORM_COPYNAME, "id",
CURLFORM_COPYCONTENTS, "daniel", CURLFORM_END);
CURLFORM_CONTENTHEADER, headers,
CURLFORM_END);
.fi
becomes:
.nf
part = curl_mime_addpart(multipart);
curl_mime_name(part, "id");
curl_mime_data(part, "daniel", CURL_ZERO_TERMINATED);
curl_mime_headers(part, headers, FALSE);
.fi
Setting the last \fIcurl_mime_headers\fP argument to TRUE would have caused
the headers to be automatically released upon destroyed the multi-part, thus
saving a clean-up call to \fIcurl_slist_free_all(3)\fP.
.nf
curl_formadd(&post, &last,
CURLFORM_PTRNAME, "logotype-image",
CURLFORM_FILECONTENT, "-",
CURLFORM_END);
.fi
becomes:
.nf
part = curl_mime_addpart(multipart);
curl_mime_name(part, "logotype-image");
curl_mime_data_cb(part, (curl_off_t) -1, fread, fseek, NULL, stdin);
.fi
\fIcurl_mime_name\fP always copies the field name. The special file name "-"
is not supported by \fIcurl_mime_file\fP: to read an open file, use
a callback source using fread(). The transfer will be chunked since the data
size is unknown.
.nf
curl_formadd(&post, &last,
CURLFORM_COPYNAME, "datafile[]",
CURLFORM_FILE, "file1",
CURLFORM_FILE, "file2",
CURLFORM_END);
.fi
becomes:
.nf
part = curl_mime_addpart(multipart);
curl_mime_name(part, "datafile[]");
curl_mime_filedata(part, "file1");
part = curl_mime_addpart(multipart);
curl_mime_name(part, "datafile[]");
curl_mime_filedata(part, "file2");
.fi
The deprecated multipart/mixed implementation of multiple files field is
translated to two distinct parts with the same name.
.nf
curl_easy_setopt(handle, CURLOPT_READFUNCTION, myreadfunc);
curl_formadd(&post, &last,
CURLFORM_COPYNAME, "stream",
CURLFORM_STREAM, arg,
CURLFORM_CONTENTLEN, (curl_off_t) datasize,
CURLFORM_FILENAME, "archive.zip",
CURLFORM_CONTENTTYPE, "application/zip",
CURLFORM_END);
.fi
becomes:
.nf
part = curl_mime_addpart(multipart);
curl_mime_name(part, "stream");
curl_mime_data_cb(part, (curl_off_t) datasize,
myreadfunc, NULL, NULL, arg);
curl_mime_filename(part, "archive.zip");
curl_mime_type(part, "application/zip");
.fi
\fICURLOPT_READFUNCTION\fP callback is not used: it is replace by directly
setting the part source data from the callback read function.
.nf
curl_formadd(&post, &last,
CURLFORM_COPYNAME, "memfile",
CURLFORM_BUFFER, "memfile.bin",
CURLFORM_BUFFERPTR, databuffer,
CURLFORM_BUFFERLENGTH, (long) sizeof databuffer,
CURLFORM_END);
.fi
becomes:
.nf
part = curl_mime_addpart(multipart);
curl_mime_name(part, "memfile");
curl_mime_data(part, databuffer, (curl_off_t) sizeof databuffer);
curl_mime_filename(part, "memfile.bin");
.fi
\fIcurl_mime_data\fP always copies the initial data: data buffer is thus
free for immediate reuse.
.nf
curl_formadd(&post, &last,
CURLFORM_COPYNAME, "message",
CURLFORM_FILECONTENT, "msg.txt",
CURLFORM_END);
.fi
becomes:
.nf
part = curl_mime_addpart(multipart);
curl_mime_name(part, "message");
curl_mime_filedata(part, "msg.txt");
curl_mime_filename(part, NULL);
.fi
Use of \fIcurl_mime_filedata\fP sets the remote file name as a side effect: it
is therefore necessary to clear it for \fICURLFORM_FILECONTENT\fP emulation.
.SH "Showing Progress"
For historical and traditional reasons, libcurl has a built-in progress meter
that can be switched on and then makes it present a progress meter in your
terminal.
Switch on the progress meter by, oddly enough, setting
\fICURLOPT_NOPROGRESS(3)\fP to zero. This option is set to 1 by default.
For most applications however, the built-in progress meter is useless and
what instead is interesting is the ability to specify a progress
callback. The function pointer you pass to libcurl will then be called on
irregular intervals with information about the current transfer.
Set the progress callback by using \fICURLOPT_PROGRESSFUNCTION(3)\fP. And pass
a pointer to a function that matches this prototype:
.nf
int progress_callback(void *clientp,
double dltotal,
double dlnow,
double ultotal,
double ulnow);
.fi
If any of the input arguments is unknown, a 0 will be passed. The first
argument, the 'clientp' is the pointer you pass to libcurl with
\fICURLOPT_PROGRESSDATA(3)\fP. libcurl will not touch it.
.SH "libcurl with C++"
There's basically only one thing to keep in mind when using C++ instead of C
when interfacing libcurl:
The callbacks CANNOT be non-static class member functions
Example C++ code:
.nf
class AClass {
static size_t write_data(void *ptr, size_t size, size_t nmemb,
void *ourpointer)
{
/* do what you want with the data */
}
}
.fi
.SH "Proxies"
What "proxy" means according to Merriam-Webster: "a person authorized to act
for another" but also "the agency, function, or office of a deputy who acts as
a substitute for another".
Proxies are exceedingly common these days. Companies often only offer Internet
access to employees through their proxies. Network clients or user-agents ask
the proxy for documents, the proxy does the actual request and then it returns
them.
libcurl supports SOCKS and HTTP proxies. When a given URL is wanted, libcurl
will ask the proxy for it instead of trying to connect to the actual host
identified in the URL.
If you are using a SOCKS proxy, you may find that libcurl does not quite support
all operations through it.
For HTTP proxies: the fact that the proxy is an HTTP proxy puts certain
restrictions on what can actually happen. A requested URL that might not be a
HTTP URL will be still be passed to the HTTP proxy to deliver back to
libcurl. This happens transparently, and an application may not need to
know. I say "may", because at times it is important to understand that all
operations over an HTTP proxy use the HTTP protocol. For example, you cannot
invoke your own custom FTP commands or even proper FTP directory listings.
.IP "Proxy Options"
To tell libcurl to use a proxy at a given port number:
.nf
curl_easy_setopt(handle, CURLOPT_PROXY, "proxy-host.com:8080");
.fi
Some proxies require user authentication before allowing a request, and you
pass that information similar to this:
.nf
curl_easy_setopt(handle, CURLOPT_PROXYUSERPWD, "user:password");
.fi
If you want to, you can specify the host name only in the
\fICURLOPT_PROXY(3)\fP option, and set the port number separately with
\fICURLOPT_PROXYPORT(3)\fP.
Tell libcurl what kind of proxy it is with \fICURLOPT_PROXYTYPE(3)\fP (if not,
it will default to assume an HTTP proxy):
.nf
curl_easy_setopt(handle, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS4);
.fi
.IP "Environment Variables"
libcurl automatically checks and uses a set of environment variables to know
what proxies to use for certain protocols. The names of the variables are
following an old tradition and are built up as "[protocol]_proxy" (note the
lower casing). Which makes the variable \&'http_proxy' checked for a name of a
proxy to use when the input URL is HTTP. Following the same rule, the variable
named 'ftp_proxy' is checked for FTP URLs. Again, the proxies are always HTTP
proxies, the different names of the variables simply allows different HTTP
proxies to be used.
The proxy environment variable contents should be in the format
\&"[protocol://][user:password@]machine[:port]". Where the protocol:// part
specifies which type of proxy it is, and the optional port number specifies on
which port the proxy operates. If not specified, the internal default port
number will be used and that is most likely not the one you would like it to
be.
There are two special environment variables. 'all_proxy' is what sets proxy
for any URL in case the protocol specific variable was not set, and
\&'no_proxy' defines a list of hosts that should not use a proxy even though a
variable may say so. If 'no_proxy' is a plain asterisk ("*") it matches all
hosts.
To explicitly disable libcurl's checking for and using the proxy environment
variables, set the proxy name to "" - an empty string - with
\fICURLOPT_PROXY(3)\fP.
.IP "SSL and Proxies"
SSL is for secure point-to-point connections. This involves strong encryption
and similar things, which effectively makes it impossible for a proxy to
operate as a "man in between" which the proxy's task is, as previously
discussed. Instead, the only way to have SSL work over an HTTP proxy is to ask
the proxy to tunnel everything through without being able to check or fiddle
with the traffic.
Opening an SSL connection over an HTTP proxy is therefore a matter of asking the
proxy for a straight connection to the target host on a specified port. This
is made with the HTTP request CONNECT. ("please dear proxy, connect me to that
remote host").
Because of the nature of this operation, where the proxy has no idea what kind
of data that is passed in and out through this tunnel, this breaks some of the
few advantages that come from using a proxy, such as caching. Many
organizations prevent this kind of tunneling to other destination port numbers
than 443 (which is the default HTTPS port number).
.IP "Tunneling Through Proxy"
As explained above, tunneling is required for SSL to work and often even
restricted to the operation intended for SSL; HTTPS.
This is however not the only time proxy-tunneling might offer benefits to
you or your application.
As tunneling opens a direct connection from your application to the remote
machine, it suddenly also re-introduces the ability to do non-HTTP
operations over an HTTP proxy. You can in fact use things such as FTP
upload or FTP custom commands this way.
Again, this is often prevented by the administrators of proxies and is
rarely allowed.
Tell libcurl to use proxy tunneling like this:
.nf
curl_easy_setopt(handle, CURLOPT_HTTPPROXYTUNNEL, 1L);
.fi
In fact, there might even be times when you want to do plain HTTP
operations using a tunnel like this, as it then enables you to operate on
the remote server instead of asking the proxy to do so. libcurl will not
stand in the way for such innovative actions either!
.IP "Proxy Auto-Config"
Netscape first came up with this. It is basically a web page (usually using a
\&.pac extension) with a JavaScript that when executed by the browser with the
requested URL as input, returns information to the browser on how to connect
to the URL. The returned information might be "DIRECT" (which means no proxy
should be used), "PROXY host:port" (to tell the browser where the proxy for
this particular URL is) or "SOCKS host:port" (to direct the browser to a SOCKS
proxy).
libcurl has no means to interpret or evaluate JavaScript and thus it does not
support this. If you get yourself in a position where you face this nasty
invention, the following advice have been mentioned and used in the past:
- Depending on the JavaScript complexity, write up a script that translates it
to another language and execute that.
- Read the JavaScript code and rewrite the same logic in another language.
- Implement a JavaScript interpreter; people have successfully used the
Mozilla JavaScript engine in the past.
- Ask your admins to stop this, for a static proxy setup or similar.
.SH "Persistence Is The Way to Happiness"
Re-cycling the same easy handle several times when doing multiple requests is
the way to go.
After each single \fIcurl_easy_perform(3)\fP operation, libcurl will keep the
connection alive and open. A subsequent request using the same easy handle to
the same host might just be able to use the already open connection! This
reduces network impact a lot.
Even if the connection is dropped, all connections involving SSL to the same
host again, will benefit from libcurl's session ID cache that drastically
reduces re-connection time.
FTP connections that are kept alive save a lot of time, as the command-
response round-trips are skipped, and also you do not risk getting blocked
without permission to login again like on many FTP servers only allowing N
persons to be logged in at the same time.
libcurl caches DNS name resolving results, to make lookups of a previously
looked up name a lot faster.
Other interesting details that improve performance for subsequent requests
may also be added in the future.
Each easy handle will attempt to keep the last few connections alive for a
while in case they are to be used again. You can set the size of this "cache"
with the \fICURLOPT_MAXCONNECTS(3)\fP option. Default is 5. There is rarely
any point in changing this value, and if you think of changing this it is
often just a matter of thinking again.
To force your upcoming request to not use an already existing connection (it
will even close one first if there happens to be one alive to the same host
you are about to operate on), you can do that by setting
\fICURLOPT_FRESH_CONNECT(3)\fP to 1. In a similar spirit, you can also forbid
the upcoming request to be "lying" around and possibly get re-used after the
request by setting \fICURLOPT_FORBID_REUSE(3)\fP to 1.
.SH "HTTP Headers Used by libcurl"
When you use libcurl to do HTTP requests, it will pass along a series of headers
automatically. It might be good for you to know and understand these. You
can replace or remove them by using the \fICURLOPT_HTTPHEADER(3)\fP option.
.IP "Host"
This header is required by HTTP 1.1 and even many 1.0 servers and should be
the name of the server we want to talk to. This includes the port number if
anything but default.
.IP "Accept"
\&"*/*".
.IP "Expect"
When doing POST requests, libcurl sets this header to \&"100-continue" to ask
the server for an "OK" message before it proceeds with sending the data part
of the post. If the posted data amount is deemed "small", libcurl will not use
this header.
.SH "Customizing Operations"
There is an ongoing development today where more and more protocols are built
upon HTTP for transport. This has obvious benefits as HTTP is a tested and
reliable protocol that is widely deployed and has excellent proxy-support.
When you use one of these protocols, and even when doing other kinds of
programming you may need to change the traditional HTTP (or FTP or...)
manners. You may need to change words, headers or various data.
libcurl is your friend here too.
.IP CUSTOMREQUEST
If just changing the actual HTTP request keyword is what you want, like when
GET, HEAD or POST is not good enough for you, \fICURLOPT_CUSTOMREQUEST(3)\fP
is there for you. It is simple to use:
.nf
curl_easy_setopt(handle, CURLOPT_CUSTOMREQUEST, "MYOWNREQUEST");
.fi
When using the custom request, you change the request keyword of the actual
request you are performing. Thus, by default you make a GET request but you can
also make a POST operation (as described before) and then replace the POST
keyword if you want to. you are the boss.
.IP "Modify Headers"
HTTP-like protocols pass a series of headers to the server when doing the
request, and you are free to pass any amount of extra headers that you
think fit. Adding headers is this easy:
.nf
struct curl_slist *headers=NULL; /* init to NULL is important */
headers = curl_slist_append(headers, "Hey-server-hey: how are you?");
headers = curl_slist_append(headers, "X-silly-content: yes");
/* pass our list of custom made headers */
curl_easy_setopt(handle, CURLOPT_HTTPHEADER, headers);
curl_easy_perform(handle); /* transfer http */
curl_slist_free_all(headers); /* free the header list */
.fi
\&... and if you think some of the internally generated headers, such as
Accept: or Host: do not contain the data you want them to contain, you can
replace them by simply setting them too:
.nf
headers = curl_slist_append(headers, "Accept: Agent-007");
headers = curl_slist_append(headers, "Host: munged.host.line");
.fi
.IP "Delete Headers"
If you replace an existing header with one with no contents, you will prevent
the header from being sent. For instance, if you want to completely prevent the
\&"Accept:" header from being sent, you can disable it with code similar to this:
headers = curl_slist_append(headers, "Accept:");
Both replacing and canceling internal headers should be done with careful
consideration and you should be aware that you may violate the HTTP protocol
when doing so.
.IP "Enforcing chunked transfer-encoding"
By making sure a request uses the custom header "Transfer-Encoding: chunked"
when doing a non-GET HTTP operation, libcurl will switch over to "chunked"
upload, even though the size of the data to upload might be known. By default,
libcurl usually switches over to chunked upload automatically if the upload
data size is unknown.
.IP "HTTP Version"
All HTTP requests includes the version number to tell the server which version
we support. libcurl speaks HTTP 1.1 by default. Some old servers do not like
getting 1.1-requests and when dealing with stubborn old things like that, you
can tell libcurl to use 1.0 instead by doing something like this:
curl_easy_setopt(handle, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_0);
.IP "FTP Custom Commands"
Not all protocols are HTTP-like, and thus the above may not help you when
you want to make, for example, your FTP transfers to behave differently.
Sending custom commands to an FTP server means that you need to send the
commands exactly as the FTP server expects them (RFC959 is a good guide here),
and you can only use commands that work on the control-connection alone. All
kinds of commands that require data interchange and thus need a
data-connection must be left to libcurl's own judgment. Also be aware that
libcurl will do its best to change directory to the target directory before
doing any transfer, so if you change directory (with CWD or similar) you might
confuse libcurl and then it might not attempt to transfer the file in the
correct remote directory.
A little example that deletes a given file before an operation:
.nf
headers = curl_slist_append(headers, "DELE file-to-remove");
/* pass the list of custom commands to the handle */
curl_easy_setopt(handle, CURLOPT_QUOTE, headers);
curl_easy_perform(handle); /* transfer ftp data! */
curl_slist_free_all(headers); /* free the header list */
.fi
If you would instead want this operation (or chain of operations) to happen
_after_ the data transfer took place the option to \fIcurl_easy_setopt(3)\fP
would instead be called \fICURLOPT_POSTQUOTE(3)\fP and used the exact same
way.
The custom FTP command will be issued to the server in the same order they are
added to the list, and if a command gets an error code returned back from the
server, no more commands will be issued and libcurl will bail out with an
error code (CURLE_QUOTE_ERROR). Note that if you use \fICURLOPT_QUOTE(3)\fP to
send commands before a transfer, no transfer will actually take place when a
quote command has failed.
If you set the \fICURLOPT_HEADER(3)\fP to 1, you will tell libcurl to get
information about the target file and output "headers" about it. The headers
will be in "HTTP-style", looking like they do in HTTP.
The option to enable headers or to run custom FTP commands may be useful to
combine with \fICURLOPT_NOBODY(3)\fP. If this option is set, no actual file
content transfer will be performed.
.IP "FTP Custom CUSTOMREQUEST"
If you do want to list the contents of an FTP directory using your own defined
FTP command, \fICURLOPT_CUSTOMREQUEST(3)\fP will do just that. "NLST" is the
default one for listing directories but you are free to pass in your idea of a
good alternative.
.SH "Cookies Without Chocolate Chips"
In the HTTP sense, a cookie is a name with an associated value. A server sends
the name and value to the client, and expects it to get sent back on every
subsequent request to the server that matches the particular conditions
set. The conditions include that the domain name and path match and that the
cookie has not become too old.
In real-world cases, servers send new cookies to replace existing ones to
update them. Server use cookies to "track" users and to keep "sessions".
Cookies are sent from server to clients with the header Set-Cookie: and
they are sent from clients to servers with the Cookie: header.
To just send whatever cookie you want to a server, you can use
\fICURLOPT_COOKIE(3)\fP to set a cookie string like this:
.nf
curl_easy_setopt(handle, CURLOPT_COOKIE, "name1=var1; name2=var2;");
.fi
In many cases, that is not enough. You might want to dynamically save
whatever cookies the remote server passes to you, and make sure those cookies
are then used accordingly on later requests.
One way to do this, is to save all headers you receive in a plain file and
when you make a request, you tell libcurl to read the previous headers to
figure out which cookies to use. Set the header file to read cookies from with
\fICURLOPT_COOKIEFILE(3)\fP.
The \fICURLOPT_COOKIEFILE(3)\fP option also automatically enables the cookie
parser in libcurl. Until the cookie parser is enabled, libcurl will not parse
or understand incoming cookies and they will just be ignored. However, when
the parser is enabled the cookies will be understood and the cookies will be
kept in memory and used properly in subsequent requests when the same handle
is used. Many times this is enough, and you may not have to save the cookies
to disk at all. Note that the file you specify to \fICURLOPT_COOKIEFILE(3)\fP
does not have to exist to enable the parser, so a common way to just enable the
parser and not read any cookies is to use the name of a file you know does not
exist.
If you would rather use existing cookies that you have previously received with
your Netscape or Mozilla browsers, you can make libcurl use that cookie file
as input. The \fICURLOPT_COOKIEFILE(3)\fP is used for that too, as libcurl
will automatically find out what kind of file it is and act accordingly.
Perhaps the most advanced cookie operation libcurl offers, is saving the
entire internal cookie state back into a Netscape/Mozilla formatted cookie
file. We call that the cookie-jar. When you set a file name with
\fICURLOPT_COOKIEJAR(3)\fP, that file name will be created and all received
cookies will be stored in it when \fIcurl_easy_cleanup(3)\fP is called. This
enables cookies to get passed on properly between multiple handles without any
information getting lost.
.SH "FTP Peculiarities We Need"
FTP transfers use a second TCP/IP connection for the data transfer. This is
usually a fact you can forget and ignore but at times this fact will come
back to haunt you. libcurl offers several different ways to customize how the
second connection is being made.
libcurl can either connect to the server a second time or tell the server to
connect back to it. The first option is the default and it is also what works
best for all the people behind firewalls, NATs or IP-masquerading setups.
libcurl then tells the server to open up a new port and wait for a second
connection. This is by default attempted with EPSV first, and if that does not
work it tries PASV instead. (EPSV is an extension to the original FTP spec
and does not exist nor work on all FTP servers.)
You can prevent libcurl from first trying the EPSV command by setting
\fICURLOPT_FTP_USE_EPSV(3)\fP to zero.
In some cases, you will prefer to have the server connect back to you for the
second connection. This might be when the server is perhaps behind a firewall
or something and only allows connections on a single port. libcurl then
informs the remote server which IP address and port number to connect to.
This is made with the \fICURLOPT_FTPPORT(3)\fP option. If you set it to "-",
libcurl will use your system's "default IP address". If you want to use a
particular IP, you can set the full IP address, a host name to resolve to an
IP address or even a local network interface name that libcurl will get the IP
address from.
When doing the "PORT" approach, libcurl will attempt to use the EPRT and the
LPRT before trying PORT, as they work with more protocols. You can disable
this behavior by setting \fICURLOPT_FTP_USE_EPRT(3)\fP to zero.
.SH "MIME API revisited for SMTP and IMAP"
In addition to support HTTP multi-part form fields, the MIME API can be used
to build structured email messages and send them via SMTP or append such
messages to IMAP directories.
A structured email message may contain several parts: some are displayed
inline by the MUA, some are attachments. Parts can also be structured as
multi-part, for example to include another email message or to offer several
text formats alternatives. This can be nested to any level.
To build such a message, you prepare the nth-level multi-part and then include
it as a source to the parent multi-part using function
\fIcurl_mime_subparts(3)\fP. Once it has been
bound to its parent multi-part, a nth-level multi-part belongs to it and
should not be freed explicitly.
Email messages data is not supposed to be non-ascii and line length is
limited: fortunately, some transfer encodings are defined by the standards to
support the transmission of such incompatible data. Function
\fIcurl_mime_encoder(3)\fP tells a part that its source data must be encoded
before being sent. It also generates the corresponding header for that part.
If the part data you want to send is already encoded in such a scheme, do not
use this function (this would over-encode it), but explicitly set the
corresponding part header.
Upon sending such a message, libcurl prepends it with the header list
set with \fICURLOPT_HTTPHEADER(3)\fP, as zero level mime part headers.
Here is an example building an email message with an inline plain/html text
alternative and a file attachment encoded in base64:
.nf
curl_mime *message = curl_mime_init(handle);
/* The inline part is an alternative proposing the html and the text
versions of the email. */
curl_mime *alt = curl_mime_init(handle);
/* HTML message. */
curl_mimepart *part = curl_mime_addpart(alt);
curl_mime_data(part, "<html><body><p>This is HTML</p></body></html>",
CURL_ZERO_TERMINATED);
curl_mime_type(part, "text/html");
/* Text message. */
part = curl_mime_addpart(alt);
curl_mime_data(part, "This is plain text message",
CURL_ZERO_TERMINATED);
/* Create the inline part. */
part = curl_mime_addpart(message);
curl_mime_subparts(part, alt);
curl_mime_type(part, "multipart/alternative");
struct curl_slist *headers = curl_slist_append(NULL,
"Content-Disposition: inline");
curl_mime_headers(part, headers, TRUE);
/* Add the attachment. */
part = curl_mime_addpart(message);
curl_mime_filedata(part, "manual.pdf");
curl_mime_encoder(part, "base64");
/* Build the mail headers. */
headers = curl_slist_append(NULL, "From: me@example.com");
headers = curl_slist_append(headers, "To: you@example.com");
/* Set these into the easy handle. */
curl_easy_setopt(handle, CURLOPT_HTTPHEADER, headers);
curl_easy_setopt(handle, CURLOPT_MIMEPOST, mime);
.fi
It should be noted that appending a message to an IMAP directory requires
the message size to be known prior upload. It is therefore not possible to
include parts with unknown data size in this context.
.SH "Headers Equal Fun"
Some protocols provide "headers", meta-data separated from the normal
data. These headers are by default not included in the normal data stream, but
you can make them appear in the data stream by setting \fICURLOPT_HEADER(3)\fP
to 1.
What might be even more useful, is libcurl's ability to separate the headers
from the data and thus make the callbacks differ. You can for example set a
different pointer to pass to the ordinary write callback by setting
\fICURLOPT_HEADERDATA(3)\fP.
Or, you can set an entirely separate function to receive the headers, by using
\fICURLOPT_HEADERFUNCTION(3)\fP.
The headers are passed to the callback function one by one, and you can
depend on that fact. It makes it easier for you to add custom header parsers
etc.
\&"Headers" for FTP transfers equal all the FTP server responses. They are not
actually true headers, but in this case we pretend they are! ;-)
.SH "Post Transfer Information"
See \fIcurl_easy_getinfo(3)\fP.
.SH "The multi Interface"
The easy interface as described in detail in this document is a synchronous
interface that transfers one file at a time and does not return until it is
done.
The multi interface, on the other hand, allows your program to transfer
multiple files in both directions at the same time, without forcing you to use
multiple threads. The name might make it seem that the multi interface is for
multi-threaded programs, but the truth is almost the reverse. The multi
interface allows a single-threaded application to perform the same kinds of
multiple, simultaneous transfers that multi-threaded programs can perform. It
allows many of the benefits of multi-threaded transfers without the complexity
of managing and synchronizing many threads.
To complicate matters somewhat more, there are even two versions of the multi
interface. The event based one, also called multi_socket and the "normal one"
designed for using with select(). See the libcurl-multi.3 man page for details
on the multi_socket event based API, this description here is for the select()
oriented one.
To use this interface, you are better off if you first understand the basics
of how to use the easy interface. The multi interface is simply a way to make
multiple transfers at the same time by adding up multiple easy handles into
a "multi stack".
You create the easy handles you want, one for each concurrent transfer, and
you set all the options just like you learned above, and then you create a
multi handle with \fIcurl_multi_init(3)\fP and add all those easy handles to
that multi handle with \fIcurl_multi_add_handle(3)\fP.
When you have added the handles you have for the moment (you can still add new
ones at any time), you start the transfers by calling
\fIcurl_multi_perform(3)\fP.
\fIcurl_multi_perform(3)\fP is asynchronous. It will only perform what can be
done now and then return control to your program. It is designed to never
block. You need to keep calling the function until all transfers are
completed.
The best usage of this interface is when you do a select() on all possible
file descriptors or sockets to know when to call libcurl again. This also
makes it easy for you to wait and respond to actions on your own application's
sockets/handles. You figure out what to select() for by using
\fIcurl_multi_fdset(3)\fP, that fills in a set of \fIfd_set\fP variables for
you with the particular file descriptors libcurl uses for the moment.
When you then call select(), it will return when one of the file handles signal
action and you then call \fIcurl_multi_perform(3)\fP to allow libcurl to do
what it wants to do. Take note that libcurl does also feature some time-out
code so we advise you to never use long timeouts on select() before you call
\fIcurl_multi_perform(3)\fP again. \fIcurl_multi_timeout(3)\fP is provided to
help you get a suitable timeout period.
Another precaution you should use: always call \fIcurl_multi_fdset(3)\fP
immediately before the select() call since the current set of file descriptors
may change in any curl function invoke.
If you want to stop the transfer of one of the easy handles in the stack, you
can use \fIcurl_multi_remove_handle(3)\fP to remove individual easy
handles. Remember that easy handles should be \fIcurl_easy_cleanup(3)\fPed.
When a transfer within the multi stack has finished, the counter of running
transfers (as filled in by \fIcurl_multi_perform(3)\fP) will decrease. When
the number reaches zero, all transfers are done.
\fIcurl_multi_info_read(3)\fP can be used to get information about completed
transfers. It then returns the CURLcode for each easy transfer, to allow you
to figure out success on each individual transfer.
.SH "SSL, Certificates and Other Tricks"
[ seeding, passwords, keys, certificates, ENGINE, ca certs ]
.SH "Sharing Data Between Easy Handles"
You can share some data between easy handles when the easy interface is used,
and some data is share automatically when you use the multi interface.
When you add easy handles to a multi handle, these easy handles will
automatically share a lot of the data that otherwise would be kept on a
per-easy handle basis when the easy interface is used.
The DNS cache is shared between handles within a multi handle, making
subsequent name resolving faster, and the connection pool that is kept to
better allow persistent connections and connection re-use is also shared. If
you are using the easy interface, you can still share these between specific
easy handles by using the share interface, see \fIlibcurl-share(3)\fP.
Some things are never shared automatically, not within multi handles, like for
example cookies so the only way to share that is with the share interface.
.SH "Footnotes"
.IP "[1]"
libcurl 7.10.3 and later have the ability to switch over to chunked
Transfer-Encoding in cases where HTTP uploads are done with data of an unknown
size.
.IP "[2]"
This happens on Windows machines when libcurl is built and used as a
DLL. However, you can still do this on Windows if you link with a static
library.
.IP "[3]"
The curl-config tool is generated at build-time (on Unix-like systems) and
should be installed with the 'make install' or similar instruction that
installs the library, header files, man pages etc.
.IP "[4]"
This behavior was different in versions before 7.17.0, where strings had to
remain valid past the end of the \fIcurl_easy_setopt(3)\fP call.
.SH "SEE ALSO"
.BR libcurl-errors "(3), " libcurl-multi "(3), " libcurl-easy "(3) "
share/man/man3/curl_multi_setopt.3 0000644 00000007050 14751150677 0013137 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_multi_setopt 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_multi_setopt \- set options for a curl multi handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_setopt(CURLM *multi_handle, CURLMoption option, param);
.fi
.SH DESCRIPTION
\fIcurl_multi_setopt(3)\fP is used to tell a libcurl multi handle how to
behave. By using the appropriate options to \fIcurl_multi_setopt(3)\fP, you
can change libcurl's behavior when using that multi handle. All options are
set with the \fIoption\fP followed by the parameter \fIparam\fP. That
parameter can be a \fBlong\fP, a \fBfunction pointer\fP, an \fBobject
pointer\fP or a \fBcurl_off_t\fP type, depending on what the specific option
expects. Read this manual carefully as bad input values may cause libcurl to
behave badly. You can only set one option in each function call.
.SH OPTIONS
.IP CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE
See \fICURLMOPT_CHUNK_LENGTH_PENALTY_SIZE(3)\fP
.IP CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE
See \fICURLMOPT_CONTENT_LENGTH_PENALTY_SIZE(3)\fP
.IP CURLMOPT_MAX_HOST_CONNECTIONS
See \fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP
.IP CURLMOPT_MAX_PIPELINE_LENGTH
See \fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP
.IP CURLMOPT_MAX_TOTAL_CONNECTIONS
See \fICURLMOPT_MAX_TOTAL_CONNECTIONS(3)\fP
.IP CURLMOPT_MAXCONNECTS
See \fICURLMOPT_MAXCONNECTS(3)\fP
.IP CURLMOPT_PIPELINING
See \fICURLMOPT_PIPELINING(3)\fP
.IP CURLMOPT_PIPELINING_SITE_BL
See \fICURLMOPT_PIPELINING_SITE_BL(3)\fP
.IP CURLMOPT_PIPELINING_SERVER_BL
See \fICURLMOPT_PIPELINING_SERVER_BL(3)\fP
.IP CURLMOPT_PUSHFUNCTION
See \fICURLMOPT_PUSHFUNCTION(3)\fP
.IP CURLMOPT_PUSHDATA
See \fICURLMOPT_PUSHDATA(3)\fP
.IP CURLMOPT_SOCKETFUNCTION
See \fICURLMOPT_SOCKETFUNCTION(3)\fP
.IP CURLMOPT_SOCKETDATA
See \fICURLMOPT_SOCKETDATA(3)\fP
.IP CURLMOPT_TIMERFUNCTION
See \fICURLMOPT_TIMERFUNCTION(3)\fP
.IP CURLMOPT_TIMERDATA
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 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
does not know of.
.SH "SEE ALSO"
.BR curl_multi_cleanup "(3), " curl_multi_init "(3), "
.BR curl_multi_socket "(3), " curl_multi_info_read "(3)"
share/man/man3/CURLOPT_SSLCERTTYPE.3 0000644 00000005053 14751150677 0012414 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SSLCERTTYPE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSLCERTTYPE \- type of client SSL certificate
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLCERTTYPE, char *type);
.fi
.SH DESCRIPTION
Pass a pointer to a null-terminated string as parameter. The string should be
the format of your certificate.
Supported formats are "PEM" and "DER", except with Secure Transport or
Schannel. OpenSSL (versions 0.9.3 and later), Secure Transport (on iOS 5 or
later, or OS X 10.7 or later) and Schannel support "P12" for PKCS#12-encoded
files.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
"PEM"
.SH PROTOCOLS
All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_SSLCERT, "client.pem");
curl_easy_setopt(curl, CURLOPT_SSLCERTTYPE, "PEM");
curl_easy_setopt(curl, CURLOPT_SSLKEY, "key.pem");
curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "s3cret");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
If built TLS enabled. Added in 7.9.3
.SH RETURN VALUE
Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_SSLCERT "(3), " CURLOPT_SSLKEY "(3), "
share/man/man3/CURLOPT_PROXY_ISSUERCERT_BLOB.3 0000644 00000007046 14751150677 0014066 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXY_ISSUERCERT_BLOB 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXY_ISSUERCERT_BLOB \- proxy issuer SSL certificate from memory blob
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_ISSUERCERT_BLOB,
struct curl_blob *blob);
.fi
.SH DESCRIPTION
Pass a pointer to a curl_blob struct, which contains information (pointer and
size) about a memory block with binary data of a CA certificate in PEM
format. If the option is set, an additional check against the peer certificate
is performed to verify the issuer of the the HTTPS proxy is indeed the one
associated with the certificate provided by the option. This additional check
is useful in multi-level PKI where one needs to enforce that the peer
certificate is from a specific branch of the tree.
This option should be used in combination with the
\fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP option. Otherwise, the result of the
check is not considered as failure.
A specific error code (CURLE_SSL_ISSUER_ERROR) is defined with the option,
which is returned if the setup of the SSL/TLS session has failed due to a
mismatch with the issuer of peer certificate
(\fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP has to be set too for the check to
fail).
If the blob is initialized with the flags member of struct curl_blob set to
CURL_BLOB_COPY, the application does not have to keep the buffer around after
setting this.
This option is an alternative to \fICURLOPT_PROXY_ISSUERCERT(3)\fP which
instead expects a file name as input.
.SH DEFAULT
NULL
.SH PROTOCOLS
All TLS-based protocols
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
struct curl_blob blob;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
/* using an HTTPS proxy */
curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost:443");
blob.data = certificateData;
blob.len = filesize;
blob.flags = CURL_BLOB_COPY;
curl_easy_setopt(curl, CURLOPT_PROXY_ISSUERCERT_BLOB, &blob);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.71.0. This option is supported by the OpenSSL backends.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_PROXY_SSL_VERIFYPEER "(3), " CURLOPT_PROXY_SSL_VERIFYHOST "(3), "
.BR CURLOPT_SSL_VERIFYPEER "(3), " CURLOPT_SSL_VERIFYHOST "(3), "
share/man/man3/CURLOPT_DOH_SSL_VERIFYSTATUS.3 0000644 00000005221 14751150677 0013753 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_DOH_SSL_VERIFYSTATUS 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_DOH_SSL_VERIFYSTATUS \- verify the DoH SSL certificate's status
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DOH_SSL_VERIFYSTATUS,
long verify);
.fi
.SH DESCRIPTION
Pass a long as parameter set to 1 to enable or 0 to disable.
This option determines whether libcurl verifies the status of the DoH
(DNS-over-HTTPS) server cert using the "Certificate Status Request" TLS
extension (aka. OCSP stapling).
This option is the DoH equivalent of \fICURLOPT_SSL_VERIFYSTATUS(3)\fP and
only affects requests to the DoH server.
Note that if this option is enabled but the server does not support the TLS
extension, the verification will fail.
.SH DEFAULT
0
.SH PROTOCOLS
DoH
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_DOH_URL, "https://cloudflare-dns.com/dns-query");
/* Ask for OCSP stapling when verifying the DoH server */
curl_easy_setopt(curl, CURLOPT_DOH_SSL_VERIFYSTATUS, 1L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.76.0. This option is currently only supported by the OpenSSL, GnuTLS
and NSS TLS backends.
.SH RETURN VALUE
Returns CURLE_OK if OCSP stapling is supported by the SSL backend, otherwise
returns CURLE_NOT_BUILT_IN.
.SH "SEE ALSO"
.BR CURLOPT_DOH_SSL_VERIFYHOST "(3), "
.BR CURLOPT_DOH_SSL_VERIFYPEER "(3), "
.BR CURLOPT_SSL_VERIFYSTATUS "(3), "
share/man/man3/libcurl-symbols.3 0000644 00000153266 14751150677 0012517 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH libcurl-symbols 3 "Oct 26, 2022" "libcurl 7.41.0" "libcurl symbols"
.SH NAME
libcurl-symbols \- libcurl symbol version information
.SH "libcurl symbols"
This man page details version information for public symbols provided in the
libcurl header files. This lists the first version in which the symbol was
introduced and for some symbols two additional information pieces:
The first version in which the symbol is marked "deprecated" - meaning that
since that version no new code should be written to use the symbol as it is
marked for getting removed in a future.
The last version that featured the specific symbol. Using the symbol in source
code will make it no longer compile error-free after that specified version.
This man page is automatically generated from the symbols-in-versions file.
.IP CURL_AT_LEAST_VERSION
Introduced in 7.43.0
.IP CURL_BLOB_COPY
Introduced in 7.71.0
.IP CURL_BLOB_NOCOPY
Introduced in 7.71.0
.IP CURL_CHUNK_BGN_FUNC_FAIL
Introduced in 7.21.0
.IP CURL_CHUNK_BGN_FUNC_OK
Introduced in 7.21.0
.IP CURL_CHUNK_BGN_FUNC_SKIP
Introduced in 7.21.0
.IP CURL_CHUNK_END_FUNC_FAIL
Introduced in 7.21.0
.IP CURL_CHUNK_END_FUNC_OK
Introduced in 7.21.0
.IP CURL_CSELECT_ERR
Introduced in 7.16.3
.IP CURL_CSELECT_IN
Introduced in 7.16.3
.IP CURL_CSELECT_OUT
Introduced in 7.16.3
.IP CURL_DID_MEMORY_FUNC_TYPEDEFS
Introduced in 7.49.0
.IP CURL_EASY_NONE
Introduced in 7.14.0
.IP CURL_EASY_TIMEOUT
Introduced in 7.14.0
.IP CURL_ERROR_SIZE
Introduced in 7.1
.IP CURL_FNMATCHFUNC_FAIL
Introduced in 7.21.0
.IP CURL_FNMATCHFUNC_MATCH
Introduced in 7.21.0
.IP CURL_FNMATCHFUNC_NOMATCH
Introduced in 7.21.0
.IP CURL_FORMADD_DISABLED
Introduced in 7.12.1
Deprecated since 7.56.0
.IP CURL_FORMADD_ILLEGAL_ARRAY
Introduced in 7.9.8
Deprecated since 7.56.0
.IP CURL_FORMADD_INCOMPLETE
Introduced in 7.9.8
Deprecated since 7.56.0
.IP CURL_FORMADD_MEMORY
Introduced in 7.9.8
Deprecated since 7.56.0
.IP CURL_FORMADD_NULL
Introduced in 7.9.8
Deprecated since 7.56.0
.IP CURL_FORMADD_OK
Introduced in 7.9.8
Deprecated since 7.56.0
.IP CURL_FORMADD_OPTION_TWICE
Introduced in 7.9.8
Deprecated since 7.56.0
.IP CURL_FORMADD_UNKNOWN_OPTION
Introduced in 7.9.8
Deprecated since 7.56.0
.IP CURL_GLOBAL_ACK_EINTR
Introduced in 7.30.0
.IP CURL_GLOBAL_ALL
Introduced in 7.8
.IP CURL_GLOBAL_DEFAULT
Introduced in 7.8
.IP CURL_GLOBAL_NOTHING
Introduced in 7.8
.IP CURL_GLOBAL_SSL
Introduced in 7.8
.IP CURL_GLOBAL_WIN32
Introduced in 7.8.1
.IP CURL_HET_DEFAULT
Introduced in 7.59.0
.IP CURL_HTTP_VERSION_1_0
Introduced in 7.9.1
.IP CURL_HTTP_VERSION_1_1
Introduced in 7.9.1
.IP CURL_HTTP_VERSION_2
Introduced in 7.43.0
.IP CURL_HTTP_VERSION_2_0
Introduced in 7.33.0
.IP CURL_HTTP_VERSION_2_PRIOR_KNOWLEDGE
Introduced in 7.49.0
.IP CURL_HTTP_VERSION_2TLS
Introduced in 7.47.0
.IP CURL_HTTP_VERSION_3
Introduced in 7.66.0
.IP CURL_HTTP_VERSION_NONE
Introduced in 7.9.1
.IP CURL_HTTPPOST_BUFFER
Introduced in 7.46.0
.IP CURL_HTTPPOST_CALLBACK
Introduced in 7.46.0
.IP CURL_HTTPPOST_FILENAME
Introduced in 7.46.0
.IP CURL_HTTPPOST_LARGE
Introduced in 7.46.0
.IP CURL_HTTPPOST_PTRBUFFER
Introduced in 7.46.0
.IP CURL_HTTPPOST_PTRCONTENTS
Introduced in 7.46.0
.IP CURL_HTTPPOST_PTRNAME
Introduced in 7.46.0
.IP CURL_HTTPPOST_READFILE
Introduced in 7.46.0
.IP CURL_IPRESOLVE_V4
Introduced in 7.10.8
.IP CURL_IPRESOLVE_V6
Introduced in 7.10.8
.IP CURL_IPRESOLVE_WHATEVER
Introduced in 7.10.8
.IP CURL_ISOCPP
Introduced in 7.10.2
.IP CURL_LOCK_ACCESS_NONE
Introduced in 7.10.3
.IP CURL_LOCK_ACCESS_SHARED
Introduced in 7.10.3
.IP CURL_LOCK_ACCESS_SINGLE
Introduced in 7.10.3
.IP CURL_LOCK_DATA_CONNECT
Introduced in 7.10.3
.IP CURL_LOCK_DATA_COOKIE
Introduced in 7.10.3
.IP CURL_LOCK_DATA_DNS
Introduced in 7.10.3
.IP CURL_LOCK_DATA_NONE
Introduced in 7.10.3
.IP CURL_LOCK_DATA_PSL
Introduced in 7.61.0
.IP CURL_LOCK_DATA_SHARE
Introduced in 7.10.4
.IP CURL_LOCK_DATA_SSL_SESSION
Introduced in 7.10.3
.IP CURL_LOCK_TYPE_CONNECT
Introduced in 7.10
.IP CURL_LOCK_TYPE_COOKIE
Introduced in 7.10
.IP CURL_LOCK_TYPE_DNS
Introduced in 7.10
.IP CURL_LOCK_TYPE_NONE
Introduced in 7.10
.IP CURL_LOCK_TYPE_SSL_SESSION
Introduced in 7.10
.IP CURL_MAX_HTTP_HEADER
Introduced in 7.19.7
.IP CURL_MAX_READ_SIZE
Introduced in 7.53.0
.IP CURL_MAX_WRITE_SIZE
Introduced in 7.9.7
.IP CURL_NETRC_IGNORED
Introduced in 7.9.8
.IP CURL_NETRC_OPTIONAL
Introduced in 7.9.8
.IP CURL_NETRC_REQUIRED
Introduced in 7.9.8
.IP CURL_POLL_IN
Introduced in 7.14.0
.IP CURL_POLL_INOUT
Introduced in 7.14.0
.IP CURL_POLL_NONE
Introduced in 7.14.0
.IP CURL_POLL_OUT
Introduced in 7.14.0
.IP CURL_POLL_REMOVE
Introduced in 7.14.0
.IP CURL_PREREQFUNC_ABORT
Introduced in 7.79.0
.IP CURL_PREREQFUNC_OK
Introduced in 7.79.0
.IP CURL_PROGRESS_BAR
Introduced in 7.1.1
.IP CURL_PROGRESS_STATS
Introduced in 7.1.1
.IP CURL_PROGRESSFUNC_CONTINUE
Introduced in 7.68.0
.IP CURL_PULL_SYS_POLL_H
Introduced in 7.56.0
.IP CURL_PUSH_DENY
Introduced in 7.44.0
.IP CURL_PUSH_ERROROUT
Introduced in 7.72.0
.IP CURL_PUSH_OK
Introduced in 7.44.0
.IP CURL_READFUNC_ABORT
Introduced in 7.12.1
.IP CURL_READFUNC_PAUSE
Introduced in 7.18.0
.IP CURL_REDIR_GET_ALL
Introduced in 7.19.1
.IP CURL_REDIR_POST_301
Introduced in 7.19.1
.IP CURL_REDIR_POST_302
Introduced in 7.19.1
.IP CURL_REDIR_POST_303
Introduced in 7.25.1
.IP CURL_REDIR_POST_ALL
Introduced in 7.19.1
.IP CURL_RTSPREQ_ANNOUNCE
Introduced in 7.20.0
.IP CURL_RTSPREQ_DESCRIBE
Introduced in 7.20.0
.IP CURL_RTSPREQ_GET_PARAMETER
Introduced in 7.20.0
.IP CURL_RTSPREQ_NONE
Introduced in 7.20.0
.IP CURL_RTSPREQ_OPTIONS
Introduced in 7.20.0
.IP CURL_RTSPREQ_PAUSE
Introduced in 7.20.0
.IP CURL_RTSPREQ_PLAY
Introduced in 7.20.0
.IP CURL_RTSPREQ_RECEIVE
Introduced in 7.20.0
.IP CURL_RTSPREQ_RECORD
Introduced in 7.20.0
.IP CURL_RTSPREQ_SET_PARAMETER
Introduced in 7.20.0
.IP CURL_RTSPREQ_SETUP
Introduced in 7.20.0
.IP CURL_RTSPREQ_TEARDOWN
Introduced in 7.20.0
.IP CURL_SEEKFUNC_CANTSEEK
Introduced in 7.19.5
.IP CURL_SEEKFUNC_FAIL
Introduced in 7.19.5
.IP CURL_SEEKFUNC_OK
Introduced in 7.19.5
.IP CURL_SOCKET_BAD
Introduced in 7.14.0
.IP CURL_SOCKET_TIMEOUT
Introduced in 7.14.0
.IP CURL_SOCKOPT_ALREADY_CONNECTED
Introduced in 7.21.5
.IP CURL_SOCKOPT_ERROR
Introduced in 7.21.5
.IP CURL_SOCKOPT_OK
Introduced in 7.21.5
.IP CURL_SSLVERSION_DEFAULT
Introduced in 7.9.2
.IP CURL_SSLVERSION_MAX_DEFAULT
Introduced in 7.54.0
.IP CURL_SSLVERSION_MAX_NONE
Introduced in 7.54.0
.IP CURL_SSLVERSION_MAX_TLSv1_0
Introduced in 7.54.0
.IP CURL_SSLVERSION_MAX_TLSv1_1
Introduced in 7.54.0
.IP CURL_SSLVERSION_MAX_TLSv1_2
Introduced in 7.54.0
.IP CURL_SSLVERSION_MAX_TLSv1_3
Introduced in 7.54.0
.IP CURL_SSLVERSION_SSLv2
Introduced in 7.9.2
.IP CURL_SSLVERSION_SSLv3
Introduced in 7.9.2
.IP CURL_SSLVERSION_TLSv1
Introduced in 7.9.2
.IP CURL_SSLVERSION_TLSv1_0
Introduced in 7.34.0
.IP CURL_SSLVERSION_TLSv1_1
Introduced in 7.34.0
.IP CURL_SSLVERSION_TLSv1_2
Introduced in 7.34.0
.IP CURL_SSLVERSION_TLSv1_3
Introduced in 7.52.0
.IP CURL_STRICTER
Introduced in 7.50.2
.IP CURL_TIMECOND_IFMODSINCE
Introduced in 7.9.7
.IP CURL_TIMECOND_IFUNMODSINCE
Introduced in 7.9.7
.IP CURL_TIMECOND_LASTMOD
Introduced in 7.9.7
.IP CURL_TIMECOND_NONE
Introduced in 7.9.7
.IP CURL_TLSAUTH_NONE
Introduced in 7.21.4
.IP CURL_TLSAUTH_SRP
Introduced in 7.21.4
.IP CURL_TRAILERFUNC_ABORT
Introduced in 7.64.0
.IP CURL_TRAILERFUNC_OK
Introduced in 7.64.0
.IP CURL_UPKEEP_INTERVAL_DEFAULT
Introduced in 7.62.0
.IP CURL_VERSION_ALTSVC
Introduced in 7.64.1
.IP CURL_VERSION_ASYNCHDNS
Introduced in 7.10.7
.IP CURL_VERSION_BITS
Introduced in 7.43.0
.IP CURL_VERSION_BROTLI
Introduced in 7.57.0
.IP CURL_VERSION_CONV
Introduced in 7.15.4
.IP CURL_VERSION_CURLDEBUG
Introduced in 7.19.6
.IP CURL_VERSION_DEBUG
Introduced in 7.10.6
.IP CURL_VERSION_GSASL
Introduced in 7.76.0
.IP CURL_VERSION_GSSAPI
Introduced in 7.38.0
.IP CURL_VERSION_GSSNEGOTIATE
Introduced in 7.10.6
Deprecated since 7.38.0
.IP CURL_VERSION_HSTS
Introduced in 7.74.0
.IP CURL_VERSION_HTTP2
Introduced in 7.33.0
.IP CURL_VERSION_HTTP3
Introduced in 7.66.0
.IP CURL_VERSION_HTTPS_PROXY
Introduced in 7.52.0
.IP CURL_VERSION_IDN
Introduced in 7.12.0
.IP CURL_VERSION_IPV6
Introduced in 7.10
.IP CURL_VERSION_KERBEROS4
Introduced in 7.10
Deprecated since 7.33.0
.IP CURL_VERSION_KERBEROS5
Introduced in 7.40.0
.IP CURL_VERSION_LARGEFILE
Introduced in 7.11.1
.IP CURL_VERSION_LIBZ
Introduced in 7.10
.IP CURL_VERSION_MULTI_SSL
Introduced in 7.56.0
.IP CURL_VERSION_NTLM
Introduced in 7.10.6
.IP CURL_VERSION_NTLM_WB
Introduced in 7.22.0
.IP CURL_VERSION_PSL
Introduced in 7.47.0
.IP CURL_VERSION_SPNEGO
Introduced in 7.10.8
.IP CURL_VERSION_SSL
Introduced in 7.10
.IP CURL_VERSION_SSPI
Introduced in 7.13.2
.IP CURL_VERSION_THREADSAFE
Introduced in 7.84.0
.IP CURL_VERSION_TLSAUTH_SRP
Introduced in 7.21.4
.IP CURL_VERSION_UNICODE
Introduced in 7.72.0
.IP CURL_VERSION_UNIX_SOCKETS
Introduced in 7.40.0
.IP CURL_VERSION_ZSTD
Introduced in 7.72.0
.IP CURL_WAIT_POLLIN
Introduced in 7.28.0
.IP CURL_WAIT_POLLOUT
Introduced in 7.28.0
.IP CURL_WAIT_POLLPRI
Introduced in 7.28.0
.IP CURL_WIN32
Introduced in 7.69.0
.IP CURL_WRITEFUNC_PAUSE
Introduced in 7.18.0
.IP CURL_ZERO_TERMINATED
Introduced in 7.56.0
.IP CURLALTSVC_H1
Introduced in 7.64.1
.IP CURLALTSVC_H2
Introduced in 7.64.1
.IP CURLALTSVC_H3
Introduced in 7.64.1
.IP CURLALTSVC_READONLYFILE
Introduced in 7.64.1
.IP CURLAUTH_ANY
Introduced in 7.10.6
.IP CURLAUTH_ANYSAFE
Introduced in 7.10.6
.IP CURLAUTH_AWS_SIGV4
Introduced in 7.75.0
.IP CURLAUTH_BASIC
Introduced in 7.10.6
.IP CURLAUTH_BEARER
Introduced in 7.61.0
.IP CURLAUTH_DIGEST
Introduced in 7.10.6
.IP CURLAUTH_DIGEST_IE
Introduced in 7.19.3
.IP CURLAUTH_GSSAPI
Introduced in 7.55.0
.IP CURLAUTH_GSSNEGOTIATE
Introduced in 7.10.6
Deprecated since 7.38.0
.IP CURLAUTH_NEGOTIATE
Introduced in 7.38.0
.IP CURLAUTH_NONE
Introduced in 7.10.6
.IP CURLAUTH_NTLM
Introduced in 7.10.6
.IP CURLAUTH_NTLM_WB
Introduced in 7.22.0
.IP CURLAUTH_ONLY
Introduced in 7.21.3
.IP CURLCLOSEPOLICY_CALLBACK
Introduced in 7.7
.IP CURLCLOSEPOLICY_LEAST_RECENTLY_USED
Introduced in 7.7
.IP CURLCLOSEPOLICY_LEAST_TRAFFIC
Introduced in 7.7
.IP CURLCLOSEPOLICY_NONE
Introduced in 7.7
.IP CURLCLOSEPOLICY_OLDEST
Introduced in 7.7
.IP CURLCLOSEPOLICY_SLOWEST
Introduced in 7.7
.IP CURLE_ABORTED_BY_CALLBACK
Introduced in 7.1
.IP CURLE_AGAIN
Introduced in 7.18.2
.IP CURLE_ALREADY_COMPLETE
Introduced in 7.7.2
Deprecated since 7.8
.IP CURLE_AUTH_ERROR
Introduced in 7.66.0
.IP CURLE_BAD_CALLING_ORDER
Introduced in 7.1
Deprecated since 7.17.0
.IP CURLE_BAD_CONTENT_ENCODING
Introduced in 7.10
.IP CURLE_BAD_DOWNLOAD_RESUME
Introduced in 7.10
.IP CURLE_BAD_FUNCTION_ARGUMENT
Introduced in 7.1
.IP CURLE_BAD_PASSWORD_ENTERED
Introduced in 7.4.2
Deprecated since 7.17.0
.IP CURLE_CHUNK_FAILED
Introduced in 7.21.0
.IP CURLE_CONV_FAILED
Introduced in 7.15.4
Deprecated since 7.82.0
.IP CURLE_CONV_REQD
Introduced in 7.15.4
Deprecated since 7.82.0
.IP CURLE_COULDNT_CONNECT
Introduced in 7.1
.IP CURLE_COULDNT_RESOLVE_HOST
Introduced in 7.1
.IP CURLE_COULDNT_RESOLVE_PROXY
Introduced in 7.1
.IP CURLE_FAILED_INIT
Introduced in 7.1
.IP CURLE_FILE_COULDNT_READ_FILE
Introduced in 7.1
.IP CURLE_FILESIZE_EXCEEDED
Introduced in 7.10.8
.IP CURLE_FTP_ACCEPT_FAILED
Introduced in 7.24.0
.IP CURLE_FTP_ACCEPT_TIMEOUT
Introduced in 7.24.0
.IP CURLE_FTP_ACCESS_DENIED
Introduced in 7.1
Deprecated since 7.17.0
.IP CURLE_FTP_BAD_DOWNLOAD_RESUME
Introduced in 7.1
Deprecated since 7.1
.IP CURLE_FTP_BAD_FILE_LIST
Introduced in 7.21.0
.IP CURLE_FTP_CANT_GET_HOST
Introduced in 7.1
.IP CURLE_FTP_CANT_RECONNECT
Introduced in 7.1
Deprecated since 7.17.0
.IP CURLE_FTP_COULDNT_GET_SIZE
Introduced in 7.1
Deprecated since 7.17.0
.IP CURLE_FTP_COULDNT_RETR_FILE
Introduced in 7.1
.IP CURLE_FTP_COULDNT_SET_ASCII
Introduced in 7.1
Deprecated since 7.17.0
.IP CURLE_FTP_COULDNT_SET_BINARY
Introduced in 7.1
Deprecated since 7.17.0
.IP CURLE_FTP_COULDNT_SET_TYPE
Introduced in 7.17.0
.IP CURLE_FTP_COULDNT_STOR_FILE
Introduced in 7.1
Deprecated since 7.16.3
.IP CURLE_FTP_COULDNT_USE_REST
Introduced in 7.1
.IP CURLE_FTP_PARTIAL_FILE
Introduced in 7.1
Deprecated since 7.1
.IP CURLE_FTP_PORT_FAILED
Introduced in 7.1
.IP CURLE_FTP_PRET_FAILED
Introduced in 7.20.0
.IP CURLE_FTP_QUOTE_ERROR
Introduced in 7.1
Deprecated since 7.17.0
.IP CURLE_FTP_SSL_FAILED
Introduced in 7.11.0
Deprecated since 7.17.0
.IP CURLE_FTP_USER_PASSWORD_INCORRECT
Introduced in 7.1
Deprecated since 7.17.0
.IP CURLE_FTP_WEIRD_227_FORMAT
Introduced in 7.1
.IP CURLE_FTP_WEIRD_PASS_REPLY
Introduced in 7.1
.IP CURLE_FTP_WEIRD_PASV_REPLY
Introduced in 7.1
.IP CURLE_FTP_WEIRD_SERVER_REPLY
Introduced in 7.1
Deprecated since 7.51.0
.IP CURLE_FTP_WEIRD_USER_REPLY
Introduced in 7.1
Deprecated since 7.17.0
.IP CURLE_FTP_WRITE_ERROR
Introduced in 7.1
Deprecated since 7.17.0
.IP CURLE_FUNCTION_NOT_FOUND
Introduced in 7.1
.IP CURLE_GOT_NOTHING
Introduced in 7.9.1
.IP CURLE_HTTP2
Introduced in 7.38.0
.IP CURLE_HTTP2_STREAM
Introduced in 7.49.0
.IP CURLE_HTTP3
Introduced in 7.68.0
.IP CURLE_HTTP_NOT_FOUND
Introduced in 7.1
Deprecated since 7.10.3
.IP CURLE_HTTP_PORT_FAILED
Introduced in 7.3
Deprecated since 7.12.0
.IP CURLE_HTTP_POST_ERROR
Introduced in 7.1
.IP CURLE_HTTP_RANGE_ERROR
Introduced in 7.1
Deprecated since 7.17.0
.IP CURLE_HTTP_RETURNED_ERROR
Introduced in 7.10.3
.IP CURLE_INTERFACE_FAILED
Introduced in 7.12.0
.IP CURLE_LDAP_CANNOT_BIND
Introduced in 7.1
.IP CURLE_LDAP_INVALID_URL
Introduced in 7.10.8
Deprecated since 7.82.0
.IP CURLE_LDAP_SEARCH_FAILED
Introduced in 7.1
.IP CURLE_LIBRARY_NOT_FOUND
Introduced in 7.1
Deprecated since 7.17.0
.IP CURLE_LOGIN_DENIED
Introduced in 7.13.1
.IP CURLE_MALFORMAT_USER
Introduced in 7.1
Deprecated since 7.17.0
.IP CURLE_NO_CONNECTION_AVAILABLE
Introduced in 7.30.0
.IP CURLE_NOT_BUILT_IN
Introduced in 7.21.5
.IP CURLE_OK
Introduced in 7.1
.IP CURLE_OPERATION_TIMEDOUT
Introduced in 7.10.2
.IP CURLE_OPERATION_TIMEOUTED
Introduced in 7.1
Deprecated since 7.17.0
.IP CURLE_OUT_OF_MEMORY
Introduced in 7.1
.IP CURLE_PARTIAL_FILE
Introduced in 7.1
.IP CURLE_PEER_FAILED_VERIFICATION
Introduced in 7.17.1
.IP CURLE_PROXY
Introduced in 7.73.0
.IP CURLE_QUIC_CONNECT_ERROR
Introduced in 7.69.0
.IP CURLE_QUOTE_ERROR
Introduced in 7.17.0
.IP CURLE_RANGE_ERROR
Introduced in 7.17.0
.IP CURLE_READ_ERROR
Introduced in 7.1
.IP CURLE_RECURSIVE_API_CALL
Introduced in 7.59.0
.IP CURLE_RECV_ERROR
Introduced in 7.10
.IP CURLE_REMOTE_ACCESS_DENIED
Introduced in 7.17.0
.IP CURLE_REMOTE_DISK_FULL
Introduced in 7.17.0
.IP CURLE_REMOTE_FILE_EXISTS
Introduced in 7.17.0
.IP CURLE_REMOTE_FILE_NOT_FOUND
Introduced in 7.16.1
.IP CURLE_RTSP_CSEQ_ERROR
Introduced in 7.20.0
.IP CURLE_RTSP_SESSION_ERROR
Introduced in 7.20.0
.IP CURLE_SEND_ERROR
Introduced in 7.10
.IP CURLE_SEND_FAIL_REWIND
Introduced in 7.12.3
.IP CURLE_SETOPT_OPTION_SYNTAX
Introduced in 7.78.0
.IP CURLE_SHARE_IN_USE
Introduced in 7.9.6
Deprecated since 7.17.0
.IP CURLE_SSH
Introduced in 7.16.1
.IP CURLE_SSL_CACERT
Introduced in 7.10
Deprecated since 7.62.0
.IP CURLE_SSL_CACERT_BADFILE
Introduced in 7.16.0
.IP CURLE_SSL_CERTPROBLEM
Introduced in 7.10
.IP CURLE_SSL_CIPHER
Introduced in 7.10
.IP CURLE_SSL_CLIENTCERT
Introduced in 7.77.0
.IP CURLE_SSL_CONNECT_ERROR
Introduced in 7.1
.IP CURLE_SSL_CRL_BADFILE
Introduced in 7.19.0
.IP CURLE_SSL_ENGINE_INITFAILED
Introduced in 7.12.3
.IP CURLE_SSL_ENGINE_NOTFOUND
Introduced in 7.9.3
.IP CURLE_SSL_ENGINE_SETFAILED
Introduced in 7.9.3
.IP CURLE_SSL_INVALIDCERTSTATUS
Introduced in 7.41.0
.IP CURLE_SSL_ISSUER_ERROR
Introduced in 7.19.0
.IP CURLE_SSL_PEER_CERTIFICATE
Introduced in 7.8
Deprecated since 7.17.1
.IP CURLE_SSL_PINNEDPUBKEYNOTMATCH
Introduced in 7.39.0
.IP CURLE_SSL_SHUTDOWN_FAILED
Introduced in 7.16.1
.IP CURLE_TELNET_OPTION_SYNTAX
Introduced in 7.7
.IP CURLE_TFTP_DISKFULL
Introduced in 7.15.0
Deprecated since 7.17.0
.IP CURLE_TFTP_EXISTS
Introduced in 7.15.0
Deprecated since 7.17.0
.IP CURLE_TFTP_ILLEGAL
Introduced in 7.15.0
.IP CURLE_TFTP_NOSUCHUSER
Introduced in 7.15.0
.IP CURLE_TFTP_NOTFOUND
Introduced in 7.15.0
.IP CURLE_TFTP_PERM
Introduced in 7.15.0
.IP CURLE_TFTP_UNKNOWNID
Introduced in 7.15.0
.IP CURLE_TOO_MANY_REDIRECTS
Introduced in 7.5
.IP CURLE_UNKNOWN_OPTION
Introduced in 7.21.5
.IP CURLE_UNKNOWN_TELNET_OPTION
Introduced in 7.7
Deprecated since 7.21.5
.IP CURLE_UNRECOVERABLE_POLL
Introduced in 7.84.0
.IP CURLE_UNSUPPORTED_PROTOCOL
Introduced in 7.1
.IP CURLE_UPLOAD_FAILED
Introduced in 7.16.3
.IP CURLE_URL_MALFORMAT
Introduced in 7.1
.IP CURLE_URL_MALFORMAT_USER
Introduced in 7.1
Deprecated since 7.17.0
.IP CURLE_USE_SSL_FAILED
Introduced in 7.17.0
.IP CURLE_WEIRD_SERVER_REPLY
Introduced in 7.51.0
.IP CURLE_WRITE_ERROR
Introduced in 7.1
.IP CURLFILETYPE_DEVICE_BLOCK
Introduced in 7.21.0
.IP CURLFILETYPE_DEVICE_CHAR
Introduced in 7.21.0
.IP CURLFILETYPE_DIRECTORY
Introduced in 7.21.0
.IP CURLFILETYPE_DOOR
Introduced in 7.21.0
.IP CURLFILETYPE_FILE
Introduced in 7.21.0
.IP CURLFILETYPE_NAMEDPIPE
Introduced in 7.21.0
.IP CURLFILETYPE_SOCKET
Introduced in 7.21.0
.IP CURLFILETYPE_SYMLINK
Introduced in 7.21.0
.IP CURLFILETYPE_UNKNOWN
Introduced in 7.21.0
.IP CURLFINFOFLAG_KNOWN_FILENAME
Introduced in 7.21.0
.IP CURLFINFOFLAG_KNOWN_FILETYPE
Introduced in 7.21.0
.IP CURLFINFOFLAG_KNOWN_GID
Introduced in 7.21.0
.IP CURLFINFOFLAG_KNOWN_HLINKCOUNT
Introduced in 7.21.0
.IP CURLFINFOFLAG_KNOWN_PERM
Introduced in 7.21.0
.IP CURLFINFOFLAG_KNOWN_SIZE
Introduced in 7.21.0
.IP CURLFINFOFLAG_KNOWN_TIME
Introduced in 7.21.0
.IP CURLFINFOFLAG_KNOWN_UID
Introduced in 7.21.0
.IP CURLFORM_ARRAY
Introduced in 7.9.1
Deprecated since 7.56.0
.IP CURLFORM_ARRAY_END
Introduced in 7.9.1
Deprecated since 7.9.5
Last used in 7.9.6
.IP CURLFORM_ARRAY_START
Introduced in 7.9.1
Deprecated since 7.9.5
Last used in 7.9.6
.IP CURLFORM_BUFFER
Introduced in 7.9.8
Deprecated since 7.56.0
.IP CURLFORM_BUFFERLENGTH
Introduced in 7.9.8
Deprecated since 7.56.0
.IP CURLFORM_BUFFERPTR
Introduced in 7.9.8
Deprecated since 7.56.0
.IP CURLFORM_CONTENTHEADER
Introduced in 7.9.3
Deprecated since 7.56.0
.IP CURLFORM_CONTENTLEN
Introduced in 7.46.0
Deprecated since 7.56.0
.IP CURLFORM_CONTENTSLENGTH
Introduced in 7.9
Deprecated since 7.56.0
.IP CURLFORM_CONTENTTYPE
Introduced in 7.9
Deprecated since 7.56.0
.IP CURLFORM_COPYCONTENTS
Introduced in 7.9
Deprecated since 7.56.0
.IP CURLFORM_COPYNAME
Introduced in 7.9
Deprecated since 7.56.0
.IP CURLFORM_END
Introduced in 7.9
Deprecated since 7.56.0
.IP CURLFORM_FILE
Introduced in 7.9
Deprecated since 7.56.0
.IP CURLFORM_FILECONTENT
Introduced in 7.9.1
Deprecated since 7.56.0
.IP CURLFORM_FILENAME
Introduced in 7.9.6
Deprecated since 7.56.0
.IP CURLFORM_NAMELENGTH
Introduced in 7.9
Deprecated since 7.56.0
.IP CURLFORM_NOTHING
Introduced in 7.9
Deprecated since 7.56.0
.IP CURLFORM_PTRCONTENTS
Introduced in 7.9
Deprecated since 7.56.0
.IP CURLFORM_PTRNAME
Introduced in 7.9
Deprecated since 7.56.0
.IP CURLFORM_STREAM
Introduced in 7.18.2
Deprecated since 7.56.0
.IP CURLFTP_CREATE_DIR
Introduced in 7.19.4
.IP CURLFTP_CREATE_DIR_NONE
Introduced in 7.19.4
.IP CURLFTP_CREATE_DIR_RETRY
Introduced in 7.19.4
.IP CURLFTPAUTH_DEFAULT
Introduced in 7.12.2
.IP CURLFTPAUTH_SSL
Introduced in 7.12.2
.IP CURLFTPAUTH_TLS
Introduced in 7.12.2
.IP CURLFTPMETHOD_DEFAULT
Introduced in 7.15.3
.IP CURLFTPMETHOD_MULTICWD
Introduced in 7.15.3
.IP CURLFTPMETHOD_NOCWD
Introduced in 7.15.3
.IP CURLFTPMETHOD_SINGLECWD
Introduced in 7.15.3
.IP CURLFTPSSL_ALL
Introduced in 7.11.0
Deprecated since 7.17.0
.IP CURLFTPSSL_CCC_ACTIVE
Introduced in 7.16.2
.IP CURLFTPSSL_CCC_NONE
Introduced in 7.16.2
.IP CURLFTPSSL_CCC_PASSIVE
Introduced in 7.16.1
.IP CURLFTPSSL_CONTROL
Introduced in 7.11.0
Deprecated since 7.17.0
.IP CURLFTPSSL_NONE
Introduced in 7.11.0
Deprecated since 7.17.0
.IP CURLFTPSSL_TRY
Introduced in 7.11.0
Deprecated since 7.17.0
.IP CURLGSSAPI_DELEGATION_FLAG
Introduced in 7.22.0
.IP CURLGSSAPI_DELEGATION_NONE
Introduced in 7.22.0
.IP CURLGSSAPI_DELEGATION_POLICY_FLAG
Introduced in 7.22.0
.IP CURLH_1XX
Introduced in 7.83.0
.IP CURLH_CONNECT
Introduced in 7.83.0
.IP CURLH_HEADER
Introduced in 7.83.0
.IP CURLH_PSEUDO
Introduced in 7.83.0
.IP CURLH_TRAILER
Introduced in 7.83.0
.IP CURLHE_BAD_ARGUMENT
Introduced in 7.83.0
.IP CURLHE_BADINDEX
Introduced in 7.83.0
.IP CURLHE_MISSING
Introduced in 7.83.0
.IP CURLHE_NOHEADERS
Introduced in 7.83.0
.IP CURLHE_NOREQUEST
Introduced in 7.83.0
.IP CURLHE_NOT_BUILT_IN
Introduced in 7.83.0
.IP CURLHE_OK
Introduced in 7.83.0
.IP CURLHE_OUT_OF_MEMORY
Introduced in 7.83.0
.IP CURLHEADER_SEPARATE
Introduced in 7.37.0
.IP CURLHEADER_UNIFIED
Introduced in 7.37.0
.IP CURLHSTS_ENABLE
Introduced in 7.74.0
.IP CURLHSTS_READONLYFILE
Introduced in 7.74.0
.IP CURLINFO_ACTIVESOCKET
Introduced in 7.45.0
.IP CURLINFO_APPCONNECT_TIME
Introduced in 7.19.0
.IP CURLINFO_APPCONNECT_TIME_T
Introduced in 7.61.0
.IP CURLINFO_CAINFO
Introduced in 7.84.0
.IP CURLINFO_CAPATH
Introduced in 7.84.0
.IP CURLINFO_CERTINFO
Introduced in 7.19.1
.IP CURLINFO_CONDITION_UNMET
Introduced in 7.19.4
.IP CURLINFO_CONNECT_TIME
Introduced in 7.4.1
.IP CURLINFO_CONNECT_TIME_T
Introduced in 7.61.0
.IP CURLINFO_CONTENT_LENGTH_DOWNLOAD
Introduced in 7.6.1
Deprecated since 7.55.0
.IP CURLINFO_CONTENT_LENGTH_DOWNLOAD_T
Introduced in 7.55.0
.IP CURLINFO_CONTENT_LENGTH_UPLOAD
Introduced in 7.6.1
Deprecated since 7.55.0
.IP CURLINFO_CONTENT_LENGTH_UPLOAD_T
Introduced in 7.55.0
.IP CURLINFO_CONTENT_TYPE
Introduced in 7.9.4
.IP CURLINFO_COOKIELIST
Introduced in 7.14.1
.IP CURLINFO_DATA_IN
Introduced in 7.9.6
.IP CURLINFO_DATA_OUT
Introduced in 7.9.6
.IP CURLINFO_DOUBLE
Introduced in 7.4.1
.IP CURLINFO_EFFECTIVE_METHOD
Introduced in 7.72.0
.IP CURLINFO_EFFECTIVE_URL
Introduced in 7.4
.IP CURLINFO_END
Introduced in 7.9.6
.IP CURLINFO_FILETIME
Introduced in 7.5
.IP CURLINFO_FILETIME_T
Introduced in 7.59.0
.IP CURLINFO_FTP_ENTRY_PATH
Introduced in 7.15.4
.IP CURLINFO_HEADER_IN
Introduced in 7.9.6
.IP CURLINFO_HEADER_OUT
Introduced in 7.9.6
.IP CURLINFO_HEADER_SIZE
Introduced in 7.4.1
.IP CURLINFO_HTTP_CODE
Introduced in 7.4.1
Deprecated since 7.10.8
.IP CURLINFO_HTTP_CONNECTCODE
Introduced in 7.10.7
.IP CURLINFO_HTTP_VERSION
Introduced in 7.50.0
.IP CURLINFO_HTTPAUTH_AVAIL
Introduced in 7.10.8
.IP CURLINFO_LASTONE
Introduced in 7.4.1
.IP CURLINFO_LASTSOCKET
Introduced in 7.15.2
Deprecated since 7.45.0
.IP CURLINFO_LOCAL_IP
Introduced in 7.21.0
.IP CURLINFO_LOCAL_PORT
Introduced in 7.21.0
.IP CURLINFO_LONG
Introduced in 7.4.1
.IP CURLINFO_MASK
Introduced in 7.4.1
.IP CURLINFO_NAMELOOKUP_TIME
Introduced in 7.4.1
.IP CURLINFO_NAMELOOKUP_TIME_T
Introduced in 7.61.0
.IP CURLINFO_NONE
Introduced in 7.4.1
.IP CURLINFO_NUM_CONNECTS
Introduced in 7.12.3
.IP CURLINFO_OFF_T
Introduced in 7.55.0
.IP CURLINFO_OS_ERRNO
Introduced in 7.12.2
.IP CURLINFO_PRETRANSFER_TIME
Introduced in 7.4.1
.IP CURLINFO_PRETRANSFER_TIME_T
Introduced in 7.61.0
.IP CURLINFO_PRIMARY_IP
Introduced in 7.19.0
.IP CURLINFO_PRIMARY_PORT
Introduced in 7.21.0
.IP CURLINFO_PRIVATE
Introduced in 7.10.3
.IP CURLINFO_PROTOCOL
Introduced in 7.52.0
Deprecated since 7.85.0
.IP CURLINFO_PROXY_ERROR
Introduced in 7.73.0
.IP CURLINFO_PROXY_SSL_VERIFYRESULT
Introduced in 7.52.0
.IP CURLINFO_PROXYAUTH_AVAIL
Introduced in 7.10.8
.IP CURLINFO_PTR
Introduced in 7.54.1
.IP CURLINFO_REDIRECT_COUNT
Introduced in 7.9.7
.IP CURLINFO_REDIRECT_TIME
Introduced in 7.9.7
.IP CURLINFO_REDIRECT_TIME_T
Introduced in 7.61.0
.IP CURLINFO_REDIRECT_URL
Introduced in 7.18.2
.IP CURLINFO_REFERER
Introduced in 7.76.0
.IP CURLINFO_REQUEST_SIZE
Introduced in 7.4.1
.IP CURLINFO_RESPONSE_CODE
Introduced in 7.10.8
.IP CURLINFO_RETRY_AFTER
Introduced in 7.66.0
.IP CURLINFO_RTSP_CLIENT_CSEQ
Introduced in 7.20.0
.IP CURLINFO_RTSP_CSEQ_RECV
Introduced in 7.20.0
.IP CURLINFO_RTSP_SERVER_CSEQ
Introduced in 7.20.0
.IP CURLINFO_RTSP_SESSION_ID
Introduced in 7.20.0
.IP CURLINFO_SCHEME
Introduced in 7.52.0
.IP CURLINFO_SIZE_DOWNLOAD
Introduced in 7.4.1
Deprecated since 7.55.0
.IP CURLINFO_SIZE_DOWNLOAD_T
Introduced in 7.55.0
.IP CURLINFO_SIZE_UPLOAD
Introduced in 7.4.1
Deprecated since 7.55.0
.IP CURLINFO_SIZE_UPLOAD_T
Introduced in 7.55.0
.IP CURLINFO_SLIST
Introduced in 7.12.3
.IP CURLINFO_SOCKET
Introduced in 7.45.0
.IP CURLINFO_SPEED_DOWNLOAD
Introduced in 7.4.1
Deprecated since 7.55.0
.IP CURLINFO_SPEED_DOWNLOAD_T
Introduced in 7.55.0
.IP CURLINFO_SPEED_UPLOAD
Introduced in 7.4.1
Deprecated since 7.55.0
.IP CURLINFO_SPEED_UPLOAD_T
Introduced in 7.55.0
.IP CURLINFO_SSL_DATA_IN
Introduced in 7.12.1
.IP CURLINFO_SSL_DATA_OUT
Introduced in 7.12.1
.IP CURLINFO_SSL_ENGINES
Introduced in 7.12.3
.IP CURLINFO_SSL_VERIFYRESULT
Introduced in 7.5
.IP CURLINFO_STARTTRANSFER_TIME
Introduced in 7.9.2
.IP CURLINFO_STARTTRANSFER_TIME_T
Introduced in 7.61.0
.IP CURLINFO_STRING
Introduced in 7.4.1
.IP CURLINFO_TEXT
Introduced in 7.9.6
.IP CURLINFO_TLS_SESSION
Introduced in 7.34.0
Deprecated since 7.48.0
.IP CURLINFO_TLS_SSL_PTR
Introduced in 7.48.0
.IP CURLINFO_TOTAL_TIME
Introduced in 7.4.1
.IP CURLINFO_TOTAL_TIME_T
Introduced in 7.61.0
.IP CURLINFO_TYPEMASK
Introduced in 7.4.1
.IP CURLIOCMD_NOP
Introduced in 7.12.3
.IP CURLIOCMD_RESTARTREAD
Introduced in 7.12.3
.IP CURLIOE_FAILRESTART
Introduced in 7.12.3
.IP CURLIOE_OK
Introduced in 7.12.3
.IP CURLIOE_UNKNOWNCMD
Introduced in 7.12.3
.IP CURLKHMATCH_MISMATCH
Introduced in 7.19.6
.IP CURLKHMATCH_MISSING
Introduced in 7.19.6
.IP CURLKHMATCH_OK
Introduced in 7.19.6
.IP CURLKHSTAT_DEFER
Introduced in 7.19.6
.IP CURLKHSTAT_FINE
Introduced in 7.19.6
.IP CURLKHSTAT_FINE_ADD_TO_FILE
Introduced in 7.19.6
.IP CURLKHSTAT_FINE_REPLACE
Introduced in 7.73.0
.IP CURLKHSTAT_REJECT
Introduced in 7.19.6
.IP CURLKHTYPE_DSS
Introduced in 7.19.6
.IP CURLKHTYPE_ECDSA
Introduced in 7.58.0
.IP CURLKHTYPE_ED25519
Introduced in 7.58.0
.IP CURLKHTYPE_RSA
Introduced in 7.19.6
.IP CURLKHTYPE_RSA1
Introduced in 7.19.6
.IP CURLKHTYPE_UNKNOWN
Introduced in 7.19.6
.IP CURLM_ABORTED_BY_CALLBACK
Introduced in 7.81.0
.IP CURLM_ADDED_ALREADY
Introduced in 7.32.1
.IP CURLM_BAD_EASY_HANDLE
Introduced in 7.9.6
.IP CURLM_BAD_FUNCTION_ARGUMENT
Introduced in 7.69.0
.IP CURLM_BAD_HANDLE
Introduced in 7.9.6
.IP CURLM_BAD_SOCKET
Introduced in 7.15.4
.IP CURLM_CALL_MULTI_PERFORM
Introduced in 7.9.6
.IP CURLM_CALL_MULTI_SOCKET
Introduced in 7.15.5
.IP CURLM_INTERNAL_ERROR
Introduced in 7.9.6
.IP CURLM_OK
Introduced in 7.9.6
.IP CURLM_OUT_OF_MEMORY
Introduced in 7.9.6
.IP CURLM_RECURSIVE_API_CALL
Introduced in 7.59.0
.IP CURLM_UNKNOWN_OPTION
Introduced in 7.15.4
.IP CURLM_UNRECOVERABLE_POLL
Introduced in 7.84.0
.IP CURLM_WAKEUP_FAILURE
Introduced in 7.68.0
.IP CURLMIMEOPT_FORMESCAPE
Introduced in 7.81.0
.IP CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE
Introduced in 7.30.0
.IP CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE
Introduced in 7.30.0
.IP CURLMOPT_MAX_CONCURRENT_STREAMS
Introduced in 7.67.0
.IP CURLMOPT_MAX_HOST_CONNECTIONS
Introduced in 7.30.0
.IP CURLMOPT_MAX_PIPELINE_LENGTH
Introduced in 7.30.0
.IP CURLMOPT_MAX_TOTAL_CONNECTIONS
Introduced in 7.30.0
.IP CURLMOPT_MAXCONNECTS
Introduced in 7.16.3
.IP CURLMOPT_PIPELINING
Introduced in 7.16.0
.IP CURLMOPT_PIPELINING_SERVER_BL
Introduced in 7.30.0
.IP CURLMOPT_PIPELINING_SITE_BL
Introduced in 7.30.0
.IP CURLMOPT_PUSHDATA
Introduced in 7.44.0
.IP CURLMOPT_PUSHFUNCTION
Introduced in 7.44.0
.IP CURLMOPT_SOCKETDATA
Introduced in 7.15.4
.IP CURLMOPT_SOCKETFUNCTION
Introduced in 7.15.4
.IP CURLMOPT_TIMERDATA
Introduced in 7.16.0
.IP CURLMOPT_TIMERFUNCTION
Introduced in 7.16.0
.IP CURLMSG_DONE
Introduced in 7.9.6
.IP CURLMSG_NONE
Introduced in 7.9.6
.IP CURLOPT
Introduced in 7.69.0
.IP CURLOPT_ABSTRACT_UNIX_SOCKET
Introduced in 7.53.0
.IP CURLOPT_ACCEPT_ENCODING
Introduced in 7.21.6
.IP CURLOPT_ACCEPTTIMEOUT_MS
Introduced in 7.24.0
.IP CURLOPT_ADDRESS_SCOPE
Introduced in 7.19.0
.IP CURLOPT_ALTSVC
Introduced in 7.64.1
.IP CURLOPT_ALTSVC_CTRL
Introduced in 7.64.1
.IP CURLOPT_APPEND
Introduced in 7.17.0
.IP CURLOPT_AUTOREFERER
Introduced in 7.1
.IP CURLOPT_AWS_SIGV4
Introduced in 7.75.0
.IP CURLOPT_BUFFERSIZE
Introduced in 7.10
.IP CURLOPT_CAINFO
Introduced in 7.4.2
.IP CURLOPT_CAINFO_BLOB
Introduced in 7.77.0
.IP CURLOPT_CAPATH
Introduced in 7.9.8
.IP CURLOPT_CERTINFO
Introduced in 7.19.1
.IP CURLOPT_CHUNK_BGN_FUNCTION
Introduced in 7.21.0
.IP CURLOPT_CHUNK_DATA
Introduced in 7.21.0
.IP CURLOPT_CHUNK_END_FUNCTION
Introduced in 7.21.0
.IP CURLOPT_CLOSEFUNCTION
Introduced in 7.7
Deprecated since 7.11.1
Last used in 7.15.5
.IP CURLOPT_CLOSEPOLICY
Introduced in 7.7
Deprecated since 7.16.1
.IP CURLOPT_CLOSESOCKETDATA
Introduced in 7.21.7
.IP CURLOPT_CLOSESOCKETFUNCTION
Introduced in 7.21.7
.IP CURLOPT_CONNECT_ONLY
Introduced in 7.15.2
.IP CURLOPT_CONNECT_TO
Introduced in 7.49.0
.IP CURLOPT_CONNECTTIMEOUT
Introduced in 7.7
.IP CURLOPT_CONNECTTIMEOUT_MS
Introduced in 7.16.2
.IP CURLOPT_CONV_FROM_NETWORK_FUNCTION
Introduced in 7.15.4
Deprecated since 7.82.0
.IP CURLOPT_CONV_FROM_UTF8_FUNCTION
Introduced in 7.15.4
Deprecated since 7.82.0
.IP CURLOPT_CONV_TO_NETWORK_FUNCTION
Introduced in 7.15.4
Deprecated since 7.82.0
.IP CURLOPT_COOKIE
Introduced in 7.1
.IP CURLOPT_COOKIEFILE
Introduced in 7.1
.IP CURLOPT_COOKIEJAR
Introduced in 7.9
.IP CURLOPT_COOKIELIST
Introduced in 7.14.1
.IP CURLOPT_COOKIESESSION
Introduced in 7.9.7
.IP CURLOPT_COPYPOSTFIELDS
Introduced in 7.17.1
.IP CURLOPT_CRLF
Introduced in 7.1
.IP CURLOPT_CRLFILE
Introduced in 7.19.0
.IP CURLOPT_CURLU
Introduced in 7.63.0
.IP CURLOPT_CUSTOMREQUEST
Introduced in 7.1
.IP CURLOPT_DEBUGDATA
Introduced in 7.9.6
.IP CURLOPT_DEBUGFUNCTION
Introduced in 7.9.6
.IP CURLOPT_DEFAULT_PROTOCOL
Introduced in 7.45.0
.IP CURLOPT_DIRLISTONLY
Introduced in 7.17.0
.IP CURLOPT_DISALLOW_USERNAME_IN_URL
Introduced in 7.61.0
.IP CURLOPT_DNS_CACHE_TIMEOUT
Introduced in 7.9.3
.IP CURLOPT_DNS_INTERFACE
Introduced in 7.33.0
.IP CURLOPT_DNS_LOCAL_IP4
Introduced in 7.33.0
.IP CURLOPT_DNS_LOCAL_IP6
Introduced in 7.33.0
.IP CURLOPT_DNS_SERVERS
Introduced in 7.24.0
.IP CURLOPT_DNS_SHUFFLE_ADDRESSES
Introduced in 7.60.0
.IP CURLOPT_DNS_USE_GLOBAL_CACHE
Introduced in 7.9.3
Deprecated since 7.11.1
.IP CURLOPT_DOH_SSL_VERIFYHOST
Introduced in 7.76.0
.IP CURLOPT_DOH_SSL_VERIFYPEER
Introduced in 7.76.0
.IP CURLOPT_DOH_SSL_VERIFYSTATUS
Introduced in 7.76.0
.IP CURLOPT_DOH_URL
Introduced in 7.62.0
.IP CURLOPT_EGDSOCKET
Introduced in 7.7
Deprecated since 7.84.0
.IP CURLOPT_ENCODING
Introduced in 7.10
Deprecated since 7.21.6
.IP CURLOPT_ERRORBUFFER
Introduced in 7.1
.IP CURLOPT_EXPECT_100_TIMEOUT_MS
Introduced in 7.36.0
.IP CURLOPT_FAILONERROR
Introduced in 7.1
.IP CURLOPT_FILE
Introduced in 7.1
Deprecated since 7.9.7
.IP CURLOPT_FILETIME
Introduced in 7.5
.IP CURLOPT_FNMATCH_DATA
Introduced in 7.21.0
.IP CURLOPT_FNMATCH_FUNCTION
Introduced in 7.21.0
.IP CURLOPT_FOLLOWLOCATION
Introduced in 7.1
.IP CURLOPT_FORBID_REUSE
Introduced in 7.7
.IP CURLOPT_FRESH_CONNECT
Introduced in 7.7
.IP CURLOPT_FTP_ACCOUNT
Introduced in 7.13.0
.IP CURLOPT_FTP_ALTERNATIVE_TO_USER
Introduced in 7.15.5
.IP CURLOPT_FTP_CREATE_MISSING_DIRS
Introduced in 7.10.7
.IP CURLOPT_FTP_FILEMETHOD
Introduced in 7.15.1
.IP CURLOPT_FTP_RESPONSE_TIMEOUT
Introduced in 7.10.8
Deprecated since 7.85.0
.IP CURLOPT_FTP_SKIP_PASV_IP
Introduced in 7.15.0
.IP CURLOPT_FTP_SSL
Introduced in 7.11.0
Deprecated since 7.16.4
.IP CURLOPT_FTP_SSL_CCC
Introduced in 7.16.1
.IP CURLOPT_FTP_USE_EPRT
Introduced in 7.10.5
.IP CURLOPT_FTP_USE_EPSV
Introduced in 7.9.2
.IP CURLOPT_FTP_USE_PRET
Introduced in 7.20.0
.IP CURLOPT_FTPAPPEND
Introduced in 7.1
Deprecated since 7.16.4
.IP CURLOPT_FTPASCII
Introduced in 7.1
Deprecated since 7.11.1
Last used in 7.15.5
.IP CURLOPT_FTPLISTONLY
Introduced in 7.1
Deprecated since 7.16.4
.IP CURLOPT_FTPPORT
Introduced in 7.1
.IP CURLOPT_FTPSSLAUTH
Introduced in 7.12.2
.IP CURLOPT_GSSAPI_DELEGATION
Introduced in 7.22.0
.IP CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS
Introduced in 7.59.0
.IP CURLOPT_HAPROXYPROTOCOL
Introduced in 7.60.0
.IP CURLOPT_HEADER
Introduced in 7.1
.IP CURLOPT_HEADERDATA
Introduced in 7.10
.IP CURLOPT_HEADERFUNCTION
Introduced in 7.7.2
.IP CURLOPT_HEADEROPT
Introduced in 7.37.0
.IP CURLOPT_HSTS
Introduced in 7.74.0
.IP CURLOPT_HSTS_CTRL
Introduced in 7.74.0
.IP CURLOPT_HSTSREADDATA
Introduced in 7.74.0
.IP CURLOPT_HSTSREADFUNCTION
Introduced in 7.74.0
.IP CURLOPT_HSTSWRITEDATA
Introduced in 7.74.0
.IP CURLOPT_HSTSWRITEFUNCTION
Introduced in 7.74.0
.IP CURLOPT_HTTP09_ALLOWED
Introduced in 7.64.0
.IP CURLOPT_HTTP200ALIASES
Introduced in 7.10.3
.IP CURLOPT_HTTP_CONTENT_DECODING
Introduced in 7.16.2
.IP CURLOPT_HTTP_TRANSFER_DECODING
Introduced in 7.16.2
.IP CURLOPT_HTTP_VERSION
Introduced in 7.9.1
.IP CURLOPT_HTTPAUTH
Introduced in 7.10.6
.IP CURLOPT_HTTPGET
Introduced in 7.8.1
.IP CURLOPT_HTTPHEADER
Introduced in 7.1
.IP CURLOPT_HTTPPOST
Introduced in 7.1
Deprecated since 7.56.0
.IP CURLOPT_HTTPPROXYTUNNEL
Introduced in 7.3
.IP CURLOPT_HTTPREQUEST
Introduced in 7.1
.IP CURLOPT_IGNORE_CONTENT_LENGTH
Introduced in 7.14.1
.IP CURLOPT_INFILE
Introduced in 7.1
Deprecated since 7.9.7
.IP CURLOPT_INFILESIZE
Introduced in 7.1
.IP CURLOPT_INFILESIZE_LARGE
Introduced in 7.11.0
.IP CURLOPT_INTERFACE
Introduced in 7.3
.IP CURLOPT_INTERLEAVEDATA
Introduced in 7.20.0
.IP CURLOPT_INTERLEAVEFUNCTION
Introduced in 7.20.0
.IP CURLOPT_IOCTLDATA
Introduced in 7.12.3
Deprecated since 7.18.0
.IP CURLOPT_IOCTLFUNCTION
Introduced in 7.12.3
Deprecated since 7.18.0
.IP CURLOPT_IPRESOLVE
Introduced in 7.10.8
.IP CURLOPT_ISSUERCERT
Introduced in 7.19.0
.IP CURLOPT_ISSUERCERT_BLOB
Introduced in 7.71.0
.IP CURLOPT_KEEP_SENDING_ON_ERROR
Introduced in 7.51.0
.IP CURLOPT_KEYPASSWD
Introduced in 7.17.0
.IP CURLOPT_KRB4LEVEL
Introduced in 7.3
Deprecated since 7.17.0
.IP CURLOPT_KRBLEVEL
Introduced in 7.16.4
.IP CURLOPT_LOCALPORT
Introduced in 7.15.2
.IP CURLOPT_LOCALPORTRANGE
Introduced in 7.15.2
.IP CURLOPT_LOGIN_OPTIONS
Introduced in 7.34.0
.IP CURLOPT_LOW_SPEED_LIMIT
Introduced in 7.1
.IP CURLOPT_LOW_SPEED_TIME
Introduced in 7.1
.IP CURLOPT_MAIL_AUTH
Introduced in 7.25.0
.IP CURLOPT_MAIL_FROM
Introduced in 7.20.0
.IP CURLOPT_MAIL_RCPT
Introduced in 7.20.0
.IP CURLOPT_MAIL_RCPT_ALLLOWFAILS
Introduced in 7.69.0
.IP CURLOPT_MAX_RECV_SPEED_LARGE
Introduced in 7.15.5
.IP CURLOPT_MAX_SEND_SPEED_LARGE
Introduced in 7.15.5
.IP CURLOPT_MAXAGE_CONN
Introduced in 7.65.0
.IP CURLOPT_MAXCONNECTS
Introduced in 7.7
.IP CURLOPT_MAXFILESIZE
Introduced in 7.10.8
.IP CURLOPT_MAXFILESIZE_LARGE
Introduced in 7.11.0
.IP CURLOPT_MAXLIFETIME_CONN
Introduced in 7.80.0
.IP CURLOPT_MAXREDIRS
Introduced in 7.5
.IP CURLOPT_MIME_OPTIONS
Introduced in 7.81.0
.IP CURLOPT_MIMEPOST
Introduced in 7.56.0
.IP CURLOPT_MUTE
Introduced in 7.1
Deprecated since 7.8
Last used in 7.15.5
.IP CURLOPT_NETRC
Introduced in 7.1
.IP CURLOPT_NETRC_FILE
Introduced in 7.11.0
.IP CURLOPT_NEW_DIRECTORY_PERMS
Introduced in 7.16.4
.IP CURLOPT_NEW_FILE_PERMS
Introduced in 7.16.4
.IP CURLOPT_NOBODY
Introduced in 7.1
.IP CURLOPT_NOPROGRESS
Introduced in 7.1
.IP CURLOPT_NOPROXY
Introduced in 7.19.4
.IP CURLOPT_NOSIGNAL
Introduced in 7.10
.IP CURLOPT_NOTHING
Introduced in 7.1.1
Deprecated since 7.11.1
Last used in 7.11.0
.IP CURLOPT_OPENSOCKETDATA
Introduced in 7.17.1
.IP CURLOPT_OPENSOCKETFUNCTION
Introduced in 7.17.1
.IP CURLOPT_PASSWDDATA
Introduced in 7.4.2
Deprecated since 7.11.1
Last used in 7.15.5
.IP CURLOPT_PASSWDFUNCTION
Introduced in 7.4.2
Deprecated since 7.11.1
Last used in 7.15.5
.IP CURLOPT_PASSWORD
Introduced in 7.19.1
.IP CURLOPT_PASV_HOST
Introduced in 7.12.1
Deprecated since 7.16.0
Last used in 7.15.5
.IP CURLOPT_PATH_AS_IS
Introduced in 7.42.0
.IP CURLOPT_PINNEDPUBLICKEY
Introduced in 7.39.0
.IP CURLOPT_PIPEWAIT
Introduced in 7.43.0
.IP CURLOPT_PORT
Introduced in 7.1
.IP CURLOPT_POST
Introduced in 7.1
.IP CURLOPT_POST301
Introduced in 7.17.1
Deprecated since 7.19.1
.IP CURLOPT_POSTFIELDS
Introduced in 7.1
.IP CURLOPT_POSTFIELDSIZE
Introduced in 7.2
.IP CURLOPT_POSTFIELDSIZE_LARGE
Introduced in 7.11.1
.IP CURLOPT_POSTQUOTE
Introduced in 7.1
.IP CURLOPT_POSTREDIR
Introduced in 7.19.1
.IP CURLOPT_PRE_PROXY
Introduced in 7.52.0
.IP CURLOPT_PREQUOTE
Introduced in 7.9.5
.IP CURLOPT_PREREQDATA
Introduced in 7.80.0
.IP CURLOPT_PREREQFUNCTION
Introduced in 7.80.0
.IP CURLOPT_PRIVATE
Introduced in 7.10.3
.IP CURLOPT_PROGRESSDATA
Introduced in 7.1
.IP CURLOPT_PROGRESSFUNCTION
Introduced in 7.1
Deprecated since 7.32.0
.IP CURLOPT_PROTOCOLS
Introduced in 7.19.4
Deprecated since 7.85.0
.IP CURLOPT_PROTOCOLS_STR
Introduced in 7.85.0
.IP CURLOPT_PROXY
Introduced in 7.1
.IP CURLOPT_PROXY_CAINFO
Introduced in 7.52.0
.IP CURLOPT_PROXY_CAINFO_BLOB
Introduced in 7.77.0
.IP CURLOPT_PROXY_CAPATH
Introduced in 7.52.0
.IP CURLOPT_PROXY_CRLFILE
Introduced in 7.52.0
.IP CURLOPT_PROXY_ISSUERCERT
Introduced in 7.71.0
.IP CURLOPT_PROXY_ISSUERCERT_BLOB
Introduced in 7.71.0
.IP CURLOPT_PROXY_KEYPASSWD
Introduced in 7.52.0
.IP CURLOPT_PROXY_PINNEDPUBLICKEY
Introduced in 7.52.0
.IP CURLOPT_PROXY_SERVICE_NAME
Introduced in 7.43.0
.IP CURLOPT_PROXY_SSL_CIPHER_LIST
Introduced in 7.52.0
.IP CURLOPT_PROXY_SSL_OPTIONS
Introduced in 7.52.0
.IP CURLOPT_PROXY_SSL_VERIFYHOST
Introduced in 7.52.0
.IP CURLOPT_PROXY_SSL_VERIFYPEER
Introduced in 7.52.0
.IP CURLOPT_PROXY_SSLCERT
Introduced in 7.52.0
.IP CURLOPT_PROXY_SSLCERT_BLOB
Introduced in 7.71.0
.IP CURLOPT_PROXY_SSLCERTTYPE
Introduced in 7.52.0
.IP CURLOPT_PROXY_SSLKEY
Introduced in 7.52.0
.IP CURLOPT_PROXY_SSLKEY_BLOB
Introduced in 7.71.0
.IP CURLOPT_PROXY_SSLKEYTYPE
Introduced in 7.52.0
.IP CURLOPT_PROXY_SSLVERSION
Introduced in 7.52.0
.IP CURLOPT_PROXY_TLS13_CIPHERS
Introduced in 7.61.0
.IP CURLOPT_PROXY_TLSAUTH_PASSWORD
Introduced in 7.52.0
.IP CURLOPT_PROXY_TLSAUTH_TYPE
Introduced in 7.52.0
.IP CURLOPT_PROXY_TLSAUTH_USERNAME
Introduced in 7.52.0
.IP CURLOPT_PROXY_TRANSFER_MODE
Introduced in 7.18.0
.IP CURLOPT_PROXYAUTH
Introduced in 7.10.7
.IP CURLOPT_PROXYHEADER
Introduced in 7.37.0
.IP CURLOPT_PROXYPASSWORD
Introduced in 7.19.1
.IP CURLOPT_PROXYPORT
Introduced in 7.1
.IP CURLOPT_PROXYTYPE
Introduced in 7.10
.IP CURLOPT_PROXYUSERNAME
Introduced in 7.19.1
.IP CURLOPT_PROXYUSERPWD
Introduced in 7.1
.IP CURLOPT_PUT
Introduced in 7.1
Deprecated since 7.12.1
.IP CURLOPT_QUOTE
Introduced in 7.1
.IP CURLOPT_RANDOM_FILE
Introduced in 7.7
Deprecated since 7.84.0
.IP CURLOPT_RANGE
Introduced in 7.1
.IP CURLOPT_READDATA
Introduced in 7.9.7
.IP CURLOPT_READFUNCTION
Introduced in 7.1
.IP CURLOPT_REDIR_PROTOCOLS
Introduced in 7.19.4
Deprecated since 7.85.0
.IP CURLOPT_REDIR_PROTOCOLS_STR
Introduced in 7.85.0
.IP CURLOPT_REFERER
Introduced in 7.1
.IP CURLOPT_REQUEST_TARGET
Introduced in 7.55.0
.IP CURLOPT_RESOLVE
Introduced in 7.21.3
.IP CURLOPT_RESOLVER_START_DATA
Introduced in 7.59.0
.IP CURLOPT_RESOLVER_START_FUNCTION
Introduced in 7.59.0
.IP CURLOPT_RESUME_FROM
Introduced in 7.1
.IP CURLOPT_RESUME_FROM_LARGE
Introduced in 7.11.0
.IP CURLOPT_RTSP_CLIENT_CSEQ
Introduced in 7.20.0
.IP CURLOPT_RTSP_REQUEST
Introduced in 7.20.0
.IP CURLOPT_RTSP_SERVER_CSEQ
Introduced in 7.20.0
.IP CURLOPT_RTSP_SESSION_ID
Introduced in 7.20.0
.IP CURLOPT_RTSP_STREAM_URI
Introduced in 7.20.0
.IP CURLOPT_RTSP_TRANSPORT
Introduced in 7.20.0
.IP CURLOPT_RTSPHEADER
Introduced in 7.20.0
.IP CURLOPT_SASL_AUTHZID
Introduced in 7.66.0
.IP CURLOPT_SASL_IR
Introduced in 7.31.0
.IP CURLOPT_SEEKDATA
Introduced in 7.18.0
.IP CURLOPT_SEEKFUNCTION
Introduced in 7.18.0
.IP CURLOPT_SERVER_RESPONSE_TIMEOUT
Introduced in 7.20.0
.IP CURLOPT_SERVICE_NAME
Introduced in 7.43.0
.IP CURLOPT_SHARE
Introduced in 7.10
.IP CURLOPT_SOCKOPTDATA
Introduced in 7.16.0
.IP CURLOPT_SOCKOPTFUNCTION
Introduced in 7.16.0
.IP CURLOPT_SOCKS5_AUTH
Introduced in 7.55.0
.IP CURLOPT_SOCKS5_GSSAPI_NEC
Introduced in 7.19.4
.IP CURLOPT_SOCKS5_GSSAPI_SERVICE
Introduced in 7.19.4
Deprecated since 7.49.0
.IP CURLOPT_SOURCE_HOST
Introduced in 7.12.1
.IP CURLOPT_SOURCE_PATH
Introduced in 7.12.1
.IP CURLOPT_SOURCE_PORT
Introduced in 7.12.1
.IP CURLOPT_SOURCE_POSTQUOTE
Introduced in 7.12.1
.IP CURLOPT_SOURCE_PREQUOTE
Introduced in 7.12.1
.IP CURLOPT_SOURCE_QUOTE
Introduced in 7.13.0
.IP CURLOPT_SOURCE_URL
Introduced in 7.13.0
.IP CURLOPT_SOURCE_USERPWD
Introduced in 7.12.1
.IP CURLOPT_SSH_AUTH_TYPES
Introduced in 7.16.1
.IP CURLOPT_SSH_COMPRESSION
Introduced in 7.56.0
.IP CURLOPT_SSH_HOST_PUBLIC_KEY_MD5
Introduced in 7.17.1
.IP CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256
Introduced in 7.80.0
.IP CURLOPT_SSH_HOSTKEYDATA
Introduced in 7.84.0
.IP CURLOPT_SSH_HOSTKEYFUNCTION
Introduced in 7.84.0
.IP CURLOPT_SSH_KEYDATA
Introduced in 7.19.6
.IP CURLOPT_SSH_KEYFUNCTION
Introduced in 7.19.6
.IP CURLOPT_SSH_KNOWNHOSTS
Introduced in 7.19.6
.IP CURLOPT_SSH_PRIVATE_KEYFILE
Introduced in 7.16.1
.IP CURLOPT_SSH_PUBLIC_KEYFILE
Introduced in 7.16.1
.IP CURLOPT_SSL_CIPHER_LIST
Introduced in 7.9
.IP CURLOPT_SSL_CTX_DATA
Introduced in 7.10.6
.IP CURLOPT_SSL_CTX_FUNCTION
Introduced in 7.10.6
.IP CURLOPT_SSL_EC_CURVES
Introduced in 7.73.0
.IP CURLOPT_SSL_ENABLE_ALPN
Introduced in 7.36.0
.IP CURLOPT_SSL_ENABLE_NPN
Introduced in 7.36.0
Deprecated since 7.86.0
.IP CURLOPT_SSL_FALSESTART
Introduced in 7.42.0
.IP CURLOPT_SSL_OPTIONS
Introduced in 7.25.0
.IP CURLOPT_SSL_SESSIONID_CACHE
Introduced in 7.16.0
.IP CURLOPT_SSL_VERIFYHOST
Introduced in 7.8.1
.IP CURLOPT_SSL_VERIFYPEER
Introduced in 7.4.2
.IP CURLOPT_SSL_VERIFYSTATUS
Introduced in 7.41.0
.IP CURLOPT_SSLCERT
Introduced in 7.1
.IP CURLOPT_SSLCERT_BLOB
Introduced in 7.71.0
.IP CURLOPT_SSLCERTPASSWD
Introduced in 7.1.1
Deprecated since 7.17.0
.IP CURLOPT_SSLCERTTYPE
Introduced in 7.9.3
.IP CURLOPT_SSLENGINE
Introduced in 7.9.3
.IP CURLOPT_SSLENGINE_DEFAULT
Introduced in 7.9.3
.IP CURLOPT_SSLKEY
Introduced in 7.9.3
.IP CURLOPT_SSLKEY_BLOB
Introduced in 7.71.0
.IP CURLOPT_SSLKEYPASSWD
Introduced in 7.9.3
Deprecated since 7.17.0
.IP CURLOPT_SSLKEYTYPE
Introduced in 7.9.3
.IP CURLOPT_SSLVERSION
Introduced in 7.1
.IP CURLOPT_STDERR
Introduced in 7.1
.IP CURLOPT_STREAM_DEPENDS
Introduced in 7.46.0
.IP CURLOPT_STREAM_DEPENDS_E
Introduced in 7.46.0
.IP CURLOPT_STREAM_WEIGHT
Introduced in 7.46.0
.IP CURLOPT_SUPPRESS_CONNECT_HEADERS
Introduced in 7.54.0
.IP CURLOPT_TCP_FASTOPEN
Introduced in 7.49.0
.IP CURLOPT_TCP_KEEPALIVE
Introduced in 7.25.0
.IP CURLOPT_TCP_KEEPIDLE
Introduced in 7.25.0
.IP CURLOPT_TCP_KEEPINTVL
Introduced in 7.25.0
.IP CURLOPT_TCP_NODELAY
Introduced in 7.11.2
.IP CURLOPT_TELNETOPTIONS
Introduced in 7.7
.IP CURLOPT_TFTP_BLKSIZE
Introduced in 7.19.4
.IP CURLOPT_TFTP_NO_OPTIONS
Introduced in 7.48.0
.IP CURLOPT_TIMECONDITION
Introduced in 7.1
.IP CURLOPT_TIMEOUT
Introduced in 7.1
.IP CURLOPT_TIMEOUT_MS
Introduced in 7.16.2
.IP CURLOPT_TIMEVALUE
Introduced in 7.1
.IP CURLOPT_TIMEVALUE_LARGE
Introduced in 7.59.0
.IP CURLOPT_TLS13_CIPHERS
Introduced in 7.61.0
.IP CURLOPT_TLSAUTH_PASSWORD
Introduced in 7.21.4
.IP CURLOPT_TLSAUTH_TYPE
Introduced in 7.21.4
.IP CURLOPT_TLSAUTH_USERNAME
Introduced in 7.21.4
.IP CURLOPT_TRAILERDATA
Introduced in 7.64.0
.IP CURLOPT_TRAILERFUNCTION
Introduced in 7.64.0
.IP CURLOPT_TRANSFER_ENCODING
Introduced in 7.21.6
.IP CURLOPT_TRANSFERTEXT
Introduced in 7.1.1
.IP CURLOPT_UNIX_SOCKET_PATH
Introduced in 7.40.0
.IP CURLOPT_UNRESTRICTED_AUTH
Introduced in 7.10.4
.IP CURLOPT_UPKEEP_INTERVAL_MS
Introduced in 7.62.0
.IP CURLOPT_UPLOAD
Introduced in 7.1
.IP CURLOPT_UPLOAD_BUFFERSIZE
Introduced in 7.62.0
.IP CURLOPT_URL
Introduced in 7.1
.IP CURLOPT_USE_SSL
Introduced in 7.17.0
.IP CURLOPT_USERAGENT
Introduced in 7.1
.IP CURLOPT_USERNAME
Introduced in 7.19.1
.IP CURLOPT_USERPWD
Introduced in 7.1
.IP CURLOPT_VERBOSE
Introduced in 7.1
.IP CURLOPT_WILDCARDMATCH
Introduced in 7.21.0
.IP CURLOPT_WRITEDATA
Introduced in 7.9.7
.IP CURLOPT_WRITEFUNCTION
Introduced in 7.1
.IP CURLOPT_WRITEHEADER
Introduced in 7.1
.IP CURLOPT_WRITEINFO
Introduced in 7.1
.IP CURLOPT_WS_OPTIONS
Introduced in 7.86.0
.IP CURLOPT_XFERINFODATA
Introduced in 7.32.0
.IP CURLOPT_XFERINFOFUNCTION
Introduced in 7.32.0
.IP CURLOPT_XOAUTH2_BEARER
Introduced in 7.33.0
.IP CURLOPTTYPE_BLOB
Introduced in 7.71.0
.IP CURLOPTTYPE_CBPOINT
Introduced in 7.73.0
.IP CURLOPTTYPE_FUNCTIONPOINT
Introduced in 7.1
.IP CURLOPTTYPE_LONG
Introduced in 7.1
.IP CURLOPTTYPE_OBJECTPOINT
Introduced in 7.1
.IP CURLOPTTYPE_OFF_T
Introduced in 7.11.0
.IP CURLOPTTYPE_SLISTPOINT
Introduced in 7.65.2
.IP CURLOPTTYPE_STRINGPOINT
Introduced in 7.46.0
.IP CURLOPTTYPE_VALUES
Introduced in 7.73.0
.IP CURLOT_BLOB
Introduced in 7.73.0
.IP CURLOT_CBPTR
Introduced in 7.73.0
.IP CURLOT_FLAG_ALIAS
Introduced in 7.73.0
.IP CURLOT_FUNCTION
Introduced in 7.73.0
.IP CURLOT_LONG
Introduced in 7.73.0
.IP CURLOT_OBJECT
Introduced in 7.73.0
.IP CURLOT_OFF_T
Introduced in 7.73.0
.IP CURLOT_SLIST
Introduced in 7.73.0
.IP CURLOT_STRING
Introduced in 7.73.0
.IP CURLOT_VALUES
Introduced in 7.73.0
.IP CURLPAUSE_ALL
Introduced in 7.18.0
.IP CURLPAUSE_CONT
Introduced in 7.18.0
.IP CURLPAUSE_RECV
Introduced in 7.18.0
.IP CURLPAUSE_RECV_CONT
Introduced in 7.18.0
.IP CURLPAUSE_SEND
Introduced in 7.18.0
.IP CURLPAUSE_SEND_CONT
Introduced in 7.18.0
.IP CURLPIPE_HTTP1
Introduced in 7.43.0
.IP CURLPIPE_MULTIPLEX
Introduced in 7.43.0
.IP CURLPIPE_NOTHING
Introduced in 7.43.0
.IP CURLPROTO_ALL
Introduced in 7.19.4
.IP CURLPROTO_DICT
Introduced in 7.19.4
.IP CURLPROTO_FILE
Introduced in 7.19.4
.IP CURLPROTO_FTP
Introduced in 7.19.4
.IP CURLPROTO_FTPS
Introduced in 7.19.4
.IP CURLPROTO_GOPHER
Introduced in 7.21.2
.IP CURLPROTO_GOPHERS
Introduced in 7.75.0
.IP CURLPROTO_HTTP
Introduced in 7.19.4
.IP CURLPROTO_HTTPS
Introduced in 7.19.4
.IP CURLPROTO_IMAP
Introduced in 7.20.0
.IP CURLPROTO_IMAPS
Introduced in 7.20.0
.IP CURLPROTO_LDAP
Introduced in 7.19.4
.IP CURLPROTO_LDAPS
Introduced in 7.19.4
.IP CURLPROTO_MQTT
Introduced in 7.71.0
.IP CURLPROTO_POP3
Introduced in 7.20.0
.IP CURLPROTO_POP3S
Introduced in 7.20.0
.IP CURLPROTO_RTMP
Introduced in 7.21.0
.IP CURLPROTO_RTMPE
Introduced in 7.21.0
.IP CURLPROTO_RTMPS
Introduced in 7.21.0
.IP CURLPROTO_RTMPT
Introduced in 7.21.0
.IP CURLPROTO_RTMPTE
Introduced in 7.21.0
.IP CURLPROTO_RTMPTS
Introduced in 7.21.0
.IP CURLPROTO_RTSP
Introduced in 7.20.0
.IP CURLPROTO_SCP
Introduced in 7.19.4
.IP CURLPROTO_SFTP
Introduced in 7.19.4
.IP CURLPROTO_SMB
Introduced in 7.40.0
.IP CURLPROTO_SMBS
Introduced in 7.40.0
.IP CURLPROTO_SMTP
Introduced in 7.20.0
.IP CURLPROTO_SMTPS
Introduced in 7.20.0
.IP CURLPROTO_TELNET
Introduced in 7.19.4
.IP CURLPROTO_TFTP
Introduced in 7.19.4
.IP CURLPROXY_HTTP
Introduced in 7.10
.IP CURLPROXY_HTTP_1_0
Introduced in 7.19.4
.IP CURLPROXY_HTTPS
Introduced in 7.52.0
.IP CURLPROXY_SOCKS4
Introduced in 7.10
.IP CURLPROXY_SOCKS4A
Introduced in 7.18.0
.IP CURLPROXY_SOCKS5
Introduced in 7.10
.IP CURLPROXY_SOCKS5_HOSTNAME
Introduced in 7.18.0
.IP CURLPX_BAD_ADDRESS_TYPE
Introduced in 7.73.0
.IP CURLPX_BAD_VERSION
Introduced in 7.73.0
.IP CURLPX_CLOSED
Introduced in 7.73.0
.IP CURLPX_GSSAPI
Introduced in 7.73.0
.IP CURLPX_GSSAPI_PERMSG
Introduced in 7.73.0
.IP CURLPX_GSSAPI_PROTECTION
Introduced in 7.73.0
.IP CURLPX_IDENTD
Introduced in 7.73.0
.IP CURLPX_IDENTD_DIFFER
Introduced in 7.73.0
.IP CURLPX_LONG_HOSTNAME
Introduced in 7.73.0
.IP CURLPX_LONG_PASSWD
Introduced in 7.73.0
.IP CURLPX_LONG_USER
Introduced in 7.73.0
.IP CURLPX_NO_AUTH
Introduced in 7.73.0
.IP CURLPX_OK
Introduced in 7.73.0
.IP CURLPX_RECV_ADDRESS
Introduced in 7.73.0
.IP CURLPX_RECV_AUTH
Introduced in 7.73.0
.IP CURLPX_RECV_CONNECT
Introduced in 7.73.0
.IP CURLPX_RECV_REQACK
Introduced in 7.73.0
.IP CURLPX_REPLY_ADDRESS_TYPE_NOT_SUPPORTED
Introduced in 7.73.0
.IP CURLPX_REPLY_COMMAND_NOT_SUPPORTED
Introduced in 7.73.0
.IP CURLPX_REPLY_CONNECTION_REFUSED
Introduced in 7.73.0
.IP CURLPX_REPLY_GENERAL_SERVER_FAILURE
Introduced in 7.73.0
.IP CURLPX_REPLY_HOST_UNREACHABLE
Introduced in 7.73.0
.IP CURLPX_REPLY_NETWORK_UNREACHABLE
Introduced in 7.73.0
.IP CURLPX_REPLY_NOT_ALLOWED
Introduced in 7.73.0
.IP CURLPX_REPLY_TTL_EXPIRED
Introduced in 7.73.0
.IP CURLPX_REPLY_UNASSIGNED
Introduced in 7.73.0
.IP CURLPX_REQUEST_FAILED
Introduced in 7.73.0
.IP CURLPX_RESOLVE_HOST
Introduced in 7.73.0
.IP CURLPX_SEND_AUTH
Introduced in 7.73.0
.IP CURLPX_SEND_CONNECT
Introduced in 7.73.0
.IP CURLPX_SEND_REQUEST
Introduced in 7.73.0
.IP CURLPX_UNKNOWN_FAIL
Introduced in 7.73.0
.IP CURLPX_UNKNOWN_MODE
Introduced in 7.73.0
.IP CURLPX_USER_REJECTED
Introduced in 7.73.0
.IP CURLSHE_BAD_OPTION
Introduced in 7.10.3
.IP CURLSHE_IN_USE
Introduced in 7.10.3
.IP CURLSHE_INVALID
Introduced in 7.10.3
.IP CURLSHE_NOMEM
Introduced in 7.12.0
.IP CURLSHE_NOT_BUILT_IN
Introduced in 7.23.0
.IP CURLSHE_OK
Introduced in 7.10.3
.IP CURLSHOPT_LOCKFUNC
Introduced in 7.10.3
.IP CURLSHOPT_NONE
Introduced in 7.10.3
.IP CURLSHOPT_SHARE
Introduced in 7.10.3
.IP CURLSHOPT_UNLOCKFUNC
Introduced in 7.10.3
.IP CURLSHOPT_UNSHARE
Introduced in 7.10.3
.IP CURLSHOPT_USERDATA
Introduced in 7.10.3
.IP CURLSOCKTYPE_ACCEPT
Introduced in 7.28.0
.IP CURLSOCKTYPE_IPCXN
Introduced in 7.16.0
.IP CURLSSH_AUTH_AGENT
Introduced in 7.28.0
.IP CURLSSH_AUTH_ANY
Introduced in 7.16.1
.IP CURLSSH_AUTH_DEFAULT
Introduced in 7.16.1
.IP CURLSSH_AUTH_GSSAPI
Introduced in 7.58.0
.IP CURLSSH_AUTH_HOST
Introduced in 7.16.1
.IP CURLSSH_AUTH_KEYBOARD
Introduced in 7.16.1
.IP CURLSSH_AUTH_NONE
Introduced in 7.16.1
.IP CURLSSH_AUTH_PASSWORD
Introduced in 7.16.1
.IP CURLSSH_AUTH_PUBLICKEY
Introduced in 7.16.1
.IP CURLSSLBACKEND_AXTLS
Introduced in 7.38.0
Deprecated since 7.61.0
.IP CURLSSLBACKEND_BEARSSL
Introduced in 7.68.0
.IP CURLSSLBACKEND_BORINGSSL
Introduced in 7.49.0
.IP CURLSSLBACKEND_CYASSL
Introduced in 7.34.0
.IP CURLSSLBACKEND_DARWINSSL
Introduced in 7.34.0
Deprecated since 7.64.1
.IP CURLSSLBACKEND_GNUTLS
Introduced in 7.34.0
.IP CURLSSLBACKEND_GSKIT
Introduced in 7.34.0
.IP CURLSSLBACKEND_LIBRESSL
Introduced in 7.49.0
.IP CURLSSLBACKEND_MBEDTLS
Introduced in 7.46.0
.IP CURLSSLBACKEND_MESALINK
Introduced in 7.62.0
.IP CURLSSLBACKEND_NONE
Introduced in 7.34.0
.IP CURLSSLBACKEND_NSS
Introduced in 7.34.0
.IP CURLSSLBACKEND_OPENSSL
Introduced in 7.34.0
.IP CURLSSLBACKEND_POLARSSL
Introduced in 7.34.0
Deprecated since 7.69.0
.IP CURLSSLBACKEND_QSOSSL
Introduced in 7.34.0
.IP CURLSSLBACKEND_RUSTLS
Introduced in 7.76.0
.IP CURLSSLBACKEND_SCHANNEL
Introduced in 7.34.0
.IP CURLSSLBACKEND_SECURETRANSPORT
Introduced in 7.64.1
.IP CURLSSLBACKEND_WOLFSSL
Introduced in 7.49.0
.IP CURLSSLOPT_ALLOW_BEAST
Introduced in 7.25.0
.IP CURLSSLOPT_AUTO_CLIENT_CERT
Introduced in 7.77.0
.IP CURLSSLOPT_NATIVE_CA
Introduced in 7.71.0
.IP CURLSSLOPT_NO_PARTIALCHAIN
Introduced in 7.68.0
.IP CURLSSLOPT_NO_REVOKE
Introduced in 7.44.0
.IP CURLSSLOPT_REVOKE_BEST_EFFORT
Introduced in 7.70.0
.IP CURLSSLSET_NO_BACKENDS
Introduced in 7.56.0
.IP CURLSSLSET_OK
Introduced in 7.56.0
.IP CURLSSLSET_TOO_LATE
Introduced in 7.56.0
.IP CURLSSLSET_UNKNOWN_BACKEND
Introduced in 7.56.0
.IP CURLSTS_DONE
Introduced in 7.74.0
.IP CURLSTS_FAIL
Introduced in 7.74.0
.IP CURLSTS_OK
Introduced in 7.74.0
.IP CURLU_ALLOW_SPACE
Introduced in 7.78.0
.IP CURLU_APPENDQUERY
Introduced in 7.62.0
.IP CURLU_DEFAULT_PORT
Introduced in 7.62.0
.IP CURLU_DEFAULT_SCHEME
Introduced in 7.62.0
.IP CURLU_DISALLOW_USER
Introduced in 7.62.0
.IP CURLU_GUESS_SCHEME
Introduced in 7.62.0
.IP CURLU_NO_AUTHORITY
Introduced in 7.67.0
.IP CURLU_NO_DEFAULT_PORT
Introduced in 7.62.0
.IP CURLU_NON_SUPPORT_SCHEME
Introduced in 7.62.0
.IP CURLU_PATH_AS_IS
Introduced in 7.62.0
.IP CURLU_URLDECODE
Introduced in 7.62.0
.IP CURLU_URLENCODE
Introduced in 7.62.0
.IP CURLUE_BAD_FILE_URL
Introduced in 7.81.0
.IP CURLUE_BAD_FRAGMENT
Introduced in 7.81.0
.IP CURLUE_BAD_HANDLE
Introduced in 7.62.0
.IP CURLUE_BAD_HOSTNAME
Introduced in 7.81.0
.IP CURLUE_BAD_IPV6
Introduced in 7.81.0
.IP CURLUE_BAD_LOGIN
Introduced in 7.81.0
.IP CURLUE_BAD_PARTPOINTER
Introduced in 7.62.0
.IP CURLUE_BAD_PASSWORD
Introduced in 7.81.0
.IP CURLUE_BAD_PATH
Introduced in 7.81.0
.IP CURLUE_BAD_PORT_NUMBER
Introduced in 7.62.0
.IP CURLUE_BAD_QUERY
Introduced in 7.81.0
.IP CURLUE_BAD_SCHEME
Introduced in 7.81.0
.IP CURLUE_BAD_SLASHES
Introduced in 7.81.0
.IP CURLUE_BAD_USER
Introduced in 7.81.0
.IP CURLUE_MALFORMED_INPUT
Introduced in 7.62.0
.IP CURLUE_NO_FRAGMENT
Introduced in 7.62.0
.IP CURLUE_NO_HOST
Introduced in 7.62.0
.IP CURLUE_NO_OPTIONS
Introduced in 7.62.0
.IP CURLUE_NO_PASSWORD
Introduced in 7.62.0
.IP CURLUE_NO_PORT
Introduced in 7.62.0
.IP CURLUE_NO_QUERY
Introduced in 7.62.0
.IP CURLUE_NO_SCHEME
Introduced in 7.62.0
.IP CURLUE_NO_USER
Introduced in 7.62.0
.IP CURLUE_NO_ZONEID
Introduced in 7.81.0
.IP CURLUE_OK
Introduced in 7.62.0
.IP CURLUE_OUT_OF_MEMORY
Introduced in 7.62.0
.IP CURLUE_UNKNOWN_PART
Introduced in 7.62.0
.IP CURLUE_UNSUPPORTED_SCHEME
Introduced in 7.62.0
.IP CURLUE_URLDECODE
Introduced in 7.62.0
.IP CURLUE_USER_NOT_ALLOWED
Introduced in 7.62.0
.IP CURLUPART_FRAGMENT
Introduced in 7.62.0
.IP CURLUPART_HOST
Introduced in 7.62.0
.IP CURLUPART_OPTIONS
Introduced in 7.62.0
.IP CURLUPART_PASSWORD
Introduced in 7.62.0
.IP CURLUPART_PATH
Introduced in 7.62.0
.IP CURLUPART_PORT
Introduced in 7.62.0
.IP CURLUPART_QUERY
Introduced in 7.62.0
.IP CURLUPART_SCHEME
Introduced in 7.62.0
.IP CURLUPART_URL
Introduced in 7.62.0
.IP CURLUPART_USER
Introduced in 7.62.0
.IP CURLUPART_ZONEID
Introduced in 7.65.0
.IP CURLUSESSL_ALL
Introduced in 7.17.0
.IP CURLUSESSL_CONTROL
Introduced in 7.17.0
.IP CURLUSESSL_NONE
Introduced in 7.17.0
.IP CURLUSESSL_TRY
Introduced in 7.17.0
.IP CURLVERSION_EIGHTH
Introduced in 7.72.0
.IP CURLVERSION_FIFTH
Introduced in 7.57.0
.IP CURLVERSION_FIRST
Introduced in 7.10
.IP CURLVERSION_FOURTH
Introduced in 7.16.1
.IP CURLVERSION_NINTH
Introduced in 7.75.0
.IP CURLVERSION_NOW
Introduced in 7.10
.IP CURLVERSION_SECOND
Introduced in 7.11.1
.IP CURLVERSION_SEVENTH
Introduced in 7.70.0
.IP CURLVERSION_SIXTH
Introduced in 7.66.0
.IP CURLVERSION_TENTH
Introduced in 7.77.0
.IP CURLVERSION_THIRD
Introduced in 7.12.0
.IP CURLWARNING
Introduced in 7.66.0
.IP CURLWS_BINARY
Introduced in 7.86.0
.IP CURLWS_CLOSE
Introduced in 7.86.0
.IP CURLWS_CONT
Introduced in 7.86.0
.IP CURLWS_OFFSET
Introduced in 7.86.0
.IP CURLWS_PING
Introduced in 7.86.0
.IP CURLWS_PONG
Introduced in 7.86.0
.IP CURLWS_RAW_MODE
Introduced in 7.86.0
.IP CURLWS_TEXT
Introduced in 7.86.0
share/man/man3/curl_ws_recv.3 0000644 00000004306 14751150677 0012060 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH curl_ws_recv 3 "October 03, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_ws_recv - receive WebSocket data
.SH SYNOPSIS
.nf
#include <curl/easy.h>
CURLcode curl_ws_recv(CURL *curl, void *buffer, size_t buflen,
size_t *recv, struct curl_ws_frame **meta);
.fi
.SH DESCRIPTION
This function call is EXPERIMENTAL.
Retrieves as much as possible of a received WebSocket data fragment into the
\fBbuffer\fP, but not more than \fBbuflen\fP bytes. \fIrecv\fP is set to the
number of bytes actually stored.
If there is more fragment data to deliver than what fits in the provided
\fIbuffer\fP, libcurl returns a full buffer and the application needs to call
this function again to continue draining the buffer.
The \fImeta\fP pointer gets set to point to a \fIstruct curl_ws_frame\fP that
contains information about the received data. See the \fIcurl_ws_meta(3)\fP
for details on that struct.
.SH EXAMPLE
.nf
.fi
.SH AVAILABILITY
Added in 7.86.0.
.SH RETURN VALUE
.SH "SEE ALSO"
.BR curl_easy_setopt "(3), " curl_easy_perform "(3), "
.BR curl_easy_getinfo "(3), "
.BR curl_ws_send "(3) "
share/man/man3/CURLOPT_FTP_FILEMETHOD.3 0000644 00000005606 14751150677 0012730 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_FTP_FILEMETHOD 3 "October 22, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_FTP_FILEMETHOD \- select directory traversing method for FTP
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_FILEMETHOD,
long method);
.SH DESCRIPTION
Pass a long telling libcurl which \fImethod\fP to use to reach a file on a
FTP(S) server.
This option exists because some server implementations are not compliant to
what the standards say should work.
The argument should be one of the following alternatives:
.IP CURLFTPMETHOD_MULTICWD
libcurl does a single CWD operation for each path part in the given URL. For
deep hierarchies this means many commands. This is how RFC1738 says it should
be done. This is the default but the slowest behavior.
.IP CURLFTPMETHOD_NOCWD
libcurl does no CWD at all. libcurl will do SIZE, RETR, STOR etc and give a
full path to the server for all these commands. This is the fastest behavior.
.IP CURLFTPMETHOD_SINGLECWD
libcurl does one CWD with the full target directory and then operates on the
file \&"normally" (like in the multicwd case). This is somewhat more standards
compliant than 'nocwd' but without the full penalty of 'multicwd'.
.SH DEFAULT
CURLFTPMETHOD_MULTICWD
.SH PROTOCOLS
FTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/1/2/3/4/new.txt");
curl_easy_setopt(curl, CURLOPT_FTP_FILEMETHOD,
(long)CURLFTPMETHOD_SINGLECWD);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.15.1
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_DIRLISTONLY "(3), " CURLOPT_FTP_SKIP_PASV_IP "(3), "
share/man/man3/CURLOPT_PROXY_KEYPASSWD.3 0000644 00000004671 14751150677 0013153 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXY_KEYPASSWD 3 "October 11, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXY_KEYPASSWD \- passphrase for the proxy private key
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_KEYPASSWD, char *pwd);
.fi
.SH DESCRIPTION
This option is for connecting to an HTTPS proxy, not an HTTPS server.
Pass a pointer to a null-terminated string as parameter. It will be used as
the password required to use the \fICURLOPT_PROXY_SSLKEY(3)\fP private key.
You never need a pass phrase to load a certificate but you need one to load
your private key.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
Used with HTTPS proxy
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy:443");
curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "superman");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.52.0
.SH RETURN VALUE
Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_PROXY_SSLKEY "(3), " CURLOPT_SSH_PRIVATE_KEYFILE "(3), "
.BR CURLOPT_SSLKEY "(3), "
share/man/man3/CURLOPT_UPKEEP_INTERVAL_MS.3 0000644 00000005526 14751150677 0013474 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_UPKEEP_INTERVAL_MS 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_UPKEEP_INTERVAL_MS \- connection upkeep interval
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UPKEEP_INTERVAL_MS,
long upkeep_interval_ms);
.fi
.SH DESCRIPTION
Some protocols have "connection upkeep" mechanisms. These mechanisms usually
send some traffic on existing connections in order to keep them alive; this
can prevent connections from being closed due to overzealous firewalls, for
example.
The user needs to explicitly call \fIcurl_easy_upkeep(3)\fP in order to
perform the upkeep work.
Currently the only protocol with a connection upkeep mechanism is HTTP/2: when
the connection upkeep interval is exceeded and \fIcurl_easy_upkeep(3)\fP
is called, an HTTP/2 PING frame is sent on the connection.
.SH DEFAULT
CURL_UPKEEP_INTERVAL_DEFAULT (currently defined as 60000L, which is 60 seconds)
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
/* Make a connection to an HTTP/2 server. */
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* Set the interval to 30000ms / 30s */
curl_easy_setopt(curl, CURLOPT_UPKEEP_INTERVAL_MS, 30000L);
curl_easy_perform(curl);
/* Perform more work here. */
/* While the connection is being held open, curl_easy_upkeep() can be
called. If curl_easy_upkeep() is called and the time since the last
upkeep exceeds the interval, then an HTTP/2 PING is sent. */
curl_easy_upkeep(curl);
/* Perform more work here. */
/* always cleanup */
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.62.0
.SH RETURN VALUE
Returns CURLE_OK
.SH SEE ALSO
.BR CURLOPT_TCP_KEEPALIVE "(3), "
share/man/man3/curl_easy_cleanup.3 0000644 00000006062 14751150677 0013061 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH curl_easy_cleanup 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_easy_cleanup - End a libcurl easy handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
void curl_easy_cleanup(CURL *handle);
.fi
.SH DESCRIPTION
This function must be the last function to call for an easy session. It is the
opposite of the \fIcurl_easy_init(3)\fP function and must be called with the
same \fIhandle\fP as input that a \fIcurl_easy_init(3)\fP call returned.
This might close all connections this handle has used and possibly has kept
open until now - unless it was attached to a multi handle while doing the
transfers. Do not call this function if you intend to transfer more files,
re-using handles is a key to good performance with libcurl.
Occasionally you may get your progress callback or header callback called from
within \fIcurl_easy_cleanup(3)\fP (if previously set for the handle using
\fIcurl_easy_setopt(3)\fP). Like if libcurl decides to shut down the
connection and the protocol is of a kind that requires a command/response
sequence before disconnect. Examples of such protocols are FTP, POP3 and IMAP.
Any use of the \fBhandle\fP after this function has been called and have
returned, is illegal. \fIcurl_easy_cleanup(3)\fP kills the handle and all
memory associated with it!
To close an easy handle that has been used with the multi interface, make sure
to call \fIcurl_multi_remove_handle(3)\fP first to remove it from the multi
handle before it is closed.
Passing in a NULL pointer in \fIhandle\fP will make this function return
immediately with no action.
.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
Added in 7.1
.SH RETURN VALUE
None
.SH "SEE ALSO"
.BR curl_easy_init "(3), " curl_easy_duphandle "(3), "
.BR curl_easy_reset "(3), "
.BR curl_multi_cleanup "(3), " curl_multi_remove_handle "(3) "
share/man/man3/CURLOPT_PREREQFUNCTION.3 0000644 00000010233 14751150677 0012733 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 2022 - 2022, Max Dymond, <max.dymond@microsoft.com>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PREREQFUNCTION 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PREREQFUNCTION \- user callback called when a connection has been
established, but before a request has been made.
.SH SYNOPSIS
.nf
#include <curl/curl.h>
/* These are the return codes for the pre-request callback. */
#define CURL_PREREQFUNC_OK 0
#define CURL_PREREQFUNC_ABORT 1 /* fail the entire transfer */
int prereq_callback(void *clientp,
char *conn_primary_ip,
char *conn_local_ip,
int conn_primary_port,
int conn_local_port);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PREREQFUNCTION, prereq_callback);
.SH DESCRIPTION
Pass a pointer to your callback function, which should match the prototype
shown above.
This function gets called by libcurl after a connection has been established
or a connection has been reused (including any SSL handshaking), but before any
request is actually made on the connection. For example, for HTTP, this
callback is called once a connection has been established to the server, but
before a GET/HEAD/POST/etc request has been sent.
This function may be called multiple times if redirections are enabled and are
being followed (see \fICURLOPT_FOLLOWLOCATION(3)\fP).
The callback function must return \fICURL_PREREQFUNC_OK\fP on success, or
\fICURL_PREREQFUNC_ABORT\fP to cause the transfer to fail.
This function is passed the following arguments:
.IP conn_primary_ip
A null-terminated pointer to a C string containing the primary IP of the
remote server established with this connection. For FTP, this is the IP for
the control connection. IPv6 addresses are represented without surrounding
brackets.
.IP conn_local_ip
A null-terminated pointer to a C string containing the originating IP for this
connection. IPv6 addresses are represented without surrounding brackets.
.IP conn_primary_port
The primary port number on the remote server established with this connection.
For FTP, this is the port for the control connection. This can be a TCP or a
UDP port number depending on the protocol.
.IP conn_local_port
The originating port number for this connection. This can be a TCP or a UDP
port number depending on the protocol.
.IP clientp
The pointer you set with \fICURLOPT_PREREQDATA(3)\fP.
.SH DEFAULT
By default, this is NULL and unused.
.SH PROTOCOLS
ALL
.SH EXAMPLE
.nf
static int prereq_callback(void *clientp,
char *conn_primary_ip,
char *conn_local_ip,
int conn_primary_port,
int conn_local_port)
{
printf("Connection made to %s:%s\\n", conn_primary_ip, conn_primary_port);
return CURL_PREREQFUNC_OK;
}
{
struct data prereq_data;
curl_easy_setopt(CURL *handle, CURLOPT_PREREQFUNCTION, prereq_callback);
curl_easy_setopt(CURL *handle, CURLOPT_PREREQDATA, &prereq_data);
}
.fi
.SH AVAILABILITY
Added in 7.80.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_PREREQDATA "(3) "
share/man/man3/CURLOPT_HTTPPROXYTUNNEL.3 0000644 00000005610 14751150677 0013141 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_HTTPPROXYTUNNEL 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_HTTPPROXYTUNNEL \- tunnel through HTTP proxy
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPPROXYTUNNEL, long tunnel);
.fi
.SH DESCRIPTION
Set the \fBtunnel\fP parameter to 1L to make libcurl tunnel all operations
through the HTTP proxy (set with \fICURLOPT_PROXY(3)\fP). There is a big
difference between using a proxy and to tunnel through it.
Tunneling means that an HTTP CONNECT request is sent to the proxy, asking it
to connect to a remote host on a specific port number and then the traffic is
just passed through the proxy. Proxies tend to white-list specific port numbers
it allows CONNECT requests to and often only port 80 and 443 are allowed.
To suppress proxy CONNECT response headers from user callbacks use
\fICURLOPT_SUPPRESS_CONNECT_HEADERS(3)\fP.
HTTP proxies can generally only speak HTTP (for obvious reasons), which makes
libcurl convert non-HTTP requests to HTTP when using an HTTP proxy without
this tunnel option set. For example, asking for an FTP URL and specifying an
HTTP proxy will make libcurl send an FTP URL in an HTTP GET request to the
proxy. By instead tunneling through the proxy, you avoid that conversion (that
rarely works through the proxy anyway).
.SH DEFAULT
0
.SH PROTOCOLS
All network protocols
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/file.txt");
curl_easy_setopt(curl, CURLOPT_PROXY, "http://127.0.0.1:80");
curl_easy_setopt(curl, CURLOPT_HTTPPROXYTUNNEL, 1L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_PROXY "(3), " CURLOPT_PROXYTYPE "(3), " CURLOPT_PROXYPORT "(3), "
share/man/man3/CURLOPT_COOKIEFILE.3 0000644 00000007134 14751150677 0012206 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_COOKIEFILE 3 "October 06, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_COOKIEFILE \- file name to read cookies from
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIEFILE, char *filename);
.fi
.SH DESCRIPTION
Pass a pointer to a null-terminated string as parameter. It should point to
the file name of your file holding cookie data to read. The cookie data can be
in either the old Netscape / Mozilla cookie data format or just regular HTTP
headers (Set-Cookie style) dumped to a file.
It also enables the cookie engine, making libcurl parse and send cookies on
subsequent requests with this handle.
By passing the empty string ("") to this option, you enable the cookie engine
without reading any initial cookies. If you tell libcurl the file name is "-"
(just a single minus sign), libcurl will instead read from stdin.
This option only \fBreads\fP cookies. To make libcurl write cookies to file,
see \fICURLOPT_COOKIEJAR(3)\fP.
If you use the Set-Cookie file format and do not specify a domain then the
cookie is not sent since the domain will never match. To address this, set a
domain in Set-Cookie line (doing that will include sub-domains) or preferably:
use the Netscape format.
If you use this option multiple times, you just add more files to read.
Subsequent files will add more cookies.
The application does not have to keep the string around after setting this
option.
Setting this option to NULL will (since 7.77.0) explicitly disable the cookie
engine and clear the list of files to read cookies from.
.SH SECURITY
This document previously mentioned how specifying a non-existing file can also
enable the cookie engine. While true, we strongly advice against using that
method as it is too hard to be sure what files will stay that way in the long
run.
.SH DEFAULT
NULL
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
/* get cookies from an existing file */
curl_easy_setopt(curl, CURLOPT_COOKIEFILE, "/tmp/cookies.txt");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH "Cookie file format"
The cookie file format and general cookie concepts in curl are described
online here: https://curl.se/docs/http-cookies.html
.SH AVAILABILITY
As long as HTTP is supported
.SH RETURN VALUE
Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_COOKIE "(3), " CURLOPT_COOKIEJAR "(3), "
share/man/man3/CURLOPT_PROXY_TLSAUTH_TYPE.3 0000644 00000005506 14751150677 0013564 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXY_TLSAUTH_TYPE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXY_TLSAUTH_TYPE \- HTTPS proxy TLS authentication methods
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_TLSAUTH_TYPE,
char *type);
.fi
.SH DESCRIPTION
Pass a pointer to a null-terminated string as parameter. The string should be
the method of the TLS authentication used for the HTTPS connection. Supported
method is "SRP".
.IP SRP
TLS-SRP authentication. Secure Remote Password authentication for TLS is
defined in RFC5054 and provides mutual authentication if both sides have a
shared secret. To use TLS-SRP, you must also set the
\fICURLOPT_PROXY_TLSAUTH_USERNAME(3)\fP and
\fICURLOPT_PROXY_TLSAUTH_PASSWORD(3)\fP options.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
blank
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy");
curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_TYPE, "SRP");
curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_USERNAME, "user");
curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_PASSWORD, "secret");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.52.0
You need to build libcurl with GnuTLS or OpenSSL with TLS-SRP support for this
to work.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_PROXY_TLSAUTH_USERNAME "(3), " CURLOPT_PROXY_TLSAUTH_PASSWORD "(3), "
.BR CURLOPT_TLSAUTH_USERNAME "(3), " CURLOPT_TLSAUTH_PASSWORD "(3), "
share/man/man3/CURLOPT_CONV_TO_NETWORK_FUNCTION.3 0000644 00000007443 14751150677 0014465 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_CONV_TO_NETWORK_FUNCTION 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_CONV_TO_NETWORK_FUNCTION \- convert data to network from host encoding
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode conv_callback(char *ptr, size_t length);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONV_TO_NETWORK_FUNCTION,
conv_callback);
.SH DESCRIPTION
Pass a pointer to your callback function, which should match the prototype
shown above.
Applies to non-ASCII platforms. \fIcurl_version_info(3)\fP will return the
CURL_VERSION_CONV feature bit set if this option is provided.
The data to be converted is in a buffer pointed to by the \fIptr\fP parameter.
The amount of data to convert is indicated by the \fIlength\fP parameter. The
converted data overlays the input data in the buffer pointed to by the ptr
parameter. \fICURLE_OK\fP must be returned upon successful conversion. A
CURLcode return value defined by curl.h, such as \fICURLE_CONV_FAILED\fP,
should be returned if an error was encountered.
\fBCURLOPT_CONV_TO_NETWORK_FUNCTION\fP converts from host encoding to the
network encoding. It is used when commands or ASCII data are sent over the
network.
If you set a callback pointer to NULL, or do not set it at all, the built-in
libcurl iconv functions will be used. If HAVE_ICONV was not defined when
libcurl was built, and no callback has been established, conversion will
return the CURLE_CONV_REQD error code.
If HAVE_ICONV is defined, CURL_ICONV_CODESET_OF_HOST must also be defined.
For example:
\&#define CURL_ICONV_CODESET_OF_HOST "IBM-1047"
The iconv code in libcurl will default the network and UTF8 codeset names as
follows:
\&#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1"
\&#define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8"
You will need to override these definitions if they are different on your
system.
.SH DEFAULT
NULL
.SH PROTOCOLS
FTP, SMTP, IMAP, POP3
.SH EXAMPLE
.nf
static CURLcode my_conv_from_ebcdic_to_ascii(char *buffer, size_t length)
{
char *tempptrin, *tempptrout;
size_t bytes = length;
int rc;
tempptrin = tempptrout = buffer;
rc = platform_e2a(&tempptrin, &bytes, &tempptrout, &bytes);
if(rc == PLATFORM_CONV_OK) {
return CURLE_OK;
}
else {
return CURLE_CONV_FAILED;
}
}
curl_easy_setopt(curl, CURLOPT_CONV_TO_NETWORK_FUNCTION,
my_conv_from_ebcdic_to_ascii);
.fi
.SH AVAILABILITY
Not available since 7.82.0
Available only if \fBCURL_DOES_CONVERSIONS\fP was defined when libcurl was
built.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_CONV_FROM_NETWORK_FUNCTION "(3), " CURLOPT_CONV_FROM_UTF8_FUNCTION "(3), "
share/man/man3/curl_mime_addpart.3 0000644 00000004632 14751150677 0013040 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_mime_addpart 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_mime_addpart - append a new empty part to a mime structure
.SH SYNOPSIS
.nf
#include <curl/curl.h>
curl_mimepart *curl_mime_addpart(curl_mime *mime);
.fi
.SH DESCRIPTION
\fIcurl_mime_addpart(3)\fP creates and appends a new empty part to the given
mime structure and returns a handle to it. The returned part handle can
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 EXAMPLE
.nf
curl_mime *mime;
curl_mimepart *part;
/* create a mime handle */
mime = curl_mime_init(easy);
/* add a part */
part = curl_mime_addpart(mime);
/* continue and set name + data to the part */
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),"
.BR curl_mime_data "(3),"
.BR curl_mime_data_cb "(3),"
.BR curl_mime_filedata "(3),"
.BR curl_mime_filename "(3),"
.BR curl_mime_subparts "(3),"
.BR curl_mime_type "(3),"
.BR curl_mime_headers "(3),"
.BR curl_mime_encoder "(3)"
share/man/man3/CURLOPT_EGDSOCKET.3 0000644 00000004477 14751150677 0012114 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_EGDSOCKET 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_EGDSOCKET \- EGD socket path
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_EGDSOCKET, char *path);
.fi
.SH DESCRIPTION
Deprecated option. It serves no purpose anymore.
Pass a char * to the null-terminated path name to the Entropy Gathering Daemon
socket. It will be used to seed the random engine for TLS.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_EGDSOCKET, "/var/egd.socket");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
If built with TLS enabled. Only the OpenSSL backend will use this, and only
with OpenSSL versions before 1.1.0.
This option was deprecated in 7.84.0.
.SH RETURN VALUE
Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_RANDOM_FILE "(3), "
share/man/man3/CURLOPT_ISSUERCERT.3 0000644 00000005607 14751150677 0012270 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_ISSUERCERT 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_ISSUERCERT \- issuer SSL certificate filename
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ISSUERCERT, char *file);
.fi
.SH DESCRIPTION
Pass a char * to a null-terminated string naming a \fIfile\fP holding a CA
certificate in PEM format. If the option is set, an additional check against
the peer certificate is performed to verify the issuer is indeed the one
associated with the certificate provided by the option. This additional check
is useful in multi-level PKI where one needs to enforce that the peer
certificate is from a specific branch of the tree.
This option makes sense only when used in combination with the
\fICURLOPT_SSL_VERIFYPEER(3)\fP option. Otherwise, the result of the check is
not considered as failure.
A specific error code (CURLE_SSL_ISSUER_ERROR) is defined with the option,
which is returned if the setup of the SSL/TLS session has failed due to a
mismatch with the issuer of peer certificate (\fICURLOPT_SSL_VERIFYPEER(3)\fP
has to be set too for the check to fail). (Added in 7.19.0)
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
All TLS-based protocols
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_ISSUERCERT, "/etc/certs/cacert.pem");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
If built TLS enabled
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_CRLFILE "(3), " CURLOPT_SSL_VERIFYPEER "(3), "
share/man/man3/curl_easy_nextheader.3 0000644 00000010122 14751150677 0013551 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_easy_nextheader 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_easy_nextheader - get the next HTTP header
.SH SYNOPSIS
.nf
#include <curl/curl.h>
struct curl_header *curl_easy_nextheader(CURL *easy,
unsigned int origin,
int request,
struct curl_header *prev);
.fi
.SH DESCRIPTION
This function lets an application iterate over all previously received HTTP
headers.
The \fIorigin\fP argument is for specifying which headers to receive, as a
single HTTP transfer might provide headers from several different places and
they may then have different importance to the user and headers using the same
name might be used. The \fIorigin\fP is a bitmask for what header sources you
want. See the \fIcurl_easy_header(3)\fP man page for the origin descriptions.
The \fIrequest\fP argument tells libcurl from which request you want headers
from. A single transfer might consist of a series of HTTP requests and this
argument lets you specify which particular individual request you want the
headers from. 0 being the first request and then the number increases for
further redirects or when multi-state authentication is used. Passing in -1 is
a shortcut to "the last" request in the series, independently of the actual
amount of requests used.
It is suggested that you pass in the same \fBorigin\fP and \fBrequest\fP when
iterating over a range of headers as changing the value mid-loop might give
you unexpected results.
If \fIprev\fP is NULL, this function returns a pointer to the first header
stored within the given scope (origin + request).
If \fIprev\fP is a pointer to a previously returned header struct,
\fIcurl_easy_nextheader(3)\fP returns a pointer the next header stored within
the given scope. This way, an application can iterate over all available
headers.
The memory for the struct this points to, is owned and managed by libcurl and
is associated with the easy handle. Applications must copy the data if they
want it to survive subsequent API calls or the life-time of the easy handle.
.SH EXAMPLE
.nf
struct curl_header *prev = NULL;
struct curl_header *h;
/* extract the normal headers from the first request */
while((h = curl_easy_nextheader(easy, CURLH_HEADER, 0, prev))) {
print "%s: %s\\n", h->name, h->value);
prev = h;
}
/* extract the normal headers + 1xx + trailers from the last request */
unsigned int origin = CURLH_HEADER| CURLH_1XX | CURLH_TRAILER;
while((h = curl_easy_nextheader(easy, origin, -1, prev))) {
print "%s: %s\\n", h->name, h->value);
prev = h;
}
.fi
.SH AVAILABILITY
Added in 7.83.0. Officially supported since 7.84.0.
.SH RETURN VALUE
This function returns the next header, or NULL when there are no more
(matching) headers or an error occurred.
If this function returns NULL when \fIprev\fP was set to NULL, then there are
no headers available within the scope to return.
.SH "SEE ALSO"
.BR curl_easy_header "(3), " curl_easy_perform "(3) "
share/man/man3/CURLOPT_SASL_IR.3 0000644 00000004456 14751150677 0011735 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SASL_IR 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SASL_IR \- send initial response in first packet
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SASL_IR, long enable);
.fi
.SH DESCRIPTION
Pass a long. If the value is 1, curl will send the initial response to the
server in the first authentication packet in order to reduce the number of
ping pong requests. Only applicable to the following supporting SASL
authentication mechanisms:
* Login
* Plain
* GSSAPI
* NTLM
* OAuth 2.0
Note: Whilst IMAP supports this option there is no need to explicitly set it,
as libcurl can determine the feature itself when the server supports the
SASL-IR CAPABILITY.
.SH DEFAULT
0
.SH PROTOCOLS
IMAP, POP3 and SMTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "smtp://example.com/");
curl_easy_setopt(curl, CURLOPT_SASL_IR, 1L);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.31.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_MAIL_AUTH "(3), " CURLOPT_MAIL_FROM "(3), "
share/man/man3/CURLOPT_SSLVERSION.3 0000644 00000010606 14751150677 0012302 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SSLVERSION 3 "October 22, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSLVERSION \- preferred TLS/SSL version
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLVERSION, long version);
.fi
.SH DESCRIPTION
Pass a long as parameter to control which version range of SSL/TLS versions to
use.
The SSL and TLS versions have typically developed from the most insecure
version to be more and more secure in this order through history: SSL v2,
SSLv3, TLS v1.0, TLS v1.1, TLS v1.2 and the most recent TLS v1.3.
Use one of the available defines for this purpose. The available options are:
.RS
.IP CURL_SSLVERSION_DEFAULT
The default acceptable version range. The minimum acceptable version is by
default TLS v1.0 since 7.39.0 (unless the TLS library has a stricter rule).
.IP CURL_SSLVERSION_TLSv1
TLS v1.0 or later
.IP CURL_SSLVERSION_SSLv2
SSL v2 - refused
.IP CURL_SSLVERSION_SSLv3
SSL v3 - refused
.IP CURL_SSLVERSION_TLSv1_0
TLS v1.0 or later (Added in 7.34.0)
.IP CURL_SSLVERSION_TLSv1_1
TLS v1.1 or later (Added in 7.34.0)
.IP CURL_SSLVERSION_TLSv1_2
TLS v1.2 or later (Added in 7.34.0)
.IP CURL_SSLVERSION_TLSv1_3
TLS v1.3 or later (Added in 7.52.0)
.RE
The maximum TLS version can be set by using \fIone\fP of the
CURL_SSLVERSION_MAX_ macros below. It is also possible to OR \fIone\fP of the
CURL_SSLVERSION_ macros with \fIone\fP of the CURL_SSLVERSION_MAX_ macros.
The MAX macros are not supported for WolfSSL.
.RS
.IP CURL_SSLVERSION_MAX_DEFAULT
The flag defines the maximum supported TLS version by libcurl, or the default
value from the SSL library is used. libcurl will use a sensible default
maximum, which was TLS v1.2 up to before 7.61.0 and is TLS v1.3 since then -
assuming the TLS library support it. (Added in 7.54.0)
.IP CURL_SSLVERSION_MAX_TLSv1_0
The flag defines maximum supported TLS version as TLS v1.0.
(Added in 7.54.0)
.IP CURL_SSLVERSION_MAX_TLSv1_1
The flag defines maximum supported TLS version as TLS v1.1.
(Added in 7.54.0)
.IP CURL_SSLVERSION_MAX_TLSv1_2
The flag defines maximum supported TLS version as TLS v1.2.
(Added in 7.54.0)
.IP CURL_SSLVERSION_MAX_TLSv1_3
The flag defines maximum supported TLS version as TLS v1.3.
(Added in 7.54.0)
.RE
In versions of curl prior to 7.54 the CURL_SSLVERSION_TLS options were
documented to allow \fIonly\fP the specified TLS version, but behavior was
inconsistent depending on the TLS library.
.SH DEFAULT
CURL_SSLVERSION_DEFAULT
.SH PROTOCOLS
All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* ask libcurl to use TLS version 1.0 or later */
curl_easy_setopt(curl, CURLOPT_SSLVERSION, (long)CURL_SSLVERSION_TLSv1);
/* Perform the request */
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
SSLv2 and SSLv3 are refused completely since curl 7.77.0
SSLv2 is disabled by default since 7.18.1. Other SSL versions availability may
vary depending on which backend libcurl has been built to use.
SSLv3 is disabled by default since 7.39.0.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_USE_SSL "(3), " CURLOPT_HTTP_VERSION "(3), "
.BR CURLOPT_PROXY_SSLVERSION "(3), " CURLOPT_IPRESOLVE "(3) "
share/man/man3/CURLINFO_SIZE_DOWNLOAD.3 0000644 00000004761 14751150677 0012732 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_SIZE_DOWNLOAD 3 "October 12, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_SIZE_DOWNLOAD \- get the number of downloaded bytes
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SIZE_DOWNLOAD, double *dlp);
.fi
.SH DESCRIPTION
Pass a pointer to a double to receive the total amount of bytes that were
downloaded. The amount is only for the latest transfer and will be reset
again for each new transfer. This counts actual payload data, what's also
commonly called body. All meta and header data are excluded and will not be
counted in this number.
\fICURLINFO_SIZE_DOWNLOAD_T(3)\fP is a newer replacement that returns a more
sensible variable type.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* Perform the request */
res = curl_easy_perform(curl);
if(!res) {
/* check the size */
double dl;
res = curl_easy_getinfo(curl, CURLINFO_SIZE_DOWNLOAD, &dl);
if(!res) {
printf("Downloaded %.0f bytes\\n", cl);
}
}
}
.fi
.SH AVAILABILITY
Added in 7.4.1. Deprecated since 7.55.0.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
.BR CURLINFO_SIZE_DOWNLOAD_T "(3), "
.BR CURLINFO_SIZE_UPLOAD_T "(3), "
share/man/man3/curl_easy_option_next.3 0000644 00000006443 14751150700 0013766 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_easy_option_next 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_easy_option_next - iterate over easy setopt options
.SH SYNOPSIS
.nf
#include <curl/curl.h>
typedef enum {
CURLOT_LONG, /* long (a range of values) */
CURLOT_VALUES, /* (a defined set or bitmask) */
CURLOT_OFF_T, /* curl_off_t (a range of values) */
CURLOT_OBJECT, /* pointer (void *) */
CURLOT_STRING, /* (char * to null-terminated buffer) */
CURLOT_SLIST, /* (struct curl_slist *) */
CURLOT_CBPTR, /* (void * passed as-is to a callback) */
CURLOT_BLOB, /* blob (struct curl_blob *) */
CURLOT_FUNCTION /* function pointer */
} curl_easytype;
/* The CURLOPTTYPE_* id ranges can still be used to figure out what type/size
to use for curl_easy_setopt() for the given id */
struct curl_easyoption {
const char *name;
CURLoption id;
curl_easytype type;
unsigned int flags;
};
const struct curl_easyoption *
curl_easy_option_next(const struct curl_easyoption *prev);
.fi
.SH DESCRIPTION
This function returns a pointer to the first or the next \fIcurl_easyoption\fP
struct, providing an ability to iterate over all known options for
\fIcurl_easy_setopt(3)\fP in this instance of libcurl.
Pass a \fBNULL\fP argument as \fBprev\fP to get the first option returned, or
pass in the current option to get the next one returned. If there is no more
option to return, \fIcurl_easy_option_next(3)\fP returns NULL.
The options returned by this functions are the ones known to this libcurl and
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
A pointer to the \fIcurl_easyoption\fP struct for the next option or NULL if
no more options.
.SH "SEE ALSO"
.BR curl_easy_option_by_name "(3)," curl_easy_option_by_id "(3),"
.BR curl_easy_setopt "(3),"
share/man/man3/curl_multi_fdset.3 0000644 00000011267 14751150700 0012716 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_multi_fdset 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_multi_fdset - extracts file descriptor information from a multi handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_fdset(CURLM *multi_handle,
fd_set *read_fd_set,
fd_set *write_fd_set,
fd_set *exc_fd_set,
int *max_fd);
.ad
.SH DESCRIPTION
This function extracts file descriptor information from a given multi_handle.
libcurl returns its \fIfd_set\fP sets. The application can use these to
select() on, but be sure to \fIFD_ZERO\fP them before calling this function as
\fIcurl_multi_fdset(3)\fP only adds its own descriptors, it does not zero or
otherwise remove any others. The \fIcurl_multi_perform(3)\fP function should
be called as soon as one of them is ready to be read from or written to.
If the \fIread_fd_set\fP argument is not a null pointer, it points to an
object of type \fBfd_set\fP that on returns specifies the file descriptors to
be checked for being ready to read.
If the \fIwrite_fd_set\fP argument is not a null pointer, it points to an
object of type \fBfd_set\fP that on return specifies the file descriptors to
be checked for being ready to write.
If the \fIexc_fd_set\fP argument is not a null pointer, it points to an object
of type \fBfd_set\fP that on return specifies the file descriptors to be
checked for error conditions pending.
If no file descriptors are set by libcurl, \fImax_fd\fP will contain -1 when
this function returns. Otherwise it will contain the highest descriptor number
libcurl set. When libcurl returns -1 in \fImax_fd\fP, it is because libcurl
currently does something that is not possible for your application to monitor
with a socket and unfortunately you can then not know exactly when the current
action is completed using select(). You then need to wait a while before you
proceed and call \fIcurl_multi_perform(3)\fP anyway. How long to wait? Unless
\fIcurl_multi_timeout(3)\fP gives you a lower number, we suggest 100
milliseconds or so, but you may want to test it out in your own particular
conditions to find a suitable value.
When doing select(), you should use \fIcurl_multi_timeout(3)\fP to figure out
how long to wait for action. Call \fIcurl_multi_perform(3)\fP even if no
activity has been seen on the \fBfd_sets\fP after the timeout expires as
otherwise internal retries and timeouts may not work as you would think and
want.
If one of the sockets used by libcurl happens to be larger than what can be
set in an \fBfd_set\fP, which on POSIX systems means that the file descriptor
is larger than \fBFD_SETSIZE\fP, then libcurl will try to not set it. Setting
a too large file descriptor in an \fBfd_set\fP 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
\fBCURLMcode\fP type, general libcurl multi interface error code. See
\fIlibcurl-errors(3)\fP
.SH "SEE ALSO"
.BR curl_multi_cleanup "(3), " curl_multi_init "(3), "
.BR curl_multi_wait "(3), "
.BR curl_multi_timeout "(3), " curl_multi_perform "(3), " select "(2) "
share/man/man3/curl_share_strerror.3 0000644 00000003672 14751150700 0013444 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_share_strerror 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_share_strerror - return string describing error code
.SH SYNOPSIS
.nf
.B #include <curl/curl.h>
.BI "const char *curl_share_strerror(CURLSHcode " errornum ");"
.SH DESCRIPTION
The \fIcurl_share_strerror(3)\fP function returns a string describing the
\fICURLSHcode\fP 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
A pointer to a null-terminated string.
.SH "SEE ALSO"
.BR libcurl-errors "(3), " curl_multi_strerror "(3), "
.BR curl_easy_strerror "(3), " curl_url_strerror "(3)"
share/man/man3/CURLOPT_MAX_RECV_SPEED_LARGE.3 0000644 00000005032 14751150700 0013651 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_MAX_RECV_SPEED_LARGE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_MAX_RECV_SPEED_LARGE \- rate limit data download speed
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAX_RECV_SPEED_LARGE,
curl_off_t maxspeed);
.SH DESCRIPTION
Pass a curl_off_t as parameter. If a download exceeds this \fImaxspeed\fP
(counted in bytes per second) the transfer will pause to keep the speed less
than or equal to the parameter value. Defaults to unlimited speed.
This is not an exact science. libcurl attempts to keep the average speed below
the given threshold over a period time.
If you set \fImaxspeed\fP to a value lower than \fICURLOPT_BUFFERSIZE(3)\fP,
libcurl might download faster than the set limit initially.
This option does not affect transfer speeds done with FILE:// URLs.
.SH DEFAULT
0, disabled
.SH PROTOCOLS
All but file://
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode ret;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
/* cap the download speed to 31415 bytes/sec */
curl_easy_setopt(curl, CURLOPT_MAX_RECV_SPEED_LARGE, (curl_off_t)31415);
ret = curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.15.5
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_MAX_SEND_SPEED_LARGE "(3), " CURLOPT_LOW_SPEED_LIMIT "(3), "
share/man/man3/CURLINFO_RTSP_CSEQ_RECV.3 0000644 00000004213 14751150700 0013066 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_RTSP_CSEQ_RECV 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_RTSP_CSEQ_RECV \- get the recently received CSeq
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_RTSP_CSEQ_RECV, long *cseq);
.fi
.SH DESCRIPTION
Pass a pointer to a long to receive the most recently received CSeq from the
server. If your application encounters a \fICURLE_RTSP_CSEQ_ERROR\fP then you
may wish to troubleshoot and/or fix the CSeq mismatch by peeking at this
value.
.SH PROTOCOLS
RTSP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res;
curl_easy_setopt(curl, CURLOPT_URL, "rtsp://rtsp.example.com");
res = curl_easy_perform(curl);
if(res == CURLE_OK) {
long cseq;
curl_easy_getinfo(curl, CURLINFO_RTSP_CSEQ_RECV, &cseq);
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.20.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
share/man/man3/CURLMOPT_MAX_TOTAL_CONNECTIONS.3 0000644 00000005643 14751150700 0014132 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLMOPT_MAX_TOTAL_CONNECTIONS 3 "May 17, 2022" "libcurl 7.86.0" "curl_multi_setopt options"
.SH NAME
CURLMOPT_MAX_TOTAL_CONNECTIONS \- max simultaneously open connections
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_TOTAL_CONNECTIONS,
long amount);
.fi
.SH DESCRIPTION
Pass a long for the \fBamount\fP. The set number will be used as the maximum
number of simultaneously open connections in total using this multi
handle. For each new session, libcurl will open a new connection up to the
limit set by \fICURLMOPT_MAX_TOTAL_CONNECTIONS(3)\fP. When the limit is
reached, the sessions will be pending until there are available
connections. If \fICURLMOPT_PIPELINING(3)\fP is enabled, libcurl will try to
use multiplexing if the host is capable of it.
When more transfers are added to the multi handle than what can be performed
due to the set limit, they will be queued up waiting for their chance. When
that happens, the \fICURLOPT_TIMEOUT_MS(3)\fP timeout will be counted
inclusive of the waiting time, meaning that if you set a too narrow timeout in
such a case the transfer might never even start before it times out.
Even in the queued up situation, the \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP
timeout is however treated as a per-connect timeout.
.SH DEFAULT
The default value is 0, which means that there is no limit. It is then simply
controlled by the number of easy handles added.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURLM *m = curl_multi_init();
/* never do more than 15 connections */
curl_multi_setopt(m, CURLMOPT_MAX_TOTAL_CONNECTIONS, 15L);
.fi
.SH AVAILABILITY
Added in 7.30.0
.SH RETURN VALUE
Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLMOPT_MAXCONNECTS "(3), " CURLMOPT_MAX_HOST_CONNECTIONS "(3), "
share/man/man3/libcurl-url.3 0000644 00000012437 14751150700 0011606 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH libcurl 3 "September 20, 2022" "libcurl 7.86.0" "libcurl URL interface"
.SH NAME
libcurl-url \- URL interface overview
.SH DESCRIPTION
The URL interface provides functions for parsing and generating URLs.
.SH INCLUDE
You still only include <curl/curl.h> in your code.
.SH CREATE
Create a handle that holds URL info and resources with \fIcurl_url(3)\fP:
.nf
CURLU *h = curl_url();
.fi
.SH CLEANUP
When done with it, clean it up with \fIcurl_url_cleanup(3)\fP
.nf
curl_url_cleanup(h);
.fi
.SH DUPLICATE
When you need a copy of a handle, just duplicate it with \fIcurl_url_dup(3)\fP:
.nf
CURLU *nh = curl_url_dup(h);
.fi
.SH PARSING
By setting a URL to the handle with \fIcurl_url_set(3)\fP, the URL is parsed
and stored in the handle. If the URL is not syntactically correct it will
return an error instead.
.nf
rc = curl_url_set(h, CURLUPART_URL,
"https://example.com:449/foo/bar?name=moo", 0);
.fi
The zero in the fourth argument is a bitmask for changing specific features.
If successful, this stores the URL in its individual parts within the handle.
.SH REDIRECT
When a handle already contains info about a URL, setting a relative URL will
make it "redirect" to adapt to it.
.nf
rc = curl_url_set(h, CURLUPART_URL, "../test?another", 0);
.fi
.SH "GET URL"
The \fBCURLU\fP handle represents a URL and you can easily extract that with
\fIcurl_url_get(3)\fP:
.nf
char *url;
rc = curl_url_get(h, CURLUPART_URL, &url, 0);
curl_free(url);
.fi
The zero in the fourth argument is a bitmask for changing specific features.
.SH "GET PARTS"
When a URL has been parsed or parts have been set, you can extract those
pieces from the handle at any time.
.nf
rc = curl_url_get(h, CURLUPART_HOST, &host, 0);
rc = curl_url_get(h, CURLUPART_SCHEME, &scheme, 0);
rc = curl_url_get(h, CURLUPART_USER, &user, 0);
rc = curl_url_get(h, CURLUPART_PASSWORD, &password, 0);
rc = curl_url_get(h, CURLUPART_PORT, &port, 0);
rc = curl_url_get(h, CURLUPART_PATH, &path, 0);
rc = curl_url_get(h, CURLUPART_QUERY, &query, 0);
rc = curl_url_get(h, CURLUPART_FRAGMENT, &fragment, 0);
.fi
Extracted parts are not URL decoded unless the user also asks for it with the
\fICURLU_URLDECODE\fP flag set in the fourth bitmask argument.
Remember to free the returned string with \fIcurl_free(3)\fP when you are done
with it!
.SH "SET PARTS"
A user set individual URL parts, either after having parsed a full URL or
instead of parsing such.
.nf
rc = curl_url_set(urlp, CURLUPART_HOST, "www.example.com", 0);
rc = curl_url_set(urlp, CURLUPART_SCHEME, "https", 0);
rc = curl_url_set(urlp, CURLUPART_USER, "john", 0);
rc = curl_url_set(urlp, CURLUPART_PASSWORD, "doe", 0);
rc = curl_url_set(urlp, CURLUPART_PORT, "443", 0);
rc = curl_url_set(urlp, CURLUPART_PATH, "/index.html", 0);
rc = curl_url_set(urlp, CURLUPART_QUERY, "name=john", 0);
rc = curl_url_set(urlp, CURLUPART_FRAGMENT, "anchor", 0);
.fi
Set parts are not URL encoded unless the user asks for it with the
\fICURLU_URLENCODE\fP flag.
.SH "CURLU_APPENDQUERY"
An application can append a string to the right end of the query part with the
\fICURLU_APPENDQUERY\fP flag to \fIcurl_url_set(3)\fP.
Imagine a handle that holds the URL "https://example.com/?shoes=2". An
application can then add the string "hat=1" to the query part like this:
.nf
rc = curl_url_set(urlp, CURLUPART_QUERY, "hat=1", CURLU_APPENDQUERY);
.fi
It will even notice the lack of an ampersand (&) separator so it will inject
one too, and the handle's full URL will then equal
"https://example.com/?shoes=2&hat=1".
The appended string can of course also get URL encoded on add, and if asked to
URL encode, the encoding process will skip the '=' character. For example,
append "candy=N&N" to what we already have, and URL encode it to deal with the
ampersand in the data:
.nf
rc = curl_url_set(urlp, CURLUPART_QUERY, "candy=N&N",
CURLU_APPENDQUERY | CURLU_URLENCODE);
.fi
Now the URL looks like
.nf
https://example.com/?shoes=2&hat=1&candy=N%26N
.fi
.SH AVAILABILITY
The URL API was introduced in libcurl 7.62.0.
.SH "SEE ALSO"
.BR curl_url "(3), " curl_url_cleanup "(3), " curl_url_get "(3), "
.BR curl_url_dup "(3), " curl_url_set "(3), " curl_url_strerror "(3), "
.BR CURLOPT_URL "(3)"
share/man/man3/CURLINFO_CONNECT_TIME.3 0000644 00000004425 14751150700 0012560 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_CONNECT_TIME 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_CONNECT_TIME \- get the time until connect
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONNECT_TIME, double *timep);
.fi
.SH DESCRIPTION
Pass a pointer to a double to receive the total time in seconds from the start
until the connection to the remote host (or proxy) was completed.
When a redirect is followed, the time from each request is added together.
See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
double connect;
curl_easy_setopt(curl, CURLOPT_URL, url);
res = curl_easy_perform(curl);
if(CURLE_OK == res) {
res = curl_easy_getinfo(curl, CURLINFO_CONNECT_TIME, &connect);
if(CURLE_OK == res) {
printf("Time: %.1f", connect);
}
}
/* always cleanup */
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.4.1
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), " CURLINFO_CONNECT_TIME_T "(3)"
share/man/man3/CURLOPT_FTP_SSL_CCC.3 0000644 00000005056 14751150700 0012403 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_FTP_SSL_CCC 3 "October 22, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_FTP_SSL_CCC \- switch off SSL again with FTP after auth
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_SSL_CCC,
long how);
.fi
.SH DESCRIPTION
If enabled, this option makes libcurl use CCC (Clear Command Channel). It
shuts down the SSL/TLS layer after authenticating. The rest of the control
channel communication will be unencrypted. This allows NAT routers to follow
the FTP transaction. Pass a long using one of the values below
.IP CURLFTPSSL_CCC_NONE
do not attempt to use CCC.
.IP CURLFTPSSL_CCC_PASSIVE
Do not initiate the shutdown, but wait for the server to do it. Do not send a
reply.
.IP CURLFTPSSL_CCC_ACTIVE
Initiate the shutdown and wait for a reply.
.SH DEFAULT
CURLFTPSSL_CCC_NONE
.SH PROTOCOLS
FTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/file.txt");
curl_easy_setopt(curl, CURLOPT_USE_SSL, CURLUSESSL_CONTROL);
/* go back to clear-text FTP after authenticating */
curl_easy_setopt(curl, CURLOPT_FTP_SSL_CCC, (long)CURLFTPSSL_CCC_ACTIVE);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.16.1
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_USE_SSL "(3), " CURLOPT_FTPSSLAUTH "(3), "
share/man/man3/CURLOPT_KEYPASSWD.3 0000644 00000004774 14751150700 0012141 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_KEYPASSWD 3 "October 11, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_KEYPASSWD \- passphrase to private key
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_KEYPASSWD, char *pwd);
.fi
.SH DESCRIPTION
Pass a pointer to a null-terminated string as parameter. It will be used as
the password required to use the \fICURLOPT_SSLKEY(3)\fP or
\fICURLOPT_SSH_PRIVATE_KEYFILE(3)\fP private key. You never need a pass
phrase to load a certificate but you need one to load your private key.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
curl_easy_setopt(curl, CURLOPT_SSLCERT, "client.pem");
curl_easy_setopt(curl, CURLOPT_SSLKEY, "key.pem");
curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "superman");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
This option was known as CURLOPT_SSLKEYPASSWD up to 7.16.4 and
CURLOPT_SSLCERTPASSWD up to 7.9.2.
.SH RETURN VALUE
Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_SSLKEY "(3), " CURLOPT_SSH_PRIVATE_KEYFILE "(3), "
share/man/man3/CURLOPT_MAIL_RCPT.3 0000644 00000005766 14751150700 0012143 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_MAIL_RCPT 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_MAIL_RCPT \- list of SMTP mail recipients
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAIL_RCPT,
struct curl_slist *rcpts);
.SH DESCRIPTION
Pass a pointer to a linked list of recipients to pass to the server in your
SMTP mail request. The linked list should be a fully valid list of
\fBstruct curl_slist\fP structs properly filled in. Use
\fIcurl_slist_append(3)\fP to create the list and \fIcurl_slist_free_all(3)\fP
to clean up an entire list.
When performing a mail transfer, each recipient should be specified within a
pair of angled brackets (<>), however, should you not use an angled bracket as
the first character libcurl will assume you provided a single email address
and enclose that address within brackets for you.
When performing an address verification (\fBVRFY\fP command), each recipient
should be specified as the user name or user name and domain (as per Section
3.5 of RFC5321).
When performing a mailing list expand (\fBEXPN\fP command), each recipient
should be specified using the mailing list name, such as "Friends" or
"London-Office".
.SH DEFAULT
NULL
.SH PROTOCOLS
SMTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
struct curl_slist *list;
list = curl_slist_append(NULL, "root@localhost");
list = curl_slist_append(list, "person@example.com");
curl_easy_setopt(curl, CURLOPT_URL, "smtp://example.com/");
curl_easy_setopt(curl, CURLOPT_MAIL_RCPT, list);
ret = curl_easy_perform(curl);
curl_slist_free_all(list);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.20.0. The \fBVRFY\fP and \fBEXPN\fP logic was added in 7.34.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_MAIL_FROM "(3), " CURLOPT_MAIL_AUTH "(3), "
share/man/man3/curl_mime_headers.3 0000644 00000004731 14751150700 0013017 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_mime_headers 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_mime_headers - set a mime part's custom headers
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_mime_headers(curl_mimepart *part,
struct curl_slist *headers, int take_ownership);
.fi
.SH DESCRIPTION
\fIcurl_mime_headers(3)\fP sets a mime part's custom headers.
\fIpart\fP is the part's handle to assign the custom headers list to.
\fIheaders\fP is the head of a list of custom headers; it may be set to NULL
to remove a previously attached custom header list.
\fItake_ownership\fP: when non-zero, causes the list to be freed upon
replacement or mime structure deletion; in this case the list must not be
freed explicitly.
Setting a part's custom headers list multiple times is valid: only the value
set by the last call is retained.
.SH EXAMPLE
.nf
struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Custom-Header: mooo");
/* use these headers, please take ownership */
curl_mime_headers(part, headers, TRUE);
/* pass on this data */
curl_mime_data(part, "12345679", CURL_ZERO_TERMINATED);
/* 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)"
share/man/man3/curl_easy_option_by_id.3 0000644 00000004336 14751150700 0014075 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_easy_option_by_id 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_easy_option_by_id - find an easy setopt option by id
.SH SYNOPSIS
.nf
#include <curl/curl.h>
const struct curl_easyoption *curl_easy_option_by_id(CURLoption id);
.fi
.SH DESCRIPTION
Given a \fICURLoption\fP \fBid\fP, this function returns a pointer to the
\fIcurl_easyoption\fP struct, holding information about the
\fIcurl_easy_setopt(3)\fP option using that id. The option id is the CURLOPT_
prefix ones provided in the standard curl/curl.h header file. This function
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
A pointer to the \fIcurl_easyoption\fP struct for the option or NULL.
.SH "SEE ALSO"
.BR curl_easy_option_by_name "(3)," curl_easy_option_next "(3),"
.BR curl_easy_setopt "(3),"
share/man/man3/CURLINFO_SPEED_DOWNLOAD_T.3 0000644 00000004350 14751150700 0013260 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_SPEED_DOWNLOAD_T 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_SPEED_DOWNLOAD_T \- get download speed
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SPEED_DOWNLOAD_T,
curl_off_t *speed);
.fi
.SH DESCRIPTION
Pass a pointer to a \fIcurl_off_t\fP to receive the average download speed
that curl measured for the complete download. Measured in bytes/second.
.SH PROTOCOLS
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* Perform the request */
res = curl_easy_perform(curl);
if(!res) {
curl_off_t speed;
res = curl_easy_getinfo(curl, CURLINFO_SPEED_DOWNLOAD_T, &speed);
if(!res) {
printf("Download speed %" CURL_FORMAT_CURL_OFF_T " bytes/sec\\n", speed);
}
}
}
.fi
.SH AVAILABILITY
Added in 7.55.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
.BR CURLINFO_SPEED_UPLOAD "(3), "
.BR CURLINFO_SIZE_UPLOAD_T "(3), "
share/man/man3/curl_mprintf.3 0000644 00000026241 14751150700 0012054 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_printf 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_maprintf, curl_mfprintf, curl_mprintf, curl_msnprintf, curl_msprintf
curl_mvaprintf, curl_mvfprintf, curl_mvprintf, curl_mvsnprintf,
curl_mvsprintf - formatted output conversion
.SH SYNOPSIS
.nf
#include <curl/mprintf.h>
int curl_mprintf(const char *format, ...);
int curl_mfprintf(FILE *fd, const char *format, ...);
int curl_msprintf(char *buffer, const char *format, ...);
int curl_msnprintf(char *buffer, size_t maxlength, const char *format, ...);
int curl_mvprintf(const char *format, va_list args);
int curl_mvfprintf(FILE *fd, const char *format, va_list args);
int curl_mvsprintf(char *buffer, const char *format, va_list args);
int curl_mvsnprintf(char *buffer, size_t maxlength, const char *format,
va_list args);
char *curl_maprintf(const char *format , ...);
char *curl_mvaprintf(const char *format, va_list args);
.fi
.SH DESCRIPTION
These functions produce output according to the format string and given
arguments. They are mostly clones of the well-known C-style functions but
there are slight differences in behavior.
We discourage users from using any of these functions in new applications.
Functions in the curl_mprintf() family produce output according to a format as
described below. The functions \fBcurl_mprintf()\fP and \fBcurl_mvprintf()\fP
write output to stdout, the standard output stream; \fBcurl_mfprintf()\fP and
\fBcurl_mvfprintf()\fP write output to the given output stream;
\fBcurl_msprintf()\fP, \fBcurl_msnprintf()\fP, \fBcurl_mvsprintf()\fP, and
\fBcurl_mvsnprintf()\fP write to the character string \fBbuffer\fP.
The functions \fBcurl_msnprintf()\fP and \fBcurl_mvsnprintf()\fP write at most
\fImaxlength\fP bytes (including the terminating null byte ('\\0')) to
\fIbuffer\fP.
The functions \fBcurl_mvprintf()\fP, \fBcurl_mvfprintf()\fP,
\fBcurl_mvsprintf()\fP, \fBcurl_mvsnprintf()\fP are equivalent to the
functions \fBcurl_mprintf()\fP, \fBcurl_mfprintf()\fP, \fBcurl_msprintf()\fP,
\fBcurl_msnprintf()\fP, respectively, except that they are called with a
\fIva_list\fP instead of a variable number of arguments. These functions do
not call the \fIva_end\fP macro. Because they invoke the \fIva_arg\fP macro,
the value of \fIap\fP is undefined after the call.
The functions \fBcurl_maprintf()\fP and \fBcurl_mvaprintf()\fP return the
output string as pointer to a newly allocated memory area. The returned string
must be \fIcurl_free(3)\fPed by the receiver.
All of these functions write the output under the control of a format string
that specifies how subsequent arguments are converted for output.
.SH FORMAT STRING
The format string is composed of zero or more directives: ordinary characters
(not %), which are copied unchanged to the output stream; and conversion
specifications, each of which results in fetching zero or more subsequent
arguments. Each conversion specification is introduced by the character %, and
ends with a conversion specifier. In between there may be (in this order) zero
or more \fIflags\fP, an optional minimum \fIfield width\fP, an optional
\fIprecision\fP and an optional \fIlength modifier\fP.
.SH "The $ modifier"
The arguments must correspond properly with the conversion specifier. By
default, the arguments are used in the order given, where each '*' (see Field
width and Precision below) and each conversion specifier asks for the next
argument (and it is an error if insufficiently many arguments are given). One
can also specify explicitly which argument is taken, at each place where an
argument is required, by writing "%m$" instead of '%' and "*m$" instead
of '*', where the decimal integer m denotes the position in the argument list
of the desired argument, indexed starting from 1. Thus,
.nf
curl_mprintf("%*d", width, num);
.fi
and
.nf
curl_mprintf("%2$*1$d", width, num);
.fi
are equivalent. The second style allows repeated references to the same
argument.
If the style using '$' is used, it must be used throughout for all conversions
taking an argument and all width and precision arguments, but it may be mixed
with "%%" formats, which do not consume an argument. There may be no gaps in
the numbers of arguments specified using '$'; for example, if arguments 1 and
3 are specified, argument 2 must also be specified somewhere in the format
string.
.SH "Flag characters"
The character % is followed by zero or more of the following flags:
.TP
.B #
The value should be converted to its "alternate form".
.TP
.B 0
The value should be zero padded.
.TP
.B -
The converted value is to be left adjusted on the field boundary. (The
default is right justification.) The converted value is padded on the right
with blanks, rather than on the left with blanks or zeros. A '-' overrides a
\&'0' if both are given.
.TP
.B ' '
(a space) A blank should be left before a positive number (or empty string)
produced by a signed conversion.
.TP
.B +
A sign (+ or -) should always be placed before a number produced by a signed
conversion. By default, a sign is used only for negative numbers. A '+'
overrides a space if both are used.
.SH "Field width"
An optional decimal digit string (with nonzero first digit) specifying a
minimum field width. If the converted value has fewer characters than the
field width, it will be padded with spaces on the left (or right, if the
left-adjustment flag has been given). Instead of a decimal digit string one
may write "*" or "*m$" (for some decimal integer m) to specify that the field
width is given in the next argument, or in the \fIm-th\fP argument,
respectively, which must be of type int. A negative field width is taken as
a '-' flag followed by a positive field width. In no case does a nonexistent
or small field width cause truncation of a field; if the result of a
conversion is wider than the field width, the field is expanded to contain the
conversion result.
.SH "Precision"
An optional precision in the form of a period ('.') followed by an optional
decimal digit string. Instead of a decimal digit string one may write "*" or
"*m$" (for some decimal integer m) to specify that the precision is given in
the next argument, or in the \fIm-th\fP argument, respectively, which must be of
type int. If the precision is given as just '.', the precision is taken to be
zero. A negative precision is taken as if the precision were omitted. This
gives the minimum number of digits to appear for \fBd\fP, \fBi\fP, \fBo\fP,
\fBu\fP, \fBx\fP, and \fBX\fP conversions, the number of digits to appear
after the radix character for \fBa\fP, \fBA\fP, \fBe\fP, \fBE\fP, \fBf\fP, and
\fBF\fP conversions, the maximum number of significant digits for \fBg\fP and
\fBG\fP conversions, or the maximum number of characters to be printed from a
string for \fBs\fP and \fBS\fP conversions.
.SH "Length modifier"
.TP
.B h
A following integer conversion corresponds to a \fIshort\fP or \fIunsigned
short\fP argument.
.TP
.B l
(ell) A following integer conversion corresponds to a \fIlong\fP or
\fIunsigned long\fP argument, or a following n conversion corresponds to a
pointer to a long argument
.TP
.B ll
(ell-ell). A following integer conversion corresponds to a \fIlong long\fP or
\fIunsigned long long\fP argument, or a following n conversion corresponds to
a pointer to a long long argument.
.TP
.B q
A synonym for \fBll\fP.
.TP
.B L
A following a, A, e, E, f, F, g, or G conversion corresponds to a long double
argument.
.TP
.B z
A following integer conversion corresponds to a \fIsize_t\fP or \fIssize_t\fP
argument.
.SH "Conversion specifiers"
A character that specifies the type of conversion to be applied. The
conversion specifiers and their meanings are:
.TP
.B d, i
The int argument is converted to signed decimal notation. The precision, if
any, gives the minimum number of digits that must appear; if the converted
value requires fewer digits, it is padded on the left with zeros. The default
precision is 1. When 0 is printed with an explicit precision 0, the output is
empty.
.TP
.B o, u, x, X
The unsigned int argument is converted to unsigned octal (o), unsigned decimal
(u), or unsigned hexadecimal (\fBx\fP and \fBX\fP) notation. The letters
\fIabcdef\fP are used for \fBx\fP conversions; the letters \fIABCDEF\fP are
used for \fBX\fP conversions. The precision, if any, gives the minimum number
of digits that must appear; if the converted value requires fewer digits, it
is padded on the left with zeros. The default precision is 1. When 0 is
printed with an explicit precision 0, the output is empty.
.TP
.B e, E
The double argument is rounded and output in the style \fB"[-]d.ddde±dd"\fP
.TP
.B f, F
The double argument is rounded and output to decimal notation in the style
\fB"[-]ddd.ddd"\fP.
.TP
.B g, G
The double argument is converted in style f or e.
.TP
.B c
The int argument is converted to an unsigned char, and the resulting character
is written.
.TP
.B s
The \fIconst char *\fP argument is expected to be a pointer to an array of
character type (pointer to a string). Characters from the array are written up
to (but not including) a terminating null byte. If a precision is specified,
no more than the number specified are written. If a precision is given, no
null byte need be present; if the precision is not specified, or is greater
than the size of the array, the array must contain a terminating null byte.
.TP
.B p
The \fIvoid *\fP pointer argument is printed in hexadecimal.
.TP
.B n
The number of characters written so far is stored into the integer pointed to
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.
.SH RETURN VALUE
The \fBcurl_maprintf\fP and \fBcurl_mvaprintf\fP functions return a pointer to
a newly allocated string, or NULL if it failed.
All other functions return the number of characters actually printed
(excluding the null byte used to end output to strings). Note that this
sometimes differ from how the POSIX versions of these functions work.
.SH "SEE ALSO"
.BR printf "(3), " sprintf "(3), " fprintf "(3), " vprintf "(3) "
share/man/man3/CURLOPT_SSLKEY.3 0000644 00000005066 14751150700 0011574 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SSLKEY 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSLKEY \- private key file for TLS and SSL client cert
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLKEY, char *keyfile);
.fi
.SH DESCRIPTION
Pass a pointer to a null-terminated string as parameter. The string should be
the file name of your private key. The default format is "PEM" and can be
changed with \fICURLOPT_SSLKEYTYPE(3)\fP.
(Windows, iOS and Mac OS X) This option is ignored by Secure Transport and
Schannel SSL backends because they expect the private key to be already present
in the key-chain or PKCS#12 file containing the certificate.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_SSLCERT, "client.pem");
curl_easy_setopt(curl, CURLOPT_SSLKEY, "key.pem");
curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "s3cret");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
If built TLS enabled.
.SH RETURN VALUE
Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_SSLKEYTYPE "(3), " CURLOPT_SSLCERT "(3), "
share/man/man3/CURLOPT_DNS_CACHE_TIMEOUT.3 0000644 00000005562 14751150700 0013300 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_DNS_CACHE_TIMEOUT 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_DNS_CACHE_TIMEOUT \- life-time for DNS cache entries
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_CACHE_TIMEOUT, long age);
.fi
.SH DESCRIPTION
Pass a long, this sets the timeout in seconds. Name resolves will be kept in
memory and used for this number of seconds. Set to zero to completely disable
caching, or set to -1 to make the cached entries remain forever. By default,
libcurl caches this info for 60 seconds.
The name resolve functions of various libc implementations do not re-read name
server information unless explicitly told so (for example, by calling
\fIres_init(3)\fP). This may cause libcurl to keep using the older server even
if DHCP has updated the server info, and this may look like a DNS cache issue
to the casual libcurl-app user.
Note that DNS entries have a "TTL" property but libcurl does not use that. This
DNS cache timeout is entirely speculative that a name will resolve to the same
address for a certain small amount of time into the future.
.SH DEFAULT
60
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
/* only reuse addresses for a short time */
curl_easy_setopt(curl, CURLOPT_DNS_CACHE_TIMEOUT, 2L);
ret = curl_easy_perform(curl);
/* in this second request, the cache will not be used if more than
two seconds have passed since the previous name resolve */
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_DNS_USE_GLOBAL_CACHE "(3), " CURLOPT_DNS_SERVERS "(3), "
.BR CURLOPT_RESOLVE "(3), "
share/man/man3/CURLOPT_SSH_COMPRESSION.3 0000644 00000004225 14751150700 0013074 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SSH_COMPRESSION 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSH_COMPRESSION \- enable SSH compression
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_COMPRESSION, long enable);
.fi
.SH DESCRIPTION
Pass a long as parameter set to 1L to enable or 0L to disable.
Enables built-in SSH compression. This is a request, not an order; the server
may or may not do it.
.SH DEFAULT
0, disabled
.SH PROTOCOLS
All SSH based protocols: SCP, SFTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com");
/* enable built-in compression */
curl_easy_setopt(curl, CURLOPT_SSH_COMPRESSION, 1L);
/* Perform the request */
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.56.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_ACCEPT_ENCODING "(3), " CURLOPT_TRANSFER_ENCODING "(3), "
share/man/man3/curl_easy_strerror.3 0000644 00000004122 14751150700 0013272 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_easy_strerror 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_easy_strerror - return string describing error code
.SH SYNOPSIS
.nf
#include <curl/curl.h>
const char *curl_easy_strerror(CURLcode errornum);
.fi
.SH DESCRIPTION
The \fIcurl_easy_strerror(3)\fP function returns a string describing the
CURLcode error code passed in the argument \fIerrornum\fP.
Typically applications also appreciate \fICURLOPT_ERRORBUFFER(3)\fP for more
specific error descriptions generated at runtime.
.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
A pointer to a null-terminated string.
.SH "SEE ALSO"
.BR libcurl-errors "(3), " curl_multi_strerror "(3), "
.BR curl_share_strerror "(3), " curl_url_strerror "(3)"
share/man/man3/curl_multi_timeout.3 0000644 00000006467 14751150700 0013305 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_multi_timeout 3 "July 14, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_multi_timeout \- how long to wait for action before proceeding
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_timeout(CURLM *multi_handle, long *timeout);
.fi
.SH DESCRIPTION
An application using the libcurl multi interface should call
\fIcurl_multi_timeout(3)\fP to figure out how long it should wait for socket
actions \- at most \- before proceeding.
Proceeding means either doing the socket-style timeout action: call the
\fIcurl_multi_socket_action(3)\fP function with the \fBsockfd\fP argument set
to CURL_SOCKET_TIMEOUT, or call \fIcurl_multi_perform(3)\fP if you are using
the simpler and older multi interface approach.
The timeout value returned in the long \fBtimeout\fP points to, is in number
of milliseconds at this moment. If 0, it means you should proceed immediately
without waiting for anything. If it returns -1, there's no timeout at all set.
An application that uses the multi_socket API SHOULD NOT use this function,
but SHOULD instead use the \fICURLMOPT_TIMERFUNCTION(3)\fP option for proper
and desired behavior.
Note: if libcurl returns a -1 timeout here, it just means that libcurl
currently has no stored timeout value. You must not wait too long (more than a
few seconds perhaps) before you call curl_multi_perform() again.
.SH EXAMPLE
.nf
struct timeval timeout;
long timeo;
curl_multi_timeout(multi_handle, &timeo);
if(timeo < 0)
/* no set timeout, use a default */
timeo = 980;
timeout.tv_sec = timeo / 1000;
timeout.tv_usec = (timeo % 1000) * 1000;
/* wait for activities no longer than the set timeout */
select(maxfd+1, &fdread, &fdwrite, &fdexcep, &timeout);
.fi
.SH TYPICAL USAGE
Call \fIcurl_multi_timeout(3)\fP, then wait for action on the sockets. Figure
out which sockets to wait for by calling \fIcurl_multi_fdset(3)\fP.
When there is activity or timeout, call \fIcurl_multi_perform(3)\fP and then
loop - until all transfers are complete.
.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) "
share/man/man3/curl_mime_data_cb.3 0000644 00000014332 14751150700 0012757 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_mime_data_cb 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_mime_data_cb - set a callback-based data source for a mime part's body
.SH SYNOPSIS
.nf
#include <curl/curl.h>
size_t readfunc(char *buffer, size_t size, size_t nitems, void *arg);
int seekfunc(void *arg, curl_off_t offset, int origin);
void freefunc(void *arg);
CURLcode curl_mime_data_cb(curl_mimepart *part, curl_off_t datasize,
curl_read_callback readfunc,
curl_seek_callback seekfunc,
curl_free_callback freefunc, void *arg);
.fi
.SH DESCRIPTION
\fIcurl_mime_data_cb(3)\fP sets the data source of a mime part's body content
from a data read callback function.
\fIpart\fP is the part's to assign contents to.
\fIreadfunc\fP is a pointer to a data read callback function, with a signature
as shown by the above prototype. It may not be set to NULL.
\fIseekfunc\fP is a pointer to a seek callback function, with a signature as
shown by the above prototype. This function will be used upon resending data
(i.e.: after a redirect); this pointer may be set to NULL, in which case a
resend is not possible.
\fIfreefunc\fP is a pointer to a user resource freeing callback function, with
a signature as shown by the above prototype. If no resource is to be freed, it
may safely be set to NULL. This function will be called upon mime structure
freeing.
\fIarg\fP is a user defined argument to callback functions.
The read callback function gets called by libcurl as soon as it needs to
read data in order to send it to the peer - like if you ask it to upload or
post data to the server. The data area pointed at by the pointer \fIbuffer\fP
should be filled up with at most \fIsize\fP multiplied with \fInitems\fP number
of bytes by your function.
Your read function must then return the actual number of bytes that it stored
in that memory area. Returning 0 will signal end-of-file to the library and
cause it to stop the current transfer.
If you stop the current transfer by returning 0 "pre-maturely" (i.e. before the
server expected it, like when you have said you will upload N bytes and you
upload less than N bytes), you may experience that the server "hangs" waiting
for the rest of the data that will not come.
The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current
operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error
code from the transfer.
The callback can return \fICURL_READFUNC_PAUSE\fP to cause reading from this
connection to pause. See \fIcurl_easy_pause(3)\fP for further details.
The seek function gets called by libcurl to rewind input stream data or to
seek to a certain position. The function shall work like fseek(3) or lseek(3)
and it gets SEEK_SET, SEEK_CUR or SEEK_END as argument for \fIorigin\fP,
although libcurl currently only passes SEEK_SET.
The callback function must return \fICURL_SEEKFUNC_OK\fP on success,
\fICURL_SEEKFUNC_FAIL\fP to cause the upload operation to fail or
\fICURL_SEEKFUNC_CANTSEEK\fP to indicate that while the seek failed, libcurl
is free to work around the problem if possible. The latter can sometimes be
done by instead reading from the input or similar.
Care must be taken if the part is bound to a curl easy handle that is later
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 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
callback source to avoid data duplication. In this case, original data
must be retained until after the transfer terminates.
.nf
char hugedata[512000];
struct ctl {
char *buffer;
curl_off_t size;
curl_off_t position;
};
size_t read_callback(char *buffer, size_t size, size_t nitems, void *arg)
{
struct ctl *p = (struct ctl *) arg;
curl_off_t sz = p->size - p->position;
nitems *= size;
if(sz > nitems)
sz = nitems;
if(sz)
memcpy(buffer, p->buffer + p->position, sz);
p->position += sz;
return sz;
}
int seek_callback(void *arg, curl_off_t offset, int origin)
{
struct ctl *p = (struct ctl *) arg;
switch(origin) {
case SEEK_END:
offset += p->size;
break;
case SEEK_CUR:
offset += p->position;
break;
}
if(offset < 0)
return CURL_SEEKFUNC_FAIL;
p->position = offset;
return CURL_SEEKFUNC_OK;
}
CURL *easy = curl_easy_init();
curl_mime *mime = curl_mime_init(easy);
curl_mimepart *part = curl_mime_addpart(mime);
struct ctl hugectl;
hugectl.buffer = hugedata;
hugectl.size = sizeof hugedata;
hugectl.position = 0;
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),"
.BR curl_mime_name "(3),"
.BR curl_easy_duphandle "(3)"
share/man/man3/CURLOPT_CONV_FROM_UTF8_FUNCTION.3 0000644 00000007367 14751150700 0014273 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_CONV_FROM_UTF8_FUNCTION 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_CONV_FROM_UTF8_FUNCTION \- convert data from UTF8 to host encoding
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode conv_callback(char *ptr, size_t length);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONV_FROM_UTF8_FUNCTION,
conv_callback);
.SH DESCRIPTION
Pass a pointer to your callback function, which should match the prototype
shown above.
Applies to non-ASCII platforms. \fIcurl_version_info(3)\fP will return the
CURL_VERSION_CONV feature bit set if this option is provided.
The data to be converted is in a buffer pointed to by the \fIptr\fP parameter.
The amount of data to convert is indicated by the \fIlength\fP parameter. The
converted data overlays the input data in the buffer pointed to by the ptr
parameter. \fICURLE_OK\fP must be returned upon successful conversion. A
CURLcode return value defined by curl.h, such as \fICURLE_CONV_FAILED\fP,
should be returned if an error was encountered.
\fBCURLOPT_CONV_FROM_UTF8_FUNCTION\fP converts to host encoding from UTF8
encoding. It is required only for SSL processing.
If you set a callback pointer to NULL, or do not set it at all, the built-in
libcurl iconv functions will be used. If HAVE_ICONV was not defined when
libcurl was built, and no callback has been established, conversion will
return the CURLE_CONV_REQD error code.
If HAVE_ICONV is defined, CURL_ICONV_CODESET_OF_HOST must also be defined.
For example:
\&#define CURL_ICONV_CODESET_OF_HOST "IBM-1047"
The iconv code in libcurl will default the network and UTF8 codeset names as
follows:
\&#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1"
\&#define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8"
You will need to override these definitions if they are different on your
system.
.SH DEFAULT
NULL
.SH PROTOCOLS
TLS-based protocols.
.SH EXAMPLE
.nf
static CURLcode my_conv_from_utf8_to_ebcdic(char *buffer, size_t length)
{
char *tempptrin, *tempptrout;
size_t bytes = length;
int rc;
tempptrin = tempptrout = buffer;
rc = platform_u2e(&tempptrin, &bytes, &tempptrout, &bytes);
if(rc == PLATFORM_CONV_OK) {
return CURLE_OK;
}
else {
return CURLE_CONV_FAILED;
}
}
curl_easy_setopt(curl, CURLOPT_CONV_FROM_UTF8_FUNCTION,
my_conv_from_utf8_to_ebcdic);
.fi
.SH AVAILABILITY
Not available since 7.82.0
Available only if \fBCURL_DOES_CONVERSIONS\fP was defined when libcurl was
built.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_CONV_TO_NETWORK_FUNCTION "(3), " CURLOPT_CONV_FROM_NETWORK_FUNCTION "(3), "
share/man/man3/CURLOPT_RTSP_SERVER_CSEQ.3 0000644 00000004027 14751150700 0013247 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_RTSP_SERVER_CSEQ 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_RTSP_SERVER_CSEQ \- RTSP server CSEQ number
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_SERVER_CSEQ, long cseq);
.fi
.SH DESCRIPTION
Pass a long to set the CSEQ number to expect for the next RTSP Server->Client
request. \fBNOTE\fP: this feature (listening for Server requests) is
unimplemented.
.SH DEFAULT
0
.SH PROTOCOLS
RTSP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/");
curl_easy_setopt(curl, CURLOPT_RTSP_SERVER_CSEQ, 1234L);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.20.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_RTSP_CLIENT_CSEQ "(3), " CURLOPT_RTSP_STREAM_URI "(3), "
share/man/man3/CURLOPT_FTP_ALTERNATIVE_TO_USER.3 0000644 00000004622 14751150700 0014306 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2014, 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_FTP_ALTERNATIVE_TO_USER 3 "July 04, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_FTP_ALTERNATIVE_TO_USER \- command to use instead of USER with FTP
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_ALTERNATIVE_TO_USER,
char *cmd);
.SH DESCRIPTION
Pass a char * as parameter, pointing to a string which will be used to
authenticate if the usual FTP "USER user" and "PASS password" negotiation
fails. This is currently only known to be required when connecting to
Tumbleweed's Secure Transport FTPS server using client certificates for
authentication.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
FTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/foo.bin");
curl_easy_setopt(curl, CURLOPT_FTP_ALTERNATIVE_TO_USER, "two users");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.15.5
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_FTP_SKIP_PASV_IP "(3), " CURLOPT_SERVER_RESPONSE_TIMEOUT "(3), "
share/man/man3/CURLOPT_COOKIEJAR.3 0000644 00000006221 14751150700 0012062 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_COOKIEJAR 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_COOKIEJAR \- file name to store cookies to
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIEJAR, char *filename);
.fi
.SH DESCRIPTION
Pass a \fIfilename\fP as char *, null-terminated. This will make libcurl write
all internally known cookies to the specified file when
\fIcurl_easy_cleanup(3)\fP is called. If no cookies are known, no file will be
created. Specify "-" as filename to instead have the cookies written to
stdout. Using this option also enables cookies for this session, so if you for
example follow a location it will make matching cookies get sent accordingly.
Note that libcurl does not read any cookies from the cookie jar. If you want to
read cookies from a file, use \fICURLOPT_COOKIEFILE(3)\fP.
If the cookie jar file cannot be created or written to (when the
\fIcurl_easy_cleanup(3)\fP is called), libcurl will not and cannot report an
error for this. Using \fICURLOPT_VERBOSE(3)\fP or
\fICURLOPT_DEBUGFUNCTION(3)\fP will get a warning to display, but that is the
only visible feedback you get about this possibly lethal situation.
Since 7.43.0 cookies that were imported in the Set-Cookie format without a
domain name are not exported by this option.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
/* export cookies to this file when closing the handle */
curl_easy_setopt(curl, CURLOPT_COOKIEJAR, "/tmp/cookies.txt");
ret = curl_easy_perform(curl);
/* close the handle, write the cookies! */
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Along with HTTP
.SH RETURN VALUE
Returns CURLE_OK if HTTP is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_COOKIEFILE "(3), " CURLOPT_COOKIE "(3), "
.BR CURLOPT_COOKIELIST "(3), "
share/man/man3/CURLINFO_REDIRECT_TIME_T.3 0000644 00000004757 14751150700 0013163 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 2022 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_REDIRECT_TIME_T 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_REDIRECT_TIME_T \- get the time for all redirection steps
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_REDIRECT_TIME_T,
curl_off_t *timep);
.fi
.SH DESCRIPTION
Pass a pointer to a curl_off_t to receive the total time, in microseconds,
it took for
all redirection steps include name lookup, connect, pretransfer and transfer
before final transaction was started. \fICURLINFO_REDIRECT_TIME_T\fP contains
the complete execution time for multiple redirections.
See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
curl_off_t redirect;
curl_easy_setopt(curl, CURLOPT_URL, url);
res = curl_easy_perform(curl);
if(CURLE_OK == res) {
res = curl_easy_getinfo(curl, CURLINFO_REDIRECT_TIME_T, &redirect);
if(CURLE_OK == res) {
printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", redirect / 1000000,
(long)(redirect % 1000000));
}
}
/* always cleanup */
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.61.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), " CURLINFO_REDIRECT_TIME "(3)"
share/man/man3/CURLOPT_CHUNK_DATA.3 0000644 00000005564 14751150700 0012226 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_CHUNK_DATA 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_CHUNK_DATA \- pointer passed to the FTP chunk callbacks
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CHUNK_DATA, void *pointer);
.fi
.SH DESCRIPTION
Pass a \fIpointer\fP that will be untouched by libcurl and passed as the ptr
argument to the \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP and
\fICURLOPT_CHUNK_END_FUNCTION(3)\fP.
.SH DEFAULT
NULL
.SH PROTOCOLS
FTP
.SH EXAMPLE
.nf
static long file_is_coming(struct curl_fileinfo *finfo,
struct callback_data *data,
int remains)
{
printf("%3d %40s %10luB ", remains, finfo->filename,
(unsigned long)finfo->size);
switch(finfo->filetype) {
case CURLFILETYPE_DIRECTORY:
printf(" DIR\\n");
break;
case CURLFILETYPE_FILE:
printf("FILE ");
break;
default:
printf("OTHER\\n");
break;
}
if(finfo->filetype == CURLFILETYPE_FILE) {
/* do not transfer files >= 50B */
if(finfo->size > 50) {
printf("SKIPPED\\n");
return CURL_CHUNK_BGN_FUNC_SKIP;
}
data->output = fopen(finfo->filename, "wb");
if(!data->output) {
return CURL_CHUNK_BGN_FUNC_FAIL;
}
}
return CURL_CHUNK_BGN_FUNC_OK;
}
int main()
{
/* data for callback */
struct callback_data callback_info;
/* callback is called before download of concrete file started */
curl_easy_setopt(curl, CURLOPT_CHUNK_BGN_FUNCTION, file_is_coming);
curl_easy_setopt(curl, CURLOPT_CHUNK_DATA, &callback_info);
}
.fi
.SH AVAILABILITY
Added in 7.21.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_CHUNK_BGN_FUNCTION "(3), " CURLOPT_WILDCARDMATCH "(3), "
share/man/man3/CURLOPT_UNRESTRICTED_AUTH.3 0000644 00000005517 14751150700 0013317 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_UNRESTRICTED_AUTH 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_UNRESTRICTED_AUTH \- send credentials to other hosts too
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UNRESTRICTED_AUTH,
long goahead);
.SH DESCRIPTION
Set the long \fIgohead\fP parameter to 1L to make libcurl continue to send
authentication (user+password) credentials when following locations, even when
hostname changed. This option is meaningful only when setting
\fICURLOPT_FOLLOWLOCATION(3)\fP.
Further, when this option is not used or set to \fB0L\fP, libcurl will not
send custom set nor internally generated Authentication: headers on requests
done to other hosts than the one used for the initial URL.
By default, libcurl will only send credentials and Authentication headers to
the initial host name as given in the original URL, to avoid leaking username
+ password to other sites.
This option should be used with caution: when curl follows redirects it
blindly fetches the next URL as instructed by the server. Setting
\fICURLOPT_UNRESTRICTED_AUTH(3)\fP to 1L will therefore also make curl trust
the server and send possibly sensitive credentials to a host the server points
out.
.SH DEFAULT
0
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
curl_easy_setopt(curl, CURLOPT_UNRESTRICTED_AUTH, 1L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Along with HTTP
.SH RETURN VALUE
Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_FOLLOWLOCATION "(3), " CURLOPT_USERPWD "(3), "
share/man/man3/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3 0000644 00000004554 14751150700 0014637 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE 3 "September 20, 2022" "libcurl 7.86.0" "curl_multi_setopt options"
.SH NAME
CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE \- chunk length threshold for pipelining
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE,
long size);
.fi
.SH DESCRIPTION
No function since pipelining was removed in 7.62.0.
Pass a long with a \fBsize\fP in bytes. If a transfer in a pipeline is
currently processing a chunked (Transfer-encoding: chunked) request with a
current chunk length larger than \fICURLMOPT_CHUNK_LENGTH_PENALTY_SIZE(3)\fP,
that pipeline will not be considered for additional requests, even if it is
shorter than \fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP.
.SH DEFAULT
The default value is 0, which means that the penalization is inactive.
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
.nf
CURLM *m = curl_multi_init();
long maxchunk = 10000;
curl_multi_setopt(m, CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE, maxchunk);
.fi
.SH AVAILABILITY
Added in 7.30.0
.SH RETURN VALUE
Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLMOPT_PIPELINING "(3), " CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE "(3), "
.BR CURLMOPT_MAX_PIPELINE_LENGTH "(3), "
share/man/man3/CURLINFO_CONTENT_LENGTH_UPLOAD_T.3 0000644 00000004363 14751150700 0014354 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_CONTENT_LENGTH_UPLOAD_T 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_CONTENT_LENGTH_UPLOAD_T \- get the specified size of the upload
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONTENT_LENGTH_UPLOAD_T,
curl_off_t *content_length);
.fi
.SH DESCRIPTION
Pass a pointer to a \fIcurl_off_t\fP to receive the specified size of the
upload. Stores -1 if the size is not known.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* Perform the upload */
res = curl_easy_perform(curl);
if(!res) {
/* check the size */
curl_off_t cl;
res = curl_easy_getinfo(curl, CURLINFO_CONTENT_LENGTH_UPLOAD_T, &cl);
if(!res) {
printf("Upload size: %" CURL_FORMAT_CURL_OFF_T "\\n", cl);
}
}
}
.fi
.SH AVAILABILITY
Added in 7.55.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
.BR CURLINFO_CONTENT_LENGTH_DOWNLOAD_T "(3), "
share/man/man3/CURLOPT_REDIR_PROTOCOLS_STR.3 0000644 00000006765 14751150700 0013632 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_REDIR_PROTOCOLS_STR 3 "September 13, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_REDIR_PROTOCOLS_STR \- protocols allowed to redirect to
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_REDIR_PROTOCOLS_STR,
char *spec);
.fi
.SH DESCRIPTION
Pass a pointer to a string that holds a comma-separated list of case
insensitive protocol names (URL schemes). That list limits what protocols
libcurl may use in a transfer that it follows to in a redirect when
\fICURLOPT_FOLLOWLOCATION(3)\fP is enabled. This option allows applications to
limit specific transfers to only be allowed to use a subset of protocols in
redirections.
Protocols denied by \fICURLOPT_PROTOCOLS_STR(3)\fP are not overridden by this
option.
By default libcurl will allow HTTP, HTTPS, FTP and FTPS on redirects (since
7.65.2). Older versions of libcurl allowed all protocols on redirect except
several disabled for security reasons: Since 7.19.4 FILE and SCP are disabled,
and since 7.40.0 SMB and SMBS are also disabled.
These are the available protocols:
DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS,
MQTT, POP3, POP3S, RTMP, RTMPE, RTMPS, RTMPT, RTMPTE, RTMPTS, RTSP, SCP, SFTP,
SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS, WSS
You can set "ALL" as a short-cut to enable all protocols. Note that by setting
all, you may enable protocols that were not supported the day you write this
but are introduced in a future libcurl version.
If trying to set a non-existing protocol or if no matching protocol at all is
set, it returns error.
.SH DEFAULT
HTTP, HTTPS, FTP and FTPS (Added in 7.65.2).
Older versions defaulted to all protocols except FILE, SCP and since 7.40.0
SMB and SMBS.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
/* pass in the URL from an external source */
curl_easy_setopt(curl, CURLOPT_URL, argv[1]);
/* only allow redirects to HTTP and HTTPS URLs */
curl_easy_setopt(curl, CURLOPT_REDIR_PROTOCOLS_STR, "http,https");
/* Perform the request */
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.85.0.
.SH RETURN VALUE
Returns CURLE_UNKNOWN_OPTION if the option is not implemented,
CURLE_UNSUPPORTED_PROTOCOL if a listed protocol is not supported or disabled,
CURLE_BAD_FUNCTION_ARGUMENT if no protocol is listed else CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_PROTOCOLS_STR "(3), "
share/man/man3/CURLOPT_USERAGENT.3 0000644 00000004414 14751150700 0012113 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_USERAGENT 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_USERAGENT \- HTTP user-agent header
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_USERAGENT, char *ua);
.fi
.SH DESCRIPTION
Pass a pointer to a null-terminated string as parameter. It will be used to
set the User-Agent: header in the HTTP request sent to the remote server. This
can be used to fool servers or scripts. You can also set any custom header
with \fICURLOPT_HTTPHEADER(3)\fP.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL, no User-Agent: header is used by default.
.SH PROTOCOLS
HTTP, HTTPS
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_USERAGENT, "Dark Secret Ninja/1.0");
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
As long as HTTP is supported
.SH RETURN VALUE
Returns CURLE_OK if HTTP is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_REFERER "(3), " CURLOPT_HTTPHEADER "(3), "
share/man/man3/curl_multi_cleanup.3 0000644 00000004532 14751150700 0013235 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_multi_cleanup 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_multi_cleanup - close down a multi session
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_cleanup(CURLM *multi_handle);
.fi
.SH DESCRIPTION
Cleans up and removes a whole multi stack. It does not free or touch any
individual easy handles in any way - they still need to be closed
individually, using the usual \fIcurl_easy_cleanup(3)\fP way. The order of
cleaning up should be:
1 - \fIcurl_multi_remove_handle(3)\fP before any easy handles are cleaned up
2 - \fIcurl_easy_cleanup(3)\fP can now be called independently since the easy
handle is no longer connected to the multi handle
3 - \fIcurl_multi_cleanup(3)\fP should be called when all easy handles are
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.
.SH "SEE ALSO"
.BR curl_multi_init "(3)," curl_easy_cleanup "(3)," curl_easy_init "(3)"
share/man/man3/CURLOPT_APPEND.3 0000644 00000004102 14751150700 0011517 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_APPEND 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_APPEND \- append to the remote file
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_APPEND, long append);
.fi
.SH DESCRIPTION
A long parameter set to 1 tells the library to append to the remote file
instead of overwrite it. This is only useful when uploading to an FTP site.
.SH DEFAULT
0 (disabled)
.SH PROTOCOLS
FTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/to/newfile");
curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L);
curl_easy_setopt(curl, CURLOPT_APPEND, 1L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
This option was known as CURLOPT_FTPAPPEND up to 7.16.4
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_DIRLISTONLY "(3), " CURLOPT_RESUME_FROM "(3), "
.BR CURLOPT_UPLOAD "(3), "
share/man/man3/curl_multi_info_read.3 0000644 00000007425 14751150700 0013540 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_multi_info_read 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_multi_info_read - read multi stack information
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMsg *curl_multi_info_read(CURLM *multi_handle, int *msgs_in_queue);
.fi
.SH DESCRIPTION
Ask the multi handle if there are any messages from the individual
transfers. Messages may include information such as an error code from the
transfer or just the fact that a transfer is completed. More details on these
should be written down as well.
Repeated calls to this function will return a new struct each time, until a
NULL is returned as a signal that there is no more to get at this point. The
integer pointed to with \fImsgs_in_queue\fP will contain the number of
remaining messages after this function was called.
When you fetch a message using this function, it is removed from the internal
queue so calling this function again will not return the same message
again. It will instead return new messages at each new invoke until the queue
is emptied.
\fBWARNING:\fP The data the returned pointer points to will not survive
calling \fIcurl_multi_cleanup(3)\fP, \fIcurl_multi_remove_handle(3)\fP or
\fIcurl_easy_cleanup(3)\fP.
The \fICURLMsg\fP struct is simple and only contains basic information. If
more involved information is wanted, the particular "easy handle" is present
in that struct and can be used in subsequent regular
\fIcurl_easy_getinfo(3)\fP calls (or similar):
.nf
struct CURLMsg {
CURLMSG msg; /* what this message means */
CURL *easy_handle; /* the handle it concerns */
union {
void *whatever; /* message-specific data */
CURLcode result; /* return code for transfer */
} data;
};
.fi
When \fBmsg\fP is \fICURLMSG_DONE\fP, the message identifies a transfer that
is done, and then \fBresult\fP contains the return code for the easy handle
that just completed.
At this point, there are no other \fBmsg\fP types defined.
.SH EXAMPLE
.nf
struct CURLMsg *m;
/* call curl_multi_perform or curl_multi_socket_action first, then loop
through and check if there are any transfers that have completed */
do {
int msgq = 0;
m = curl_multi_info_read(multi_handle, &msgq);
if(m && (m->msg == CURLMSG_DONE)) {
CURL *e = m->easy_handle;
transfers--;
curl_multi_remove_handle(multi_handle, e);
curl_easy_cleanup(e);
}
} while(m);
.fi
.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.
.SH "SEE ALSO"
.BR curl_multi_cleanup "(3), " curl_multi_init "(3), " curl_multi_perform "(3)"
share/man/man3/CURLOPT_MAIL_AUTH.3 0000644 00000005504 14751150700 0012122 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_MAIL_AUTH 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_MAIL_AUTH \- SMTP authentication address
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAIL_AUTH, char *auth);
.fi
.SH DESCRIPTION
Pass a pointer to a null-terminated string as parameter. This will be used to
specify the authentication address (identity) of a submitted message that is
being relayed to another server.
This optional parameter allows co-operating agents in a trusted environment to
communicate the authentication of individual messages and should only be used
by the application program, using libcurl, if the application is itself a mail
server acting in such an environment. If the application is operating as such
and the AUTH address is not known or is invalid, then an empty string should
be used for this parameter.
Unlike \fICURLOPT_MAIL_FROM(3)\fP and \fICURLOPT_MAIL_RCPT(3)\fP, the address
should not be specified within a pair of angled brackets (<>). However, if an
empty string is used then a pair of brackets will be sent by libcurl as
required by RFC2554.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
SMTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "smtp://example.com/");
curl_easy_setopt(curl, CURLOPT_MAIL_AUTH, "<secret@cave>");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.25.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_MAIL_FROM "(3), " CURLOPT_MAIL_RCPT "(3), "
share/man/man3/curl_version_info.3 0000644 00000024323 14751150700 0013074 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH curl_version_info 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_version_info - returns runtime libcurl version info
.SH SYNOPSIS
.nf
#include <curl/curl.h>
curl_version_info_data *curl_version_info( CURLversion age);
.fi
.SH DESCRIPTION
Returns a pointer to a filled in static struct with information about various
features in the running version of libcurl. \fIage\fP should be set to the
version of this functionality by the time you write your program. This way,
libcurl will always return a proper struct that your program understands,
while programs in the future might get a different
struct. \fBCURLVERSION_NOW\fP will be the most recent one for the library you
have installed:
.nf
data = curl_version_info(CURLVERSION_NOW);
.fi
Applications should use this information to judge if things are possible to do
or not, instead of using compile-time checks, as dynamic/DLL libraries can be
changed independent of applications.
The curl_version_info_data struct looks like this
.nf
typedef struct {
CURLversion age; /* see description below */
const char *version; /* human readable string */
unsigned int version_num; /* numeric representation */
const char *host; /* human readable string */
int features; /* bitmask, see below */
char *ssl_version; /* human readable string */
long ssl_version_num; /* not used, always zero */
const char *libz_version; /* human readable string */
const char *const *protocols; /* protocols */
/* when 'age' is CURLVERSION_SECOND or higher, the members below exist */
const char *ares; /* human readable string */
int ares_num; /* number */
/* when 'age' is CURLVERSION_THIRD or higher, the members below exist */
const char *libidn; /* human readable string */
/* when 'age' is CURLVERSION_FOURTH or higher (>= 7.16.1), the members
below exist */
int iconv_ver_num; /* '_libiconv_version' if iconv support enabled */
const char *libssh_version; /* human readable string */
/* when 'age' is CURLVERSION_FIFTH or higher (>= 7.57.0), the members
below exist */
unsigned int brotli_ver_num; /* Numeric Brotli version
(MAJOR << 24) | (MINOR << 12) | PATCH */
const char *brotli_version; /* human readable string. */
/* when 'age' is CURLVERSION_SIXTH or higher (>= 7.66.0), the members
below exist */
unsigned int nghttp2_ver_num; /* Numeric nghttp2 version
(MAJOR << 16) | (MINOR << 8) | PATCH */
const char *nghttp2_version; /* human readable string. */
const char *quic_version; /* human readable quic (+ HTTP/3) library +
version or NULL */
/* when 'age' is CURLVERSION_SEVENTH or higher (>= 7.70.0), the members
below exist */
const char *cainfo; /* the built-in default CURLOPT_CAINFO, might
be NULL */
const char *capath; /* the built-in default CURLOPT_CAPATH, might
be NULL */
/* when 'age' is CURLVERSION_EIGHTH or higher (>= 7.71.0), the members
below exist */
unsigned int zstd_ver_num; /* Numeric Zstd version
(MAJOR << 24) | (MINOR << 12) | PATCH */
const char *zstd_version; /* human readable string. */
/* when 'age' is CURLVERSION_NINTH or higher (>= 7.75.0), the members
below exist */
const char *hyper_version; /* human readable string. */
/* when 'age' is CURLVERSION_TENTH or higher (>= 7.77.0), the members
below exist */
const char *gsasl_version; /* human readable string. */
} curl_version_info_data;
.fi
\fIage\fP describes what the age of this struct is. The number depends on how
new the libcurl you are using is. You are however guaranteed to get a struct
that you have a matching struct for in the header, as you tell libcurl your
"age" with the input argument.
\fIversion\fP is just an ascii string for the libcurl version.
\fIversion_num\fP is a 24 bit number created like this: <8 bits major number>
| <8 bits minor number> | <8 bits patch number>. Version 7.9.8 is therefore
returned as 0x070908.
\fIhost\fP is an ascii string showing what host information that this libcurl
was built for. As discovered by a configure script or set by the build
environment.
\fIfeatures\fP can have none, one or more bits set, and the currently defined
bits are:
.RS
.IP CURL_VERSION_ALTSVC
HTTP Alt-Svc parsing and the associated options (Added in 7.64.1)
.IP CURL_VERSION_ASYNCHDNS
libcurl was built with support for asynchronous name lookups, which allows
more exact timeouts (even on Windows) and less blocking when using the multi
interface. (added in 7.10.7)
.IP CURL_VERSION_BROTLI
supports HTTP Brotli content encoding using libbrotlidec (Added in 7.57.0)
.IP CURL_VERSION_ZSTD
supports HTTP zstd content encoding using zstd library (Added in 7.72.0)
.IP CURL_VERSION_CONV
libcurl was built with support for character conversions, as provided by the
CURLOPT_CONV_* callbacks. (Added in 7.15.4)
.IP CURL_VERSION_CURLDEBUG
libcurl was built with memory tracking debug capabilities. This is mainly of
interest for libcurl hackers. (added in 7.19.6)
.IP CURL_VERSION_DEBUG
libcurl was built with debug capabilities (added in 7.10.6)
.IP CURL_VERSION_GSASL
libcurl was built with libgsasl and thus with some extra SCRAM-SHA
authentication methods. (added in 7.76.0)
.IP CURL_VERSION_GSSAPI
libcurl was built with support for GSS-API. This makes libcurl use provided
functions for Kerberos and SPNEGO authentication. It also allows libcurl
to use the current user credentials without the app having to pass them on.
(Added in 7.38.0)
.IP CURL_VERSION_GSSNEGOTIATE
supports HTTP GSS-Negotiate (added in 7.10.6)
.IP CURL_VERSION_HSTS
libcurl was built with support for HSTS (HTTP Strict Transport Security)
(Added in 7.74.0)
.IP CURL_VERSION_HTTPS_PROXY
libcurl was built with support for HTTPS-proxy.
(Added in 7.52.0)
.IP CURL_VERSION_HTTP2
libcurl was built with support for HTTP2.
(Added in 7.33.0)
.IP CURL_VERSION_HTTP3
HTTP/3 and QUIC support are built-in (Added in 7.66.0)
.IP CURL_VERSION_IDN
libcurl was built with support for IDNA, domain names with international
letters. (Added in 7.12.0)
.IP CURL_VERSION_IPV6
supports IPv6
.IP CURL_VERSION_KERBEROS4
supports Kerberos V4 (when using FTP). Legacy bit. Deprecated since 7.33.0.
.IP CURL_VERSION_KERBEROS5
supports Kerberos V5 authentication for FTP, IMAP, LDAP, POP3, SMTP and
SOCKSv5 proxy. (Added in 7.40.0)
.IP CURL_VERSION_LARGEFILE
libcurl was built with support for large files. (Added in 7.11.1)
.IP CURL_VERSION_UNICODE
libcurl was built with Unicode support on Windows. This makes non-ASCII
characters work in filenames and options passed to libcurl. (Added in 7.72.0)
.IP CURL_VERSION_LIBZ
supports HTTP deflate using libz (Added in 7.10)
.IP CURL_VERSION_MULTI_SSL
libcurl was built with multiple SSL backends. For details, see
\fIcurl_global_sslset(3)\fP.
(Added in 7.56.0)
.IP CURL_VERSION_NTLM
supports HTTP NTLM (added in 7.10.6)
.IP CURL_VERSION_NTLM_WB
libcurl was built with support for NTLM delegation to a winbind helper.
(Added in 7.22.0)
.IP CURL_VERSION_PSL
libcurl was built with support for Mozilla's Public Suffix List. This makes
libcurl ignore cookies with a domain that is on the list.
(Added in 7.47.0)
.IP CURL_VERSION_SPNEGO
libcurl was built with support for SPNEGO authentication (Simple and Protected
GSS-API Negotiation Mechanism, defined in RFC 2478.) (added in 7.10.8)
.IP CURL_VERSION_SSL
supports SSL (HTTPS/FTPS) (Added in 7.10)
.IP CURL_VERSION_SSPI
libcurl was built with support for SSPI. This is only available on Windows and
makes libcurl use Windows-provided functions for Kerberos, NTLM, SPNEGO and
Digest authentication. It also allows libcurl to use the current user
credentials without the app having to pass them on. (Added in 7.13.2)
.IP CURL_VERSION_THREADSAFE
libcurl was built with thread-safety support (Atomic or SRWLOCK) to protect
curl initialization. (Added in 7.84.0) See \fIlibcurl-thread(3)\fP
.IP CURL_VERSION_TLSAUTH_SRP
libcurl was built with support for TLS-SRP (in one or more of the built-in TLS
backends). (Added in 7.21.4)
.IP CURL_VERSION_UNIX_SOCKETS
libcurl was built with support for Unix domain sockets.
(Added in 7.40.0)
.RE
\fIssl_version\fP is an ASCII string for the TLS library name + version
used. If libcurl has no SSL support, this is NULL. For example "Schannel",
\&"Secure Transport" or "OpenSSL/1.1.0g".
\fIssl_version_num\fP is always 0.
\fIlibz_version\fP is an ASCII string (there is no numerical version). If
libcurl has no libz support, this is NULL.
\fIprotocols\fP is a pointer to an array of char * pointers, containing the
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 7.10
.SH RETURN VALUE
A pointer to a curl_version_info_data struct.
.SH "SEE ALSO"
\fIcurl_version(3)\fP
share/man/man3/curl_easy_reset.3 0000644 00000004025 14751150700 0012534 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_easy_reset 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_easy_reset - reset all options of a libcurl session handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
void curl_easy_reset(CURL *handle);
.fi
.SH DESCRIPTION
Re-initializes all options previously set on a specified CURL handle to the
default values. This puts back the handle to the same state as it was in when
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
Nothing
.SH "SEE ALSO"
.BR curl_easy_init "(3)," curl_easy_cleanup "(3)," curl_easy_setopt "(3),"
.BR curl_easy_duphandle "(3)"
share/man/man3/CURLOPT_TFTP_NO_OPTIONS.3 0000644 00000005027 14751150700 0013143 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_TFTP_NO_OPTIONS 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_TFTP_NO_OPTIONS \- send no TFTP options requests
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TFTP_NO_OPTIONS, long onoff);
.fi
.SH DESCRIPTION
Set \fIonoff\fP to 1L to exclude all TFTP options defined in RFC2347, RFC2348
and RFC2349 from read and write requests.
This option improves interoperability with legacy servers that do not
acknowledge or properly implement TFTP options. When this option is used
\fICURLOPT_TFTP_BLKSIZE(3)\fP is ignored.
.SH DEFAULT
0
.SH PROTOCOLS
TFTP
.SH EXAMPLE
.nf
size_t write_callback(char *ptr, size_t size, size_t nmemb, void *fp)
{
return fwrite(ptr, size, nmemb, (FILE *)fp);
}
CURL *curl = curl_easy_init();
if(curl) {
FILE *fp = fopen("foo.bin", "wb");
if(fp) {
curl_easy_setopt(curl, CURLOPT_WRITEDATA, (void *)fp);
curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, write_callback);
curl_easy_setopt(curl, CURLOPT_URL, "tftp://example.com/foo.bin");
/* do not send TFTP options requests */
curl_easy_setopt(curl, CURLOPT_TFTP_NO_OPTIONS, 1L);
/* Perform the request */
curl_easy_perform(curl);
fclose(fp);
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.48.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH SEE ALSO
.BR CURLOPT_TFTP_BLKSIZE "(3), "
share/man/man3/CURLOPT_RESUME_FROM_LARGE.3 0000644 00000005477 14751150700 0013325 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_RESUME_FROM_LARGE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_RESUME_FROM_LARGE \- offset to resume transfer from
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RESUME_FROM_LARGE,
curl_off_t from);
.SH DESCRIPTION
Pass a curl_off_t as parameter. It contains the offset in number of bytes that
you want the transfer to start from. Set this option to 0 to make the transfer
start from the beginning (effectively disabling resume). For FTP, set this
option to -1 to make the transfer start from the end of the target file
(useful to continue an interrupted upload).
When doing uploads with FTP, the resume position is where in the local/source
file libcurl should try to resume the upload from and it will then append the
source file to the remote target file.
.SH DEFAULT
0, not used
.SH PROTOCOLS
HTTP, FTP, SFTP, FILE
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_off_t resume_position = GET_IT_SOMEHOW;
curl_off_t file_size = GET_IT_SOMEHOW_AS_WELL;
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com");
/* resuming upload at this position, possibly beyond 2GB */
curl_easy_setopt(curl, CURLOPT_RESUME_FROM_LARGE, resume_position);
/* ask for upload */
curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L);
/* set total data amount to expect */
curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, file_size);
/* Perform the request */
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.11.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_RESUME_FROM "(3), " CURLOPT_RANGE "(3), "
.BR CURLOPT_INFILESIZE_LARGE "(3), "
share/man/man3/CURLOPT_IPRESOLVE.3 0000644 00000004517 14751150700 0012132 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_IPRESOLVE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_IPRESOLVE \- IP protocol version to use
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_IPRESOLVE, long resolve);
.fi
.SH DESCRIPTION
Allows an application to select what kind of IP addresses to use when
establishing a connection or choosing one from the connection pool. This is
interesting when using host names that resolve addresses using more than
one version of IP. The allowed values are:
.IP CURL_IPRESOLVE_WHATEVER
Default, can use addresses of all IP versions that your system allows.
.IP CURL_IPRESOLVE_V4
Uses only IPv4 addresses.
.IP CURL_IPRESOLVE_V6
Uses only IPv6 addresses.
.SH DEFAULT
CURL_IPRESOLVE_WHATEVER
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
/* of all addresses example.com resolves to, only IPv6 ones are used */
curl_easy_setopt(curl, CURLOPT_IPRESOLVE, CURL_IPRESOLVE_V6);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_HTTP_VERSION "(3), " CURLOPT_SSLVERSION "(3), "
share/man/man3/CURLOPT_MIME_OPTIONS.3 0000644 00000006346 14751150700 0012526 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_MIME_OPTIONS 3 "September 02, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_MIME_OPTIONS \- set MIME option flags
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MIME_OPTIONS, long options);
.fi
.SH DESCRIPTION
Pass a long that holds a bitmask of CURLMIMEOPT_* defines. Each bit is a
Boolean flag used while encoding a MIME tree or multipart form data.
Available bits are:
.IP CURLMIMEOPT_FORMESCAPE
Tells libcurl to escape multipart form field and file names using the
backslash-escaping algorithm rather than percent-encoding (HTTP only).
Backslash-escaping consists in preceding backslashes and double quotes with
a backslash. Percent encoding maps all occurrences of double quote,
carriage return and line feed to %22, %0D and %0A respectively.
Before version 7.81.0, percent-encoding was never applied.
HTTP browsers used to do backslash-escaping in the past but have over time
transitioned to use percent-encoding. This option allows one to address
server-side applications that have not yet have been converted.
As an example, consider field or file name \fIstrange\\name"kind\fP.
When the containing multipart form is sent, this is normally transmitted as
\fIstrange\\name%22kind\fP. When this option is set, it is sent as
\fIstrange\\\\name\\"kind\fP.
.SH DEFAULT
0, meaning disabled.
.SH PROTOCOLS
HTTP, IMAP, SMTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
curl_mime *form = NULL;
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_MIME_OPTIONS, CURLMIMEOPT_FORMESCAPE);
form = curl_mime_init(curl);
if(form) {
curl_mimepart *part = curl_mime_addpart(form);
if(part) {
curl_mime_filedata(part, "strange\\\\file\\\\name");
curl_mime_name(part, "strange\\"field\\"name");
curl_easy_setopt(curl, CURLOPT_MIMEPOST, form);
/* Perform the request */
curl_easy_perform(curl);
}
}
curl_easy_cleanup(curl);
curl_mime_free(mime);
}
.fi
.SH AVAILABILITY
Option added in 7.81.0.
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_MIMEPOST "(3), " CURLOPT_HTTPPOST "(3)"
share/man/man3/CURLOPT_TIMEVALUE.3 0000644 00000004366 14751150700 0012117 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_TIMEVALUE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_TIMEVALUE \- time value for conditional
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMEVALUE, long val);
.fi
.SH DESCRIPTION
Pass a long \fIval\fP as parameter. This should be the time counted as seconds
since 1 Jan 1970, and the time will be used in a condition as specified with
\fICURLOPT_TIMECONDITION(3)\fP.
On systems with 32 bit 'long' variables, this option cannot set dates beyond
the year 2038. Consider \fICURLOPT_TIMEVALUE_LARGE(3)\fP instead.
.SH DEFAULT
0
.SH PROTOCOLS
HTTP, FTP, RTSP, and FILE
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* January 1, 2020 is 1577833200 */
curl_easy_setopt(curl, CURLOPT_TIMEVALUE, 1577833200L);
/* If-Modified-Since the above time stamp */
curl_easy_setopt(curl, CURLOPT_TIMECONDITION, CURL_TIMECOND_IFMODSINCE);
/* Perform the request */
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_TIMECONDITION "(3), "
share/man/man3/CURLOPT_NOBODY.3 0000644 00000005337 14751150700 0011555 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_NOBODY 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_NOBODY \- do the download request without getting the body
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NOBODY, long opt);
.fi
.SH DESCRIPTION
A long parameter set to 1 tells libcurl to not include the body-part in the
output when doing what would otherwise be a download. For HTTP(S), this makes
libcurl do a HEAD request. For most other protocols it means just not asking
to transfer the body data.
For HTTP operations when \fICURLOPT_NOBODY(3)\fP has been set, disabling this
option (with 0) will make it a GET again - only if the method is still set to
be HEAD. The proper way to get back to a GET request is to set
\fICURLOPT_HTTPGET(3)\fP and for other methods, use the POST or UPLOAD
options.
Enabling \fICURLOPT_NOBODY(3)\fP means asking for a download without a body.
If you do a transfer with HTTP that involves a method other than HEAD, you
will get a body (unless the resource and server sends a zero byte body for the
specific URL you request).
.SH DEFAULT
0, the body is transferred
.SH PROTOCOLS
Most
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* get us the resource without a body - use HEAD! */
curl_easy_setopt(curl, CURLOPT_NOBODY, 1L);
/* Perform the request */
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_HTTPGET "(3), " CURLOPT_POSTFIELDS "(3), " CURLOPT_UPLOAD "(3), "
.BR CURLOPT_REQUEST_TARGET "(3), " CURLOPT_MIMEPOST "(3), "
share/man/man3/CURLOPT_PASSWORD.3 0000644 00000004377 14751150700 0012030 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PASSWORD 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PASSWORD \- password to use in authentication
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PASSWORD, char *pwd);
.fi
.SH DESCRIPTION
Pass a char * as parameter, which should be pointing to the null-terminated
password to use for the transfer.
The \fICURLOPT_PASSWORD(3)\fP option should be used in conjunction with the
\fICURLOPT_USERNAME(3)\fP option.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
blank
.SH PROTOCOLS
Most
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
curl_easy_setopt(curl, CURLOPT_PASSWORD, "qwerty");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.19.1
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_USERPWD "(3), " CURLOPT_USERNAME "(3), "
.BR CURLOPT_HTTPAUTH "(3), " CURLOPT_PROXYAUTH "(3)"
share/man/man3/CURLOPT_FAILONERROR.3 0000644 00000005247 14751150700 0012345 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_FAILONERROR 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_FAILONERROR \- request failure on HTTP response >= 400
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FAILONERROR, long fail);
.fi
.SH DESCRIPTION
A long parameter set to 1 tells the library to fail the request if the HTTP
code returned is equal to or larger than 400. The default action would be to
return the page normally, ignoring that code.
This method is not fail-safe and there are occasions where non-successful
response codes will slip through, especially when authentication is involved
(response codes 401 and 407).
You might get some amounts of headers transferred before this situation is
detected, like when a "100-continue" is received as a response to a POST/PUT
and a 401 or 407 is received immediately afterwards.
When this option is used and an error is detected, it will cause the
connection to get closed and \fICURLE_HTTP_RETURNED_ERROR\fP is returned.
.SH DEFAULT
0, do not fail on error
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode ret;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_FAILONERROR, 1L);
ret = curl_easy_perform(curl);
if(ret == CURLE_HTTP_RETURNED_ERROR) {
/* an HTTP response error problem */
}
}
.fi
.SH AVAILABILITY
Along with HTTP.
.SH RETURN VALUE
Returns CURLE_OK if HTTP is enabled, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_HTTP200ALIASES "(3), " CURLOPT_KEEP_SENDING_ON_ERROR "(3), "
share/man/man3/CURLOPT_HSTS_CTRL.3 0000644 00000005137 14751150700 0012166 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 2022, 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_HSTS_CTRL 3 "October 22, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_HSTS_CTRL \- control HSTS behavior
.SH SYNOPSIS
.nf
#include <curl/curl.h>
#define CURLHSTS_ENABLE (1<<0)
#define CURLHSTS_READONLYFILE (1<<1)
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTS_CTRL, long bitmask);
.fi
.SH DESCRIPTION
HSTS (HTTP Strict Transport Security) means that an HTTPS server can instruct
the client to not contact it again over clear-text HTTP for a certain period
into the future. libcurl will then automatically redirect HTTP attempts to
such hosts to instead use HTTPS. This is done by libcurl retaining this
knowledge in an in-memory cache.
Populate the long \fIbitmask\fP with the correct set of features to instruct
libcurl how to handle HSTS for the transfers using this handle.
.SH BITS
.IP "CURLHSTS_ENABLE"
Enable the in-memory HSTS cache for this handle.
.IP "CURLHSTS_READONLYFILE"
Make the HSTS file (if specified) read-only - makes libcurl not save the cache
to the file when closing the handle.
.SH DEFAULT
0. HSTS is disabled by default.
.SH PROTOCOLS
HTTPS and HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_HSTS_CTRL, (long)CURLHSTS_ENABLE);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.74.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_HSTS "(3), " CURLOPT_CONNECT_TO "(3), " CURLOPT_RESOLVE "(3), "
.BR CURLOPT_ALTSVC "(3), "
share/man/man3/CURLINFO_CONDITION_UNMET.3 0000644 00000005473 14751150700 0013153 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_CONDITION_UNMET 3 "October 22, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_CONDITION_UNMET \- get info on unmet time conditional or 304 HTTP response.
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONDITION_UNMET,
long *unmet);
.fi
.SH DESCRIPTION
Pass a pointer to a long to receive the number 1 if the condition provided in
the previous request did not match (see \fICURLOPT_TIMECONDITION(3)\fP). Alas,
if this returns a 1 you know that the reason you did not get data in return is
because it did not fulfill the condition. The long this argument points to will
get a zero stored if the condition instead was met. This can also return 1 if
the server responded with a 304 HTTP status code, for example after sending a
custom "If-Match-*" header.
.SH PROTOCOLS
HTTP and some
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* January 1, 2020 is 1577833200 */
curl_easy_setopt(curl, CURLOPT_TIMEVALUE, 1577833200L);
/* If-Modified-Since the above time stamp */
curl_easy_setopt(curl, CURLOPT_TIMECONDITION,
(long)CURL_TIMECOND_IFMODSINCE);
/* Perform the request */
res = curl_easy_perform(curl);
if(!res) {
/* check the time condition */
long unmet;
res = curl_easy_getinfo(curl, CURLINFO_CONDITION_UNMET, &unmet);
if(!res) {
printf("The time condition was %sfulfilled\\n", unmet?"NOT":"");
}
}
}
.fi
.SH AVAILABILITY
Added in 7.19.4
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
share/man/man3/CURLOPT_FTP_USE_PRET.3 0000644 00000004245 14751150700 0012557 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_FTP_USE_PRET 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_FTP_USE_PRET \- use PRET for FTP
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_USE_PRET, long enable);
.fi
.SH DESCRIPTION
Pass a long. If the value is 1, it tells curl to send a PRET command before
PASV (and EPSV). Certain FTP servers, mainly drftpd, require this non-standard
command for directory listings as well as up and downloads in PASV mode. Has
no effect when using the active FTP transfers mode.
.SH DEFAULT
0
.SH PROTOCOLS
FTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/old-server/file.txt");
/* a drftpd server, do it! */
curl_easy_setopt(curl, CURLOPT_FTP_USE_PRET, 1L);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.20.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_FTP_USE_EPRT "(3), " CURLOPT_FTP_USE_EPSV "(3), "
share/man/man3/curl_url_get.3 0000644 00000012366 14751150700 0012041 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_url_get 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_url_get - extract a part from a URL
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLUcode curl_url_get(CURLU *url,
CURLUPart what,
char **part,
unsigned int flags)
.fi
.SH DESCRIPTION
Given the \fIurl\fP handle of an already parsed URL, this function lets the
user extract individual pieces from it.
The \fIwhat\fP argument should be the particular part to extract (see list
below) and \fIpart\fP points to a 'char *' to get updated to point to a newly
allocated string with the contents.
The \fIflags\fP argument is a bitmask with individual features.
The returned part pointer must be freed with \fIcurl_free(3)\fP after use.
.SH FLAGS
The flags argument is zero, one or more bits set in a bitmask.
.IP CURLU_DEFAULT_PORT
If the handle has no port stored, this option will make \fIcurl_url_get(3)\fP
return the default port for the used scheme.
.IP CURLU_DEFAULT_SCHEME
If the handle has no scheme stored, this option will make
\fIcurl_url_get(3)\fP return the default scheme instead of error.
.IP CURLU_NO_DEFAULT_PORT
Instructs \fIcurl_url_get(3)\fP to not return a port number if it matches the
default port for the scheme.
.IP CURLU_URLDECODE
Asks \fIcurl_url_get(3)\fP to URL decode the contents before returning it. It
will not attempt to decode the scheme, the port number or the full URL.
´
The query component will also get plus-to-space conversion as a bonus when
this bit is set.
Note that this URL decoding is charset unaware and you will get a zero
terminated string back with data that could be intended for a particular
encoding.
If there's any byte values lower than 32 in the decoded string, the get
operation will return an error instead.
.IP CURLU_URLENCODE
If set, will make \fIcurl_url_get(3)\fP URL encode the host name part when a
full URL is retrieved. If not set (default), libcurl returns the URL with the
host name "raw" to support IDN names to appear as-is. IDN host names are
typically using non-ASCII bytes that otherwise will be percent-encoded.
Note that even when not asking for URL encoding, the '%' (byte 37) will be URL
encoded to make sure the host name remains valid.
.SH PARTS
.IP CURLUPART_URL
When asked to return the full URL, \fIcurl_url_get(3)\fP will return a
normalized and possibly cleaned up version of what was previously parsed.
.IP CURLUPART_SCHEME
Scheme cannot be URL decoded on get.
.IP CURLUPART_USER
.IP CURLUPART_PASSWORD
.IP CURLUPART_OPTIONS
.IP CURLUPART_HOST
The host name. If it is an IPv6 numeric address, the zone id will not be part
of it but is provided separately in \fICURLUPART_ZONEID\fP. IPv6 numerical
addresses are returned within brackets ([]).
.IP CURLUPART_ZONEID
If the host name is a numeric IPv6 address, this field might also be set.
.IP CURLUPART_PORT
Port cannot be URL decoded on get.
.IP CURLUPART_PATH
\fIpart\fP will be '/' even if no path is supplied in the URL.
.IP CURLUPART_QUERY
The initial question mark that denotes the beginning of the query part is
a delimiter only.
It is not part of the query contents.
A not-present query will lead \fIpart\fP to be set to NULL.
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 EXAMPLE
.nf
CURLUcode rc;
CURLU *url = curl_url();
rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
if(!rc) {
char *scheme;
rc = curl_url_get(url, CURLUPART_SCHEME, &scheme, 0);
if(!rc) {
printf("the scheme is %s\\n", scheme);
curl_free(scheme);
}
curl_url_cleanup(url);
}
.fi
.SH AVAILABILITY
Added in 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)"
share/man/man3/CURLINFO_HTTPAUTH_AVAIL.3 0000644 00000005107 14751150700 0013024 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_HTTPAUTH_AVAIL 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_HTTPAUTH_AVAIL \- get available HTTP authentication methods
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_HTTPAUTH_AVAIL, long *authp);
.fi
.SH DESCRIPTION
Pass a pointer to a long to receive a bitmask indicating the authentication
method(s) available according to the previous response. The meaning of the
bits is explained in the \fICURLOPT_HTTPAUTH(3)\fP option for
\fIcurl_easy_setopt(3)\fP.
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
res = curl_easy_perform(curl);
if(!res) {
/* extract the available authentication types */
long auth;
res = curl_easy_getinfo(curl, CURLINFO_HTTPAUTH_AVAIL, &auth);
if(!res) {
if(!auth)
printf("No auth available, perhaps no 401?\\n");
else {
printf("%s%s%s%s\\n",
auth & CURLAUTH_BASIC ? "Basic ":"",
auth & CURLAUTH_DIGEST ? "Digest ":"",
auth & CURLAUTH_NEGOTIATE ? "Negotiate ":"",
auth % CURLAUTH_NTLM ? "NTLM ":"");
}
}
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added RFC2617 in 7.10.8
Added RFC7616 in 7.57.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
share/man/man3/curl_easy_unescape.3 0000644 00000005672 14751150700 0013226 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH curl_easy_unescape 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_easy_unescape - URL decodes the given string
.SH SYNOPSIS
.nf
#include <curl/curl.h>
char *curl_easy_unescape(CURL *curl, const char *url,
int inlength, int *outlength);
.fi
.SH DESCRIPTION
This function converts the given URL encoded input string to a "plain string"
and returns that in an allocated memory area. All input characters that are
URL encoded (%XX where XX is a two-digit hexadecimal number) are converted to
their binary versions.
If the \fBlength\fP argument is set to 0 (zero), \fIcurl_easy_unescape(3)\fP
will use strlen() on the input \fIurl\fP string to find out the size.
If \fBoutlength\fP is non-NULL, the function will write the length of the
returned string in the integer it points to. This allows proper handling even
for strings containing %00. Since this is a pointer to an \fIint\fP type, it
can only return a value up to \fIINT_MAX\fP so no longer string can be
returned in this parameter.
Since 7.82.0, the \fBcurl\fP parameter is ignored. Prior to that there was
per-handle character conversion support for some very old operating systems
such as TPF, but it was otherwise ignored.
You must \fIcurl_free(3)\fP the returned string when you are 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) {
/* do not assume printf() works on the decoded data! */
printf("Decoded: ");
/* ... */
curl_free(decoded);
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.15.4 and replaces the old \fIcurl_unescape(3)\fP function.
.SH RETURN VALUE
A pointer to a null-terminated string or NULL if it failed.
.SH "SEE ALSO"
.BR curl_easy_escape "(3), " curl_free "(3)," RFC 3986
share/man/man3/CURLOPT_IOCTLDATA.3 0000644 00000004421 14751150700 0012060 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_IOCTLDATA 3 "October 12, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_IOCTLDATA \- pointer passed to I/O callback
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_IOCTLDATA, void *pointer);
.fi
.SH DESCRIPTION
Pass the \fIpointer\fP that will be untouched by libcurl and passed as the 3rd
argument in the ioctl callback set with \fICURLOPT_IOCTLFUNCTION(3)\fP.
.SH DEFAULT
By default, the value of this parameter is NULL.
.SH PROTOCOLS
Used with HTTP
.SH EXAMPLE
.nf
static curlioerr ioctl_callback(CURL *handle, int cmd, void *clientp)
{
struct data *io = (struct data *)clientp;
if(cmd == CURLIOCMD_RESTARTREAD) {
lseek(fd, 0, SEEK_SET);
current_offset = 0;
return CURLIOE_OK;
}
return CURLIOE_UNKNOWNCMD;
}
{
struct data ioctl_data;
curl_easy_setopt(curl, CURLOPT_IOCTLFUNCTION, ioctl_callback);
curl_easy_setopt(curl, CURLOPT_IOCTLDATA, &ioctl_data);
}
.fi
.SH AVAILABILITY
Added in 7.12.3. Deprecated since 7.18.0.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_IOCTLFUNCTION "(3), " CURLOPT_SEEKFUNCTION "(3), "
share/man/man3/CURLOPT_OPENSOCKETFUNCTION.3 0000644 00000011400 14751150700 0013367 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_OPENSOCKETFUNCTION 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_OPENSOCKETFUNCTION \- callback for opening socket
.SH SYNOPSIS
.nf
#include <curl/curl.h>
typedef enum {
CURLSOCKTYPE_IPCXN, /* socket created for a specific IP connection */
} curlsocktype;
struct curl_sockaddr {
int family;
int socktype;
int protocol;
unsigned int addrlen;
struct sockaddr addr;
};
curl_socket_t opensocket_callback(void *clientp,
curlsocktype purpose,
struct curl_sockaddr *address);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_OPENSOCKETFUNCTION, opensocket_callback);
.SH DESCRIPTION
Pass a pointer to your callback function, which should match the prototype
shown above.
This callback function gets called by libcurl instead of the \fIsocket(2)\fP
call. The callback's \fIpurpose\fP argument identifies the exact purpose for
this particular socket. \fICURLSOCKTYPE_IPCXN\fP is for IP based connections
and is the only purpose currently used in libcurl. Future versions of libcurl
may support more purposes.
The \fIclientp\fP pointer contains whatever user-defined value set using the
\fICURLOPT_OPENSOCKETDATA(3)\fP function.
The callback gets the resolved peer address as the \fIaddress\fP argument and
is allowed to modify the address or refuse to connect completely. The callback
function should return the newly created socket or \fICURL_SOCKET_BAD\fP in
case no connection could be established or another error was detected. Any
additional \fIsetsockopt(2)\fP calls can of course be done on the socket at
the user's discretion. A \fICURL_SOCKET_BAD\fP return value from the callback
function will signal an unrecoverable error to libcurl and it will return
\fICURLE_COULDNT_CONNECT\fP from the function that triggered this callback.
This return code can be used for IP address block listing.
If you want to pass in a socket with an already established connection, pass
the socket back with this callback and then use
\fICURLOPT_SOCKOPTFUNCTION(3)\fP to signal that it already is connected.
.SH DEFAULT
The default behavior is the equivalent of this:
.nf
return socket(addr->family, addr->socktype, addr->protocol);
.fi
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
/* make libcurl use the already established socket 'sockfd' */
static curl_socket_t opensocket(void *clientp,
curlsocktype purpose,
struct curl_sockaddr *address)
{
curl_socket_t sockfd;
sockfd = *(curl_socket_t *)clientp;
/* the actual externally set socket is passed in via the OPENSOCKETDATA
option */
return sockfd;
}
static int sockopt_callback(void *clientp, curl_socket_t curlfd,
curlsocktype purpose)
{
/* This return code was added in libcurl 7.21.5 */
return CURL_SOCKOPT_ALREADY_CONNECTED;
}
curl = curl_easy_init();
if(curl) {
/* libcurl will internally think that you connect to the host
* and port that you specify in the URL option. */
curl_easy_setopt(curl, CURLOPT_URL, "http://99.99.99.99:9999");
/* call this function to get a socket */
curl_easy_setopt(curl, CURLOPT_OPENSOCKETFUNCTION, opensocket);
curl_easy_setopt(curl, CURLOPT_OPENSOCKETDATA, &sockfd);
/* call this function to set options for the socket */
curl_easy_setopt(curl, CURLOPT_SOCKOPTFUNCTION, sockopt_callback);
res = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.17.1.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_OPENSOCKETDATA "(3), " CURLOPT_SOCKOPTFUNCTION "(3), "
.BR CURLOPT_CLOSESOCKETFUNCTION "(3), "
share/man/man3/CURLOPT_NEW_FILE_PERMS.3 0000644 00000004304 14751150700 0012752 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_NEW_FILE_PERMS 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_NEW_FILE_PERMS \- permissions for remotely created files
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NEW_FILE_PERMS,
long mode);
.SH DESCRIPTION
Pass a long as a parameter, containing the value of the permissions that will
be assigned to newly created files on the remote server. The default value is
\fI0644\fP, but any valid value can be used. The only protocols that can use
this are \fIsftp://\fP, \fIscp://\fP, and \fIfile://\fP.
.SH DEFAULT
0644
.SH PROTOCOLS
SFTP, SCP and FILE
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode ret;
curl_easy_setopt(curl, CURLOPT_URL, "sftp://upload.example.com/file.txt");
curl_easy_setopt(curl, CURLOPT_NEW_FILE_PERMS, 0664L);
ret = curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.16.4
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_NEW_DIRECTORY_PERMS "(3), " CURLOPT_UPLOAD "(3), "
share/man/man3/CURLOPT_REFERER.3 0000644 00000004467 14751150700 0011660 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_REFERER 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_REFERER \- the HTTP referer header
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_REFERER, char *where);
.fi
.SH DESCRIPTION
Pass a pointer to a null-terminated string as parameter. It will be used to
set the Referer: header in the http request sent to the remote server. This
can be used to fool servers or scripts. You can also set any custom header
with \fICURLOPT_HTTPHEADER(3)\fP.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* tell it where we found the link to this place */
curl_easy_setopt(curl, CURLOPT_REFERER, "https://example.com/aboutme.html");
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
If built with HTTP support
.SH RETURN VALUE
Returns CURLE_OK if HTTP support is enabled, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_USERAGENT "(3), " CURLOPT_HTTPHEADER "(3), "
.BR CURLINFO_REFERER "(3), "
share/man/man3/CURLOPT_CONNECT_ONLY.3 0000644 00000006137 14751150700 0012514 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_CONNECT_ONLY 3 "September 12, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_CONNECT_ONLY \- stop when connected to target server
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECT_ONLY, long only);
.fi
.SH DESCRIPTION
Pass a long. If the parameter equals 1, it tells the library to perform all
the required proxy authentication and connection setup, but no data transfer,
and then return.
The option can be used to simply test a connection to a server, but is more
useful when used with the \fICURLINFO_ACTIVESOCKET(3)\fP option to
\fIcurl_easy_getinfo(3)\fP as the library can set up the connection and then
the application can obtain the most recently used socket for special data
transfers.
Since 7.86.0, this option can be set to '2' and if HTTP or WebSocket are
used, libcurl will do the request and read all response headers before handing
over control to the application.
Transfers marked connect only will not reuse any existing connections and
connections marked connect only will not be allowed to get reused.
If the connect only transfer is done using the multi interface, the particular
easy handle must remain added to the multi handle for as long as the
application wants to use it. Once it has been removed with
\fIcurl_multi_remove_handle(3)\fP, \fIcurl_easy_send(3)\fP and
\fIcurl_easy_recv(3)\fP do not function.
.SH DEFAULT
0
.SH PROTOCOLS
HTTP, SMTP, POP3 and IMAP. For WS and WSS starting in 7.86.0.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode ret;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L);
ret = curl_easy_perform(curl);
if(ret == CURLE_OK) {
/* only connected! */
}
}
.fi
.SH AVAILABILITY
Added in 7.15.2
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_VERBOSE "(3), " CURLOPT_HTTPPROXYTUNNEL "(3), "
.BR curl_easy_recv "(3), " curl_easy_send "(3) "
share/man/man3/CURLOPT_HSTSREADFUNCTION.3 0000644 00000006363 14751150700 0013146 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_HSTSREADFUNCTION 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_HSTSREADFUNCTION \- read callback for HSTS hosts
.SH SYNOPSIS
.nf
#include <curl/curl.h>
struct curl_hstsentry {
char *name;
size_t namelen;
unsigned int includeSubDomains:1;
char expire[18]; /* YYYYMMDD HH:MM:SS [null-terminated] */
};
CURLSTScode hstsread(CURL *easy, struct curl_hstsentry *sts, void *userp);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTSREADFUNCTION, hstsread);
.fi
.SH DESCRIPTION
Pass a pointer to your callback function, as the prototype shows above.
This callback function gets called by libcurl repeatedly when it populates the
in-memory HSTS cache.
Set the \fIuserp\fP argument with the \fICURLOPT_HSTSREADDATA(3)\fP option or
it will be NULL.
When this callback is invoked, the \fIsts\fP pointer points to a populated
struct: Copy the host name to \fIname\fP (no longer than \fInamelen\fP
bytes). Make it null-terminated. Set \fIincludeSubDomains\fP to TRUE or
FALSE. Set \fIexpire\fP to a date stamp or a zero length string for *forever*
(wrong date stamp format might cause the name to not get accepted)
The callback should return \fICURLSTS_OK\fP if it returns a name and is
prepared to be called again (for another host) or \fICURLSTS_DONE\fP if it has
no entry to return. It can also return \fICURLSTS_FAIL\fP to signal
error. Returning \fICURLSTS_FAIL\fP will stop the transfer from being
performed and make \fICURLE_ABORTED_BY_CALLBACK\fP get returned.
This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to
do that.
.SH DEFAULT
NULL - no callback.
.SH PROTOCOLS
This feature is only used for HTTP(S) transfer.
.SH EXAMPLE
.nf
{
/* set HSTS read callback */
curl_easy_setopt(curl, CURLOPT_HSTSREADFUNCTION, hstsread);
/* pass in suitable argument to the callback */
curl_easy_setopt(curl, CURLOPT_HSTSREADDATA, &hstspreload[0]);
result = curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.74.0
.SH RETURN VALUE
This will return CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_HSTSREADDATA "(3), " CURLOPT_HSTSWRITEFUNCTION "(3), "
.BR CURLOPT_HSTS "(3), " CURLOPT_HSTS_CTRL "(3), "
share/man/man3/CURLOPT_LOCALPORT.3 0000644 00000004324 14751150700 0012115 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_LOCALPORT 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_LOCALPORT \- local port number to use for socket
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_LOCALPORT, long port);
.fi
.SH DESCRIPTION
Pass a long. This sets the local port number of the socket used for the
connection. This can be used in combination with \fICURLOPT_INTERFACE(3)\fP
and you are recommended to use \fICURLOPT_LOCALPORTRANGE(3)\fP as well when
this option is set. Valid port numbers are 1 - 65535.
.SH DEFAULT
0, disabled - use whatever the system thinks is fine
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
curl_easy_setopt(curl, CURLOPT_LOCALPORT, 49152L);
/* and try 20 more ports following that */
curl_easy_setopt(curl, CURLOPT_LOCALPORTRANGE, 20L);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.15.2
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_LOCALPORTRANGE "(3), " CURLOPT_INTERFACE "(3), "
share/man/man3/CURLOPT_TRAILERDATA.3 0000644 00000003610 14751150700 0012307 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_TRAILERDATA 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_TRAILERDATA \- pointer passed to trailing headers callback
.SH SYNOPSIS
.nf
#include <curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TRAILERDATA, void *userdata);
.fi
.SH DESCRIPTION
Data pointer to be passed to the HTTP trailer callback function.
.SH DEFAULT
NULL
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
/* Assuming we have a CURL handle in the hndl variable. */
struct MyData data;
curl_easy_setopt(hndl, CURLOPT_TRAILERDATA, &data);
.fi
A more complete example can be found in examples/http_trailers.html
.SH AVAILABILITY
This option was added in curl 7.64.0 and is present if HTTP support is enabled
.SH RETURN VALUE
Returns CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_TRAILERFUNCTION "(3), "
share/man/man3/CURLOPT_STREAM_DEPENDS_E.3 0000644 00000005621 14751150700 0013160 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_STREAM_DEPENDS_E 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_STREAM_DEPENDS_E \- stream this transfer depends on exclusively
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_STREAM_DEPENDS_E,
CURL *dephandle);
.fi
.SH DESCRIPTION
Pass a CURL * pointer in \fIdephandle\fP to identify the stream within the
same connection that this stream is depending upon exclusively. That means it
depends on it and sets the Exclusive bit.
The spec says "Including a dependency expresses a preference to allocate
resources to the identified stream rather than to the dependent stream."
Setting a dependency with the exclusive flag for a reprioritized stream causes
all the dependencies of the new parent stream to become dependent on the
reprioritized stream.
This option can be set during transfer.
\fIdephandle\fP must not be the same as \fIhandle\fP, that will cause this
function to return an error. It must be another easy handle, and it also needs
to be a handle of a transfer that will be sent over the same HTTP/2 connection
for this option to have an actual effect.
.SH DEFAULT
NULL
.SH PROTOCOLS
HTTP/2
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
CURL *curl2 = curl_easy_init(); /* a second handle */
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/one");
/* the second depends on the first */
curl_easy_setopt(curl2, CURLOPT_URL, "https://example.com/two");
curl_easy_setopt(curl2, CURLOPT_STREAM_DEPENDS_E, curl);
/* then add both to a multi handle and transfer them! */
}
.fi
.SH AVAILABILITY
Added in 7.46.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_STREAM_WEIGHT "(3), " CURLOPT_STREAM_DEPENDS "(3), "
share/man/man3/CURLINFO_FILETIME_T.3 0000644 00000005613 14751150700 0012332 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_FILETIME 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_FILETIME_T \- get the remote time of the retrieved document
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_FILETIME_T,
curl_off_t *timep);
.fi
.SH DESCRIPTION
Pass a pointer to a curl_off_t to receive the remote time of the retrieved
document in number of seconds since January 1 1970 in the GMT/UTC time
zone. If you get -1, it can be because of many reasons (it might be unknown,
the server might hide it or the server does not support the command that tells
document time etc) and the time of the document is unknown.
You must ask libcurl to collect this information before the transfer is made,
by using the \fICURLOPT_FILETIME(3)\fP option to \fIcurl_easy_setopt(3)\fP or
you will unconditionally get a -1 back.
This option is an alternative to \fICURLINFO_FILETIME(3)\fP to allow systems
with 32 bit long variables to extract dates outside of the 32bit timestamp
range.
.SH PROTOCOLS
HTTP(S), FTP(S), SFTP
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, url);
/* Ask for filetime */
curl_easy_setopt(curl, CURLOPT_FILETIME, 1L);
res = curl_easy_perform(curl);
if(CURLE_OK == res) {
curl_off_t filetime;
res = curl_easy_getinfo(curl, CURLINFO_FILETIME_T, &filetime);
if((CURLE_OK == res) && (filetime >= 0)) {
time_t file_time = (time_t)filetime;
printf("filetime %s: %s", filename, ctime(&file_time));
}
}
/* always cleanup */
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.59.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
share/man/man3/CURLMOPT_PIPELINING_SERVER_BL.3 0000644 00000004743 14751150700 0014001 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLMOPT_PIPELINING_SERVER_BL 3 "May 17, 2022" "libcurl 7.86.0" "curl_multi_setopt options"
.SH NAME
CURLMOPT_PIPELINING_SERVER_BL \- pipelining server block list
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PIPELINING_SERVER_BL,
char **servers);
.fi
.SH DESCRIPTION
No function since pipelining was removed in 7.62.0.
Pass a \fBservers\fP array of char *, ending with a NULL entry. This is a list
of server types prefixes (in the Server: HTTP header) that are blocked from
pipelining, i.e server types that are known to not support HTTP
pipelining. The array is copied by libcurl.
Note that the comparison matches if the Server: header begins with the string
in the block list, i.e "Server: Ninja 1.2.3" and "Server: Ninja 1.4.0" can
both be blocked by having "Ninja" in the list.
Pass a NULL pointer to clear the block list.
.SH DEFAULT
The default value is NULL, which means that there is no block list.
.SH PROTOCOLS
.SH EXAMPLE
.nf
char *server_block_list[] =
{
"Microsoft-IIS/6.0",
"nginx/0.8.54",
NULL
};
curl_multi_setopt(m, CURLMOPT_PIPELINING_SERVER_BL, server_block_list);
.fi
.SH AVAILABILITY
Added in 7.30.0
.SH RETURN VALUE
Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLMOPT_PIPELINING "(3), " CURLMOPT_PIPELINING_SITE_BL "(3), "
share/man/man3/CURLOPT_URL.3 0000644 00000012775 14751150700 0011231 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_URL 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_URL \- URL for this transfer
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_URL, char *URL);
.fi
.SH DESCRIPTION
Pass in a pointer to the \fIURL\fP to work with. The parameter should be a
char * to a null-terminated string which must be URL-encoded in the following
format:
scheme://host:port/path
For a greater explanation of the format please see RFC3986.
libcurl does not validate the syntax or use this variable until the transfer is
issued. Even if you set a crazy value here, \fIcurl_easy_setopt(3)\fP will
still return \fICURLE_OK\fP.
If the given URL is missing a scheme name (such as "http://" or "ftp://" etc)
then libcurl will make a guess based on the host. If the outermost sub-domain
name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that protocol will be
used, otherwise HTTP will be used. Since 7.45.0 guessing can be disabled by
setting a default protocol, see \fICURLOPT_DEFAULT_PROTOCOL(3)\fP for details.
Should the protocol, either that specified by the scheme or deduced by libcurl
from the host name, not be supported by libcurl then
\fICURLE_UNSUPPORTED_PROTOCOL\fP will be returned from either the
\fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP functions when you
call them. Use \fIcurl_version_info(3)\fP for detailed information of which
protocols are supported by the build of libcurl you are using.
\fICURLOPT_PROTOCOLS(3)\fP can be used to limit what protocols libcurl will
use for this transfer, independent of what libcurl has been compiled to
support. That may be useful if you accept the URL from an external source and
want to limit the accessibility.
The \fICURLOPT_URL(3)\fP string will be ignored if \fICURLOPT_CURLU(3)\fP is
set.
\fICURLOPT_URL(3)\fP or \fICURLOPT_CURLU(3)\fP \fBmust\fP be set before a
transfer is started.
The application does not have to keep the string around after setting this
option.
.SH ENCODING
The string pointed to in the \fICURLOPT_URL(3)\fP argument is generally
expected to be a sequence of characters using an ASCII compatible encoding.
If libcurl is built with IDN support, the server name part of the URL can use
an "international name" by using the current encoding (according to locale) or
UTF-8 (when winidn is used; or a Windows Unicode build using libidn2).
If libcurl is built without IDN support, the server name is used exactly as
specified when passed to the name resolver functions.
.SH DEFAULT
There is no default URL. If this option is not set, no transfer can be
performed.
.SH SECURITY CONCERNS
Applications may at times find it convenient to allow users to specify URLs
for various purposes and that string would then end up fed to this option.
Getting a URL from an external untrusted party will bring reasons for several
security concerns:
If you have an application that runs as or in a server application, getting an
unfiltered URL can easily trick your application to access a local resource
instead of a remote. Protecting yourself against localhost accesses is hard
when accepting user provided URLs.
Such custom URLs can also access other ports than you planned as port numbers
are part of the regular URL format. The combination of a local host and a
custom port number can allow external users to play tricks with your local
services.
Accepting external URLs may also use other protocols than http:// or other
common ones. Restrict what accept with \fICURLOPT_PROTOCOLS(3)\fP.
User provided URLs can also be made to point to sites that redirect further on
(possibly to other protocols too). Consider your
\fICURLOPT_FOLLOWLOCATION(3)\fP and \fICURLOPT_REDIR_PROTOCOLS(3)\fP settings.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
POP3 and SMTP were added in 7.31.0
.SH RETURN VALUE
Returns CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insufficient
heap space.
Note that \fIcurl_easy_setopt(3)\fP will not actually parse the given string so
given a bad URL, it will not be detected until \fIcurl_easy_perform(3)\fP or
similar is called.
.SH "SEE ALSO"
.BR CURLOPT_VERBOSE "(3), " CURLOPT_PROTOCOLS "(3), "
.BR CURLOPT_FORBID_REUSE "(3), " CURLOPT_FRESH_CONNECT "(3), "
.BR curl_easy_perform "(3), "
.BR CURLINFO_REDIRECT_URL "(3), " CURLOPT_PATH_AS_IS "(3), " CURLOPT_CURLU "(3), "
share/man/man3/CURLOPT_WRITEFUNCTION.3 0000644 00000010650 14751150700 0012615 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_WRITEFUNCTION 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_WRITEFUNCTION \- callback for writing received data
.SH SYNOPSIS
.nf
#include <curl/curl.h>
size_t write_callback(char *ptr, size_t size, size_t nmemb, void *userdata);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WRITEFUNCTION, write_callback);
.SH DESCRIPTION
Pass a pointer to your callback function, which should match the prototype
shown above.
This callback function gets called by libcurl as soon as there is data
received that needs to be saved. For most transfers, this callback gets called
many times and each invoke delivers another chunk of data. \fIptr\fP points to
the delivered data, and the size of that data is \fInmemb\fP; \fIsize\fP is
always 1.
The callback function will be passed as much data as possible in all invokes,
but you must not make any assumptions. It may be one byte, it may be
thousands. The maximum amount of body data that will be passed to the write
callback is defined in the curl.h header file: \fICURL_MAX_WRITE_SIZE\fP (the
usual default is 16K). If \fICURLOPT_HEADER(3)\fP is enabled, which makes
header data get passed to the write callback, you can get up to
\fICURL_MAX_HTTP_HEADER\fP bytes of header data passed into it. This usually
means 100K.
This function may be called with zero bytes data if the transferred file is
empty.
The data passed to this function will not be null-terminated!
Set the \fIuserdata\fP argument with the \fICURLOPT_WRITEDATA(3)\fP option.
Your callback should return the number of bytes actually taken care of. If
that amount differs from the amount passed to your callback function, it will
signal an error condition to the library. This will cause the transfer to get
aborted and the libcurl function used will return \fICURLE_WRITE_ERROR\fP.
If your callback function returns CURL_WRITEFUNC_PAUSE it will cause this
transfer to become paused. See \fIcurl_easy_pause(3)\fP for further details.
Set this option to NULL to get the internal default function used instead of
your callback. The internal default function will write the data to the FILE *
given with \fICURLOPT_WRITEDATA(3)\fP.
This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to
do that.
.SH DEFAULT
libcurl will use 'fwrite' as a callback by default.
.SH PROTOCOLS
For all protocols
.SH EXAMPLE
.nf
struct memory {
char *response;
size_t size;
};
static size_t cb(void *data, size_t size, size_t nmemb, void *userp)
{
size_t realsize = size * nmemb;
struct memory *mem = (struct memory *)userp;
char *ptr = realloc(mem->response, mem->size + realsize + 1);
if(ptr == NULL)
return 0; /* out of memory! */
mem->response = ptr;
memcpy(&(mem->response[mem->size]), data, realsize);
mem->size += realsize;
mem->response[mem->size] = 0;
return realsize;
}
struct memory chunk = {0};
/* send all data to this function */
curl_easy_setopt(curl_handle, CURLOPT_WRITEFUNCTION, cb);
/* we pass our 'chunk' struct to the callback function */
curl_easy_setopt(curl_handle, CURLOPT_WRITEDATA, (void *)&chunk);
.fi
.SH AVAILABILITY
Support for the CURL_WRITEFUNC_PAUSE return code was added in version 7.18.0.
.SH RETURN VALUE
This will return CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_WRITEDATA "(3), " CURLOPT_READFUNCTION "(3), "
.BR CURLOPT_HEADERFUNCTION "(3), "
share/man/man3/CURLMOPT_SOCKETDATA.3 0000644 00000004606 14751150700 0012320 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLMOPT_SOCKETDATA 3 "May 17, 2022" "libcurl 7.86.0" "curl_multi_setopt options"
.SH NAME
CURLMOPT_SOCKETDATA \- custom pointer passed to the socket callback
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_SOCKETDATA, void *pointer);
.SH DESCRIPTION
A data \fIpointer\fP to pass to the socket callback set with the
\fICURLMOPT_SOCKETFUNCTION(3)\fP option.
This pointer will not be touched by libcurl but will only be passed in to the
socket callbacks's \fBuserp\fP argument.
.SH DEFAULT
NULL
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
static int sock_cb(CURL *e, curl_socket_t s, int what, void *cbp, void *sockp)
{
GlobalInfo *g = (GlobalInfo*) cbp;
SockInfo *fdp = (SockInfo*) sockp;
if(what == CURL_POLL_REMOVE) {
remsock(fdp);
}
else {
if(!fdp) {
addsock(s, e, what, g);
}
else {
setsock(fdp, s, e, what, g);
}
}
return 0;
}
main()
{
GlobalInfo setup;
/* ... use socket callback and custom pointer */
curl_multi_setopt(multi, CURLMOPT_SOCKETFUNCTION, sock_cb);
curl_multi_setopt(multi, CURLMOPT_SOCKETDATA, &setup);
}
.fi
.SH AVAILABILITY
Added in 7.15.4
.SH RETURN VALUE
Returns CURLM_OK.
.SH "SEE ALSO"
.BR CURLMOPT_SOCKETFUNCTION "(3), " curl_multi_socket_action "(3), "
.BR CURLMOPT_TIMERFUNCTION "(3) "
share/man/man3/CURLOPT_HAPROXYPROTOCOL.3 0000644 00000004331 14751150700 0013070 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_HAPROXYPROTOCOL 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_HAPROXYPROTOCOL \- send HAProxy PROXY protocol v1 header
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HAPROXYPROTOCOL,
long haproxy_protocol);
.fi
.SH DESCRIPTION
A long parameter set to 1 tells the library to send an HAProxy PROXY
protocol v1 header at beginning of the connection. The default action is not to
send this header.
This option is primarily useful when sending test requests to a service that
expects this header.
Most applications do not need this option.
.SH DEFAULT
0, do not send any HAProxy PROXY protocol header
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode ret;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_HAPROXYPROTOCOL, 1L);
ret = curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Along with HTTP. Added in 7.60.0.
.SH RETURN VALUE
Returns CURLE_OK if HTTP is enabled, and CURLE_UNKNOWN_OPTION if not.
.SH SEE ALSO
.BR CURLOPT_PROXY "(3), "
share/man/man3/CURLINFO_SPEED_UPLOAD.3 0000644 00000004355 14751150700 0012557 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_SPEED_UPLOAD 3 "October 12, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_SPEED_UPLOAD \- get upload speed
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SPEED_UPLOAD, double *speed);
.fi
.SH DESCRIPTION
Pass a pointer to a double to receive the average upload speed that curl
measured for the complete upload. Measured in bytes/second.
\fICURLINFO_SPEED_UPLOAD_T(3)\fP is a newer replacement that returns a more
sensible variable type.
.SH PROTOCOLS
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* Perform the request */
res = curl_easy_perform(curl);
if(!res) {
double speed;
res = curl_easy_getinfo(curl, CURLINFO_SPEED_UPLOAD, &speed);
if(!res) {
printf("Upload speed %.0f bytes/sec\\n", speed);
}
}
}
.fi
.SH AVAILABILITY
Added in 7.4.1. Deprecated since 7.55.0.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
.BR CURLINFO_SPEED_DOWNLOAD "(3), "
share/man/man3/CURLOPT_WS_OPTIONS.3 0000644 00000004615 14751150700 0012325 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_WS_OPTIONS 3 "October 22, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_WS_OPTIONS \- WebSocket behavior options
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WS_OPTIONS, long bitmask);
.fi
.SH DESCRIPTION
Pass a long with a bitmask to tell libcurl about specific WebSocket
behaviors.
To detach a WebSocket connection and use the \fIcurl_ws_send(3)\fP and
\fIcurl_ws_recv(3)\fP functions after the HTTP upgrade procedure, set the
\fICURLOPT_CONNECT_ONLY(3)\fP option to 2L.
Available bits in the bitmask
.IP "CURLWS_RAW_MODE (1)"
Deliver "raw" WebSocket traffic to the \fICURLOPT_WRITEFUNCTION(3)\fP
callback.
In raw mode, libcurl does not handle pings or any other frame for the
application.
.SH DEFAULT
0
.SH PROTOCOLS
WebSocket
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "ws://example.com/");
/* tell curl we deal with all the WebSocket magic ourselves */
curl_easy_setopt(curl, CURLOPT_WS_OPTIONS, (long)CURLWS_RAW_MODE);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.85.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_ws_recv "(3), " curl_ws_send "(3), "
share/man/man3/CURLOPT_HSTS.3 0000644 00000005731 14751150700 0011342 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 2022 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_HSTS 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_HSTS \- HSTS cache file name
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTS, char *filename);
.fi
.SH DESCRIPTION
Make the \fIfilename\fP point to a file name to load an existing HSTS cache
from, and to store the cache in when the easy handle is closed. Setting a file
name with this option will also enable HSTS for this handle (the equivalent of
setting \fICURLHSTS_ENABLE\fP with \fICURLOPT_HSTS_CTRL(3)\fP).
If the given file does not exist or contains no HSTS entries at startup, the
HSTS cache will simply start empty. Setting the file name to NULL or "" will
only enable HSTS without reading from or writing to any file.
If this option is set multiple times, libcurl will load cache entries from
each given file but will only store the last used name for later writing.
.SH "FILE FORMAT"
The HSTS cache is saved to and loaded from a text file with one entry per
physical line. Each line in the file has the following format:
[host] [stamp]
[host] is the domain name for the entry and the name is dot-prefixed if it is
an entry valid for all subdomains to the name as well or only for the exact
name.
[stamp] is the time (in UTC) when the entry expires and it uses the format
\&"YYYYMMDD HH:MM:SS".
Lines starting with "#" are treated as comments and are ignored. There is
currently no length or size limit.
.SH DEFAULT
NULL, no file name
.SH PROTOCOLS
HTTPS and HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_HSTS, "/home/user/.hsts-cache");
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.74.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_HSTS_CTRL "(3), " CURLOPT_ALTSVC "(3), " CURLOPT_RESOLVE "(3), "
share/man/man3/CURLOPT_TRANSFER_ENCODING.3 0000644 00000005043 14751150700 0013247 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_TRANSFER_ENCODING 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_TRANSFER_ENCODING \- ask for HTTP Transfer Encoding
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TRANSFER_ENCODING,
long enable);
.fi
.SH DESCRIPTION
Pass a long set to 1L to \fIenable\fP or 0 to disable.
Adds a request for compressed Transfer Encoding in the outgoing HTTP
request. If the server supports this and so desires, it can respond with the
HTTP response sent using a compressed Transfer-Encoding that will be
automatically uncompressed by libcurl on reception.
Transfer-Encoding differs slightly from the Content-Encoding you ask for with
\fICURLOPT_ACCEPT_ENCODING(3)\fP in that a Transfer-Encoding is strictly meant
to be for the transfer and thus MUST be decoded before the data arrives in the
client. Traditionally, Transfer-Encoding has been much less used and supported
by both HTTP clients and HTTP servers.
.SH DEFAULT
0
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_TRANSFER_ENCODING, 1L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.21.6
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_ACCEPT_ENCODING "(3), " CURLOPT_HTTP_TRANSFER_DECODING "(3), "
share/man/man3/CURLOPT_TIMEOUT_MS.3 0000644 00000005743 14751150700 0012311 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_TIMEOUT_MS 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_TIMEOUT_MS \- maximum time the transfer is allowed to complete
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMEOUT_MS, long timeout);
.fi
.SH DESCRIPTION
Pass a long as parameter containing \fItimeout\fP - the maximum time in
milliseconds that you allow the libcurl transfer operation to take. Normally,
name lookups can take a considerable time and limiting operations to less than
a few minutes risk aborting perfectly normal operations. This option may cause
libcurl to use the SIGALRM signal to timeout system calls.
If libcurl is built to use the standard system name resolver, that portion of
the transfer will still use full-second resolution for timeouts with a minimum
timeout allowed of one second.
In unix-like systems, this might cause signals to be used unless
\fICURLOPT_NOSIGNAL(3)\fP is set.
If both \fICURLOPT_TIMEOUT(3)\fP and \fICURLOPT_TIMEOUT_MS(3)\fP are set, the
value set last will be used.
Since this puts a hard limit for how long time a request is allowed to take,
it has limited use in dynamic use cases with varying transfer times. You are
then advised to explore \fICURLOPT_LOW_SPEED_LIMIT(3)\fP,
\fICURLOPT_LOW_SPEED_TIME(3)\fP or using \fICURLOPT_PROGRESSFUNCTION(3)\fP to
implement your own timeout logic.
.SH DEFAULT
Default timeout is 0 (zero) which means it never times out during transfer.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* complete within 20000 milliseconds */
curl_easy_setopt(curl, CURLOPT_TIMEOUT_MS, 20000L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_TIMEOUT "(3), "
.BR CURLOPT_CONNECTTIMEOUT "(3), " CURLOPT_LOW_SPEED_LIMIT "(3), "
share/man/man3/curl_ws_send.3 0000644 00000006365 14751150700 0012044 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH curl_ws_send 3 "October 07, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_ws_send - send WebSocket data
.SH SYNOPSIS
.nf
#include <curl/easy.h>
CURLcode curl_ws_send(CURL *curl, const void *buffer, size_t buflen,
size_t *sent, curl_off_t fragsize,
unsigned int flags);
.fi
.SH DESCRIPTION
This function call is EXPERIMENTAL.
Send the specific message fragment over an established WebSocket
connection. The \fIbuffer\fP holds the data to send and it is \fIbuflen\fP
number of payload bytes in that memory area.
\fIsent\fP is returned as the number of payload bytes actually sent.
To send a (huge) fragment using multiple calls with partial content per
invoke, set the \fICURLWS_OFFSET\fP bit and the \fIfragsize\fP argument as the
total expected size for the first part, then set the \fICURLWS_OFFSET\fP with
a zero \fIfragsize\fP for the following parts.
If not sending a partial fragment or if this is raw mode, \fIfragsize\fP
should be set to zero.
If \fBCURLWS_RAW_MODE\fP is enabled in \fICURLOPT_WS_OPTIONS(3)\fP, the
\fBflags\fP argument should be set to 0.
.SH FLAGS
.IP CURLWS_TEXT
The buffer contains text data. Note that this makes a difference to WebSocket
but libcurl itself will not make any verification of the content or
precautions that you actually send valid UTF-8 content.
.IP CURLWS_BINARY
This is binary data.
.IP CURLWS_CONT
This is not the final fragment of the message, which implies that there will
be another fragment coming as part of the same message where this bit is not
set.
.IP CURLWS_CLOSE
Close this transfer.
.IP CURLWS_PING
This as a ping.
.IP CURLWS_PONG
This as a pong.
.IP CURLWS_OFFSET
The provided data is only a partial fragment and there will be more in a
following call to \fIcurl_ws_send()\fP. When sending only a piece of the
fragment like this, the \fIfragsize\fP must be provided with the total
expected fragment size in the first call and it needs to be zero in subsequent
calls.
.SH EXAMPLE
.nf
.fi
.SH AVAILABILITY
Added in 7.86.0.
.SH RETURN VALUE
.SH "SEE ALSO"
.BR curl_easy_setopt "(3), " curl_easy_perform "(3), "
.BR curl_easy_getinfo "(3), "
.BR curl_ws_recv "(3) "
share/man/man3/CURLOPT_SSLENGINE_DEFAULT.3 0000644 00000004602 14751150700 0013250 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SSLENGINE_DEFAULT 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSLENGINE_DEFAULT \- make SSL engine default
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLENGINE_DEFAULT, long val);
.fi
.SH DESCRIPTION
Pass a long set to 1 to make the already specified crypto engine the default
for (asymmetric) crypto operations.
This option has no effect unless set after \fICURLOPT_SSLENGINE(3)\fP.
.SH DEFAULT
None
.SH PROTOCOLS
All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_SSLENGINE, "dynamic");
curl_easy_setopt(curl, CURLOPT_SSLENGINE_DEFAULT, 1L);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Only if the SSL backend is OpenSSL built with engine support.
.SH RETURN VALUE
CURLE_OK - Engine set as default.
CURLE_SSL_ENGINE_SETFAILED - Engine could not be set as default.
CURLE_NOT_BUILT_IN - Option not built in, OpenSSL is not the SSL backend.
CURLE_UNKNOWN_OPTION - Option not recognized.
CURLE_OUT_OF_MEMORY - Insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_SSLENGINE "(3), " CURLOPT_SSLCERT "(3), "
share/man/man3/curl_formadd.3 0000644 00000031151 14751150700 0012005 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_formadd 3 "October 03, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_formadd - add a section to a multipart form POST
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLFORMcode curl_formadd(struct curl_httppost **firstitem,
struct curl_httppost **lastitem, ...);
.fi
.SH DESCRIPTION
\fBThis function is deprecated.\fP Use \fIcurl_mime_init(3)\fP instead.
curl_formadd() is used to append sections when building a multipart form
post. Append one section at a time until you have added all the sections you
want included and then you pass the \fIfirstitem\fP pointer as parameter to
\fICURLOPT_HTTPPOST(3)\fP. \fIlastitem\fP is set after each
\fIcurl_formadd(3)\fP call and on repeated invokes it should be left as set to
allow repeated invokes to find the end of the list faster.
After the \fIlastitem\fP pointer follow the real arguments.
The pointers \fIfirstitem\fP and \fIlastitem\fP should both be pointing to
NULL in the first call to this function. All list-data will be allocated by
the function itself. You must call \fIcurl_formfree(3)\fP on the
\fIfirstitem\fP after the form post has been done to free the resources.
Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header.
You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP as usual.
First, there are some basics you need to understand about multipart form
posts. Each part consists of at least a NAME and a CONTENTS part. If the part
is made for file upload, there are also a stored CONTENT-TYPE and a FILENAME.
Below, we will discuss what options you use to set these properties in the
parts you want to add to your post.
The options listed first are for making normal parts. The options from
\fICURLFORM_FILE\fP through \fICURLFORM_BUFFERLENGTH\fP are for file upload
parts.
.SH OPTIONS
.IP CURLFORM_COPYNAME
followed by a string which provides the \fIname\fP of this part. libcurl
copies the string so your application does not need to keep it around after
this function call. If the name is not null-terminated, you must set its
length with \fBCURLFORM_NAMELENGTH\fP. The \fIname\fP is not allowed to
contain zero-valued bytes. The copied data will be freed by
\fIcurl_formfree(3)\fP.
.IP CURLFORM_PTRNAME
followed by a string which provides the \fIname\fP of this part. libcurl
will use the pointer and refer to the data in your application, so you
must make sure it remains until curl no longer needs it. If the name
is not null-terminated, you must set its length with \fBCURLFORM_NAMELENGTH\fP.
The \fIname\fP is not allowed to contain zero-valued bytes.
.IP CURLFORM_COPYCONTENTS
followed by a pointer to the contents of this part, the actual data
to send away. libcurl copies the provided data, so your application does not
need to keep it around after this function call. If the data is not null
terminated, or if you would like it to contain zero bytes, you must
set the length of the name with \fBCURLFORM_CONTENTSLENGTH\fP. The copied
data will be freed by \fIcurl_formfree(3)\fP.
.IP CURLFORM_PTRCONTENTS
followed by a pointer to the contents of this part, the actual data to send
away. libcurl will use the pointer and refer to the data in your application,
so you must make sure it remains until curl no longer needs it. If the data
is not null-terminated, or if you would like it to contain zero bytes, you
must set its length with \fBCURLFORM_CONTENTSLENGTH\fP.
.IP CURLFORM_CONTENTLEN
followed by a curl_off_t value giving the length of the contents. Note that
for \fICURLFORM_STREAM\fP contents, this option is mandatory.
If you pass a 0 (zero) for this option, libcurl will instead do a strlen() on
the contents to figure out the size. If you really want to send a zero byte
content then you must make sure strlen() on the data pointer returns zero.
(Option added in 7.46.0)
.IP CURLFORM_CONTENTSLENGTH
(This option is deprecated. Use \fICURLFORM_CONTENTLEN\fP instead!)
followed by a long giving the length of the contents. Note that for
\fICURLFORM_STREAM\fP contents, this option is mandatory.
If you pass a 0 (zero) for this option, libcurl will instead do a strlen() on
the contents to figure out the size. If you really want to send a zero byte
content then you must make sure strlen() on the data pointer returns zero.
.IP CURLFORM_FILECONTENT
followed by a filename, causes that file to be read and its contents used
as data in this part. This part does \fInot\fP automatically become a file
upload part simply because its data was read from a file.
The specified file needs to kept around until the associated transfer is done.
.IP CURLFORM_FILE
followed by a filename, makes this part a file upload part. It sets the
\fIfilename\fP field to the basename of the provided filename, it reads the
contents of the file and passes them as data and sets the content-type if the
given file match one of the internally known file extensions. For
\fBCURLFORM_FILE\fP the user may send one or more files in one part by
providing multiple \fBCURLFORM_FILE\fP arguments each followed by the filename
(and each \fICURLFORM_FILE\fP is allowed to have a
\fICURLFORM_CONTENTTYPE\fP).
The given upload file has to exist in its full in the file system already when
the upload starts, as libcurl needs to read the correct file size beforehand.
The specified file needs to kept around until the associated transfer is done.
.IP CURLFORM_CONTENTTYPE
is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a
string which provides the content-type for this part, possibly instead of an
internally chosen one.
.IP CURLFORM_FILENAME
is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a
string, it tells libcurl to use the given string as the \fIfilename\fP in the
file upload part instead of the actual file name.
.IP CURLFORM_BUFFER
is used for custom file upload parts without use of \fICURLFORM_FILE\fP. It
tells libcurl that the file contents are already present in a buffer. The
parameter is a string which provides the \fIfilename\fP field in the content
header.
.IP CURLFORM_BUFFERPTR
is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a pointer
to the buffer to be uploaded. This buffer must not be freed until after
\fIcurl_easy_cleanup(3)\fP is called. You must also use
\fICURLFORM_BUFFERLENGTH\fP to set the number of bytes in the buffer.
.IP CURLFORM_BUFFERLENGTH
is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a
long which gives the length of the buffer.
.IP CURLFORM_STREAM
Tells libcurl to use the \fICURLOPT_READFUNCTION(3)\fP callback to get
data. The parameter you pass to \fICURLFORM_STREAM\fP is the pointer passed on
to the read callback's fourth argument. If you want the part to look like a
file upload one, set the \fICURLFORM_FILENAME\fP parameter as well. Note that
when using \fICURLFORM_STREAM\fP, \fICURLFORM_CONTENTSLENGTH\fP must also be
set with the total expected length of the part unless the formpost is sent
chunked encoded. (Option added in libcurl 7.18.2)
.IP CURLFORM_ARRAY
Another possibility to send options to curl_formadd() is the
\fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as
its value. Each curl_forms structure element has a \fICURLformoption\fP and a
char pointer. The final element in the array must be a CURLFORM_END. All
available options can be used in an array, except the CURLFORM_ARRAY option
itself. The last argument in such an array must always be \fBCURLFORM_END\fP.
.IP CURLFORM_CONTENTHEADER
specifies extra headers for the form POST section. This takes a curl_slist
prepared in the usual way using \fBcurl_slist_append\fP and appends the list
of headers to those libcurl automatically generates. The list must exist while
the POST occurs, if you free it before the post completes you may experience
problems.
When you have passed the \fIstruct curl_httppost\fP pointer to
\fIcurl_easy_setopt(3)\fP (using the \fICURLOPT_HTTPPOST(3)\fP option), you
must not free the list until after you have called \fIcurl_easy_cleanup(3)\fP
for the curl handle.
See example below.
.SH EXAMPLE
.nf
struct curl_httppost* post = NULL;
struct curl_httppost* last = NULL;
char namebuffer[] = "name buffer";
long namelength = strlen(namebuffer);
char buffer[] = "test buffer";
char htmlbuffer[] = "<HTML>test buffer</HTML>";
long htmlbufferlength = strlen(htmlbuffer);
struct curl_forms forms[3];
char file1[] = "my-face.jpg";
char file2[] = "your-face.jpg";
/* add null character into htmlbuffer, to demonstrate that
transfers of buffers containing null characters actually work
*/
htmlbuffer[8] = '\\0';
/* Add simple name/content section */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "name",
CURLFORM_COPYCONTENTS, "content", CURLFORM_END);
/* Add simple name/content/contenttype section */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode",
CURLFORM_COPYCONTENTS, "<HTML></HTML>",
CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
/* Add name/ptrcontent section */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent",
CURLFORM_PTRCONTENTS, buffer, CURLFORM_END);
/* Add ptrname/ptrcontent section */
curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer,
CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH,
namelength, CURLFORM_END);
/* Add name/ptrcontent/contenttype section */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole",
CURLFORM_PTRCONTENTS, htmlbuffer,
CURLFORM_CONTENTSLENGTH, htmlbufferlength,
CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
/* Add simple file section */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
CURLFORM_FILE, "my-face.jpg", CURLFORM_END);
/* Add file/contenttype section */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
CURLFORM_FILE, "my-face.jpg",
CURLFORM_CONTENTTYPE, "image/jpeg", CURLFORM_END);
/* Add two file section */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
CURLFORM_FILE, "my-face.jpg",
CURLFORM_FILE, "your-face.jpg", CURLFORM_END);
/* Add two file section using CURLFORM_ARRAY */
forms[0].option = CURLFORM_FILE;
forms[0].value = file1;
forms[1].option = CURLFORM_FILE;
forms[1].value = file2;
forms[2].option = CURLFORM_END;
/* Add a buffer to upload */
curl_formadd(&post, &last,
CURLFORM_COPYNAME, "name",
CURLFORM_BUFFER, "data",
CURLFORM_BUFFERPTR, record,
CURLFORM_BUFFERLENGTH, record_length,
CURLFORM_END);
/* no option needed for the end marker */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
CURLFORM_ARRAY, forms, CURLFORM_END);
/* Add the content of a file as a normal post text value */
curl_formadd(&post, &last, CURLFORM_COPYNAME, "filecontent",
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),"
.BR curl_mime_init "(3)"
share/man/man3/CURLOPT_ALTSVC_CTRL.3 0000644 00000007073 14751150700 0012402 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_ALTSVC_CTRL 3 "October 22, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_ALTSVC_CTRL \- control alt-svc behavior
.SH SYNOPSIS
.nf
#include <curl/curl.h>
#define CURLALTSVC_READONLYFILE (1<<2)
#define CURLALTSVC_H1 (1<<3)
#define CURLALTSVC_H2 (1<<4)
#define CURLALTSVC_H3 (1<<5)
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ALTSVC_CTRL, long bitmask);
.fi
.SH DESCRIPTION
Populate the long \fIbitmask\fP with the correct set of features to instruct
libcurl how to handle Alt-Svc for the transfers using this handle.
libcurl only accepts Alt-Svc headers over a secure transport, meaning
HTTPS. It will also only complete a request to an alternative origin if that
origin is properly hosted over HTTPS. These requirements are there to make
sure both the source and the destination are legitimate.
Alternative services are only used when setting up new connections. If there
exists an existing connection to the host in the connection pool, then that
will be preferred.
Setting any bit will enable the alt-svc engine.
.IP "CURLALTSVC_READONLYFILE"
Do not write the alt-svc cache back to the file specified with
\fICURLOPT_ALTSVC(3)\fP even if it gets updated. By default a file specified
with that option will be read and written to as deemed necessary.
.IP "CURLALTSVC_H1"
Accept alternative services offered over HTTP/1.1.
.IP "CURLALTSVC_H2"
Accept alternative services offered over HTTP/2. This will only be used if
libcurl was also built to actually support HTTP/2, otherwise this bit will be
ignored.
.IP "CURLALTSVC_H3"
Accept alternative services offered over HTTP/3. This will only be used if
libcurl was also built to actually support HTTP/3, otherwise this bit will be
ignored.
.SH DEFAULT
Alt-Svc handling is disabled by default. If \fICURLOPT_ALTSVC(3)\fP is set,
\fICURLOPT_ALTSVC_CTRL(3)\fP has a default value corresponding to
CURLALTSVC_H1 | CURLALTSVC_H2 | CURLALTSVC_H3 - the HTTP/2 and HTTP/3 bits are
only set if libcurl was built with support for those versions.
.SH PROTOCOLS
HTTPS
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_ALTSVC_CTRL, (long)CURLALTSVC_H1);
curl_easy_setopt(curl, CURLOPT_ALTSVC, "altsvc-cache.txt");
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.64.1
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_ALTSVC "(3), " CURLOPT_CONNECT_TO "(3), " CURLOPT_RESOLVE "(3), "
share/man/man3/CURLOPT_DOH_SSL_VERIFYPEER.3 0000644 00000007773 14751150700 0013464 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_DOH_SSL_VERIFYPEER 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_DOH_SSL_VERIFYPEER \- verify the DoH SSL certificate
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DOH_SSL_VERIFYPEER,
long verify);
.fi
.SH DESCRIPTION
Pass a long as parameter set to 1L to enable or 0L to disable.
This option tells curl to verify the authenticity of the DoH (DNS-over-HTTPS)
server's certificate. A value of 1 means curl verifies; 0 (zero) means it
does not.
This option is the DoH equivalent of \fICURLOPT_SSL_VERIFYPEER(3)\fP and
only affects requests to the DoH server.
When negotiating a TLS or SSL connection, the server sends a certificate
indicating its identity. Curl verifies whether the certificate is authentic,
i.e. that you can trust that the server is who the certificate says it is.
This trust is based on a chain of digital signatures, rooted in certification
authority (CA) certificates you supply. curl uses a default bundle of CA
certificates (the path for that is determined at build time) and you can
specify alternate certificates with the \fICURLOPT_CAINFO(3)\fP option
or the \fICURLOPT_CAPATH(3)\fP option.
When \fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP is enabled, and the verification
fails to prove that the certificate is authentic, the connection fails. When
the option is zero, the peer certificate verification succeeds regardless.
Authenticating the certificate is not enough to be sure about the server. You
typically also want to ensure that the server is the server you mean to be
talking to. Use \fICURLOPT_DOH_SSL_VERIFYHOST(3)\fP for that. The check
that the host name in the certificate is valid for the host name you are
connecting to is done independently of the
\fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP option.
WARNING: disabling verification of the certificate allows bad guys to
man-in-the-middle the communication without you knowing it. Disabling
verification makes the communication insecure. Just having encryption on a
transfer is not enough as you cannot be sure that you are communicating with
the correct end-point.
.SH DEFAULT
1
.SH PROTOCOLS
DoH
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_DOH_URL, "https://cloudflare-dns.com/dns-query");
/* Disable certificate verification of the DoH server */
curl_easy_setopt(curl, CURLOPT_DOH_SSL_VERIFYPEER, 0L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.76.0
If built TLS enabled.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_DOH_SSL_VERIFYHOST "(3), "
.BR CURLOPT_SSL_VERIFYHOST "(3), "
.BR CURLOPT_SSL_VERIFYPEER "(3), "
.BR CURLOPT_PROXY_SSL_VERIFYPEER "(3), "
.BR CURLOPT_PROXY_SSL_VERIFYHOST "(3), "
.BR CURLOPT_CAINFO "(3), "
.BR CURLOPT_CAPATH "(3), "
share/man/man3/CURLOPT_SERVER_RESPONSE_TIMEOUT.3 0000644 00000005326 14751150700 0014313 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SERVER_RESPONSE_TIMEOUT 3 "July 04, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SERVER_RESPONSE_TIMEOUT \- time allowed to wait for server response
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SERVER_RESPONSE_TIMEOUT,
long timeout);
.fi
.SH DESCRIPTION
Pass a long. Causes libcurl to set a \fItimeout\fP period (in seconds) on the
amount of time that the server is allowed to take in order to send a response
message for a command before the session is considered dead. While libcurl is
waiting for a response, this value overrides \fICURLOPT_TIMEOUT(3)\fP. It is
recommended that if used in conjunction with \fICURLOPT_TIMEOUT(3)\fP, you set
\fICURLOPT_SERVER_RESPONSE_TIMEOUT(3)\fP to a value smaller than
\fICURLOPT_TIMEOUT(3)\fP.
This option was formerly known as \fBCURLOPT_FTP_RESPONSE_TIMEOUT\fP.
.SH DEFAULT
None
.SH PROTOCOLS
FTP, IMAP, POP3 and SMTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/slow.txt");
/* wait no more than 23 seconds */
curl_easy_setopt(curl, CURLOPT_SERVER_RESPONSE_TIMEOUT, 23L);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.10.8. Used under this name since 7.20.0
.SH RETURN VALUE
Returns CURLE_OK if supported, and CURLE_UNKNOWN_OPTION if not. Returns
CURLE_BAD_FUNCTION_ARGUMENT if set to a negative value or a value that when
converted to milliseconds is too large.
.SH "SEE ALSO"
.BR CURLOPT_TIMEOUT "(3), " CURLOPT_CONNECTTIMEOUT "(3), "
.BR CURLOPT_LOW_SPEED_LIMIT "(3), "
share/man/man3/CURLINFO_SSL_ENGINES.3 0000644 00000004654 14751150700 0012466 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_SSL_ENGINES 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_SSL_ENGINES \- get an slist of OpenSSL crypto-engines
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SSL_ENGINES,
struct curl_slist **engine_list);
.fi
.SH DESCRIPTION
Pass the address of a 'struct curl_slist *' to receive a linked-list of
OpenSSL crypto-engines supported. Note that engines are normally implemented
in separate dynamic libraries. Hence not all the returned engines may be
available at runtime. \fBNOTE:\fP you must call \fIcurl_slist_free_all(3)\fP
on the list pointer once you are done with it, as libcurl will not free the
data for you.
.SH PROTOCOLS
All TLS based ones.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res;
struct curl_slist *engines;
res = curl_easy_getinfo(curl, CURLINFO_SSL_ENGINES, &engines);
if((res == CURLE_OK) && engines) {
/* we have a list, free it when done using it */
curl_slist_free_all(engines);
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.12.3. Available in OpenSSL builds with "engine" support.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
share/man/man3/CURLOPT_SUPPRESS_CONNECT_HEADERS.3 0000644 00000006075 14751150700 0014353 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SUPPRESS_CONNECT_HEADERS 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SUPPRESS_CONNECT_HEADERS \- suppress proxy CONNECT response headers from user callbacks
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SUPPRESS_CONNECT_HEADERS, long onoff);
.fi
.SH DESCRIPTION
When \fICURLOPT_HTTPPROXYTUNNEL(3)\fP is used and a CONNECT request is made,
suppress proxy CONNECT response headers from the user callback functions
\fICURLOPT_HEADERFUNCTION(3)\fP and \fICURLOPT_WRITEFUNCTION(3)\fP.
Proxy CONNECT response headers can complicate header processing since it's
essentially a separate set of headers. You can enable this option to suppress
those headers.
For example let's assume an HTTPS URL is to be retrieved via CONNECT. On
success there would normally be two sets of headers, and each header line sent
to the header function and/or the write function. The data given to the
callbacks would look like this:
.nf
HTTP/1.1 200 Connection established
{headers}...
HTTP/1.1 200 OK
Content-Type: application/json
{headers}...
{body}...
.fi
However by enabling this option the CONNECT response headers are suppressed, so
the data given to the callbacks would look like this:
.nf
HTTP/1.1 200 OK
Content-Type: application/json
{headers}...
{body}...
.fi
.SH DEFAULT
0
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_HEADER, 1L);
curl_easy_setopt(curl, CURLOPT_PROXY, "http://foo:3128");
curl_easy_setopt(curl, CURLOPT_HTTPPROXYTUNNEL, 1L);
curl_easy_setopt(curl, CURLOPT_SUPPRESS_CONNECT_HEADERS, 1L);
curl_easy_perform(curl);
/* always cleanup */
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.54.0
.SH RETURN VALUE
CURLE_OK or an error such as CURLE_UNKNOWN_OPTION.
.SH "SEE ALSO"
.BR CURLOPT_HEADER "(3), " CURLOPT_PROXY "(3), "
.BR CURLOPT_HTTPPROXYTUNNEL "(3), "
share/man/man3/curl_easy_perform.3 0000644 00000007152 14751150700 0013070 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_easy_perform 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_easy_perform - perform a blocking file transfer
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_perform(CURL *easy_handle);
.fi
.SH DESCRIPTION
Invoke this function after \fIcurl_easy_init(3)\fP and all the
\fIcurl_easy_setopt(3)\fP calls are made, and it performs the transfer as
described in the options. It must be called with the same \fBeasy_handle\fP as
input as the \fIcurl_easy_init(3)\fP call returned.
\fIcurl_easy_perform(3)\fP performs the entire request in a blocking manner
and returns when done, or earlier if it fails. For non-blocking behavior, see
\fIcurl_multi_perform(3)\fP.
You can do any amount of calls to \fIcurl_easy_perform(3)\fP while using the
same \fBeasy_handle\fP. If you intend to transfer more than one file, you are
even encouraged to do so. libcurl will then attempt to re-use the same
connection for the following transfers, thus making the operations faster,
less CPU intense and using less network resources. Just note that you will
have to use \fIcurl_easy_setopt(3)\fP between the invokes to set options for
the following curl_easy_perform.
You must never call this function simultaneously from two places using the
same \fBeasy_handle\fP. Let the function return first before invoking it
another time. If you want parallel transfers, you must use several curl
easy_handles.
A network transfer moves data to a peer or from a peer. An application tells
libcurl how to receive data by setting the \fICURLOPT_WRITEFUNCTION(3)\fP and
\fICURLOPT_WRITEDATA(3)\fP options. To tell libcurl what data to send, there
are a few more alternatives but two common ones are
\fICURLOPT_READFUNCTION(3)\fP and \fICURLOPT_POSTFIELDS(3)\fP.
While the \fBeasy_handle\fP is added to a multi handle, it cannot be used by
\fIcurl_easy_perform(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
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), "
.BR libcurl-errors "(3), "
share/man/man3/CURLOPT_XFERINFODATA.3 0000644 00000004706 14751150700 0012434 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_XFERINFODATA 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_XFERINFODATA \- pointer passed to the progress callback
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_XFERINFODATA, void *pointer);
.fi
.SH DESCRIPTION
Pass a \fIpointer\fP that will be untouched by libcurl and passed as the first
argument in the progress callback set with \fICURLOPT_XFERINFOFUNCTION(3)\fP.
This is an alias for \fICURLOPT_PROGRESSDATA(3)\fP.
.SH DEFAULT
The default value of this parameter is NULL.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
struct progress {
char *private;
size_t size;
};
static size_t progress_callback(void *clientp,
curl_off_t dltotal,
curl_off_t dlnow,
curl_off_t ultotal,
curl_off_t ulnow)
{
struct memory *progress = (struct progress *)userp;
/* use the values */
return 0; /* all is good */
}
struct progress data;
/* pass struct to callback */
curl_easy_setopt(curl_handle, CURLOPT_XFERINFODATA, &data);
curl_easy_setopt(curl_handle, CURLOPT_XFERINFOFUNCTION, progress_callback);
.fi
.SH AVAILABILITY
Added in 7.32.0
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_XFERINFOFUNCTION "(3), " CURLOPT_VERBOSE "(3), "
share/man/man3/CURLOPT_PREREQDATA.3 0000644 00000004436 14751150700 0012212 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 2022, Max Dymond, <max.dymond@microsoft.com>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PREREQDATA 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PREREQDATA \- pointer passed to the pre-request callback
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PREREQDATA, void *pointer);
.fi
.SH DESCRIPTION
Pass a \fIpointer\fP that will be untouched by libcurl and passed as the first
argument in the pre-request callback set with
\fICURLOPT_PREREQFUNCTION(3)\fP.
.SH DEFAULT
NULL
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
static int prereq_callback(void *clientp,
char *conn_primary_ip,
char *conn_local_ip,
int conn_primary_port,
int conn_local_port)
{
printf("Connection made to %s:%s\\n", conn_primary_ip, conn_primary_port);
return CURL_PREREQFUNC_OK;
}
{
struct data prereq_data;
curl_easy_setopt(CURL *handle, CURLOPT_PREREQFUNCTION, prereq_callback);
curl_easy_setopt(CURL *handle, CURLOPT_PREREQDATA, &prereq_data);
}
.fi
.SH AVAILABILITY
Added in 7.80.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_PREREQFUNCTION "(3) "
share/man/man3/CURLOPT_CHUNK_END_FUNCTION.3 0000644 00000004720 14751150700 0013421 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_CHUNK_END_FUNCTION 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_CHUNK_END_FUNCTION \- callback after a transfer with FTP wildcard match
.SH SYNOPSIS
.nf
#include <curl/curl.h>
long chunk_end_callback(void *ptr);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CHUNK_END_FUNCTION,
chunk_end_callback);
.SH DESCRIPTION
Pass a pointer to your callback function, which should match the prototype
shown above.
This function gets called by libcurl as soon as a part of the stream has been
transferred (or skipped).
Return \fICURL_CHUNK_END_FUNC_OK\fP if everything is fine or
\fBCURL_CHUNK_END_FUNC_FAIL\fP to tell the lib to stop if some error occurred.
.SH DEFAULT
NULL
.SH PROTOCOLS
FTP
.SH EXAMPLE
.nf
static long file_is_downloaded(struct callback_data *data)
{
if(data->output) {
fclose(data->output);
data->output = 0x0;
}
return CURL_CHUNK_END_FUNC_OK;
}
int main()
{
/* data for callback */
struct callback_data callback_info;
curl_easy_setopt(curl, CURLOPT_CHUNK_END_FUNCTION, file_is_downloaded);
curl_easy_setopt(curl, CURLOPT_CHUNK_DATA, &callback_info);
}
.fi
.SH AVAILABILITY
Added in 7.21.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_WILDCARDMATCH "(3), " CURLOPT_CHUNK_BGN_FUNCTION "(3), "
share/man/man3/CURLINFO_REQUEST_SIZE.3 0000644 00000004340 14751150700 0012627 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_REQUEST_SIZE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_REQUEST_SIZE \- get size of sent request
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_REQUEST_SIZE, long *sizep);
.fi
.SH DESCRIPTION
Pass a pointer to a long to receive the total size of the issued
requests. This is so far only for HTTP requests. Note that this may be more
than one request if \fICURLOPT_FOLLOWLOCATION(3)\fP is enabled.
.SH PROTOCOLS
All
.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);
if(res == CURLE_OK) {
long req;
res = curl_easy_getinfo(curl, CURLINFO_REQUEST_SIZE, &req);
if(!res)
printf("Request size: %ld bytes\\n", req);
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.4.1
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
.BR CURLINFO_HEADER_SIZE "(3), "
.BR CURLINFO_SIZE_DOWNLOAD "(3), "
share/man/man3/libcurl-multi.3 0000644 00000022316 14751150700 0012133 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH libcurl-multi 3 "September 20, 2022" "libcurl 7.86.0" "libcurl multi interface"
.SH NAME
libcurl-multi \- how to use the multi interface
.SH DESCRIPTION
This is an overview on how to use the libcurl multi interface in your C
programs. There are specific man pages for each function mentioned in
here. There's also the \fIlibcurl-tutorial(3)\fP man page for a complete
tutorial to programming with libcurl and the \fIlibcurl-easy(3)\fP man page
for an overview of the libcurl easy interface.
All functions in the multi interface are prefixed with curl_multi.
.SH "OBJECTIVES"
The multi interface offers several abilities that the easy interface does not.
They are mainly:
1. Enable a "pull" interface. The application that uses libcurl decides where
and when to ask libcurl to get/send data.
2. Enable multiple simultaneous transfers in the same thread without making it
complicated for the application.
3. Enable the application to wait for action on its own file descriptors and
curl's file descriptors simultaneously.
4. Enable event-based handling and scaling transfers up to and beyond
thousands of parallel connections.
.SH "ONE MULTI HANDLE MANY EASY HANDLES"
To use the multi interface, you must first create a 'multi handle' with
\fIcurl_multi_init(3)\fP. This handle is then used as input to all further
curl_multi_* functions.
With a multi handle and the multi interface you can do several simultaneous
transfers in parallel. Each single transfer is built up around an easy
handle. You create all the easy handles you need, and setup the appropriate
options for each easy handle using \fIcurl_easy_setopt(3)\fP.
There are two flavors of the multi interface, the select() oriented one and
the event based one we call multi_socket. You will benefit from reading
through the description of both versions to fully understand how they work and
differentiate. We start out with the select() oriented version.
When an easy handle is setup and ready for transfer, then instead of using
\fIcurl_easy_perform(3)\fP like when using the easy interface for transfers,
you should add the easy handle to the multi handle with
\fIcurl_multi_add_handle(3)\fP. You can add more easy handles to a multi
handle at any point, even if other transfers are already running.
Should you change your mind, the easy handle is again removed from the multi
stack using \fIcurl_multi_remove_handle(3)\fP. Once removed from the multi
handle, you can again use other easy interface functions like
\fIcurl_easy_perform(3)\fP on the handle or whatever you think is
necessary. You can remove handles at any point during transfers.
Adding the easy handle to the multi handle does not start the transfer.
Remember that one of the main ideas with this interface is to let your
application drive. You drive the transfers by invoking
\fIcurl_multi_perform(3)\fP. libcurl will then transfer data if there is
anything available to transfer. it will use the callbacks and everything else
you have setup in the individual easy handles. it will transfer data on all
current transfers in the multi stack that are ready to transfer anything. It
may be all, it may be none. When there's nothing more to do for now, it
returns back to the calling application.
Your application extracts info from libcurl about when it would like to get
invoked to transfer data or do other work. The most convenient way is to use
\fIcurl_multi_poll(3)\fP that will help you wait until the application should
call libcurl again. The older API to accomplish the same thing is
\fIcurl_multi_fdset(3)\fP that extracts \fIfd_sets\fP from libcurl to use in
select() or poll() calls in order to get to know when the transfers in the
multi stack might need attention. Both these APIs allow for your program to
wait for input on your own private file descriptors at the same time.
\fIcurl_multi_timeout(3)\fP also helps you with providing a suitable timeout
period for your select() calls.
\fIcurl_multi_perform(3)\fP stores the number of still running transfers in
one of its input arguments, and by reading that you can figure out when all
the transfers in the multi handles are done. 'done' does not mean
successful. One or more of the transfers may have failed.
To get information about completed transfers, to figure out success or not and
similar, \fIcurl_multi_info_read(3)\fP should be called. It can return a
message about a current or previous transfer. Repeated invokes of the function
get more messages until the message queue is empty. The information you
receive there includes an easy handle pointer which you may use to identify
which easy handle the information regards.
When a single transfer is completed, the easy handle is still left added to
the multi stack. You need to first remove the easy handle with
\fIcurl_multi_remove_handle(3)\fP and then close it with
\fIcurl_easy_cleanup(3)\fP, or possibly set new options to it and add it again
with \fIcurl_multi_add_handle(3)\fP to start another transfer.
When all transfers in the multi stack are done, close the multi handle with
\fIcurl_multi_cleanup(3)\fP. Be careful and please note that you \fBMUST\fP
invoke separate \fIcurl_easy_cleanup(3)\fP calls for every single easy handle
to clean them up properly.
If you want to re-use an easy handle that was added to the multi handle for
transfer, you must first remove it from the multi stack and then re-add it
again (possibly after having altered some options at your own choice).
.SH "MULTI_SOCKET"
\fIcurl_multi_socket_action(3)\fP function offers a way for applications to
not only avoid being forced to use select(), but it also offers a much more
high-performance API that will make a significant difference for applications
using large numbers of simultaneous connections.
\fIcurl_multi_socket_action(3)\fP is then used instead of
\fIcurl_multi_perform(3)\fP.
When using this API, you add easy handles to the multi handle just as with the
normal multi interface. Then you also set two callbacks with the
\fICURLMOPT_SOCKETFUNCTION(3)\fP and \fICURLMOPT_TIMERFUNCTION(3)\fP options
to \fIcurl_multi_setopt(3)\fP. They are two callback functions that libcurl
will call with information about what sockets to wait for, and for what
activity, and what the current timeout time is - if that expires libcurl
should be notified.
The multi_socket API is designed to inform your application about which
sockets libcurl is currently using and for what activities (read and/or write)
on those sockets your application is expected to wait for.
Your application must make sure to receive all sockets informed about in the
\fICURLMOPT_SOCKETFUNCTION(3)\fP callback and make sure it reacts on the given
activity on them. When a socket has the given activity, you call
\fIcurl_multi_socket_action(3)\fP specifying which socket and action there
are.
The \fICURLMOPT_TIMERFUNCTION(3)\fP callback is called to set a timeout. When
that timeout expires, your application should call the
\fIcurl_multi_socket_action(3)\fP function saying it was due to a timeout.
This API is typically used with an event-driven underlying functionality (like
libevent, libev, kqueue, epoll or similar) with which the application
"subscribes" on socket changes. This allows applications and libcurl to much
better scale upward and beyond thousands of simultaneous transfers without
losing performance.
When you have added your initial set of handles, you call
\fIcurl_multi_socket_action(3)\fP with CURL_SOCKET_TIMEOUT set in the
\fIsockfd\fP argument, and you will get callbacks call that sets you up and
you then continue to call \fIcurl_multi_socket_action(3)\fP accordingly when
you get activity on the sockets you have been asked to wait on, or if the
timeout timer expires.
You can poll \fIcurl_multi_info_read(3)\fP to see if any transfer has
completed, as it then has a message saying so.
.SH "BLOCKING"
A few areas in the code are still using blocking code, even when used from the
multi interface. While we certainly want and intend for these to get fixed in
the future, you should be aware of the following current restrictions:
.nf
- Name resolves unless the c-ares or threaded-resolver backends are used
- file:// transfers
- TELNET transfers
.fi
.SH "SEE ALSO"
.BR libcurl-errors "(3), " libcurl-easy "(3), " libcurl "(3) "
share/man/man3/CURLOPT_TIMEOUT.3 0000644 00000005745 14751150700 0011714 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_TIMEOUT 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_TIMEOUT \- maximum time the transfer is allowed to complete
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMEOUT, long timeout);
.fi
.SH DESCRIPTION
Pass a long as parameter containing \fItimeout\fP - the maximum time in
seconds that you allow the libcurl transfer operation to take. Normally, name
lookups can take a considerable time and limiting operations risk aborting
perfectly normal operations. This option may cause libcurl to use the SIGALRM
signal to timeout system calls.
In unix-like systems, this might cause signals to be used unless
\fICURLOPT_NOSIGNAL(3)\fP is set.
If both \fICURLOPT_TIMEOUT(3)\fP and \fICURLOPT_TIMEOUT_MS(3)\fP are set, the
value set last will be used.
Since this option puts a hard limit on how long time a request is allowed to
take, it has limited use in dynamic use cases with varying transfer times. That
is especially apparent when using the multi interface, which may queue the
transfer, and that time is included. You are advised to explore
\fICURLOPT_LOW_SPEED_LIMIT(3)\fP, \fICURLOPT_LOW_SPEED_TIME(3)\fP or using
\fICURLOPT_PROGRESSFUNCTION(3)\fP to implement your own timeout logic.
.SH DEFAULT
Default timeout is 0 (zero) which means it never times out during transfer.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* complete within 20 seconds */
curl_easy_setopt(curl, CURLOPT_TIMEOUT, 20L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK. Returns CURLE_BAD_FUNCTION_ARGUMENT if set to a negative
value or a value that when converted to milliseconds is too large.
.SH "SEE ALSO"
.BR CURLOPT_TIMEOUT_MS "(3), "
.BR CURLOPT_CONNECTTIMEOUT "(3), " CURLOPT_LOW_SPEED_LIMIT "(3), "
share/man/man3/CURLOPT_INTERFACE.3 0000644 00000005556 14751150700 0012066 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_INTERFACE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_INTERFACE \- source interface for outgoing traffic
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_INTERFACE, char *interface);
.fi
.SH DESCRIPTION
Pass a char * as parameter. This sets the \fIinterface\fP name to use as
outgoing network interface. The name can be an interface name, an IP address,
or a host name.
If the parameter starts with "if!" then it is treated as only as interface
name and no attempt will ever be named to do treat it as an IP address or to
do name resolution on it. If the parameter starts with \&"host!" it is
treated as either an IP address or a hostname. Hostnames are resolved
synchronously. Using the if! format is highly recommended when using the
multi interfaces to avoid allowing the code to block. If "if!" is specified
but the parameter does not match an existing interface, CURLE_INTERFACE_FAILED
is returned from the libcurl function used to perform the transfer.
libcurl does not support using network interface names for this option on
Windows.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL, use whatever the TCP stack finds suitable
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
curl_easy_setopt(curl, CURLOPT_INTERFACE, "eth0");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
The "if!" and "host!" syntax was added in 7.24.0.
.SH RETURN VALUE
Returns CURLE_OK on success or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_SOCKOPTFUNCTION "(3), " CURLOPT_TCP_NODELAY "(3), "
share/man/man3/curl_mime_filename.3 0000644 00000005347 14751150700 0013170 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_mime_filename 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_mime_filename - set a mime part's remote file name
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_mime_filename(curl_mimepart *part,
const char *filename);
.fi
.SH DESCRIPTION
\fIcurl_mime_filename(3)\fP sets a mime part's remote file name. When remote
file name is set, content data is processed as a file, whatever is the part's
content source. A part's remote file name is transmitted to the server in the
associated Content-Disposition generated header.
\fIpart\fP is the part's handle to assign the remote file name to.
\fIfilename\fP points to the null-terminated file name string; it may be set
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 multiple times is valid: only the value set by the last call is retained.
.SH EXAMPLE
.nf
curl_mime *mime;
curl_mimepart *part;
/* create a mime handle */
mime = curl_mime_init(easy);
/* add a part */
part = curl_mime_addpart(mime);
/* send image data from memory */
curl_mime_data(part, imagebuf, imagebuf_len);
/* set a file name to make it look like a file upload */
curl_mime_filename(part, "image.png");
/* 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),"
.BR curl_mime_data "(3)"
share/man/man3/CURLOPT_DNS_SHUFFLE_ADDRESSES.3 0000644 00000005272 14751150700 0013756 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_DNS_SHUFFLE_ADDRESSES 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_DNS_SHUFFLE_ADDRESSES \- shuffle IP addresses for hostname
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_SHUFFLE_ADDRESSES, long onoff);
.fi
.SH DESCRIPTION
When a name is resolved and more than one IP address is returned, shuffle the
order of all returned addresses so that they will be used in a random order.
This is similar to the ordering behavior of gethostbyname which is no longer
used on most platforms.
Addresses will not be reshuffled if a name resolution is completed using the
DNS cache. \fICURLOPT_DNS_CACHE_TIMEOUT(3)\fP can be used together with this
option to reduce DNS cache timeout or disable caching entirely if frequent
reshuffling is needed.
Since the addresses returned will be reordered randomly, their order will not
be in accordance with RFC 3484 or any other deterministic order that may be
generated by the system's name resolution implementation. This may have
performance impacts and may cause IPv4 to be used before IPv6 or vice versa.
.SH DEFAULT
0 (disabled)
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_DNS_SHUFFLE_ADDRESSES, 1L);
curl_easy_perform(curl);
/* always cleanup */
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.60.0
.SH RETURN VALUE
CURLE_OK or an error such as CURLE_UNKNOWN_OPTION.
.SH "SEE ALSO"
.BR CURLOPT_DNS_CACHE_TIMEOUT "(3), " CURLOPT_IPRESOLVE "(3), "
share/man/man3/CURLOPT_USERPWD.3 0000644 00000007077 14751150700 0011717 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_USERPWD 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_USERPWD \- user name and password to use in authentication
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_USERPWD, char *userpwd);
.fi
.SH DESCRIPTION
Pass a char * as parameter, pointing to a null-terminated login details string
for the connection. The format of which is: [user name]:[password].
When using Kerberos V5 authentication with a Windows based server, you should
specify the user name part with the domain name in order for the server to
successfully obtain a Kerberos Ticket. If you do not then the initial part of
the authentication handshake may fail.
When using NTLM, the user name can be specified simply as the user name
without the domain name should the server be part of a single domain and
forest.
To specify the domain name use either Down-Level Logon Name or UPN (User
Principal Name) formats. For example, EXAMPLE\\user and user@example.com
respectively.
Some HTTP servers (on Windows) support inclusion of the domain for Basic
authentication as well.
When using HTTP and \fICURLOPT_FOLLOWLOCATION(3)\fP, libcurl might perform
several requests to possibly different hosts. libcurl will only send this user
and password information to hosts using the initial host name (unless
\fICURLOPT_UNRESTRICTED_AUTH(3)\fP is set), so if libcurl follows locations to
other hosts it will not send the user and password to those. This is enforced
to prevent accidental information leakage.
Use \fICURLOPT_HTTPAUTH(3)\fP to specify the authentication method for HTTP
based connections or \fICURLOPT_LOGIN_OPTIONS(3)\fP to control IMAP, POP3 and
SMTP options.
The user and password strings are not URL decoded, so there's no way to send
in a user name containing a colon using this option. Use
\fICURLOPT_USERNAME(3)\fP for that, or include it in the URL.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
Most
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
curl_easy_setopt(curl, CURLOPT_USERPWD, "clark:kent");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK on success or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_USERNAME "(3), " CURLOPT_PASSWORD "(3), "
.BR CURLOPT_PROXYUSERPWD "(3), "
share/man/man3/CURLOPT_SSL_SESSIONID_CACHE.3 0000644 00000004465 14751150700 0013530 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SSL_SESSIONID_CACHE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSL_SESSIONID_CACHE \- use the SSL session-ID cache
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_SESSIONID_CACHE,
long enabled);
.SH DESCRIPTION
Pass a long set to 0 to disable libcurl's use of SSL session-ID caching. Set
this to 1 to enable it. By default all transfers are done using the cache
enabled. While nothing ever should get hurt by attempting to reuse SSL
session-IDs, there seem to be or have been broken SSL implementations in the
wild that may require you to disable this in order for you to succeed.
.SH DEFAULT
1
.SH PROTOCOLS
All TLS-based
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
/* switch off session-id use! */
curl_easy_setopt(curl, CURLOPT_SSL_SESSIONID_CACHE, 0L);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.16.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_DNS_CACHE_TIMEOUT "(3), " CURLOPT_SSLVERSION "(3), "
share/man/man3/CURLOPT_DNS_INTERFACE.3 0000644 00000004712 14751150700 0012563 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_DNS_INTERFACE 3 "September 05, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_DNS_INTERFACE \- interface to speak DNS over
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_INTERFACE, char *ifname);
.fi
.SH DESCRIPTION
Pass a char * as parameter. Set the name of the network interface that the DNS
resolver should bind to. This must be an interface name (not an address). Set
this option to NULL to use the default setting (do not bind to a specific
interface).
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
All protocols except file:// - protocols that resolve host names.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
curl_easy_setopt(curl, CURLOPT_DNS_INTERFACE, "eth0");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.33.0. This option also requires that libcurl was built with a
resolver backend that supports this operation. The c-ares backend is the only
such one.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not,
or CURLE_NOT_BUILT_IN if support was disabled at compile-time.
.SH "SEE ALSO"
.BR CURLOPT_DNS_SERVERS "(3), " CURLOPT_DNS_LOCAL_IP4 "(3), "
share/man/man3/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.3 0000644 00000005200 14751150700 0014516 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS \- head start for IPv6 for happy eyeballs
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS,
long timeout);
.fi
.SH DESCRIPTION
Happy eyeballs is an algorithm that attempts to connect to both IPv4 and IPv6
addresses for dual-stack hosts, preferring IPv6 first for \fItimeout\fP
milliseconds. If the IPv6 address cannot be connected to within that time then
a connection attempt is made to the IPv4 address in parallel. The first
connection to be established is the one that is used.
The range of suggested useful values for \fItimeout\fP is limited. Happy
Eyeballs RFC 6555 says "It is RECOMMENDED that connection attempts be paced
150-250 ms apart to balance human factors against network load." libcurl
currently defaults to 200 ms. Firefox and Chrome currently default to 300 ms.
.SH DEFAULT
CURL_HET_DEFAULT (currently defined as 200L)
.SH PROTOCOLS
All except FILE
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS, 300L);
curl_easy_perform(curl);
/* always cleanup */
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.59.0
.SH RETURN VALUE
Returns CURLE_OK
.SH SEE ALSO
.BR CURLOPT_CONNECTTIMEOUT_MS "(3), "
.BR CURLOPT_TIMEOUT "(3), " CURLOPT_LOW_SPEED_LIMIT "(3), "
share/man/man3/curl_share_cleanup.3 0000644 00000004171 14751150700 0013204 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_share_cleanup 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_share_cleanup - Clean up a shared object
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLSHcode curl_share_cleanup(CURLSH *share_handle);
.fi
.SH DESCRIPTION
This function deletes a shared object. The share handle cannot be used anymore
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 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
man page for the full list with descriptions. If an error occurs, then the
share object will not be deleted.
.SH "SEE ALSO"
.BR curl_share_init "(3), " curl_share_setopt "(3)"
share/man/man3/CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.3 0000644 00000004463 14751150700 0014600 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_CONTENT_LENGTH_DOWNLOAD_T 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_CONTENT_LENGTH_DOWNLOAD_T \- get content-length of download
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONTENT_LENGTH_DOWNLOAD_T,
curl_off_t *content_length);
.fi
.SH DESCRIPTION
Pass a pointer to a \fIcurl_off_t\fP to receive the content-length of the
download. This is the value read from the Content-Length: field. Stores -1 if
the size is not known.
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* Perform the request */
res = curl_easy_perform(curl);
if(!res) {
/* check the size */
curl_off_t cl;
res = curl_easy_getinfo(curl, CURLINFO_CONTENT_LENGTH_DOWNLOAD_T, &cl);
if(!res) {
printf("Download size: %" CURL_FORMAT_CURL_OFF_T "\\n", cl);
}
}
}
.fi
.SH AVAILABILITY
Added in 7.55.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
.BR CURLINFO_CONTENT_LENGTH_UPLOAD_T "(3), "
share/man/man3/CURLOPT_ALTSVC.3 0000644 00000005775 14751150700 0011565 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_ALTSVC 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_ALTSVC \- alt-svc cache file name
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ALTSVC, char *filename);
.fi
.SH DESCRIPTION
Pass in a pointer to a \fIfilename\fP to instruct libcurl to use that file as
the Alt-Svc cache to read existing cache contents from and possibly also write
it back to a after a transfer, unless \fBCURLALTSVC_READONLYFILE\fP is set in
\fICURLOPT_ALTSVC_CTRL(3)\fP.
Specify a blank file name ("") to make libcurl not load from a file at all.
.SH DEFAULT
NULL. The alt-svc cache is not read nor written to file.
.SH PROTOCOLS
HTTPS
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_ALTSVC_CTRL, CURLALTSVC_H1);
curl_easy_setopt(curl, CURLOPT_ALTSVC, "altsvc-cache.txt");
curl_easy_perform(curl);
}
.fi
.SH "FILE FORMAT"
A text based file with one line per alt-svc entry and each line consists of
nine space-separated fields.
An example line could look like
h2 www.example 8443 h3 second.example 443 "20190808 06:18:37" 1 0
The fields of that line are:
.IP h2
ALPN id for the source origin
.IP www.example
Host name for the source origin
.IP 8443
Port number for the source origin
.IP h3
ALPN id for the destination host
.IP second.example
Host name for the destination host
.IP 443
Port number for the destination host
.IP 2019*
Expiration date and time of this entry within double quotes. The date format
is "YYYYMMDD HH:MM:SS" and the time zone is GMT.
.IP 1
Boolean (1 or 0) if "persist" was set for this entry
.IP 0
Integer priority value (not currently used)
.SH AVAILABILITY
Added in 7.64.1
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_ALTSVC_CTRL "(3), " CURLOPT_CONNECT_TO "(3), " CURLOPT_RESOLVE "(3), "
.BR CURLOPT_COOKIEFILE "(3), "
share/man/man3/CURLMOPT_PUSHFUNCTION.3 0000644 00000012557 14751150700 0012627 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLMOPT_PUSHFUNCTION 3 "September 20, 2022" "libcurl 7.86.0" "curl_multi_setopt options"
.SH NAME
CURLMOPT_PUSHFUNCTION \- callback that approves or denies server pushes
.SH SYNOPSIS
.nf
#include <curl/curl.h>
char *curl_pushheader_bynum(struct curl_pushheaders *h, size_t num);
char *curl_pushheader_byname(struct curl_pushheaders *h, const char *name);
int curl_push_callback(CURL *parent,
CURL *easy,
size_t num_headers,
struct curl_pushheaders *headers,
void *userp);
CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PUSHFUNCTION,
curl_push_callback func);
.fi
.SH DESCRIPTION
This callback gets called when a new HTTP/2 stream is being pushed by the
server (using the PUSH_PROMISE frame). If no push callback is set, all offered
pushes will be denied automatically.
.SH CALLBACK DESCRIPTION
The callback gets its arguments like this:
\fIparent\fP is the handle of the stream on which this push arrives. The new
handle has been duplicated from the parent, meaning that it has gotten all its
options inherited. It is then up to the application to alter any options if
desired.
\fIeasy\fP is a newly created handle that represents this upcoming transfer.
\fInum_headers\fP is the number of name+value pairs that was received and can
be accessed
\fIheaders\fP is a handle used to access push headers using the accessor
functions described below. This only accesses and provides the PUSH_PROMISE
headers, the normal response headers will be provided in the header callback
as usual.
\fIuserp\fP is the pointer set with \fICURLMOPT_PUSHDATA(3)\fP
If the callback returns CURL_PUSH_OK, the 'easy' handle will be added to the
multi handle, the callback must not do that by itself.
The callback can access PUSH_PROMISE headers with two accessor
functions. These functions can only be used from within this callback and they
can only access the PUSH_PROMISE headers. The normal response headers will be
passed to the header callback for pushed streams just as for normal streams.
.IP curl_pushheader_bynum
Returns the header at index \fInum\fP (or NULL). The returned pointer points
to a "name:value" string that will be freed when this callback returns.
.IP curl_pushheader_byname
Returns the value for the given header name (or NULL). This is a shortcut so
that the application does not have to loop through all headers to find the one
it is interested in. The data pointed will be freed when this callback
returns. If more than one header field use the same name, this returns only
the first one.
.SH CALLBACK RETURN VALUE
.IP "CURL_PUSH_OK (0)"
The application has accepted the stream and it can now start receiving data,
the ownership of the CURL handle has been taken over by the application.
.IP "CURL_PUSH_DENY (1)"
The callback denies the stream and no data for this will reach the
application, the easy handle will be destroyed by libcurl.
.IP "CURL_PUSH_ERROROUT (2)"
Returning this will reject the pushed stream and return an error back on the
parent stream making it get closed with an error. (Added in 7.72.0)
.IP *
All other return codes are reserved for future use.
.SH DEFAULT
NULL, no callback
.SH PROTOCOLS
HTTP(S) (HTTP/2 only)
.SH EXAMPLE
.nf
/* only allow pushes for file names starting with "push-" */
int push_callback(CURL *parent,
CURL *easy,
size_t num_headers,
struct curl_pushheaders *headers,
void *userp)
{
char *headp;
int *transfers = (int *)userp;
FILE *out;
headp = curl_pushheader_byname(headers, ":path");
if(headp && !strncmp(headp, "/push-", 6)) {
fprintf(stderr, "The PATH is %s\\n", headp);
/* save the push here */
out = fopen("pushed-stream", "wb");
/* write to this file */
curl_easy_setopt(easy, CURLOPT_WRITEDATA, out);
(*transfers)++; /* one more */
return CURL_PUSH_OK;
}
return CURL_PUSH_DENY;
}
curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_callback);
curl_multi_setopt(multi, CURLMOPT_PUSHDATA, &counter);
.fi
.SH AVAILABILITY
Added in 7.44.0
.SH RETURN VALUE
Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLMOPT_PUSHDATA "(3), " CURLMOPT_PIPELINING "(3), " CURLOPT_PIPEWAIT "(3), "
.BR RFC 7540
share/man/man3/CURLOPT_RESOLVE.3 0000644 00000010116 14751150700 0011671 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_RESOLVE 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_RESOLVE \- provide custom host name to IP address resolves
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RESOLVE,
struct curl_slist *hosts);
.SH DESCRIPTION
Pass a pointer to a linked list of strings with host name resolve information
to use for requests with this handle. The linked list should be a fully valid
list of \fBstruct curl_slist\fP structs properly filled in. Use
\fIcurl_slist_append(3)\fP to create the list and \fIcurl_slist_free_all(3)\fP
to clean up an entire list.
Each resolve rule to add should be written using the format
.nf
[+]HOST:PORT:ADDRESS[,ADDRESS]
.fi
\&... where HOST is the name libcurl will try to resolve, PORT is the port
number of the service where libcurl wants to connect to the HOST and ADDRESS
is one or more numerical IP addresses. If you specify multiple IP addresses
they need to be separated by comma. If libcurl is built to support IPv6, each
of the ADDRESS entries can of course be either IPv4 or IPv6 style addressing.
This option effectively pre-populates the DNS cache with entries for the
host+port pair so redirects and everything that operations against the
HOST+PORT will instead use your provided ADDRESS.
The optional leading "+" specifies that the new entry should time-out. Entries
added without the leading plus character will never time-out whereas entries
added with "+HOST:..." will time-out just like ordinary DNS cache entries.
If the DNS cache already has an entry for the given host+port pair, the new
entry will override the former one.
An ADDRESS provided by this option will only be used if not restricted by the
setting of \fICURLOPT_IPRESOLVE(3)\fP to a different IP version.
To remove names from the DNS cache again, to stop providing these fake
resolves, include a string in the linked list that uses the format
.nf
-HOST:PORT
.fi
The entry to remove must be prefixed with a dash, and the host name and port
number must exactly match what was added previously.
.SH DEFAULT
NULL
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl;
struct curl_slist *host = NULL;
host = curl_slist_append(NULL, "example.com:443:127.0.0.1");
curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_RESOLVE, host);
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_perform(curl);
/* always cleanup */
curl_easy_cleanup(curl);
}
curl_slist_free_all(host);
.fi
.SH AVAILABILITY
Added in 7.21.3. Removal support added in 7.42.0.
Support for providing the ADDRESS within [brackets] was added in 7.57.0.
Support for providing multiple IP addresses per entry was added in 7.59.0.
Support for adding non-permanent entries by using the "+" prefix was added in
7.75.0.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_IPRESOLVE "(3), " CURLOPT_DNS_CACHE_TIMEOUT "(3), "
.BR CURLOPT_CONNECT_TO "(3), "
share/man/man3/CURLOPT_WRITEDATA.3 0000644 00000005271 14751150700 0012104 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_WRITEDATA 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_WRITEDATA \- pointer passed to the write callback
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WRITEDATA, void *pointer);
.fi
.SH DESCRIPTION
A data \fIpointer\fP to pass to the write callback. If you use the
\fICURLOPT_WRITEFUNCTION(3)\fP option, this is the pointer you will get in
that callback's fourth and last argument. If you do not use a write callback,
you must make \fIpointer\fP a 'FILE *' (cast to 'void *') as libcurl will pass
this to \fIfwrite(3)\fP when writing data.
The internal \fICURLOPT_WRITEFUNCTION(3)\fP will write the data to the FILE *
given with this option, or to stdout if this option has not been set.
If you are using libcurl as a win32 DLL, you \fBMUST\fP use a
\fICURLOPT_WRITEFUNCTION(3)\fP if you set this option or you will experience
crashes.
.SH DEFAULT
By default, this is a FILE * to stdout.
.SH PROTOCOLS
Used for all protocols.
.SH EXAMPLE
A common technique is to use the write callback to store the incoming data
into a dynamically growing allocated buffer, and then this
\fICURLOPT_WRITEDATA(3)\fP is used to point to a struct or the buffer to store
data in. Like in the getinmemory example:
https://curl.se/libcurl/c/getinmemory.html
.SH AVAILABILITY
Available in all libcurl versions. This option was formerly known as
\fICURLOPT_FILE\fP, the name \fICURLOPT_WRITEDATA(3)\fP was introduced in
7.9.7.
.SH RETURN VALUE
This will return CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_WRITEFUNCTION "(3), " CURLOPT_READDATA "(3), "
share/man/man3/CURLOPT_TIMEVALUE_LARGE.3 0000644 00000004650 14751150700 0013025 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_TIMEVALUE_LARGE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_TIMEVALUE_LARGE \- time value for conditional
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMEVALUE_LARGE,
curl_off_t val);
.fi
.SH DESCRIPTION
Pass a curl_off_t \fIval\fP as parameter. This should be the time counted as
seconds since 1 Jan 1970, and the time will be used in a condition as
specified with \fICURLOPT_TIMECONDITION(3)\fP.
The difference between this option and \fICURLOPT_TIMEVALUE(3)\fP is the type
of the argument. On systems where 'long' is only 32 bit wide, this option has
to be used to set dates beyond the year 2038.
.SH DEFAULT
0
.SH PROTOCOLS
HTTP, FTP, RTSP, and FILE
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* January 1, 2020 is 1577833200 */
curl_easy_setopt(curl, CURLOPT_TIMEVALUE_LARGE, (curl_off_t)1577833200);
/* If-Modified-Since the above time stamp */
curl_easy_setopt(curl, CURLOPT_TIMECONDITION, CURL_TIMECOND_IFMODSINCE);
/* Perform the request */
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.59.0.
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_TIMECONDITION "(3), "
.BR CURLOPT_TIMEVALUE_LARGE "(3), "
share/man/man3/CURLOPT_CUSTOMREQUEST.3 0000644 00000010544 14751150700 0012642 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_CUSTOMREQUEST 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_CUSTOMREQUEST \- custom request method
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CUSTOMREQUEST, char *request);
.fi
.SH DESCRIPTION
Pass a pointer to a null-terminated string as parameter.
When you change the request method by setting \fICURLOPT_CUSTOMREQUEST(3)\fP
to something, you do not actually change how libcurl behaves or acts in regards
to the particular request method, it will only change the actual string sent
in the request.
Restore to the internal default by setting this to NULL.
This option can be used to specify the request:
.IP HTTP
Instead of GET or HEAD when performing HTTP based requests. This is
particularly useful, for example, for performing an HTTP DELETE request.
For example:
When you tell libcurl to do a HEAD request, but then specify a GET though a
custom request libcurl will still act as if it sent a HEAD. To switch to a
proper HEAD use \fICURLOPT_NOBODY(3)\fP, to switch to a proper POST use
\fICURLOPT_POST(3)\fP or \fICURLOPT_POSTFIELDS(3)\fP and to switch to a proper
GET use \fICURLOPT_HTTPGET(3)\fP.
Many people have wrongly used this option to replace the entire request with
their own, including multiple headers and POST contents. While that might work
in many cases, it will cause libcurl to send invalid requests and it could
possibly confuse the remote server badly. Use \fICURLOPT_POST(3)\fP and
\fICURLOPT_POSTFIELDS(3)\fP to set POST data. Use \fICURLOPT_HTTPHEADER(3)\fP
to replace or extend the set of headers sent by libcurl. Use
\fICURLOPT_HTTP_VERSION(3)\fP to change HTTP version.
.IP FTP
Instead of LIST and NLST when performing FTP directory listings.
.IP IMAP
Instead of LIST when issuing IMAP based requests.
.IP POP3
Instead of LIST and RETR when issuing POP3 based requests.
For example:
When you tell libcurl to use a custom request it will behave like a LIST or
RETR command was sent where it expects data to be returned by the server. As
such \fICURLOPT_NOBODY(3)\fP should be used when specifying commands such as
\fBDELE\fP and \fBNOOP\fP for example.
.IP SMTP
Instead of a \fBHELP\fP or \fBVRFY\fP when issuing SMTP based requests.
For example:
Normally a multi line response is returned which can be used, in conjunction
with \fICURLOPT_MAIL_RCPT(3)\fP, to specify an EXPN request. If the
\fICURLOPT_NOBODY(3)\fP option is specified then the request can be used to
issue \fBNOOP\fP and \fBRSET\fP commands.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
HTTP, FTP, IMAP, POP3 and SMTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
/* DELETE the given path */
curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "DELETE");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
IMAP is supported since 7.30.0, POP3 since 7.26.0 and SMTP since 7.34.0.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_HTTPHEADER "(3), " CURLOPT_NOBODY "(3), "
.BR CURLOPT_REQUEST_TARGET "(3), "
share/man/man3/curl_easy_setopt.3 0000644 00000100117 14751150700 0012727 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH curl_easy_setopt 3 "October 12, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_easy_setopt \- set options for a curl easy handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLoption option, parameter);
.fi
.SH DESCRIPTION
\fIcurl_easy_setopt(3)\fP is used to tell libcurl how to behave. By setting
the appropriate options, the application can change libcurl's behavior. All
options are set with an \fIoption\fP followed by a \fIparameter\fP. That
parameter can be a \fBlong\fP, a \fBfunction pointer\fP, an \fBobject
pointer\fP or a \fBcurl_off_t\fP, depending on what the specific option
expects. Read this manual carefully as bad input values may cause libcurl to
behave badly! You can only set one option in each function call. A typical
application uses many \fIcurl_easy_setopt(3)\fP calls in the setup phase.
Options set with this function call are valid for all forthcoming transfers
performed using this \fIhandle\fP. The options are not in any way reset
between transfers, so if you want subsequent transfers with different options,
you must change them between the transfers. You can optionally reset all
options back to internal default with \fIcurl_easy_reset(3)\fP.
Strings passed to libcurl as 'char *' arguments, are copied by the library;
the string storage associated to the pointer argument may be discarded or
reused after \fIcurl_easy_setopt(3)\fP returns. The only exception to this
rule is really \fICURLOPT_POSTFIELDS(3)\fP, but the alternative that copies
the string \fICURLOPT_COPYPOSTFIELDS(3)\fP has some usage characteristics you
need to read up on. This function does not accept input strings longer than
\fBCURL_MAX_INPUT_LENGTH\fP (8 MB).
The order in which the options are set does not matter.
Before version 7.17.0, strings were not copied. Instead the user was forced
keep them available until libcurl no longer needed them.
The \fIhandle\fP is the return code from a \fIcurl_easy_init(3)\fP or
\fIcurl_easy_duphandle(3)\fP call.
.SH BEHAVIOR OPTIONS
.IP CURLOPT_VERBOSE
Display verbose information. See \fICURLOPT_VERBOSE(3)\fP
.IP CURLOPT_HEADER
Include the header in the body output. See \fICURLOPT_HEADER(3)\fP
.IP CURLOPT_NOPROGRESS
Shut off the progress meter. See \fICURLOPT_NOPROGRESS(3)\fP
.IP CURLOPT_NOSIGNAL
Do not install signal handlers. See \fICURLOPT_NOSIGNAL(3)\fP
.IP CURLOPT_WILDCARDMATCH
Transfer multiple files according to a file name pattern. See \fICURLOPT_WILDCARDMATCH(3)\fP
.SH CALLBACK OPTIONS
.IP CURLOPT_WRITEFUNCTION
Callback for writing data. See \fICURLOPT_WRITEFUNCTION(3)\fP
.IP CURLOPT_WRITEDATA
Data pointer to pass to the write callback. See \fICURLOPT_WRITEDATA(3)\fP
.IP CURLOPT_READFUNCTION
Callback for reading data. See \fICURLOPT_READFUNCTION(3)\fP
.IP CURLOPT_READDATA
Data pointer to pass to the read callback. See \fICURLOPT_READDATA(3)\fP
.IP CURLOPT_IOCTLFUNCTION
\fBDeprecated option\fP Callback for I/O operations.
See \fICURLOPT_IOCTLFUNCTION(3)\fP
.IP CURLOPT_IOCTLDATA
\fBDeprecated option\fP Data pointer to pass to the I/O callback.
See \fICURLOPT_IOCTLDATA(3)\fP
.IP CURLOPT_SEEKFUNCTION
Callback for seek operations. See \fICURLOPT_SEEKFUNCTION(3)\fP
.IP CURLOPT_SEEKDATA
Data pointer to pass to the seek callback. See \fICURLOPT_SEEKDATA(3)\fP
.IP CURLOPT_SOCKOPTFUNCTION
Callback for sockopt operations. See \fICURLOPT_SOCKOPTFUNCTION(3)\fP
.IP CURLOPT_SOCKOPTDATA
Data pointer to pass to the sockopt callback. See \fICURLOPT_SOCKOPTDATA(3)\fP
.IP CURLOPT_OPENSOCKETFUNCTION
Callback for socket creation. See \fICURLOPT_OPENSOCKETFUNCTION(3)\fP
.IP CURLOPT_OPENSOCKETDATA
Data pointer to pass to the open socket callback. See \fICURLOPT_OPENSOCKETDATA(3)\fP
.IP CURLOPT_CLOSESOCKETFUNCTION
Callback for closing socket. See \fICURLOPT_CLOSESOCKETFUNCTION(3)\fP
.IP CURLOPT_CLOSESOCKETDATA
Data pointer to pass to the close socket callback. See \fICURLOPT_CLOSESOCKETDATA(3)\fP
.IP CURLOPT_PROGRESSFUNCTION
\fBOBSOLETE\fP callback for progress meter.
See \fICURLOPT_PROGRESSFUNCTION(3)\fP
.IP CURLOPT_PROGRESSDATA
Data pointer to pass to the progress meter callback. See \fICURLOPT_PROGRESSDATA(3)\fP
.IP CURLOPT_XFERINFOFUNCTION
Callback for progress meter. See \fICURLOPT_XFERINFOFUNCTION(3)\fP
.IP CURLOPT_XFERINFODATA
Data pointer to pass to the progress meter callback. See \fICURLOPT_XFERINFODATA(3)\fP
.IP CURLOPT_HEADERFUNCTION
Callback for writing received headers. See \fICURLOPT_HEADERFUNCTION(3)\fP
.IP CURLOPT_HEADERDATA
Data pointer to pass to the header callback. See \fICURLOPT_HEADERDATA(3)\fP
.IP CURLOPT_DEBUGFUNCTION
Callback for debug information. See \fICURLOPT_DEBUGFUNCTION(3)\fP
.IP CURLOPT_DEBUGDATA
Data pointer to pass to the debug callback. See \fICURLOPT_DEBUGDATA(3)\fP
.IP CURLOPT_SSL_CTX_FUNCTION
Callback for SSL context logic. See \fICURLOPT_SSL_CTX_FUNCTION(3)\fP
.IP CURLOPT_SSL_CTX_DATA
Data pointer to pass to the SSL context callback. See \fICURLOPT_SSL_CTX_DATA(3)\fP
.IP CURLOPT_CONV_TO_NETWORK_FUNCTION
Callback for code base conversion. See \fICURLOPT_CONV_TO_NETWORK_FUNCTION(3)\fP
.IP CURLOPT_CONV_FROM_NETWORK_FUNCTION
Callback for code base conversion. See \fICURLOPT_CONV_FROM_NETWORK_FUNCTION(3)\fP
.IP CURLOPT_CONV_FROM_UTF8_FUNCTION
Callback for code base conversion. See \fICURLOPT_CONV_FROM_UTF8_FUNCTION(3)\fP
.IP CURLOPT_INTERLEAVEFUNCTION
Callback for RTSP interleaved data. See \fICURLOPT_INTERLEAVEFUNCTION(3)\fP
.IP CURLOPT_INTERLEAVEDATA
Data pointer to pass to the RTSP interleave callback. See \fICURLOPT_INTERLEAVEDATA(3)\fP
.IP CURLOPT_CHUNK_BGN_FUNCTION
Callback for wildcard download start of chunk. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP
.IP CURLOPT_CHUNK_END_FUNCTION
Callback for wildcard download end of chunk. See \fICURLOPT_CHUNK_END_FUNCTION(3)\fP
.IP CURLOPT_CHUNK_DATA
Data pointer to pass to the chunk callbacks. See \fICURLOPT_CHUNK_DATA(3)\fP
.IP CURLOPT_FNMATCH_FUNCTION
Callback for wildcard matching. See \fICURLOPT_FNMATCH_FUNCTION(3)\fP
.IP CURLOPT_FNMATCH_DATA
Data pointer to pass to the wildcard matching callback. See \fICURLOPT_FNMATCH_DATA(3)\fP
.IP CURLOPT_SUPPRESS_CONNECT_HEADERS
Suppress proxy CONNECT response headers from user callbacks. See \fICURLOPT_SUPPRESS_CONNECT_HEADERS(3)\fP
.IP CURLOPT_RESOLVER_START_FUNCTION
Callback to be called before a new resolve request is started. See \fICURLOPT_RESOLVER_START_FUNCTION(3)\fP
.IP CURLOPT_RESOLVER_START_DATA
Data pointer to pass to resolver start callback. See \fICURLOPT_RESOLVER_START_DATA(3)\fP
.IP CURLOPT_PREREQFUNCTION
Callback to be called after a connection is established but before a request is made on that connection. See \fICURLOPT_PREREQFUNCTION(3)\fP
.IP CURLOPT_PREREQDATA
Data pointer to pass to the CURLOPT_PREREQFUNCTION callback. See \fICURLOPT_PREREQDATA(3)\fP
.SH ERROR OPTIONS
.IP CURLOPT_ERRORBUFFER
Error message buffer. See \fICURLOPT_ERRORBUFFER(3)\fP
.IP CURLOPT_STDERR
stderr replacement stream. See \fICURLOPT_STDERR(3)\fP
.IP CURLOPT_FAILONERROR
Fail on HTTP 4xx errors. \fICURLOPT_FAILONERROR(3)\fP
.IP CURLOPT_KEEP_SENDING_ON_ERROR
Keep sending on HTTP >= 300 errors. \fICURLOPT_KEEP_SENDING_ON_ERROR(3)\fP
.SH NETWORK OPTIONS
.IP CURLOPT_URL
URL to work on. See \fICURLOPT_URL(3)\fP
.IP CURLOPT_PATH_AS_IS
Disable squashing /../ and /./ sequences in the path. See \fICURLOPT_PATH_AS_IS(3)\fP
.IP CURLOPT_PROTOCOLS
\fBDeprecated option\fP Allowed protocols. See \fICURLOPT_PROTOCOLS(3)\fP
.IP CURLOPT_PROTOCOLS_STR
Allowed protocols. See \fICURLOPT_PROTOCOLS_STR(3)\fP
.IP CURLOPT_REDIR_PROTOCOLS
\fBDeprecated option\fP Protocols to allow redirects to. See
\fICURLOPT_REDIR_PROTOCOLS(3)\fP
.IP CURLOPT_REDIR_PROTOCOLS_STR
Protocols to allow redirects to. See \fICURLOPT_REDIR_PROTOCOLS_STR(3)\fP
.IP CURLOPT_DEFAULT_PROTOCOL
Default protocol. See \fICURLOPT_DEFAULT_PROTOCOL(3)\fP
.IP CURLOPT_PROXY
Proxy to use. See \fICURLOPT_PROXY(3)\fP
.IP CURLOPT_PRE_PROXY
Socks proxy to use. See \fICURLOPT_PRE_PROXY(3)\fP
.IP CURLOPT_PROXYPORT
Proxy port to use. See \fICURLOPT_PROXYPORT(3)\fP
.IP CURLOPT_PROXYTYPE
Proxy type. See \fICURLOPT_PROXYTYPE(3)\fP
.IP CURLOPT_NOPROXY
Filter out hosts from proxy use. \fICURLOPT_NOPROXY(3)\fP
.IP CURLOPT_HTTPPROXYTUNNEL
Tunnel through the HTTP proxy. \fICURLOPT_HTTPPROXYTUNNEL(3)\fP
.IP CURLOPT_CONNECT_TO
Connect to a specific host and port. See \fICURLOPT_CONNECT_TO(3)\fP
.IP CURLOPT_SOCKS5_AUTH
Socks5 authentication methods. See \fICURLOPT_SOCKS5_AUTH(3)\fP
.IP CURLOPT_SOCKS5_GSSAPI_SERVICE
\fBDeprecated option\fP Socks5 GSSAPI service name.
See \fICURLOPT_SOCKS5_GSSAPI_SERVICE(3)\fP
.IP CURLOPT_SOCKS5_GSSAPI_NEC
Socks5 GSSAPI NEC mode. See \fICURLOPT_SOCKS5_GSSAPI_NEC(3)\fP
.IP CURLOPT_PROXY_SERVICE_NAME
Proxy authentication service name. \fICURLOPT_PROXY_SERVICE_NAME(3)\fP
.IP CURLOPT_HAPROXYPROTOCOL
Send an HAProxy PROXY protocol v1 header. See \fICURLOPT_HAPROXYPROTOCOL(3)\fP
.IP CURLOPT_SERVICE_NAME
Authentication service name. \fICURLOPT_SERVICE_NAME(3)\fP
.IP CURLOPT_INTERFACE
Bind connection locally to this. See \fICURLOPT_INTERFACE(3)\fP
.IP CURLOPT_LOCALPORT
Bind connection locally to this port. See \fICURLOPT_LOCALPORT(3)\fP
.IP CURLOPT_LOCALPORTRANGE
Bind connection locally to port range. See \fICURLOPT_LOCALPORTRANGE(3)\fP
.IP CURLOPT_DNS_CACHE_TIMEOUT
Timeout for DNS cache. See \fICURLOPT_DNS_CACHE_TIMEOUT(3)\fP
.IP CURLOPT_DNS_USE_GLOBAL_CACHE
\fBOBSOLETE\fP Enable global DNS cache.
See \fICURLOPT_DNS_USE_GLOBAL_CACHE(3)\fP
.IP CURLOPT_DOH_URL
Use this DoH server for name resolves. See \fICURLOPT_DOH_URL(3)\fP
.IP CURLOPT_BUFFERSIZE
Ask for alternate buffer size. See \fICURLOPT_BUFFERSIZE(3)\fP
.IP CURLOPT_PORT
Port number to connect to. See \fICURLOPT_PORT(3)\fP
.IP CURLOPT_TCP_FASTOPEN
Enable TCP Fast Open. See \fICURLOPT_TCP_FASTOPEN(3)\fP
.IP CURLOPT_TCP_NODELAY
Disable the Nagle algorithm. See \fICURLOPT_TCP_NODELAY(3)\fP
.IP CURLOPT_ADDRESS_SCOPE
IPv6 scope for local addresses. See \fICURLOPT_ADDRESS_SCOPE(3)\fP
.IP CURLOPT_TCP_KEEPALIVE
Enable TCP keep-alive. See \fICURLOPT_TCP_KEEPALIVE(3)\fP
.IP CURLOPT_TCP_KEEPIDLE
Idle time before sending keep-alive. See \fICURLOPT_TCP_KEEPIDLE(3)\fP
.IP CURLOPT_TCP_KEEPINTVL
Interval between keep-alive probes. See \fICURLOPT_TCP_KEEPINTVL(3)\fP
.IP CURLOPT_UNIX_SOCKET_PATH
Path to a Unix domain socket. See \fICURLOPT_UNIX_SOCKET_PATH(3)\fP
.IP CURLOPT_ABSTRACT_UNIX_SOCKET
Path to an abstract Unix domain socket. See \fICURLOPT_ABSTRACT_UNIX_SOCKET(3)\fP
.SH NAMES and PASSWORDS OPTIONS (Authentication)
.IP CURLOPT_NETRC
Enable .netrc parsing. See \fICURLOPT_NETRC(3)\fP
.IP CURLOPT_NETRC_FILE
\&.netrc file name. See \fICURLOPT_NETRC_FILE(3)\fP
.IP CURLOPT_USERPWD
User name and password. See \fICURLOPT_USERPWD(3)\fP
.IP CURLOPT_PROXYUSERPWD
Proxy user name and password. See \fICURLOPT_PROXYUSERPWD(3)\fP
.IP CURLOPT_USERNAME
User name. See \fICURLOPT_USERNAME(3)\fP
.IP CURLOPT_PASSWORD
Password. See \fICURLOPT_PASSWORD(3)\fP
.IP CURLOPT_LOGIN_OPTIONS
Login options. See \fICURLOPT_LOGIN_OPTIONS(3)\fP
.IP CURLOPT_PROXYUSERNAME
Proxy user name. See \fICURLOPT_PROXYUSERNAME(3)\fP
.IP CURLOPT_PROXYPASSWORD
Proxy password. See \fICURLOPT_PROXYPASSWORD(3)\fP
.IP CURLOPT_HTTPAUTH
HTTP server authentication methods. See \fICURLOPT_HTTPAUTH(3)\fP
.IP CURLOPT_TLSAUTH_USERNAME
TLS authentication user name. See \fICURLOPT_TLSAUTH_USERNAME(3)\fP
.IP CURLOPT_PROXY_TLSAUTH_USERNAME
Proxy TLS authentication user name. See \fICURLOPT_PROXY_TLSAUTH_USERNAME(3)\fP
.IP CURLOPT_TLSAUTH_PASSWORD
TLS authentication password. See \fICURLOPT_TLSAUTH_PASSWORD(3)\fP
.IP CURLOPT_PROXY_TLSAUTH_PASSWORD
Proxy TLS authentication password. See \fICURLOPT_PROXY_TLSAUTH_PASSWORD(3)\fP
.IP CURLOPT_TLSAUTH_TYPE
TLS authentication methods. See \fICURLOPT_TLSAUTH_TYPE(3)\fP
.IP CURLOPT_PROXY_TLSAUTH_TYPE
Proxy TLS authentication methods. See \fICURLOPT_PROXY_TLSAUTH_TYPE(3)\fP
.IP CURLOPT_PROXYAUTH
HTTP proxy authentication methods. See \fICURLOPT_PROXYAUTH(3)\fP
.IP CURLOPT_SASL_AUTHZID
SASL authorization identity (identity to act as). See \fICURLOPT_SASL_AUTHZID(3)\fP
.IP CURLOPT_SASL_IR
Enable SASL initial response. See \fICURLOPT_SASL_IR(3)\fP
.IP CURLOPT_XOAUTH2_BEARER
OAuth2 bearer token. See \fICURLOPT_XOAUTH2_BEARER(3)\fP
.IP CURLOPT_DISALLOW_USERNAME_IN_URL
Do not allow username in URL. See \fICURLOPT_DISALLOW_USERNAME_IN_URL(3)\fP
.SH HTTP OPTIONS
.IP CURLOPT_AUTOREFERER
Automatically set Referer: header. See \fICURLOPT_AUTOREFERER(3)\fP
.IP CURLOPT_ACCEPT_ENCODING
Accept-Encoding and automatic decompressing data. See \fICURLOPT_ACCEPT_ENCODING(3)\fP
.IP CURLOPT_TRANSFER_ENCODING
Request Transfer-Encoding. See \fICURLOPT_TRANSFER_ENCODING(3)\fP
.IP CURLOPT_FOLLOWLOCATION
Follow HTTP redirects. See \fICURLOPT_FOLLOWLOCATION(3)\fP
.IP CURLOPT_UNRESTRICTED_AUTH
Do not restrict authentication to original host. \fICURLOPT_UNRESTRICTED_AUTH(3)\fP
.IP CURLOPT_MAXREDIRS
Maximum number of redirects to follow. See \fICURLOPT_MAXREDIRS(3)\fP
.IP CURLOPT_POSTREDIR
How to act on redirects after POST. See \fICURLOPT_POSTREDIR(3)\fP
.IP CURLOPT_PUT
\fBDeprecated option\fP Issue an HTTP PUT request. See \fICURLOPT_PUT(3)\fP
.IP CURLOPT_POST
Issue an HTTP POST request. See \fICURLOPT_POST(3)\fP
.IP CURLOPT_POSTFIELDS
Send a POST with this data. See \fICURLOPT_POSTFIELDS(3)\fP
.IP CURLOPT_POSTFIELDSIZE
The POST data is this big. See \fICURLOPT_POSTFIELDSIZE(3)\fP
.IP CURLOPT_POSTFIELDSIZE_LARGE
The POST data is this big. See \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP
.IP CURLOPT_COPYPOSTFIELDS
Send a POST with this data - and copy it. See \fICURLOPT_COPYPOSTFIELDS(3)\fP
.IP CURLOPT_HTTPPOST
\fBDeprecated option\fP Multipart formpost HTTP POST.
See \fICURLOPT_HTTPPOST(3)\fP
.IP CURLOPT_REFERER
Referer: header. See \fICURLOPT_REFERER(3)\fP
.IP CURLOPT_USERAGENT
User-Agent: header. See \fICURLOPT_USERAGENT(3)\fP
.IP CURLOPT_HTTPHEADER
Custom HTTP headers. See \fICURLOPT_HTTPHEADER(3)\fP
.IP CURLOPT_HEADEROPT
Control custom headers. See \fICURLOPT_HEADEROPT(3)\fP
.IP CURLOPT_PROXYHEADER
Custom HTTP headers sent to proxy. See \fICURLOPT_PROXYHEADER(3)\fP
.IP CURLOPT_HTTP200ALIASES
Alternative versions of 200 OK. See \fICURLOPT_HTTP200ALIASES(3)\fP
.IP CURLOPT_COOKIE
Cookie(s) to send. See \fICURLOPT_COOKIE(3)\fP
.IP CURLOPT_COOKIEFILE
File to read cookies from. See \fICURLOPT_COOKIEFILE(3)\fP
.IP CURLOPT_COOKIEJAR
File to write cookies to. See \fICURLOPT_COOKIEJAR(3)\fP
.IP CURLOPT_COOKIESESSION
Start a new cookie session. See \fICURLOPT_COOKIESESSION(3)\fP
.IP CURLOPT_COOKIELIST
Add or control cookies. See \fICURLOPT_COOKIELIST(3)\fP
.IP CURLOPT_ALTSVC
Specify the Alt-Svc: cache file name. See \fICURLOPT_ALTSVC(3)\fP
.IP CURLOPT_ALTSVC_CTRL
Enable and configure Alt-Svc: treatment. See \fICURLOPT_ALTSVC_CTRL(3)\fP
.IP CURLOPT_HSTS
Set HSTS cache file. See \fICURLOPT_HSTS(3)\fP
.IP CURLOPT_HSTS_CTRL
Enable HSTS. See \fICURLOPT_HSTS_CTRL(3)\fP
.IP CURLOPT_HSTSREADFUNCTION
Set HSTS read callback. See \fICURLOPT_HSTSREADFUNCTION(3)\fP
.IP CURLOPT_HSTSREADDATA
Pass pointer to the HSTS read callback. See \fICURLOPT_HSTSREADDATA(3)\fP
.IP CURLOPT_HSTSWRITEFUNCTION
Set HSTS write callback. See \fICURLOPT_HSTSWRITEFUNCTION(3)\fP
.IP CURLOPT_HSTSWRITEDATA
Pass pointer to the HSTS write callback. See \fICURLOPT_HSTSWRITEDATA(3)\fP
.IP CURLOPT_HTTPGET
Do an HTTP GET request. See \fICURLOPT_HTTPGET(3)\fP
.IP CURLOPT_REQUEST_TARGET
Set the request target. \fICURLOPT_REQUEST_TARGET(3)\fP
.IP CURLOPT_HTTP_VERSION
HTTP version to use. \fICURLOPT_HTTP_VERSION(3)\fP
.IP CURLOPT_HTTP09_ALLOWED
Allow HTTP/0.9 responses. \fICURLOPT_HTTP09_ALLOWED(3)\fP
.IP CURLOPT_IGNORE_CONTENT_LENGTH
Ignore Content-Length. See \fICURLOPT_IGNORE_CONTENT_LENGTH(3)\fP
.IP CURLOPT_HTTP_CONTENT_DECODING
Disable Content decoding. See \fICURLOPT_HTTP_CONTENT_DECODING(3)\fP
.IP CURLOPT_HTTP_TRANSFER_DECODING
Disable Transfer decoding. See \fICURLOPT_HTTP_TRANSFER_DECODING(3)\fP
.IP CURLOPT_EXPECT_100_TIMEOUT_MS
100-continue timeout. See \fICURLOPT_EXPECT_100_TIMEOUT_MS(3)\fP
.IP CURLOPT_TRAILERFUNCTION
Set callback for sending trailing headers. See
\fICURLOPT_TRAILERFUNCTION(3)\fP
.IP CURLOPT_TRAILERDATA
Custom pointer passed to the trailing headers callback. See
\fICURLOPT_TRAILERDATA(3)\fP
.IP CURLOPT_PIPEWAIT
Wait on connection to pipeline on it. See \fICURLOPT_PIPEWAIT(3)\fP
.IP CURLOPT_STREAM_DEPENDS
This HTTP/2 stream depends on another. See \fICURLOPT_STREAM_DEPENDS(3)\fP
.IP CURLOPT_STREAM_DEPENDS_E
This HTTP/2 stream depends on another exclusively. See
\fICURLOPT_STREAM_DEPENDS_E(3)\fP
.IP CURLOPT_STREAM_WEIGHT
Set this HTTP/2 stream's weight. See \fICURLOPT_STREAM_WEIGHT(3)\fP
.SH SMTP OPTIONS
.IP CURLOPT_MAIL_FROM
Address of the sender. See \fICURLOPT_MAIL_FROM(3)\fP
.IP CURLOPT_MAIL_RCPT
Address of the recipients. See \fICURLOPT_MAIL_RCPT(3)\fP
.IP CURLOPT_MAIL_AUTH
Authentication address. See \fICURLOPT_MAIL_AUTH(3)\fP
.IP CURLOPT_MAIL_RCPT_ALLLOWFAILS
Allow RCPT TO command to fail for some recipients. See \fICURLOPT_MAIL_RCPT_ALLLOWFAILS(3)\fP
.SH TFTP OPTIONS
.IP CURLOPT_TFTP_BLKSIZE
TFTP block size. See \fICURLOPT_TFTP_BLKSIZE(3)\fP
.IP CURLOPT_TFTP_NO_OPTIONS
Do not send TFTP options requests. See \fICURLOPT_TFTP_NO_OPTIONS(3)\fP
.SH FTP OPTIONS
.IP CURLOPT_FTPPORT
Use active FTP. See \fICURLOPT_FTPPORT(3)\fP
.IP CURLOPT_QUOTE
Commands to run before transfer. See \fICURLOPT_QUOTE(3)\fP
.IP CURLOPT_POSTQUOTE
Commands to run after transfer. See \fICURLOPT_POSTQUOTE(3)\fP
.IP CURLOPT_PREQUOTE
Commands to run just before transfer. See \fICURLOPT_PREQUOTE(3)\fP
.IP CURLOPT_APPEND
Append to remote file. See \fICURLOPT_APPEND(3)\fP
.IP CURLOPT_FTP_USE_EPRT
Use EPRT. See \fICURLOPT_FTP_USE_EPRT(3)\fP
.IP CURLOPT_FTP_USE_EPSV
Use EPSV. See \fICURLOPT_FTP_USE_EPSV(3)\fP
.IP CURLOPT_FTP_USE_PRET
Use PRET. See \fICURLOPT_FTP_USE_PRET(3)\fP
.IP CURLOPT_FTP_CREATE_MISSING_DIRS
Create missing directories on the remote server. See \fICURLOPT_FTP_CREATE_MISSING_DIRS(3)\fP
.IP CURLOPT_SERVER_RESPONSE_TIMEOUT
Timeout for server responses. See \fICURLOPT_SERVER_RESPONSE_TIMEOUT(3)\fP
.IP CURLOPT_FTP_ALTERNATIVE_TO_USER
Alternative to USER. See \fICURLOPT_FTP_ALTERNATIVE_TO_USER(3)\fP
.IP CURLOPT_FTP_SKIP_PASV_IP
Ignore the IP address in the PASV response. See \fICURLOPT_FTP_SKIP_PASV_IP(3)\fP
.IP CURLOPT_FTPSSLAUTH
Control how to do TLS. See \fICURLOPT_FTPSSLAUTH(3)\fP
.IP CURLOPT_FTP_SSL_CCC
Back to non-TLS again after authentication. See \fICURLOPT_FTP_SSL_CCC(3)\fP
.IP CURLOPT_FTP_ACCOUNT
Send ACCT command. See \fICURLOPT_FTP_ACCOUNT(3)\fP
.IP CURLOPT_FTP_FILEMETHOD
Specify how to reach files. See \fICURLOPT_FTP_FILEMETHOD(3)\fP
.SH RTSP OPTIONS
.IP CURLOPT_RTSP_REQUEST
RTSP request. See \fICURLOPT_RTSP_REQUEST(3)\fP
.IP CURLOPT_RTSP_SESSION_ID
RTSP session-id. See \fICURLOPT_RTSP_SESSION_ID(3)\fP
.IP CURLOPT_RTSP_STREAM_URI
RTSP stream URI. See \fICURLOPT_RTSP_STREAM_URI(3)\fP
.IP CURLOPT_RTSP_TRANSPORT
RTSP Transport: header. See \fICURLOPT_RTSP_TRANSPORT(3)\fP
.IP CURLOPT_RTSP_CLIENT_CSEQ
Client CSEQ number. See \fICURLOPT_RTSP_CLIENT_CSEQ(3)\fP
.IP CURLOPT_RTSP_SERVER_CSEQ
CSEQ number for RTSP Server->Client request. See \fICURLOPT_RTSP_SERVER_CSEQ(3)\fP
.IP CURLOPT_AWS_SIGV4
AWS HTTP V4 Signature. See \fICURLOPT_AWS_SIGV4(3)\fP
.SH PROTOCOL OPTIONS
.IP CURLOPT_TRANSFERTEXT
Use text transfer. See \fICURLOPT_TRANSFERTEXT(3)\fP
.IP CURLOPT_PROXY_TRANSFER_MODE
Add transfer mode to URL over proxy. See \fICURLOPT_PROXY_TRANSFER_MODE(3)\fP
.IP CURLOPT_CRLF
Convert newlines. See \fICURLOPT_CRLF(3)\fP
.IP CURLOPT_RANGE
Range requests. See \fICURLOPT_RANGE(3)\fP
.IP CURLOPT_RESUME_FROM
Resume a transfer. See \fICURLOPT_RESUME_FROM(3)\fP
.IP CURLOPT_RESUME_FROM_LARGE
Resume a transfer. See \fICURLOPT_RESUME_FROM_LARGE(3)\fP
.IP CURLOPT_CURLU
Set URL to work on with a URL handle. See \fICURLOPT_CURLU(3)\fP
.IP CURLOPT_CUSTOMREQUEST
Custom request/method. See \fICURLOPT_CUSTOMREQUEST(3)\fP
.IP CURLOPT_FILETIME
Request file modification date and time. See \fICURLOPT_FILETIME(3)\fP
.IP CURLOPT_DIRLISTONLY
List only. See \fICURLOPT_DIRLISTONLY(3)\fP
.IP CURLOPT_NOBODY
Do not get the body contents. See \fICURLOPT_NOBODY(3)\fP
.IP CURLOPT_INFILESIZE
Size of file to send. \fICURLOPT_INFILESIZE(3)\fP
.IP CURLOPT_INFILESIZE_LARGE
Size of file to send. \fICURLOPT_INFILESIZE_LARGE(3)\fP
.IP CURLOPT_UPLOAD
Upload data. See \fICURLOPT_UPLOAD(3)\fP
.IP CURLOPT_UPLOAD_BUFFERSIZE
Set upload buffer size. See \fICURLOPT_UPLOAD_BUFFERSIZE(3)\fP
.IP CURLOPT_MIMEPOST
Post/send MIME data. See \fICURLOPT_MIMEPOST(3)\fP
.IP CURLOPT_MIME_OPTIONS
Set MIME option flags. See \fICURLOPT_MIME_OPTIONS(3)\fP
.IP CURLOPT_MAXFILESIZE
Maximum file size to get. See \fICURLOPT_MAXFILESIZE(3)\fP
.IP CURLOPT_MAXFILESIZE_LARGE
Maximum file size to get. See \fICURLOPT_MAXFILESIZE_LARGE(3)\fP
.IP CURLOPT_TIMECONDITION
Make a time conditional request. See \fICURLOPT_TIMECONDITION(3)\fP
.IP CURLOPT_TIMEVALUE
Time value for the time conditional request. See \fICURLOPT_TIMEVALUE(3)\fP
.IP CURLOPT_TIMEVALUE_LARGE
Time value for the time conditional request. See \fICURLOPT_TIMEVALUE_LARGE(3)\fP
.SH CONNECTION OPTIONS
.IP CURLOPT_TIMEOUT
Timeout for the entire request. See \fICURLOPT_TIMEOUT(3)\fP
.IP CURLOPT_TIMEOUT_MS
Millisecond timeout for the entire request. See \fICURLOPT_TIMEOUT_MS(3)\fP
.IP CURLOPT_LOW_SPEED_LIMIT
Low speed limit to abort transfer. See \fICURLOPT_LOW_SPEED_LIMIT(3)\fP
.IP CURLOPT_LOW_SPEED_TIME
Time to be below the speed to trigger low speed abort. See \fICURLOPT_LOW_SPEED_TIME(3)\fP
.IP CURLOPT_MAX_SEND_SPEED_LARGE
Cap the upload speed to this. See \fICURLOPT_MAX_SEND_SPEED_LARGE(3)\fP
.IP CURLOPT_MAX_RECV_SPEED_LARGE
Cap the download speed to this. See \fICURLOPT_MAX_RECV_SPEED_LARGE(3)\fP
.IP CURLOPT_MAXCONNECTS
Maximum number of connections in the connection pool. See \fICURLOPT_MAXCONNECTS(3)\fP
.IP CURLOPT_FRESH_CONNECT
Use a new connection. \fICURLOPT_FRESH_CONNECT(3)\fP
.IP CURLOPT_FORBID_REUSE
Prevent subsequent connections from re-using this. See \fICURLOPT_FORBID_REUSE(3)\fP
.IP CURLOPT_MAXAGE_CONN
Limit the age (idle time) of connections for reuse. See \fICURLOPT_MAXAGE_CONN(3)\fP
.IP CURLOPT_MAXLIFETIME_CONN
Limit the age (since creation) of connections for reuse. See \fICURLOPT_MAXLIFETIME_CONN(3)\fP
.IP CURLOPT_CONNECTTIMEOUT
Timeout for the connection phase. See \fICURLOPT_CONNECTTIMEOUT(3)\fP
.IP CURLOPT_CONNECTTIMEOUT_MS
Millisecond timeout for the connection phase. See \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP
.IP CURLOPT_IPRESOLVE
IP version to use. See \fICURLOPT_IPRESOLVE(3)\fP
.IP CURLOPT_CONNECT_ONLY
Only connect, nothing else. See \fICURLOPT_CONNECT_ONLY(3)\fP
.IP CURLOPT_USE_SSL
Use TLS/SSL. See \fICURLOPT_USE_SSL(3)\fP
.IP CURLOPT_RESOLVE
Provide fixed/fake name resolves. See \fICURLOPT_RESOLVE(3)\fP
.IP CURLOPT_DNS_INTERFACE
Bind name resolves to this interface. See \fICURLOPT_DNS_INTERFACE(3)\fP
.IP CURLOPT_DNS_LOCAL_IP4
Bind name resolves to this IP4 address. See \fICURLOPT_DNS_LOCAL_IP4(3)\fP
.IP CURLOPT_DNS_LOCAL_IP6
Bind name resolves to this IP6 address. See \fICURLOPT_DNS_LOCAL_IP6(3)\fP
.IP CURLOPT_DNS_SERVERS
Preferred DNS servers. See \fICURLOPT_DNS_SERVERS(3)\fP
.IP CURLOPT_DNS_SHUFFLE_ADDRESSES
Shuffle addresses before use. See \fICURLOPT_DNS_SHUFFLE_ADDRESSES(3)\fP
.IP CURLOPT_ACCEPTTIMEOUT_MS
Timeout for waiting for the server's connect back to be accepted. See \fICURLOPT_ACCEPTTIMEOUT_MS(3)\fP
.IP CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS
Timeout for happy eyeballs. See \fICURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS(3)\fP
.IP CURLOPT_UPKEEP_INTERVAL_MS
Sets the interval at which connection upkeep are performed. See
\fICURLOPT_UPKEEP_INTERVAL_MS(3)\fP
.SH SSL and SECURITY OPTIONS
.IP CURLOPT_SSLCERT
Client cert. See \fICURLOPT_SSLCERT(3)\fP
.IP CURLOPT_SSLCERT_BLOB
Client cert memory buffer. See \fICURLOPT_SSLCERT_BLOB(3)\fP
.IP CURLOPT_PROXY_SSLCERT
Proxy client cert. See \fICURLOPT_PROXY_SSLCERT(3)\fP
.IP CURLOPT_PROXY_SSLCERT_BLOB
Proxy client cert memory buffer. See \fICURLOPT_PROXY_SSLCERT_BLOB(3)\fP
.IP CURLOPT_SSLCERTTYPE
Client cert type. See \fICURLOPT_SSLCERTTYPE(3)\fP
.IP CURLOPT_PROXY_SSLCERTTYPE
Proxy client cert type. See \fICURLOPT_PROXY_SSLCERTTYPE(3)\fP
.IP CURLOPT_SSLKEY
Client key. See \fICURLOPT_SSLKEY(3)\fP
.IP CURLOPT_SSLKEY_BLOB
Client key memory buffer. See \fICURLOPT_SSLKEY_BLOB(3)\fP
.IP CURLOPT_PROXY_SSLKEY
Proxy client key. See \fICURLOPT_PROXY_SSLKEY(3)\fP
.IP CURLOPT_PROXY_SSLKEY_BLOB
Proxy client key. See \fICURLOPT_PROXY_SSLKEY_BLOB(3)\fP
.IP CURLOPT_SSLKEYTYPE
Client key type. See \fICURLOPT_SSLKEYTYPE(3)\fP
.IP CURLOPT_PROXY_SSLKEYTYPE
Proxy client key type. See \fICURLOPT_PROXY_SSLKEYTYPE(3)\fP
.IP CURLOPT_KEYPASSWD
Client key password. See \fICURLOPT_KEYPASSWD(3)\fP
.IP CURLOPT_PROXY_KEYPASSWD
Proxy client key password. See \fICURLOPT_PROXY_KEYPASSWD(3)\fP
.IP CURLOPT_SSL_EC_CURVES
Set key exchange curves. See \fICURLOPT_SSL_EC_CURVES(3)\fP
.IP CURLOPT_SSL_ENABLE_ALPN
Enable use of ALPN. See \fICURLOPT_SSL_ENABLE_ALPN(3)\fP
.IP CURLOPT_SSL_ENABLE_NPN
\fBOBSOLETE\fP Enable use of NPN. See \fICURLOPT_SSL_ENABLE_NPN(3)\fP
.IP CURLOPT_SSLENGINE
Use identifier with SSL engine. See \fICURLOPT_SSLENGINE(3)\fP
.IP CURLOPT_SSLENGINE_DEFAULT
Default SSL engine. See \fICURLOPT_SSLENGINE_DEFAULT(3)\fP
.IP CURLOPT_SSL_FALSESTART
Enable TLS False Start. See \fICURLOPT_SSL_FALSESTART(3)\fP
.IP CURLOPT_SSLVERSION
SSL version to use. See \fICURLOPT_SSLVERSION(3)\fP
.IP CURLOPT_PROXY_SSLVERSION
Proxy SSL version to use. See \fICURLOPT_PROXY_SSLVERSION(3)\fP
.IP CURLOPT_SSL_VERIFYHOST
Verify the host name in the SSL certificate. See \fICURLOPT_SSL_VERIFYHOST(3)\fP
.IP CURLOPT_DOH_SSL_VERIFYHOST
Verify the host name in the DoH (DNS-over-HTTPS) SSL certificate. See
\fICURLOPT_DOH_SSL_VERIFYHOST(3)\fP
.IP CURLOPT_PROXY_SSL_VERIFYHOST
Verify the host name in the proxy SSL certificate. See \fICURLOPT_PROXY_SSL_VERIFYHOST(3)\fP
.IP CURLOPT_SSL_VERIFYPEER
Verify the SSL certificate. See \fICURLOPT_SSL_VERIFYPEER(3)\fP
.IP CURLOPT_DOH_SSL_VERIFYPEER
Verify the DoH (DNS-over-HTTPS) SSL certificate. See
\fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP
.IP CURLOPT_PROXY_SSL_VERIFYPEER
Verify the proxy SSL certificate. See \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP
.IP CURLOPT_SSL_VERIFYSTATUS
Verify the SSL certificate's status. See \fICURLOPT_SSL_VERIFYSTATUS(3)\fP
.IP CURLOPT_DOH_SSL_VERIFYSTATUS
Verify the DoH (DNS-over-HTTPS) SSL certificate's status. See
\fICURLOPT_DOH_SSL_VERIFYSTATUS(3)\fP
.IP CURLOPT_CAINFO
CA cert bundle. See \fICURLOPT_CAINFO(3)\fP
.IP CURLOPT_CAINFO_BLOB
CA cert bundle memory buffer. See \fICURLOPT_CAINFO_BLOB(3)\fP
.IP CURLOPT_PROXY_CAINFO
Proxy CA cert bundle. See \fICURLOPT_PROXY_CAINFO(3)\fP
.IP CURLOPT_PROXY_CAINFO_BLOB
Proxy CA cert bundle memory buffer. See \fICURLOPT_PROXY_CAINFO_BLOB(3)\fP
.IP CURLOPT_ISSUERCERT
Issuer certificate. See \fICURLOPT_ISSUERCERT(3)\fP
.IP CURLOPT_ISSUERCERT_BLOB
Issuer certificate memory buffer. See \fICURLOPT_ISSUERCERT_BLOB(3)\fP
.IP CURLOPT_PROXY_ISSUERCERT
Proxy issuer certificate. See \fICURLOPT_PROXY_ISSUERCERT(3)\fP
.IP CURLOPT_PROXY_ISSUERCERT_BLOB
Proxy issuer certificate memory buffer. See \fICURLOPT_PROXY_ISSUERCERT_BLOB(3)\fP
.IP CURLOPT_CAPATH
Path to CA cert bundle. See \fICURLOPT_CAPATH(3)\fP
.IP CURLOPT_PROXY_CAPATH
Path to proxy CA cert bundle. See \fICURLOPT_PROXY_CAPATH(3)\fP
.IP CURLOPT_CRLFILE
Certificate Revocation List. See \fICURLOPT_CRLFILE(3)\fP
.IP CURLOPT_PROXY_CRLFILE
Proxy Certificate Revocation List. See \fICURLOPT_PROXY_CRLFILE(3)\fP
.IP CURLOPT_CERTINFO
Extract certificate info. See \fICURLOPT_CERTINFO(3)\fP
.IP CURLOPT_PINNEDPUBLICKEY
Set pinned SSL public key . See \fICURLOPT_PINNEDPUBLICKEY(3)\fP
.IP CURLOPT_PROXY_PINNEDPUBLICKEY
Set the proxy's pinned SSL public key. See
\fICURLOPT_PROXY_PINNEDPUBLICKEY(3)\fP
.IP CURLOPT_RANDOM_FILE
\fBOBSOLETE\fP Provide source for entropy random data.
See \fICURLOPT_RANDOM_FILE(3)\fP
.IP CURLOPT_EGDSOCKET
\fBOBSOLETE\fP Identify EGD socket for entropy. See \fICURLOPT_EGDSOCKET(3)\fP
.IP CURLOPT_SSL_CIPHER_LIST
Ciphers to use. See \fICURLOPT_SSL_CIPHER_LIST(3)\fP
.IP CURLOPT_PROXY_SSL_CIPHER_LIST
Proxy ciphers to use. See \fICURLOPT_PROXY_SSL_CIPHER_LIST(3)\fP
.IP CURLOPT_TLS13_CIPHERS
TLS 1.3 cipher suites to use. See \fICURLOPT_TLS13_CIPHERS(3)\fP
.IP CURLOPT_PROXY_TLS13_CIPHERS
Proxy TLS 1.3 cipher suites to use. See \fICURLOPT_PROXY_TLS13_CIPHERS(3)\fP
.IP CURLOPT_SSL_SESSIONID_CACHE
Disable SSL session-id cache. See \fICURLOPT_SSL_SESSIONID_CACHE(3)\fP
.IP CURLOPT_SSL_OPTIONS
Control SSL behavior. See \fICURLOPT_SSL_OPTIONS(3)\fP
.IP CURLOPT_PROXY_SSL_OPTIONS
Control proxy SSL behavior. See \fICURLOPT_PROXY_SSL_OPTIONS(3)\fP
.IP CURLOPT_KRBLEVEL
Kerberos security level. See \fICURLOPT_KRBLEVEL(3)\fP
.IP CURLOPT_GSSAPI_DELEGATION
Disable GSS-API delegation. See \fICURLOPT_GSSAPI_DELEGATION(3)\fP
.SH SSH OPTIONS
.IP CURLOPT_SSH_AUTH_TYPES
SSH authentication types. See \fICURLOPT_SSH_AUTH_TYPES(3)\fP
.IP CURLOPT_SSH_COMPRESSION
Enable SSH compression. See \fICURLOPT_SSH_COMPRESSION(3)\fP
.IP CURLOPT_SSH_HOST_PUBLIC_KEY_MD5
MD5 of host's public key. See \fICURLOPT_SSH_HOST_PUBLIC_KEY_MD5(3)\fP
.IP CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256
SHA256 of host's public key. See \fICURLOPT_SSH_HOST_PUBLIC_KEY_SHA256(3)\fP
.IP CURLOPT_SSH_PUBLIC_KEYFILE
File name of public key. See \fICURLOPT_SSH_PUBLIC_KEYFILE(3)\fP
.IP CURLOPT_SSH_PRIVATE_KEYFILE
File name of private key. See \fICURLOPT_SSH_PRIVATE_KEYFILE(3)\fP
.IP CURLOPT_SSH_KNOWNHOSTS
File name with known hosts. See \fICURLOPT_SSH_KNOWNHOSTS(3)\fP
.IP CURLOPT_SSH_KEYFUNCTION
Callback for known hosts handling. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP
.IP CURLOPT_SSH_KEYDATA
Custom pointer to pass to ssh key callback. See \fICURLOPT_SSH_KEYDATA(3)\fP
.IP CURLOPT_SSH_HOSTKEYFUNCTION
Callback for checking host key handling. See \fICURLOPT_SSH_HOSTKEYFUNCTION(3)\fP
.IP CURLOPT_SSH_HOSTKEYDATA
Custom pointer to pass to ssh host key callback. See \fICURLOPT_SSH_HOSTKEYDATA(3)\fP
.SH WEBSOCKET
.IP CURLOPT_WS_OPTIONS
Set WebSocket options. See \fICURLOPT_WS_OPTIONS(3)\fP
.SH OTHER OPTIONS
.IP CURLOPT_PRIVATE
Private pointer to store. See \fICURLOPT_PRIVATE(3)\fP
.IP CURLOPT_SHARE
Share object to use. See \fICURLOPT_SHARE(3)\fP
.IP CURLOPT_NEW_FILE_PERMS
Mode for creating new remote files. See \fICURLOPT_NEW_FILE_PERMS(3)\fP
.IP CURLOPT_NEW_DIRECTORY_PERMS
Mode for creating new remote directories. See \fICURLOPT_NEW_DIRECTORY_PERMS(3)\fP
.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
man page for the full list with descriptions.
Strings passed on to libcurl must be shorter than 8000000 bytes, otherwise
\fIcurl_easy_setopt(3)\fP returns \fBCURLE_BAD_FUNCTION_ARGUMENT\fP (added in
7.65.0).
\fBCURLE_BAD_FUNCTION_ARGUMENT\fP is returned when the argument to an option
is invalid, like perhaps out of range.
If you try to set an option that libcurl does not know about, perhaps because
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 "SEE ALSO"
.BR curl_easy_init "(3), " curl_easy_cleanup "(3), " curl_easy_reset "(3), "
.BR curl_easy_getinfo "(3), " curl_multi_setopt "(3), "
.BR curl_easy_option_next "(3), " curl_easy_option_by_name "(3), "
.BR curl_easy_option_by_id "(3), "
share/man/man3/CURLOPT_SSH_KEYDATA.3 0000644 00000004672 14751150700 0012363 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SSH_KEYDATA 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSH_KEYDATA \- pointer passed to the SSH key callback
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_KEYDATA, void *pointer);
.fi
.SH DESCRIPTION
Pass a void * as parameter. This \fIpointer\fP will be passed along verbatim
to the callback set with \fICURLOPT_SSH_KEYFUNCTION(3)\fP.
.SH DEFAULT
NULL
.SH PROTOCOLS
SFTP and SCP
.SH EXAMPLE
.nf
static int keycb(CURL *easy,
const struct curl_khkey *knownkey,
const struct curl_khkey *foundkey,
enum curl_khmatch,
void *clientp)
{
/* 'clientp' points to the callback_data struct */
/* investigate the situation and return the correct value */
return CURLKHSTAT_FINE_ADD_TO_FILE;
}
{
curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/thisfile.txt");
curl_easy_setopt(curl, CURLOPT_SSH_KEYFUNCTION, keycb);
curl_easy_setopt(curl, CURLOPT_SSH_KEYDATA, &callback_data);
curl_easy_setopt(curl, CURLOPT_SSH_KNOWNHOSTS, "/home/user/known_hosts");
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.19.6
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_SSH_KEYDATA "(3), " CURLOPT_SSH_KNOWNHOSTS "(3), "
share/man/man3/CURLOPT_SOCKOPTDATA.3 0000644 00000004753 14751150700 0012340 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SOCKOPTDATA 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SOCKOPTDATA \- pointer to pass to sockopt callback
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKOPTDATA, void *pointer);
.fi
.SH DESCRIPTION
Pass a \fIpointer\fP that will be untouched by libcurl and passed as the first
argument in the sockopt callback set with \fICURLOPT_SOCKOPTFUNCTION(3)\fP.
.SH DEFAULT
The default value of this parameter is NULL.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
static int sockopt_callback(void *clientp, curl_socket_t curlfd,
curlsocktype purpose)
{
int val = *(int *)clientp;
setsockopt(curldfd, SOL_SOCKET, SO_RCVBUF, (const char *)&val, sizeof(val));
return CURL_SOCKOPT_OK;
}
curl = curl_easy_init();
if(curl) {
int recvbuffersize = 256 * 1024;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
/* call this function to set options for the socket */
curl_easy_setopt(curl, CURLOPT_SOCKOPTFUNCTION, sockopt_callback);
curl_easy_setopt(curl, CURLOPT_SOCKOPTDATA, &recvbuffersize);
res = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.16.0
.SH RETURN VALUE
Returns \fICURLE_OK\fP if the option is supported, and \fICURLE_UNKNOWN_OPTION\fP if not.
.SH "SEE ALSO"
.BR CURLOPT_SOCKOPTFUNCTION "(3), " CURLOPT_OPENSOCKETFUNCTION "(3), "
share/man/man3/CURLOPT_FTP_ACCOUNT.3 0000644 00000004300 14751150700 0012355 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_FTP_ACCOUNT 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_FTP_ACCOUNT \- account info for FTP
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_ACCOUNT, char *account);
.fi
.SH DESCRIPTION
Pass a pointer to a null-terminated string (or NULL to disable). When an FTP
server asks for "account data" after user name and password has been provided,
this data is sent off using the ACCT command.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
FTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/foo.bin");
curl_easy_setopt(curl, CURLOPT_FTP_ACCOUNT, "human-resources");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.13.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_USERNAME "(3), " CURLOPT_PASSWORD "(3), "
share/man/man3/curl_free.3 0000644 00000003601 14751150700 0011311 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_free 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_free - reclaim memory that has been obtained through a libcurl call
.SH SYNOPSIS
.nf
#include <curl/curl.h>
void curl_free(char *ptr);
.fi
.SH DESCRIPTION
curl_free reclaims memory that has been obtained through a libcurl call. Use
\fIcurl_free(3)\fP instead of free() to avoid anomalies that can result from
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"
.BR curl_easy_unescape "(3), " curl_easy_escape "(3) "
share/man/man3/curl_strequal.3 0000644 00000004412 14751150700 0012231 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_strequal 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_strequal, curl_strnequal - case insensitive string comparisons
.SH SYNOPSIS
.nf
#include <curl/curl.h>
int curl_strequal(char *str1, char *str2);
int curl_strnequal(char *str1, char *str2, size_t length);
.fi
.SH DESCRIPTION
The
.B curl_strequal()
function compares the two strings \fIstr1\fP and \fIstr2\fP, ignoring the case
of the characters. It returns a non-zero (TRUE) integer if the strings are
identical.
.sp
The \fBcurl_strnequal()\fP function is similar, except it only compares the
first \fIlength\fP characters of \fIstr1\fP.
.sp
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
Always
.SH RETURN VALUE
Non-zero if the strings are identical. Zero if they are not.
.SH "SEE ALSO"
.BR strcmp "(3), " strcasecmp "(3)"
share/man/man3/CURLOPT_FTP_SKIP_PASV_IP.3 0000644 00000005157 14751150700 0013263 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_FTP_SKIP_PASV_IP 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_FTP_SKIP_PASV_IP \- ignore the IP address in the PASV response
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_SKIP_PASV_IP, long skip);
.fi
.SH DESCRIPTION
Pass a long. If \fIskip\fP is set to 1, it instructs libcurl to not use the IP
address the server suggests in its 227-response to libcurl's PASV command when
libcurl connects the data connection. Instead libcurl will re-use the same IP
address it already uses for the control connection. But it will use the port
number from the 227-response.
This option thus allows libcurl to work around broken server installations
that due to NATs, firewalls or incompetence report the wrong IP address
back. Setting the option also reduces the risk for various sorts of client
abuse by malicious servers.
This option has no effect if PORT, EPRT or EPSV is used instead of PASV.
.SH DEFAULT
1 since 7.74.0, was 0 before then.
.SH PROTOCOLS
FTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/file.txt");
/* please ignore the IP in the PASV response */
curl_easy_setopt(curl, CURLOPT_FTP_SKIP_PASV_IP, 1L);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.14.2
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_FTPPORT "(3), " CURLOPT_FTP_USE_EPRT "(3), "
share/man/man3/curl_multi_add_handle.3 0000644 00000006725 14751150700 0013657 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_multi_add_handle 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_multi_add_handle - add an easy handle to a multi session
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_add_handle(CURLM *multi_handle, CURL *easy_handle);
.fi
.SH DESCRIPTION
Adds a standard easy handle to the multi stack. This function call will make
this \fImulti_handle\fP control the specified \fIeasy_handle\fP.
While an easy handle is added to a multi stack, you cannot and you must not
use \fIcurl_easy_perform(3)\fP on that handle. After having removed the easy
handle from the multi stack again, it is perfectly fine to use it with the
easy interface again.
If the easy handle is not set to use a shared (\fICURLOPT_SHARE(3)\fP) or
global DNS cache (\fICURLOPT_DNS_USE_GLOBAL_CACHE(3)\fP), it will be made to
use the DNS cache that is shared between all easy handles within the multi
handle when \fIcurl_multi_add_handle(3)\fP is called.
When an easy interface is added to a multi handle, it will use a shared
connection cache owned by the multi handle. Removing and adding new easy
handles will not affect the pool of connections or the ability to do
connection re-use.
If you have \fICURLMOPT_TIMERFUNCTION(3)\fP set in the multi handle (and you
really should if you are working event-based with
\fIcurl_multi_socket_action(3)\fP and friends), that callback will be called
from within this function to ask for an updated timer so that your main event
loop will get the activity on this handle to get started.
The easy handle will remain added to the multi handle until you remove it
again with \fIcurl_multi_remove_handle(3)\fP - even when a transfer with that
specific easy handle is completed.
You should remove the easy handle from the multi stack before you terminate
first the easy handle and then the multi handle:
1 - \fIcurl_multi_remove_handle(3)\fP
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"
.BR curl_multi_cleanup "(3)," curl_multi_init "(3), "
.BR curl_multi_setopt "(3), " curl_multi_socket_action "(3) "
share/man/man3/CURLOPT_MAX_SEND_SPEED_LARGE.3 0000644 00000005165 14751150700 0013652 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_MAX_SEND_SPEED_LARGE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_MAX_SEND_SPEED_LARGE \- rate limit data upload speed
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAX_SEND_SPEED_LARGE,
curl_off_t maxspeed);
.SH DESCRIPTION
Pass a curl_off_t as parameter with the \fImaxspeed\fP. If an upload exceeds
this speed (counted in bytes per second) the transfer will pause to keep the
speed less than or equal to the parameter value. Defaults to unlimited
speed.
This is not an exact science. libcurl attempts to keep the average speed below
the given threshold over a period time.
If you set \fImaxspeed\fP to a value lower than
\fICURLOPT_UPLOAD_BUFFERSIZE(3)\fP, libcurl might "shoot over" the limit on
its first send and still send off a full buffer.
This option does not affect transfer speeds done with FILE:// URLs.
.SH DEFAULT
0, disabled
.SH PROTOCOLS
All except file://
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode ret;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
/* cap the upload speed to 1000 bytes/sec */
curl_easy_setopt(curl, CURLOPT_MAX_SEND_SPEED_LARGE, (curl_off_t)1000);
/* (set some upload options as well!) */
ret = curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.15.5
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_MAX_RECV_SPEED_LARGE "(3), " CURLOPT_LOW_SPEED_LIMIT "(3), "
share/man/man3/CURLINFO_HTTP_VERSION.3 0000644 00000004302 14751150700 0012627 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_HTTP_VERSION 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_HTTP_VERSION \- get the http version used in the connection
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_HTTP_VERSION, long *p);
.fi
.SH DESCRIPTION
Pass a pointer to a long to receive the version used in the last http
connection. The returned value will be CURL_HTTP_VERSION_1_0,
CURL_HTTP_VERSION_1_1, CURL_HTTP_VERSION_2_0, CURL_HTTP_VERSION_3 or 0 if the
version cannot be determined.
.SH PROTOCOLS
HTTP
.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);
if(res == CURLE_OK) {
long http_version;
curl_easy_getinfo(curl, CURLINFO_HTTP_VERSION, &http_version);
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.50.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLINFO_RESPONSE_CODE "(3), "
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
share/man/man3/CURLOPT_SSH_AUTH_TYPES.3 0000644 00000004676 14751150700 0013032 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SSH_AUTH_TYPES 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSH_AUTH_TYPES \- auth types for SFTP and SCP
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_AUTH_TYPES, long bitmask);
.fi
.SH DESCRIPTION
Pass a long set to a bitmask consisting of one or more of
CURLSSH_AUTH_PUBLICKEY, CURLSSH_AUTH_PASSWORD, CURLSSH_AUTH_HOST,
CURLSSH_AUTH_KEYBOARD and CURLSSH_AUTH_AGENT.
Set \fICURLSSH_AUTH_ANY\fP to let libcurl pick a suitable one. Currently
CURLSSH_AUTH_HOST has no effect. If CURLSSH_AUTH_AGENT is used, libcurl
attempts to connect to ssh-agent or pageant and let the agent attempt the
authentication.
.SH DEFAULT
CURLSSH_AUTH_ANY (all available)
.SH PROTOCOLS
SFTP and SCP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file");
curl_easy_setopt(curl, CURLOPT_SSH_AUTH_TYPES,
CURLSSH_AUTH_PUBLICKEY | CURLSSH_AUTH_KEYBOARD);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
CURLSSH_AUTH_HOST was added in 7.16.1, CURLSSH_AUTH_AGENT was added in 7.28.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 "(3), " CURLOPT_SSH_PUBLIC_KEYFILE "(3), "
share/man/man3/CURLOPT_DOH_SSL_VERIFYHOST.3 0000644 00000006626 14751150700 0013502 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_DOH_SSL_VERIFYHOST 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_DOH_SSL_VERIFYHOST \- verify the host name in the DoH SSL certificate
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DOH_SSL_VERIFYHOST,
long verify);
.fi
.SH DESCRIPTION
Pass a long set to 2L as asking curl to \fIverify\fP the DoH (DNS-over-HTTPS)
server's certificate name fields against the host name.
This option is the DoH equivalent of \fICURLOPT_SSL_VERIFYHOST(3)\fP and
only affects requests to the DoH server.
When \fICURLOPT_DOH_SSL_VERIFYHOST(3)\fP is 2, the SSL certificate provided by
the DoH server must indicate that the server name is the same as the server
name to which you meant to connect to, or the connection fails.
Curl considers the DoH server the intended one when the Common Name field or a
Subject Alternate Name field in the certificate matches the host name in the
DoH URL to which you told Curl to connect.
When the \fIverify\fP value is set to 1L it is treated the same as 2L. However
for consistency with the other \fIVERIFYHOST\fP options we suggest use 2 and
not 1.
When the \fIverify\fP value is set to 0L, the connection succeeds regardless of
the names used in the certificate. Use that ability with caution!
See also \fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP to verify the digital signature
of the DoH server certificate. If libcurl is built against NSS and
\fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP is zero,
\fICURLOPT_DOH_SSL_VERIFYHOST(3)\fP is also set to zero and cannot be
overridden.
.SH DEFAULT
2
.SH PROTOCOLS
DoH
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_DOH_URL, "https://cloudflare-dns.com/dns-query");
/* Disable host name verification of the DoH server */
curl_easy_setopt(curl, CURLOPT_DOH_SSL_VERIFYHOST, 0L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.76.0
If built TLS enabled.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_DOH_SSL_VERIFYPEER "(3), "
.BR CURLOPT_SSL_VERIFYHOST "(3), "
.BR CURLOPT_SSL_VERIFYPEER "(3), "
.BR CURLOPT_PROXY_SSL_VERIFYPEER "(3), "
.BR CURLOPT_PROXY_SSL_VERIFYHOST "(3), "
share/man/man3/CURLOPT_CAPATH.3 0000644 00000005430 14751150700 0011515 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_CAPATH 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_CAPATH \- directory holding CA certificates
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CAPATH, char *capath);
.fi
.SH DESCRIPTION
Pass a char * to a null-terminated string naming a directory holding multiple
CA certificates to verify the peer with. If libcurl is built against OpenSSL,
the certificate directory must be prepared using the OpenSSL c_rehash utility.
This makes sense only when used in combination with the
\fICURLOPT_SSL_VERIFYPEER(3)\fP option.
The \fICURLOPT_CAPATH(3)\fP function apparently does not work in Windows due
to some limitation in OpenSSL.
The application does not have to keep the string around after setting this
option.
The default value for this can be figured out with \fICURLINFO_CAPATH(3)\fP.
.SH DEFAULT
A default path detected at build time.
.SH PROTOCOLS
All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_CAPATH, "/etc/cert-dir");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
This option is supported by the OpenSSL, GnuTLS and mbedTLS (since 7.56.0)
backends. The NSS backend provides the option only for backward compatibility.
.SH RETURN VALUE
CURLE_OK if supported; or an error such as:
CURLE_NOT_BUILT_IN - Not supported by the SSL backend
CURLE_UNKNOWN_OPTION
CURLE_OUT_OF_MEMORY
.SH "SEE ALSO"
.BR CURLOPT_CAINFO "(3), "
.BR CURLOPT_STDERR "(3), " CURLOPT_DEBUGFUNCTION "(3), "
.BR CURLINFO_CAPATH "(3), "
share/man/man3/curl_mime_free.3 0000644 00000004425 14751150700 0012325 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_mime_free 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_mime_free - free a previously built mime structure
.SH SYNOPSIS
.nf
#include <curl/curl.h>
void curl_mime_free(curl_mime *mime);
.fi
.SH DESCRIPTION
\fIcurl_mime_free(3)\fP is used to clean up data previously built/appended
with \fIcurl_mime_addpart(3)\fP and other mime-handling functions. This must
be called when the data has been used, which typically means after
\fIcurl_easy_perform(3)\fP has been called.
The handle to free is the one you passed to the \fICURLOPT_MIMEPOST(3)\fP
option: attached sub part mime structures must not be explicitly freed as they
are by the top structure freeing.
\fBmime\fP is the handle as returned from a previous call to
\fIcurl_mime_init(3)\fP and may be NULL.
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
None
.SH "SEE ALSO"
.BR curl_mime_init "(3)"
share/man/man3/CURLINFO_CERTINFO.3 0000644 00000006152 14751150700 0012061 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_CERTINFO 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_CERTINFO \- get the TLS certificate chain
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CERTINFO,
struct curl_certinfo **chainp);
.fi
.SH DESCRIPTION
Pass a pointer to a \fIstruct curl_certinfo *\fP and you will get it set to
point to a struct that holds a number of linked lists with info about the
certificate chain, assuming you had \fICURLOPT_CERTINFO(3)\fP enabled when the
request was made. The struct reports how many certs it found and then you can
extract info for each of those certs by following the linked lists. The info
chain is provided in a series of data in the format "name:content" where the
content is for the specific named data. See also the \fIcertinfo.c\fP example.
.SH PROTOCOLS
All TLS-based
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://www.example.com/");
/* connect to any HTTPS site, trusted or not */
curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L);
curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L);
curl_easy_setopt(curl, CURLOPT_CERTINFO, 1L);
res = curl_easy_perform(curl);
if (!res) {
struct curl_certinfo *ci;
res = curl_easy_getinfo(curl, CURLINFO_CERTINFO, &ci);
if (!res) {
printf("%d certs!\\n", ci->num_of_certs);
for(i = 0; i < ci->num_of_certs; i++) {
struct curl_slist *slist;
for(slist = ci->certinfo[i]; slist; slist = slist->next)
printf("%s\\n", slist->data);
}
}
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
This option is only working in libcurl built with OpenSSL, NSS, Schannel, GSKit
or Secure Transport support. Schannel support added in 7.50.0. Secure Transport
support added in 7.79.0.
Added in 7.19.1
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
share/man/man3/CURLOPT_DEBUGFUNCTION.3 0000644 00000012530 14751150700 0012550 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_DEBUGFUNCTION 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_DEBUGFUNCTION \- debug callback
.SH SYNOPSIS
.nf
#include <curl/curl.h>
typedef enum {
CURLINFO_TEXT = 0,
CURLINFO_HEADER_IN, /* 1 */
CURLINFO_HEADER_OUT, /* 2 */
CURLINFO_DATA_IN, /* 3 */
CURLINFO_DATA_OUT, /* 4 */
CURLINFO_SSL_DATA_IN, /* 5 */
CURLINFO_SSL_DATA_OUT, /* 6 */
CURLINFO_END
} curl_infotype;
int debug_callback(CURL *handle,
curl_infotype type,
char *data,
size_t size,
void *userptr);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DEBUGFUNCTION,
debug_callback);
.SH DESCRIPTION
Pass a pointer to your callback function, which should match the prototype
shown above.
\fICURLOPT_DEBUGFUNCTION(3)\fP replaces the standard debug function used when
\fICURLOPT_VERBOSE(3)\fP is in effect. This callback receives debug
information, as specified in the \fItype\fP argument. This function must
return 0. The \fIdata\fP pointed to by the char * passed to this function WILL
NOT be null-terminated, but will be exactly of the \fIsize\fP as told by the
\fIsize\fP argument.
The \fIuserptr\fP argument is the pointer set with \fICURLOPT_DEBUGDATA(3)\fP.
Available \fBcurl_infotype\fP values:
.IP CURLINFO_TEXT
The data is informational text.
.IP CURLINFO_HEADER_IN
The data is header (or header-like) data received from the peer.
.IP CURLINFO_HEADER_OUT
The data is header (or header-like) data sent to the peer.
.IP CURLINFO_DATA_IN
The data is protocol data received from the peer.
.IP CURLINFO_DATA_OUT
The data is protocol data sent to the peer.
.IP CURLINFO_SSL_DATA_OUT
The data is SSL/TLS (binary) data sent to the peer.
.IP CURLINFO_SSL_DATA_IN
The data is SSL/TLS (binary) data received from the peer.
.SH DEFAULT
NULL
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
static
void dump(const char *text,
FILE *stream, unsigned char *ptr, size_t size)
{
size_t i;
size_t c;
unsigned int width=0x10;
fprintf(stream, "%s, %10.10ld bytes (0x%8.8lx)\\n",
text, (long)size, (long)size);
for(i=0; i<size; i+= width) {
fprintf(stream, "%4.4lx: ", (long)i);
/* show hex to the left */
for(c = 0; c < width; c++) {
if(i+c < size)
fprintf(stream, "%02x ", ptr[i+c]);
else
fputs(" ", stream);
}
/* show data on the right */
for(c = 0; (c < width) && (i+c < size); c++) {
char x = (ptr[i+c] >= 0x20 && ptr[i+c] < 0x80) ? ptr[i+c] : '.';
fputc(x, stream);
}
fputc('\\n', stream); /* newline */
}
}
static
int my_trace(CURL *handle, curl_infotype type,
char *data, size_t size,
void *userp)
{
const char *text;
(void)handle; /* prevent compiler warning */
(void)userp;
switch (type) {
case CURLINFO_TEXT:
fprintf(stderr, "== Info: %s", data);
default: /* in case a new one is introduced to shock us */
return 0;
case CURLINFO_HEADER_OUT:
text = "=> Send header";
break;
case CURLINFO_DATA_OUT:
text = "=> Send data";
break;
case CURLINFO_SSL_DATA_OUT:
text = "=> Send SSL data";
break;
case CURLINFO_HEADER_IN:
text = "<= Recv header";
break;
case CURLINFO_DATA_IN:
text = "<= Recv data";
break;
case CURLINFO_SSL_DATA_IN:
text = "<= Recv SSL data";
break;
}
dump(text, stderr, (unsigned char *)data, size);
return 0;
}
int main(void)
{
CURL *curl;
CURLcode res;
curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_DEBUGFUNCTION, my_trace);
/* the DEBUGFUNCTION has no effect until we enable VERBOSE */
curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L);
/* example.com is redirected, so we tell libcurl to follow redirection */
curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
res = curl_easy_perform(curl);
/* Check for errors */
if(res != CURLE_OK)
fprintf(stderr, "curl_easy_perform() failed: %s\\n",
curl_easy_strerror(res));
/* always cleanup */
curl_easy_cleanup(curl);
}
return 0;
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_VERBOSE "(3), " CURLOPT_DEBUGDATA "(3), "
share/man/man3/CURLOPT_USERNAME.3 0000644 00000006203 14751150700 0011773 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_USERNAME 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_USERNAME \- user name to use in authentication
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_USERNAME,
char *username);
.SH DESCRIPTION
Pass a char * as parameter, which should be pointing to the null-terminated
user name to use for the transfer.
\fICURLOPT_USERNAME(3)\fP sets the user name to be used in protocol
authentication. You should not use this option together with the (older)
\fICURLOPT_USERPWD(3)\fP option.
When using Kerberos V5 authentication with a Windows based server, you should
include the domain name in order for the server to successfully obtain a
Kerberos Ticket. If you do not then the initial part of the authentication
handshake may fail.
When using NTLM, the user name can be specified simply as the user name
without the domain name should the server be part of a single domain and
forest.
To include the domain name use either Down-Level Logon Name or UPN (User
Principal Name) formats. For example, EXAMPLE\\user and user@example.com
respectively.
Some HTTP servers (on Windows) support inclusion of the domain for Basic
authentication as well.
To specify the password and login options, along with the user name, use the
\fICURLOPT_PASSWORD(3)\fP and \fICURLOPT_LOGIN_OPTIONS(3)\fP options.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
blank
.SH PROTOCOLS
Most
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
curl_easy_setopt(curl, CURLOPT_USERNAME, "clark");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.19.1
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_USERPWD "(3), " CURLOPT_PASSWORD "(3), "
.BR CURLOPT_HTTPAUTH "(3), " CURLOPT_PROXYAUTH "(3)"
share/man/man3/CURLOPT_SSLKEYTYPE.3 0000644 00000005214 14751150700 0012271 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SSLKEYTYPE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSLKEYTYPE \- type of the private key file
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLKEYTYPE, char *type);
.fi
.SH DESCRIPTION
Pass a pointer to a null-terminated string as parameter. The string should be
the format of your private key. Supported formats are "PEM", "DER" and "ENG".
The format "ENG" enables you to load the private key from a crypto engine. In
this case \fICURLOPT_SSLKEY(3)\fP is used as an identifier passed to the
engine. You have to set the crypto engine with \fICURLOPT_SSLENGINE(3)\fP.
\&"DER" format key file currently does not work because of a bug in OpenSSL.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
"PEM"
.SH PROTOCOLS
All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_SSLCERT, "client.pem");
curl_easy_setopt(curl, CURLOPT_SSLKEY, "key.pem");
curl_easy_setopt(curl, CURLOPT_SSLKEYTYPE, "PEM");
curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "s3cret");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
If built TLS enabled.
.SH RETURN VALUE
Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_SSLKEY "(3), " CURLOPT_SSLCERT "(3), "
share/man/man3/libcurl-security.3 0000644 00000054701 14751150700 0012653 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH libcurl-security 3 "September 20, 2022" "libcurl 7.86.0" "libcurl security"
.SH NAME
libcurl-security \- security considerations when using libcurl
.SH "Security"
The libcurl project takes security seriously. The library is written with
caution and precautions are taken to mitigate many kinds of risks encountered
while operating with potentially malicious servers on the Internet. It is a
powerful library, however, which allows application writers to make trade-offs
between ease of writing and exposure to potential risky operations. If used
the right way, you can use libcurl to transfer data pretty safely.
Many applications are used in closed networks where users and servers can
(possibly) be trusted, but many others are used on arbitrary servers and are
fed input from potentially untrusted users. Following is a discussion about
some risks in the ways in which applications commonly use libcurl and
potential mitigations of those risks. It is not comprehensive, but shows
classes of attacks that robust applications should consider. The Common
Weakness Enumeration project at https://cwe.mitre.org/ is a good reference for
many of these and similar types of weaknesses of which application writers
should be aware.
.SH "Command Lines"
If you use a command line tool (such as curl) that uses libcurl, and you give
options to the tool on the command line those options can get read by other
users of your system when they use \fIps\fP or other tools to list currently
running processes.
To avoid these problems, never feed sensitive things to programs using command
line options. Write them to a protected file and use the \-K option to avoid
this.
.SH ".netrc"
\&.netrc is a pretty handy file/feature that allows you to login quickly and
automatically to frequently visited sites. The file contains passwords in
clear text and is a real security risk. In some cases, your .netrc is also
stored in a home directory that is NFS mounted or used on another network
based file system, so the clear text password will fly through your network
every time anyone reads that file.
For applications that enable .netrc use, a user who manage to set the right
URL might then be possible to pass on passwords.
To avoid these problems, do not use .netrc files and never store passwords in
plain text anywhere.
.SH "Clear Text Passwords"
Many of the protocols libcurl supports send name and password unencrypted as
clear text (HTTP Basic authentication, FTP, TELNET etc). It is easy for anyone
on your network or a network nearby yours to just fire up a network analyzer
tool and eavesdrop on your passwords. do not let the fact that HTTP Basic uses
base64 encoded passwords fool you. They may not look readable at a first
glance, but they are easily "deciphered" by anyone within seconds.
To avoid this problem, use an authentication mechanism or other protocol that
does not let snoopers see your password: Digest, CRAM-MD5, Kerberos, SPNEGO or
NTLM authentication. Or even better: use authenticated protocols that protect
the entire connection and everything sent over it.
.SH "Unauthenticated Connections"
Protocols that do not have any form of cryptographic authentication cannot
with any certainty know that they communicate with the right remote server.
If your application is using a fixed scheme or fixed host name, it is not safe
as long as the connection is unauthenticated. There can be a man-in-the-middle
or in fact the whole server might have been replaced by an evil actor.
Unauthenticated protocols are unsafe. The data that comes back to curl may
have been injected by an attacker. The data that curl sends might be modified
before it reaches the intended server. If it even reaches the intended server
at all.
Remedies:
.IP "Restrict operations to authenticated transfers"
Use authenticated protocols protected with HTTPS or SSH.
.IP "Make sure the server's certificate etc is verified"
Never ever switch off certificate verification.
.SH "Redirects"
The \fICURLOPT_FOLLOWLOCATION(3)\fP option automatically follows HTTP
redirects sent by a remote server. These redirects can refer to any kind of
URL, not just HTTP. libcurl restricts the protocols allowed to be used in
redirects for security reasons: only HTTP, HTTPS, FTP and FTPS are
enabled by default. Applications may opt to restrict that set further.
A redirect to a file: URL would cause the libcurl to read (or write) arbitrary
files from the local filesystem. If the application returns the data back to
the user (as would happen in some kinds of CGI scripts), an attacker could
leverage this to read otherwise forbidden data (e.g.
\fBfile://localhost/etc/passwd\fP).
If authentication credentials are stored in the ~/.netrc file, or Kerberos is
in use, any other URL type (not just file:) that requires authentication is
also at risk. A redirect such as ftp://some-internal-server/private-file would
then return data even when the server is password protected.
In the same way, if an unencrypted SSH private key has been configured for the
user running the libcurl application, SCP: or SFTP: URLs could access password
or private-key protected resources,
e.g. \fBsftp://user@some-internal-server/etc/passwd\fP
The \fICURLOPT_REDIR_PROTOCOLS(3)\fP and \fICURLOPT_NETRC(3)\fP options can be
used to mitigate against this kind of attack.
A redirect can also specify a location available only on the machine running
libcurl, including servers hidden behind a firewall from the attacker.
e.g. http://127.0.0.1/ or http://intranet/delete-stuff.cgi?delete=all or
tftp://bootp-server/pc-config-data
Applications can mitigate against this by disabling
\fICURLOPT_FOLLOWLOCATION(3)\fP and handling redirects itself, sanitizing URLs
as necessary. Alternately, an app could leave \fICURLOPT_FOLLOWLOCATION(3)\fP
enabled but set \fICURLOPT_REDIR_PROTOCOLS(3)\fP and install a
\fICURLOPT_OPENSOCKETFUNCTION(3)\fP or \fICURLOPT_PREREQFUNCTION(3)\fP callback
function in which addresses are sanitized before use.
.SH "CRLF in Headers"
For all options in libcurl which specify headers, including but not limited to
\fICURLOPT_HTTPHEADER(3)\fP, \fICURLOPT_PROXYHEADER(3)\fP,
\fICURLOPT_COOKIE(3)\fP, \fICURLOPT_USERAGENT(3)\fP, \fICURLOPT_REFERER(3)\fP
and \fICURLOPT_RANGE(3)\fP, libcurl will send the headers as-is and will not
apply any special sanitation or normalization to them.
If you allow untrusted user input into these options without sanitizing CRLF
sequences in them, someone malicious may be able to modify the request in a
way you did not intend such as injecting new headers.
.SH "Local Resources"
A user who can control the DNS server of a domain being passed in within a URL
can change the address of the host to a local, private address which a
server-side libcurl-using application could then use. e.g. the innocuous URL
\fBhttp://fuzzybunnies.example.com/\fP could actually resolve to the IP
address of a server behind a firewall, such as 127.0.0.1 or
10.1.2.3. Applications can mitigate against this by setting a
\fICURLOPT_OPENSOCKETFUNCTION(3)\fP or \fICURLOPT_PREREQFUNCTION(3)\fP and
checking the address before a connection.
All the malicious scenarios regarding redirected URLs apply just as well to
non-redirected URLs, if the user is allowed to specify an arbitrary URL that
could point to a private resource. For example, a web app providing a
translation service might happily translate \fBfile://localhost/etc/passwd\fP
and display the result. Applications can mitigate against this with the
\fICURLOPT_PROTOCOLS(3)\fP option as well as by similar mitigation techniques
for redirections.
A malicious FTP server could in response to the PASV command return an IP
address and port number for a server local to the app running libcurl but
behind a firewall. Applications can mitigate against this by using the
\fICURLOPT_FTP_SKIP_PASV_IP(3)\fP option or \fICURLOPT_FTPPORT(3)\fP.
Local servers sometimes assume local access comes from friends and trusted
users. An application that expects https://example.com/file_to_read that and
instead gets http://192.168.0.1/my_router_config might print a file that would
otherwise be protected by the firewall.
Allowing your application to connect to local hosts, be it the same machine
that runs the application or a machine on the same local network, might be
possible to exploit by an attacker who then perhaps can "port-scan" the
particular hosts - depending on how the application and servers acts.
.SH "IPv4 Addresses"
Some users might be tempted to filter access to local resources or similar
based on numerical IPv4 addresses used in URLs. This is a bad and error-prone
idea because of the many different ways a numerical IPv4 address can be
specified and libcurl accepts: one to four dot-separated fields using one of
or a mix of decimal, octal or hexadecimal encoding.
.SH "IPv6 Addresses"
libcurl will normally handle IPv6 addresses transparently and just as easily
as IPv4 addresses. That means that a sanitizing function that filters out
addresses like 127.0.0.1 is not sufficient--the equivalent IPv6 addresses
\fB::1\fP, \fB::\fP, \fB0:00::0:1\fP, \fB::127.0.0.1\fP and
\fB::ffff:7f00:1\fP supplied somehow by an attacker would all bypass a naive
filter and could allow access to undesired local resources. IPv6 also has
special address blocks like link-local and site-local that generally should
not be accessed by a server-side libcurl-using application. A poorly
configured firewall installed in a data center, organization or server may
also be configured to limit IPv4 connections but leave IPv6 connections wide
open. In some cases, setting \fICURLOPT_IPRESOLVE(3)\fP to CURL_IPRESOLVE_V4
can be used to limit resolved addresses to IPv4 only and bypass these issues.
.SH Uploads
When uploading, a redirect can cause a local (or remote) file to be
overwritten. Applications must not allow any unsanitized URL to be passed in
for uploads. Also, \fICURLOPT_FOLLOWLOCATION(3)\fP should not be used on
uploads. Instead, the applications should consider handling redirects itself,
sanitizing each URL first.
.SH Authentication
Use of \fICURLOPT_UNRESTRICTED_AUTH(3)\fP could cause authentication
information to be sent to an unknown second server. Applications can mitigate
against this by disabling \fICURLOPT_FOLLOWLOCATION(3)\fP and handling
redirects itself, sanitizing where necessary.
Use of the CURLAUTH_ANY option to \fICURLOPT_HTTPAUTH(3)\fP could result in
user name and password being sent in clear text to an HTTP server. Instead,
use CURLAUTH_ANYSAFE which ensures that the password is encrypted over the
network, or else fail the request.
Use of the CURLUSESSL_TRY option to \fICURLOPT_USE_SSL(3)\fP could result in
user name and password being sent in clear text to an FTP server. Instead,
use CURLUSESSL_CONTROL to ensure that an encrypted connection is used or else
fail the request.
.SH Cookies
If cookies are enabled and cached, then a user could craft a URL which
performs some malicious action to a site whose authentication is already
stored in a cookie. e.g. http://mail.example.com/delete-stuff.cgi?delete=all
Applications can mitigate against this by disabling cookies or clearing them
between requests.
.SH "Dangerous SCP URLs"
SCP URLs can contain raw commands within the scp: URL, which is a side effect
of how the SCP protocol is designed. e.g.
.nf
scp://user:pass@host/a;date >/tmp/test;
.fi
Applications must not allow unsanitized SCP: URLs to be passed in for
downloads.
.SH "file://"
By default curl and libcurl support file:// URLs. Such a URL is always an
access, or attempted access, to a local resource. If your application wants to
avoid that, keep control of what URLs to use and/or prevent curl/libcurl from
using the protocol.
By default, libcurl prohibits redirects to file:// URLs.
.SH "Warning: file:// on Windows"
The Windows operating system will automatically, and without any way for
applications to disable it, try to establish a connection to another host over
the network and access it (over SMB or other protocols), if only the correct
file path is accessed.
When first realizing this, the curl team tried to filter out such attempts in
order to protect applications for inadvertent probes of for example internal
networks etc. This resulted in CVE-2019-15601 and the associated security fix.
However, we have since been made aware of the fact that the previous fix was far
from adequate as there are several other ways to accomplish more or less the
same thing: accessing a remote host over the network instead of the local file
system.
The conclusion we have come to is that this is a weakness or feature in the
Windows operating system itself, that we as an application cannot safely
protect users against. It would just be a whack-a-mole race we do not want to
participate in. There are too many ways to do it and there's no knob we can
use to turn off the practice.
If you use curl or libcurl on Windows (any version), disable the use of the
FILE protocol in curl or be prepared that accesses to a range of "magic paths"
will potentially make your system try to access other hosts on your
network. curl cannot protect you against this.
.SH "What if the user can set the URL"
Applications may find it tempting to let users set the URL that it can work
on. That is probably fine, but opens up for mischief and trickery that you as
an application author may want to address or take precautions against.
If your curl-using script allow a custom URL do you also, perhaps
unintentionally, allow the user to pass other options to the curl command line
if creative use of special characters are applied?
If the user can set the URL, the user can also specify the scheme part to
other protocols that you did not intend for users to use and perhaps did not
consider. curl supports over 20 different URL schemes. "http://" might be what
you thought, "ftp://" or "imap://" might be what the user gives your
application. Also, cross-protocol operations might be done by using a
particular scheme in the URL but point to a server doing a different protocol
on a non-standard port.
Remedies:
.IP "Use --proto"
curl command lines can use \fI--proto\fP to limit what URL schemes it accepts
.IP "Use CURLOPT_PROTOCOLS"
libcurl programs can use \fICURLOPT_PROTOCOLS(3)\fP to limit what URL schemes it accepts
.IP "consider not allowing the user to set the full URL"
Maybe just let the user provide data for parts of it? Or maybe filter input to
only allow specific choices?
.SH "RFC 3986 vs WHATWG URL"
curl supports URLs mostly according to how they are defined in RFC 3986, and
has done so since the beginning.
Web browsers mostly adhere to the WHATWG URL Specification.
This deviance makes some URLs copied between browsers (or returned over HTTP
for redirection) and curl not work the same way. It can also cause problems if
an application parses URLs differently from libcurl and makes different
assumptions about a link. This can mislead users into getting the wrong thing,
connecting to the wrong host or otherwise not working identically.
Within an application, this can be mitigated by always using the
\fIcurl_url(3)\fP API to parse URLs, ensuring that they are parsed the same way
as within libcurl itself.
.SH "FTP uses two connections"
When performing an FTP transfer, two TCP connections are used: one for setting
up the transfer and one for the actual data.
FTP is not only unauthenticated, but the setting up of the second transfer is
also a weak spot. The second connection to use for data, is either setup with
the PORT/EPRT command that makes the server connect back to the client on the
given IP+PORT, or with PASV/EPSV that makes the server setup a port to listen
to and tells the client to connect to a given IP+PORT.
Again, unauthenticated means that the connection might be meddled with by a
man-in-the-middle or that there's a malicious server pretending to be the
right one.
A malicious FTP server can respond to PASV commands with the IP+PORT of a
totally different machine. Perhaps even a third party host, and when there are
many clients trying to connect to that third party, it could create a
Distributed Denial-Of-Service attack out of it. If the client makes an upload
operation, it can make the client send the data to another site. If the
attacker can affect what data the client uploads, it can be made to work as a
HTTP request and then the client could be made to issue HTTP requests to third
party hosts.
An attacker that manages to control curl's command line options can tell curl
to send an FTP PORT command to ask the server to connect to a third party host
instead of back to curl.
The fact that FTP uses two connections makes it vulnerable in a way that is
hard to avoid.
.SH "Denial of Service"
A malicious server could cause libcurl to effectively hang by sending data
slowly, or even no data at all but just keeping the TCP connection open. This
could effectively result in a denial-of-service attack. The
\fICURLOPT_TIMEOUT(3)\fP and/or \fICURLOPT_LOW_SPEED_LIMIT(3)\fP options can
be used to mitigate against this.
A malicious server could cause libcurl to download an infinite amount of data,
potentially causing all of memory or disk to be filled. Setting the
\fICURLOPT_MAXFILESIZE_LARGE(3)\fP option is not sufficient to guard against
this. Instead, applications should monitor the amount of data received within
the write or progress callback and abort once the limit is reached.
A malicious HTTP server could cause an infinite redirection loop, causing a
denial-of-service. This can be mitigated by using the
\fICURLOPT_MAXREDIRS(3)\fP option.
.SH "Arbitrary Headers"
User-supplied data must be sanitized when used in options like
\fICURLOPT_USERAGENT(3)\fP, \fICURLOPT_HTTPHEADER(3)\fP,
\fICURLOPT_POSTFIELDS(3)\fP and others that are used to generate structured
data. Characters like embedded carriage returns or ampersands could allow the
user to create additional headers or fields that could cause malicious
transactions.
.SH "Server-supplied Names"
A server can supply data which the application may, in some cases, use as a
file name. The curl command-line tool does this with
\fI--remote-header-name\fP, using the Content-disposition: header to generate
a file name. An application could also use \fICURLINFO_EFFECTIVE_URL(3)\fP to
generate a file name from a server-supplied redirect URL. Special care must be
taken to sanitize such names to avoid the possibility of a malicious server
supplying one like \fB"/etc/passwd"\fP, \fB"\\autoexec.bat"\fP, \fB"prn:"\fP
or even \fB".bashrc"\fP.
.SH "Server Certificates"
A secure application should never use the \fICURLOPT_SSL_VERIFYPEER(3)\fP
option to disable certificate validation. There are numerous attacks that are
enabled by applications that fail to properly validate server TLS/SSL
certificates, thus enabling a malicious server to spoof a legitimate
one. HTTPS without validated certificates is potentially as insecure as a
plain HTTP connection.
.SH "Showing What You Do"
Relatedly, be aware that in situations when you have problems with libcurl and
ask someone for help, everything you reveal in order to get best possible help
might also impose certain security related risks. Host names, user names,
paths, operating system specifics, etc. (not to mention passwords of course)
may in fact be used by intruders to gain additional information of a potential
target.
Be sure to limit access to application logs if they could hold private or
security-related data. Besides the obvious candidates like user names and
passwords, things like URLs, cookies or even file names could also hold
sensitive data.
To avoid this problem, you must of course use your common sense. Often, you
can just edit out the sensitive data or just search/replace your true
information with faked data.
.SH "setuid applications using libcurl"
libcurl-using applications that set the 'setuid' bit to run with elevated or
modified rights also implicitly give that extra power to libcurl and this
should only be done after careful considerations.
Giving setuid powers to the application means that libcurl can save files using
those new rights (if for example the `SSLKEYLOGFILE` environment variable is
set). Also: if the application wants these powers to read or manage secrets
that the user is otherwise not able to view (like credentials for a login
etc), it should be noted that libcurl still might understand proxy environment
variables that allow the user to redirect libcurl operations to use a proxy
controlled by the user.
.SH "File descriptors, fork and NTLM"
An application that uses libcurl and invokes \fIfork()\fP will get all file
descriptors duplicated in the child process, including the ones libcurl
created.
libcurl itself uses \fIfork()\fP and \fIexecl()\fP if told to use the
\fBCURLAUTH_NTLM_WB\fP authentication method which then will invoke the helper
command in a child process with file descriptors duplicated. Make sure that
only the trusted and reliable helper program is invoked!
.SH "Secrets in memory"
When applications pass user names, passwords or other sensitive data to
libcurl to be used for upcoming transfers, those secrets will be kept around
as-is in memory. In many cases they will be stored in heap for as long as the
handle itself for which the options are set.
If an attacker can access the heap, like maybe by reading swap space or via a
core dump file, such data might be accessible.
Further, when eventually closing a handle and the secrets are no longer
needed, libcurl does not explicitly clear memory before freeing it, so
credentials may be left in freed data.
.SH "Report Security Problems"
Should you detect or just suspect a security problem in libcurl or curl,
contact the project curl security team immediately. See
https://curl.se/dev/secprocess.html for details.
share/man/man3/CURLOPT_TRANSFERTEXT.3 0000644 00000004544 14751150700 0012513 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_TRANSFERTEXT 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_TRANSFERTEXT \- request a text based transfer for FTP
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TRANSFERTEXT, long text);
.fi
.SH DESCRIPTION
A parameter set to 1 tells the library to use ASCII mode for FTP transfers,
instead of the default binary transfer. For win32 systems it does not set the
stdout to binary mode. This option can be usable when transferring text data
between systems with different views on certain characters, such as newlines
or similar.
libcurl does not do a complete ASCII conversion when doing ASCII transfers
over FTP. This is a known limitation/flaw that nobody has rectified. libcurl
simply sets the mode to ASCII and performs a standard transfer.
.SH DEFAULT
0, disabled
.SH PROTOCOLS
FTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/textfile");
curl_easy_setopt(curl, CURLOPT_TRANSFERTEXT, 1L);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Along with FTP
.SH RETURN VALUE
Returns CURLE_OK if FTP is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_CRLF "(3), "
share/man/man3/CURLOPT_SSLENGINE.3 0000644 00000004701 14751150700 0012104 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SSLENGINE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSLENGINE \- SSL engine identifier
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLENGINE, char *id);
.fi
.SH DESCRIPTION
Pass a pointer to a null-terminated string as parameter. It will be used as
the identifier for the crypto engine you want to use for your private key.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_SSLENGINE, "dynamic");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Only if the SSL backend is OpenSSL built with engine support.
.SH RETURN VALUE
CURLE_OK - Engine found.
CURLE_SSL_ENGINE_NOTFOUND - Engine not found, or OpenSSL was not built with
engine support.
CURLE_SSL_ENGINE_INITFAILED - Engine found but initialization failed.
CURLE_NOT_BUILT_IN - Option not built in, OpenSSL is not the SSL backend.
CURLE_UNKNOWN_OPTION - Option not recognized.
CURLE_OUT_OF_MEMORY - Insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_SSLENGINE_DEFAULT "(3), " CURLOPT_SSLKEY "(3), "
share/man/man3/curl_mime_type.3 0000644 00000005520 14751150700 0012362 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_mime_type 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_mime_type - set a mime part's content type
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_mime_type(curl_mimepart *part, const char *mimetype);
.fi
.SH DESCRIPTION
\fIcurl_mime_type(3)\fP sets a mime part's content type.
\fIpart\fP is the part's handle to assign the content type to.
\fImimetype\fP points to the null-terminated file mime type string; it may be
set to NULL to remove a previously attached mime type.
The mime type string is copied into the part, thus the associated storage may
safely be released or reused after call. Setting a part's type multiple times
is valid: only the value set by the last call is retained.
In the absence of a mime type and if needed by the protocol specifications,
a default mime type is determined by the context:
.br
- If set as a custom header, use this value.
.br
- application/form-data for an HTTP form post.
.br
- If a remote file name is set, the mime type is taken from the file name
extension, or application/octet-stream by default.
.br
- For a multipart part, multipart/mixed.
.br
- text/plain in other cases.
.SH EXAMPLE
.nf
curl_mime *mime;
curl_mimepart *part;
/* create a mime handle */
mime = curl_mime_init(easy);
/* add a part */
part = curl_mime_addpart(mime);
/* get data from this file */
curl_mime_filedata(part, "image.png");
/* content-type for this part */
curl_mime_type(part, "image/png");
/* 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),"
.BR curl_mime_data "(3)"
share/man/man3/CURLOPT_MAXAGE_CONN.3 0000644 00000005155 14751150700 0012340 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 2022 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_MAXAGE_CONN 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_MAXAGE_CONN \- max idle time allowed for reusing a connection
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXAGE_CONN, long age);
.fi
.SH DESCRIPTION
Pass a long as parameter containing \fIage\fP - the maximum time in seconds
that you allow an existing connection to have been idle to be considered for
reuse for this request.
The "connection cache" that holds previously used connections. When a new
request is to be done, it will consider any connection that matches for
reuse. The \fICURLOPT_MAXAGE_CONN(3)\fP limit prevents libcurl from trying too
old connections for reuse, since old connections have a high risk of not
working and thus trying them is a performance loss and sometimes service loss
due to the difficulties to figure out the situation. If a connection is found
in the cache that is older than this set \fIage\fP, it will instead be closed.
.SH DEFAULT
Default maximum age is set to 118 seconds.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* only allow 30 seconds idle time */
curl_easy_setopt(curl, CURLOPT_MAXAGE_CONN, 30L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.65.0
.SH RETURN VALUE
Returns CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_TIMEOUT "(3), " CURLOPT_FORBID_REUSE "(3), "
.BR CURLOPT_FRESH_CONNECT "(3), " CURLOPT_MAXLIFETIME_CONN "(3), "
share/man/man3/CURLOPT_CRLF.3 0000644 00000004040 14751150700 0011277 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_CRLF 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_CRLF \- CRLF conversion
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CRLF, long conv);
.fi
.SH DESCRIPTION
Pass a long. If the value is set to 1 (one), libcurl converts Unix newlines to
CRLF newlines on transfers. Disable this option again by setting the value to
0 (zero).
This is a legacy option of questionable use.
.SH DEFAULT
0
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode ret;
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/");
curl_easy_setopt(curl, CURLOPT_CRLF, 1L);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
SMTP since 7.40.0, other protocols since they were introduced
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_CONV_FROM_NETWORK_FUNCTION "(3), " CURLOPT_CONV_TO_NETWORK_FUNCTION "(3), "
share/man/man3/curl_global_sslset.3 0000644 00000011344 14751150700 0013230 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_global_sslset 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_global_sslset - Select SSL backend to use with libcurl
.SH SYNOPSIS
.nf
#include <curl/curl.h>
typedef struct {
curl_sslbackend id;
const char *name;
} curl_ssl_backend;
typedef enum {
CURLSSLBACKEND_NONE = 0,
CURLSSLBACKEND_OPENSSL = 1,
CURLSSLBACKEND_GNUTLS = 2,
CURLSSLBACKEND_NSS = 3,
CURLSSLBACKEND_GSKIT = 5,
CURLSSLBACKEND_POLARSSL = 6, /* deprecated */
CURLSSLBACKEND_WOLFSSL = 7,
CURLSSLBACKEND_SCHANNEL = 8,
CURLSSLBACKEND_SECURETRANSPORT = 9,
CURLSSLBACKEND_AXTLS = 10, /* deprecated */
CURLSSLBACKEND_MBEDTLS = 11,
CURLSSLBACKEND_MESALINK = 12,
CURLSSLBACKEND_BEARSSL = 13
} curl_sslbackend;
CURLsslset curl_global_sslset(curl_sslbackend id,
const char *name,
curl_ssl_backend ***avail);
.fi
.SH DESCRIPTION
This function configures at runtime which SSL backend to use with
libcurl. This function can only be used to select an SSL backend once, and it
must be called \fBbefore\fP \fIcurl_global_init(3)\fP.
The backend can be identified by the \fIid\fP
(e.g. \fBCURLSSLBACKEND_OPENSSL\fP). The backend can also be specified via the
\fIname\fP parameter for a case insensitive match (passing -1 as \fIid\fP). If
both \fIid\fP and \fIname\fP are specified, the \fIname\fP will be ignored.
If neither \fIid\fP nor \fPname\fP are specified, the function will fail with
\fBCURLSSLSET_UNKNOWN_BACKEND\fP and set the \fIavail\fP pointer to the
NULL-terminated list of available backends. The available backends are those
that this particular build of libcurl supports.
Since libcurl 7.60.0, the \fIavail\fP pointer will always be set to the list
of alternatives if non-NULL.
Upon success, the function returns \fBCURLSSLSET_OK\fP.
If the specified SSL backend is not available, the function returns
\fBCURLSSLSET_UNKNOWN_BACKEND\fP and sets the \fIavail\fP pointer to a
NULL-terminated list of available SSL backends. In this case, you may call the
function again to try to select a different backend.
The SSL backend can be set only once. If it has already been set, a subsequent
attempt to change it will result in a \fBCURLSSLSET_TOO_LATE\fP.
This function is thread-safe since libcurl 7.84.0 if
\fIcurl_version_info(3)\fP has the CURL_VERSION_THREADSAFE feature bit set
(most platforms).
If this is not thread-safe, you must not call this function when any other
thread in the program (i.e. a thread sharing the same memory) is running.
This does not 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.
.SH RETURN VALUE
If this function returns \fICURLSSLSET_OK\fP, 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.
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.
If this libcurl was built completely without SSL support, with no backends at
all, this function returns \fICURLSSLSET_NO_BACKENDS\fP.
.SH "SEE ALSO"
.BR curl_global_init "(3), "
.BR libcurl "(3) "
share/man/man3/CURLOPT_COOKIE.3 0000644 00000006552 14751150700 0011534 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_COOKIE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_COOKIE \- HTTP Cookie header
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIE, char *cookie);
.fi
.SH DESCRIPTION
Pass a pointer to a null-terminated string as parameter. It will be used to
set a cookie in the HTTP request. The format of the string should be
NAME=CONTENTS, where NAME is the cookie name and CONTENTS is what the cookie
should contain.
If you need to set multiple cookies, set them all using a single option
concatenated like this: "name1=content1; name2=content2;" etc.
This option sets the cookie header explicitly in the outgoing request(s). If
multiple requests are done due to authentication, followed redirections or
similar, they will all get this cookie passed on.
The cookies set by this option are separate from the internal cookie storage
held by the cookie engine and will not be modified by it. If you enable the
cookie engine and either you have imported a cookie of the same name (e.g. 'foo')
or the server has set one, it will have no effect on the cookies you set here.
A request to the server will send both the 'foo' held by the cookie engine and
the 'foo' held by this option. To set a cookie that is instead held by the
cookie engine and can be modified by the server use
\fICURLOPT_COOKIELIST(3)\fP.
Using this option multiple times will only make the latest string override the
previous ones.
This option will not enable the cookie engine. Use \fICURLOPT_COOKIEFILE(3)\fP
or \fICURLOPT_COOKIEJAR(3)\fP to enable parsing and sending cookies
automatically.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL, no cookies
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_COOKIE, "tool=curl; fun=yes;");
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
If HTTP is enabled
.SH RETURN VALUE
Returns CURLE_OK if HTTP is enabled, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_COOKIEFILE "(3), " CURLOPT_COOKIEJAR "(3), " CURLOPT_COOKIELIST "(3), "
.BR CURLOPT_HTTPHEADER "(3), "
share/man/man3/CURLOPT_CERTINFO.3 0000644 00000005556 14751150700 0011777 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_CERTINFO 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_CERTINFO \- request SSL certificate information
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CERTINFO, long certinfo);
.fi
.SH DESCRIPTION
Pass a long set to 1 to enable libcurl's certificate chain info gatherer. With
this enabled, libcurl will extract lots of information and data about the
certificates in the certificate chain used in the SSL connection. This data
may then be retrieved after a transfer using \fIcurl_easy_getinfo(3)\fP and
its option \fICURLINFO_CERTINFO(3)\fP.
.SH DEFAULT
0
.SH PROTOCOLS
All TLS-based
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://www.example.com/");
/* connect to any HTTPS site, trusted or not */
curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L);
curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L);
curl_easy_setopt(curl, CURLOPT_CERTINFO, 1L);
res = curl_easy_perform(curl);
if (!res) {
struct curl_certinfo *ci;
res = curl_easy_getinfo(curl, CURLINFO_CERTINFO, &ci);
if (!res) {
printf("%d certs!\\n", ci->num_of_certs);
for(i = 0; i < ci->num_of_certs; i++) {
struct curl_slist *slist;
for(slist = ci->certinfo[i]; slist; slist = slist->next)
printf("%s\\n", slist->data);
}
}
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
This option is supported by the OpenSSL, GnuTLS, Schannel, NSS, GSKit and
Secure Transport backends. Schannel support added in 7.50.0. Secure Transport
support added in 7.79.0.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_CAINFO "(3), " CURLOPT_SSL_VERIFYPEER "(3), "
share/man/man3/CURLINFO_APPCONNECT_TIME_T.3 0000644 00000005234 14751150700 0013403 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 2022 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_APPCONNECT_TIME_T 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_APPCONNECT_TIME_T \- get the time until the SSL/SSH handshake is completed
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_APPCONNECT_TIME_T,
curl_off_t *timep);
.fi
.SH DESCRIPTION
Pass a pointer to a curl_off_t to receive the time, in microseconds, it took
from the start until the SSL/SSH connect/handshake to the remote host was
completed. This time is most often close to the
\fICURLINFO_PRETRANSFER_TIME_T(3)\fP time, except for cases such as HTTP
pipelining where the pretransfer time can be delayed due to waits in line for
the pipeline and more.
When a redirect is followed, the time from each request is added together.
See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
curl_off_t connect;
curl_easy_setopt(curl, CURLOPT_URL, url);
res = curl_easy_perform(curl);
if(CURLE_OK == res) {
res = curl_easy_getinfo(curl, CURLINFO_APPCONNECT_TIME_T, &connect);
if(CURLE_OK == res) {
printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", connect / 1000000,
(long)(connect % 1000000));
}
}
/* always cleanup */
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.61.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), " CURLINFO_APPCONNECT_TIME "(3)"
share/man/man3/CURLOPT_ERRORBUFFER.3 0000644 00000006752 14751150700 0012350 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_ERRORBUFFER 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_ERRORBUFFER \- error buffer for error messages
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ERRORBUFFER, char *buf);
.fi
.SH DESCRIPTION
Pass a char * to a buffer that libcurl \fBmay\fP store human readable error
messages on failures or problems. This may be more helpful than just the
return code from \fIcurl_easy_perform(3)\fP and related functions. The buffer
\fBmust be at least CURL_ERROR_SIZE bytes big\fP.
You must keep the associated buffer available until libcurl no longer needs
it. Failing to do so will cause odd behavior or even crashes. libcurl will
need it until you call \fIcurl_easy_cleanup(3)\fP or you set the same option
again to use a different pointer.
Do not rely on the contents of the buffer unless an error code was returned.
Since 7.60.0 libcurl will initialize the contents of the error buffer to an
empty string before performing the transfer. For earlier versions if an error
code was returned but there was no error detail then the buffer is untouched.
Consider \fICURLOPT_VERBOSE(3)\fP and \fICURLOPT_DEBUGFUNCTION(3)\fP to better
debug and trace why errors happen.
.SH DEFAULT
NULL
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
CURLcode res;
char errbuf[CURL_ERROR_SIZE];
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* provide a buffer to store errors in */
curl_easy_setopt(curl, CURLOPT_ERRORBUFFER, errbuf);
/* set the error buffer as empty before performing a request */
errbuf[0] = 0;
/* perform the request */
res = curl_easy_perform(curl);
/* if the request did not complete correctly, show the error
information. if no detailed error information was written to errbuf
show the more generic information from curl_easy_strerror instead.
*/
if(res != CURLE_OK) {
size_t len = strlen(errbuf);
fprintf(stderr, "\\nlibcurl: (%d) ", res);
if(len)
fprintf(stderr, "%s%s", errbuf,
((errbuf[len - 1] != '\\n') ? "\\n" : ""));
else
fprintf(stderr, "%s\\n", curl_easy_strerror(res));
}
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_DEBUGFUNCTION "(3), " CURLOPT_VERBOSE "(3), "
.BR curl_easy_strerror "(3), " curl_multi_strerror "(3), "
.BR curl_share_strerror "(3), " curl_url_strerror "(3)"
share/man/man3/CURLOPT_CURLU.3 0000644 00000005106 14751150700 0011447 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_CURLU 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_CURLU \- URL in URL handle format
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CURLU, void *pointer);
.fi
.SH DESCRIPTION
Pass in a pointer to the \fIURL\fP to work with. The parameter should be a
\fICURLU *\fP. Setting \fICURLOPT_CURLU(3)\fP will explicitly override
\fICURLOPT_URL(3)\fP.
\fICURLOPT_URL(3)\fP or \fICURLOPT_CURLU(3)\fP \fBmust\fP be set before a
transfer is started.
libcurl will use this handle and its contents read-only and will not change
its contents. An application can update the contents of the URL handle after a
transfer is done and if the same handle is then used in a subsequent request
the updated contents will then be used.
.SH DEFAULT
The default value of this parameter is NULL.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *handle = curl_easy_init();
CURLU *urlp = curl_url();
int res = 0;
if(curl) {
res = curl_url_set(urlp, CURLUPART_URL, "https://example.com", 0);
curl_easy_setopt(handle, CURLOPT_CURLU, urlp);
ret = curl_easy_perform(handle);
curl_url_cleanup(urlp);
curl_easy_cleanup(handle);
}
.fi
.SH AVAILABILITY
Added in 7.63.0.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_URL "(3), "
.BR curl_url "(3), " curl_url_get "(3), " curl_url_set "(3), "
.BR curl_url_dup "(3), " curl_url_cleanup "(3), " curl_url_strerror "(3)"
share/man/man3/CURLOPT_UPLOAD_BUFFERSIZE.3 0000644 00000005430 14751150700 0013265 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_UPLOAD_BUFFERSIZE 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_UPLOAD_BUFFERSIZE \- upload buffer size
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UPLOAD_BUFFERSIZE, long size);
.fi
.SH DESCRIPTION
Pass a long specifying your preferred \fIsize\fP (in bytes) for the upload
buffer in libcurl. It makes libcurl uses a larger buffer that gets passed to
the next layer in the stack to get sent off. In some setups and for some
protocols, there's a huge performance benefit of having a larger upload
buffer.
This is just treated as a request, not an order. You cannot be guaranteed to
actually get the given size.
The upload buffer size is by default 64 kilobytes. The maximum buffer size
allowed to be set is 2 megabytes. The minimum buffer size allowed to be set is
16 kilobytes.
Since curl 7.61.1 the upload buffer is allocated on-demand - so if the handle
is not used for upload, this buffer will not be allocated at all.
DO NOT set this option on a handle that is currently used for an active
transfer as that may lead to unintended consequences.
.SH DEFAULT
65536 bytes
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/foo.bin");
/* ask libcurl to allocate a larger upload buffer */
curl_easy_setopt(curl, CURLOPT_UPLOAD_BUFFERSIZE, 120000L);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.62.0.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_BUFFERSIZE "(3), " CURLOPT_READFUNCTION "(3), "
share/man/man3/CURLINFO_SSL_VERIFYRESULT.3 0000644 00000004462 14751150700 0013336 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_SSL_VERIFYRESULT 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_SSL_VERIFYRESULT \- get the result of the certificate verification
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SSL_VERIFYRESULT,
long *result);
.fi
.SH DESCRIPTION
Pass a pointer to a long to receive the result of the server SSL certificate
verification that was requested (using the \fICURLOPT_SSL_VERIFYPEER(3)\fP
option).
0 is a positive result. Non-zero is an error.
.SH PROTOCOLS
All using TLS
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res;
long verifyresult;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
res = curl_easy_perform(curl);
curl_easy_getinfo(curl, CURLINFO_SSL_VERIFYRESULT, &verifyresult);
printf("The peer verification said %s\\n", verifyresult?
"BAAAD":"fine");
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.5. Only set by the OpenSSL/libressl/boringssl, NSS and GnuTLS backends.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
share/man/man3/libcurl.3 0000644 00000027121 14751150700 0011002 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH libcurl 3 "September 20, 2022" "libcurl 7.86.0" "libcurl overview"
.SH NAME
libcurl \- client-side URL transfers
.SH DESCRIPTION
This is a short overview on how to use libcurl in your C programs. There are
specific man pages for each function mentioned in here. See
\fIlibcurl-easy(3)\fP, \fIlibcurl-multi(3)\fP, \fIlibcurl-share(3)\fP,
\fIlibcurl-url(3)\fP and \fIlibcurl-tutorial(3)\fP for in-depth understanding
on how to program with libcurl.
There are many bindings available that bring libcurl access to your favorite
language. Look elsewhere for documentation on those.
libcurl has a global constant environment that you must set up and maintain
while using libcurl. This essentially means you call \fIcurl_global_init(3)\fP
at the start of your program and \fIcurl_global_cleanup(3)\fP at the end. See
\fBGLOBAL CONSTANTS\fP below for details.
If libcurl was compiled with support for multiple SSL backends, the function
\fIcurl_global_sslset(3)\fP can be called before \fIcurl_global_init(3)\fP
to select the active SSL backend.
To transfer files, you create an "easy handle" using \fIcurl_easy_init(3)\fP
for a single individual transfer (in either direction). You then set your
desired set of options in that handle with \fIcurl_easy_setopt(3)\fP. Options
you set with \fIcurl_easy_setopt(3)\fP stick. They will be used on every
repeated use of this handle until you either change the option, or you reset
them all with \fIcurl_easy_reset(3)\fP.
To actually transfer data you have the option of using the "easy" interface,
or the "multi" interface.
The easy interface is a synchronous interface with which you call
\fIcurl_easy_perform(3)\fP and let it perform the transfer. When it is
completed, the function returns and you can continue. More details are found in
the \fIlibcurl-easy(3)\fP man page.
The multi interface on the other hand is an asynchronous interface, that you
call and that performs only a little piece of the transfer on each invoke. It
is perfect if you want to do things while the transfer is in progress, or
similar. The multi interface allows you to select() on libcurl action, and
even to easily download multiple files simultaneously using a single
thread. See further details in the \fIlibcurl-multi(3)\fP man page.
You can have multiple easy handles share certain data, even if they are used
in different threads. This magic is setup using the share interface, as
described in the \fIlibcurl-share(3)\fP man page.
There is also a series of other helpful functions to use, including these:
.RS
.IP curl_version_info()
gets detailed libcurl (and other used libraries) version info
.IP curl_getdate()
converts a date string to time_t
.IP curl_easy_getinfo()
get information about a performed transfer
.IP curl_formadd()
helps building an HTTP form POST
.IP curl_formfree()
free a list built with \fIcurl_formadd(3)\fP
.IP curl_slist_append()
builds a linked list
.IP curl_slist_free_all()
frees a whole curl_slist
.IP curl_url_set()
parses a URL
.RE
.SH "LINKING WITH LIBCURL"
On unix-like machines, there's a tool named curl-config that gets installed
with the rest of the curl stuff when 'make install' is performed.
curl-config is added to make it easier for applications to link with libcurl
and developers to learn about libcurl and how to use it.
Run 'curl-config --libs' to get the (additional) linker options you need to
link with the particular version of libcurl you have installed. See the
\fIcurl-config(1)\fP man page for further details.
Unix-like operating system that ship libcurl as part of their distributions
often do not provide the curl-config tool, but simply install the library and
headers in the common path for this purpose.
Many Linux and similar systems use pkg-config to provide build and link
options about libraries and libcurl supports that as well.
.SH "LIBCURL SYMBOL NAMES"
All public functions in the libcurl interface are prefixed with 'curl_' (with
a lowercase c). You can find other functions in the library source code, but
other prefixes indicate that the functions are private and may change without
further notice in the next release.
Only use documented functions and functionality!
.SH "PORTABILITY"
libcurl works
.B exactly
the same, on any of the platforms it compiles and builds on.
.SH "THREADS"
libcurl is thread safe but there are a few exceptions. Refer to
\fIlibcurl-thread(3)\fP for more information.
.SH "PERSISTENT CONNECTIONS"
Persistent connections means that libcurl can re-use the same connection for
several transfers, if the conditions are right.
libcurl will \fBalways\fP attempt to use persistent connections. Whenever you
use \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP etc, libcurl
will attempt to use an existing connection to do the transfer, and if none
exists it will open a new one that will be subject for re-use on a possible
following call to \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP.
To allow libcurl to take full advantage of persistent connections, you should
do as many of your file transfers as possible using the same handle.
If you use the easy interface, and you call \fIcurl_easy_cleanup(3)\fP, all
the possibly open connections held by libcurl will be closed and forgotten.
When you have created a multi handle and are using the multi interface, the
connection pool is instead kept in the multi handle so closing and creating
new easy handles to do transfers will not affect them. Instead all added easy
handles can take advantage of the single shared pool.
.SH "GLOBAL CONSTANTS"
There are a variety of constants that libcurl uses, mainly through its
internal use of other libraries, which are too complicated for the
library loader to set up. Therefore, a program must call a library
function after the program is loaded and running to finish setting up
the library code. For example, when libcurl is built for SSL
capability via the GNU TLS library, there is an elaborate tree inside
that library that describes the SSL protocol.
\fIcurl_global_init(3)\fP is the function that you must call. This may
allocate resources (e.g. the memory for the GNU TLS tree mentioned above), so
the companion function \fIcurl_global_cleanup(3)\fP releases them.
The global constant functions are thread-safe since libcurl 7.84.0 if
\fIcurl_version_info(3)\fP has the CURL_VERSION_THREADSAFE feature bit set
(most platforms). Read \fIlibcurl-thread(3)\fP for thread safety guidelines.
If the global constant functions are \fInot thread safe\fP, then you must
not call them when any other thread in the program is running. It
is not good enough that no other thread is using libcurl at the time,
because these functions internally call similar functions of other
libraries, and those functions are similarly thread-unsafe. You cannot
generally know what these libraries are, or whether other threads are
using them.
If the global constant functions are \fInot thread safe\fP, then the basic rule
for constructing a program that uses libcurl is this: Call
\fIcurl_global_init(3)\fP, with a \fICURL_GLOBAL_ALL\fP argument, immediately
after the program starts, while it is still only one thread and before it uses
libcurl at all. Call \fIcurl_global_cleanup(3)\fP immediately before the
program exits, when the program is again only one thread and after its last
use of libcurl.
It is not actually required that the functions be called at the beginning
and end of the program -- that is just usually the easiest way to do it.
You can call both of these multiple times, as long as all calls meet
these requirements and the number of calls to each is the same.
The global constant situation merits special consideration when the
code you are writing to use libcurl is not the main program, but rather
a modular piece of a program, e.g. another library. As a module,
your code does not know about other parts of the program -- it does not
know whether they use libcurl or not. And its code does not necessarily
run at the start and end of the whole program.
A module like this must have global constant functions of its own, just like
\fIcurl_global_init(3)\fP and \fIcurl_global_cleanup(3)\fP. The module thus
has control at the beginning and end of the program and has a place to call
the libcurl functions. If multiple modules in the program use libcurl, they
all will separately call the libcurl functions, and that is OK because only
the first \fIcurl_global_init(3)\fP and the last \fIcurl_global_cleanup(3)\fP
in a program change anything. (libcurl uses a reference count in static
memory).
In a C++ module, it is common to deal with the global constant situation by
defining a special class that represents the global constant environment of
the module. A program always has exactly one object of the class, in static
storage. That way, the program automatically calls the constructor of the
object as the program starts up and the destructor as it terminates. As the
author of this libcurl-using module, you can make the constructor call
\fIcurl_global_init(3)\fP and the destructor call \fIcurl_global_cleanup(3)\fP
and satisfy libcurl's requirements without your user having to think about it.
(Caveat: If you are initializing libcurl from a Windows DLL you should not
initialize it from \fIDllMain\fP or a static initializer because Windows holds
the loader lock during that time and it could cause a deadlock.)
\fIcurl_global_init(3)\fP has an argument that tells what particular parts of
the global constant environment to set up. In order to successfully use any
value except \fICURL_GLOBAL_ALL\fP (which says to set up the whole thing), you
must have specific knowledge of internal workings of libcurl and all other
parts of the program of which it is part.
A special part of the global constant environment is the identity of the
memory allocator. \fIcurl_global_init(3)\fP selects the system default memory
allocator, but you can use \fIcurl_global_init_mem(3)\fP to supply one of your
own. However, there is no way to use \fIcurl_global_init_mem(3)\fP in a
modular program -- all modules in the program that might use libcurl would
have to agree on one allocator.
There is a failsafe in libcurl that makes it usable in simple situations
without you having to worry about the global constant environment at all:
\fIcurl_easy_init(3)\fP sets up the environment itself if it has not been done
yet. The resources it acquires to do so get released by the operating system
automatically when the program exits.
This failsafe feature exists mainly for backward compatibility because there
was a time when the global functions did not exist. Because it is sufficient
only in the simplest of programs, it is not recommended for any program to
rely on it.
share/man/man3/CURLOPT_DNS_USE_GLOBAL_CACHE.3 0000644 00000004655 14751150700 0013630 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_DNS_USE_GLOBAL_CACHE 3 "October 12, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_DNS_USE_GLOBAL_CACHE \- global DNS cache
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_USE_GLOBAL_CACHE,
long enable);
.fi
.SH DESCRIPTION
Has no function since 7.62.0. Do not use!
Pass a long. If the \fIenable\fP value is 1, it tells curl to use a global DNS
cache that will survive between easy handle creations and deletions. This is
not thread-safe and this will use a global variable.
\fBWARNING:\fP this option is considered obsolete. Stop using it. Switch over
to using the share interface instead! See \fICURLOPT_SHARE(3)\fP and
\fIcurl_share_init(3)\fP.
.SH DEFAULT
0
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode ret;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
/* switch off the use of a global, thread unsafe, cache */
curl_easy_setopt(curl, CURLOPT_DNS_USE_GLOBAL_CACHE, 0L);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Deprecated since 7.11.1. Function removed in 7.62.0.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_SHARE "(3), " CURLOPT_DNS_CACHE_TIMEOUT "(3), "
share/man/man3/CURLINFO_CONTENT_LENGTH_UPLOAD.3 0000644 00000004533 14751150700 0014070 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_CONTENT_LENGTH_UPLOAD 3 "October 12, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_CONTENT_LENGTH_UPLOAD \- get the specified size of the upload
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONTENT_LENGTH_UPLOAD,
double *content_length);
.fi
.SH DESCRIPTION
Pass a pointer to a double to receive the specified size of the upload. Since
7.19.4, this returns -1 if the size is not known.
\fICURLINFO_CONTENT_LENGTH_UPLOAD_T(3)\fP is a newer replacement that returns a
more sensible variable type.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* Perform the upload */
res = curl_easy_perform(curl);
if(!res) {
/* check the size */
double cl;
res = curl_easy_getinfo(curl, CURLINFO_CONTENT_LENGTH_UPLOAD, &cl);
if(!res) {
printf("Size: %.0f\\n", cl);
}
}
}
.fi
.SH AVAILABILITY
Added in 7.6.1. Deprecated since 7.55.0.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
.BR CURLINFO_CONTENT_LENGTH_DOWNLOAD_T "(3), "
share/man/man3/CURLINFO_HEADER_SIZE.3 0000644 00000004362 14751150700 0012433 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_HEADER_SIZE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_HEADER_SIZE \- get size of retrieved headers
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_HEADER_SIZE, long *sizep);
.fi
.SH DESCRIPTION
Pass a pointer to a long to receive the total size of all the headers
received. Measured in number of bytes.
The total includes the size of any received headers suppressed by
\fICURLOPT_SUPPRESS_CONNECT_HEADERS(3)\fP.
.SH PROTOCOLS
All
.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);
if(res == CURLE_OK) {
long size;
res = curl_easy_getinfo(curl, CURLINFO_HEADER_SIZE, &size);
if(!res)
printf("Header size: %ld bytes\\n", size);
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.4.1
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
.BR CURLINFO_REQUEST_SIZE "(3), "
.BR CURLINFO_SIZE_DOWNLOAD "(3), "
share/man/man3/curl_share_setopt.3 0000644 00000004335 14751150700 0013075 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_share_setopt 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_share_setopt - Set options for a shared object
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLSHcode curl_share_setopt(CURLSH *share, CURLSHoption option, parameter);
.fi
.SH DESCRIPTION
Set the \fIoption\fP to \fIparameter\fP for the given \fIshare\fP.
.SH OPTIONS
.IP CURLSHOPT_LOCKFUNC
See \fICURLSHOPT_LOCKFUNC(3)\fP.
.IP CURLSHOPT_UNLOCKFUNC
See \fICURLSHOPT_UNLOCKFUNC(3)\fP.
.IP CURLSHOPT_SHARE
See \fICURLSHOPT_SHARE(3)\fP.
.IP CURLSHOPT_UNSHARE
See \fICURLSHOPT_UNSHARE(3)\fP.
.IP CURLSHOPT_USERDATA
See \fICURLSHOPT_USERDATA(3)\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
Added in 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
man page for the full list with descriptions.
.SH "SEE ALSO"
.BR curl_share_cleanup "(3), " curl_share_init "(3)"
share/man/man3/CURLOPT_DISALLOW_USERNAME_IN_URL.3 0000644 00000004227 14751150700 0014405 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_DISALLOW_USERNAME_IN_URL 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_DISALLOW_USERNAME_IN_URL \- disallow specifying username in the URL
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DISALLOW_USERNAME_IN_URL,
long disallow);
.fi
.SH DESCRIPTION
A long parameter set to 1 tells the library to not allow URLs that include a
username.
.SH DEFAULT
0 (disabled) - user names are allowed by default.
.SH PROTOCOLS
Several
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_DISALLOW_USERNAME_IN_URL, 1L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.61.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
curl_easy_perform() will return CURLE_LOGIN_DENIED if this option is enabled
and a URL containing a username is specified.
.SH "SEE ALSO"
.BR libcurl-security "(3), ", CURLOPT_PROTOCOLS "(3)"
share/man/man3/CURLOPT_IGNORE_CONTENT_LENGTH.3 0000644 00000005247 14751150700 0014001 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_IGNORE_CONTENT_LENGTH 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_IGNORE_CONTENT_LENGTH \- ignore content length
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_IGNORE_CONTENT_LENGTH,
long ignore);
.SH DESCRIPTION
If \fIignore\fP is set to 1L, ignore the Content-Length header in the HTTP
response and ignore asking for or relying on it for FTP transfers.
This is useful for HTTP with Apache 1.x (and similar servers) which will
report incorrect content length for files over 2 gigabytes. If this option is
used, curl will not be able to accurately report progress, and will simply
stop the download when the server ends the connection.
It is also useful with FTP when for example the file is growing while the
transfer is in progress which otherwise will unconditionally cause libcurl to
report error.
Only use this option if strictly necessary.
.SH DEFAULT
0
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* we know the server is silly, ignore content-length */
curl_easy_setopt(curl, CURLOPT_IGNORE_CONTENT_LENGTH, 1L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.14.1. Support for FTP added in 7.46.0. This option is not working
for HTTP when libcurl is built to use the hyper backend.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_HTTP_VERSION "(3), " CURLOPT_MAXFILESIZE_LARGE "(3), "
share/man/man3/curl_url_dup.3 0000644 00000003742 14751150700 0012050 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_url_dup 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_url_dup - duplicate a URL handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLU *curl_url_dup(CURLU *inhandle);
.fi
.SH DESCRIPTION
Duplicates a given \fICURLU\fP \fIinhandle\fP and all its contents and returns
a pointer to a new \fICURLU\fP handle. The new handle also needs to be freed
with \fIcurl_url_cleanup(3)\fP.
.SH EXAMPLE
.nf
CURLUcode rc;
CURLU *url = curl_url();
CURLU *url2;
rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
if(!rc) {
url2 = curl_url_dup(url); /* clone it! */
curl_url_cleanup(url2);
}
curl_url_cleanup(url);
.fi
.SH AVAILABILITY
Added in 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), "
share/man/man3/CURLINFO_CONNECT_TIME_T.3 0000644 00000004627 14751150700 0013047 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 2022 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_CONNECT_TIME_T 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_CONNECT_TIME_T \- get the time until connect
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_CONNECT_TIME_T,
curl_off_t *timep);
.fi
.SH DESCRIPTION
Pass a pointer to a curl_off_t to receive the total time in microseconds from
the start until the connection to the remote host (or proxy) was completed.
When a redirect is followed, the time from each request is added together.
See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
curl_off_t connect;
curl_easy_setopt(curl, CURLOPT_URL, url);
res = curl_easy_perform(curl);
if(CURLE_OK == res) {
res = curl_easy_getinfo(curl, CURLINFO_CONNECT_TIME_T, &connect);
if(CURLE_OK == res) {
printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", connect / 1000000,
(long)(connect % 1000000));
}
}
/* always cleanup */
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.61.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), " CURLINFO_CONNECT_TIME "(3)"
share/man/man3/curl_getdate.3 0000644 00000012141 14751150700 0012004 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_getdate 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_getdate - Convert a date string to number of seconds
.SH SYNOPSIS
.nf
#include <curl/curl.h>
time_t curl_getdate(char *datestring, time_t *now);
.fi
.SH DESCRIPTION
\fIcurl_getdate(3)\fP returns the number of seconds since the Epoch, January
1st 1970 00:00:00 in the UTC time zone, for the date and time that the
\fIdatestring\fP parameter specifies. The \fInow\fP parameter is not used,
pass a NULL there.
This function works with valid dates and does not always detect and reject
wrong dates, such as February 30.
.SH PARSING DATES AND TIMES
A "date" is a string containing several items separated by whitespace. The
order of the items is immaterial. A date string may contain many flavors of
items:
.TP 0.8i
.B calendar date items
Can be specified several ways. Month names can only be three-letter English
abbreviations, numbers can be zero-prefixed and the year may use 2 or 4
digits. Examples: 06 Nov 1994, 06-Nov-94 and Nov-94 6.
.TP
.B time of the day items
This string specifies the time on a given day. You must specify it with 6
digits with two colons: HH:MM:SS. To not include the time in a date string,
will make the function assume 00:00:00. Example: 18:19:21.
.TP
.B time zone items
Specifies international time zone. There are a few acronyms supported, but in
general you should instead use the specific relative time compared to
UTC. Supported formats include: -1200, MST, +0100.
.TP
.B day of the week items
Specifies a day of the week. Days of the week may be spelled out in full
(using English): `Sunday', `Monday', etc or they may be abbreviated to their
first three letters. This is usually not info that adds anything.
.TP
.B pure numbers
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.
.SH EXAMPLE
.nf
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 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 \fIasctime()\fP 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.
On systems with a signed 32 bit time_t: if the year is larger than 2037 or
less than 1903, this function will return -1.
On systems with an unsigned 32 bit time_t: if the year is larger than 2106 or
less than 1970, this function will return -1.
On systems with 64 bit time_t: if the year is less than 1583, this function
will return -1. (The Gregorian calendar was first introduced 1582 so no "real"
dates in this way of doing dates existed before then.)
.SH "SEE ALSO"
.BR curl_easy_escape "(3), " curl_easy_unescape "(3), "
.BR CURLOPT_TIMECONDITION "(3), " CURLOPT_TIMEVALUE "(3) "
share/man/man3/CURLOPT_REQUEST_TARGET.3 0000644 00000004110 14751150700 0012745 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_REQUEST_TARGET 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_REQUEST_TARGET \- alternative target for this request
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_REQUEST_TARGET, string);
.fi
.SH DESCRIPTION
Pass a char * to string which libcurl uses in the upcoming request instead of
the path as extracted from the URL.
.SH DEFAULT
NULL
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/*");
curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "OPTIONS");
/* issue an OPTIONS * request (no leading slash) */
curl_easy_setopt(curl, CURLOPT_REQUEST_TARGET, "*");
/* Perform the request */
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.55.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_CUSTOMREQUEST "(3), " CURLOPT_HTTPGET "(3), "
share/man/man3/curl_mime_subparts.3 0000644 00000005467 14751150700 0013256 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_mime_subparts 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_mime_subparts - set sub-parts of a multipart mime part
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_mime_subparts(curl_mimepart *part, curl_mime *subparts);
.fi
.SH DESCRIPTION
\fIcurl_mime_subparts(3)\fP sets a multipart mime part's content from a mime
structure.
\fIpart\fP is a handle to the multipart part.
\fIsubparts\fP is a mime structure handle holding the sub-parts. After
\fIcurl_mime_subparts\fP succeeds, the mime structure handle belongs to the
multipart part and must not be freed explicitly. It may however be updated by
subsequent calls to mime API functions.
Setting a part's contents multiple times 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 email. */
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 "SEE ALSO"
.BR curl_mime_addpart "(3),"
.BR curl_mime_init "(3)"
share/man/man3/CURLOPT_PROGRESSDATA.3 0000644 00000004601 14751150700 0012452 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROGRESSDATA 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROGRESSDATA \- pointer passed to the progress callback
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROGRESSDATA, void *pointer);
.fi
.SH DESCRIPTION
Pass a \fIpointer\fP that will be untouched by libcurl and passed as the first
argument in the progress callback set with \fICURLOPT_PROGRESSFUNCTION(3)\fP.
.SH DEFAULT
The default value of this parameter is NULL.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
struct progress {
char *private;
size_t size;
};
static size_t progress_callback(void *clientp,
double dltotal,
double dlnow,
double ultotal,
double ulnow)
{
struct memory *progress = (struct progress *)userp;
/* use the values */
return 0; /* all is good */
}
struct progress data;
/* pass struct to callback */
curl_easy_setopt(curl_handle, CURLOPT_PROGRESSDATA, &data);
curl_easy_setopt(curl_handle, CURLOPT_PROGRESSFUNCTION, progress_callback);
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_PROGRESSFUNCTION "(3), " CURLOPT_XFERINFOFUNCTION "(3), "
share/man/man3/CURLOPT_ISSUERCERT_BLOB.3 0000644 00000006516 14751150700 0013051 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_ISSUERCERT_BLOB 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_ISSUERCERT_BLOB \- issuer SSL certificate from memory blob
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ISSUERCERT_BLOB,
struct curl_blob *stblob);
.fi
.SH DESCRIPTION
Pass a pointer to a curl_blob structure, which contains information (pointer
and size) about a memory block with binary data of a CA certificate in PEM
format. If the option is set, an additional check against the peer certificate
is performed to verify the issuer is indeed the one associated with the
certificate provided by the option. This additional check is useful in
multi-level PKI where one needs to enforce that the peer certificate is from a
specific branch of the tree.
This option should be used in combination with the
\fICURLOPT_SSL_VERIFYPEER(3)\fP option. Otherwise, the result of the check is
not considered as failure.
A specific error code (CURLE_SSL_ISSUER_ERROR) is defined with the option,
which is returned if the setup of the SSL/TLS session has failed due to a
mismatch with the issuer of peer certificate (\fICURLOPT_SSL_VERIFYPEER(3)\fP
has to be set too for the check to fail).
If the blob is initialized with the flags member of struct curl_blob set to
CURL_BLOB_COPY, the application does not have to keep the buffer around after
setting this.
This option is an alternative to \fICURLOPT_ISSUERCERT(3)\fP which instead
expects a file name as input.
.SH DEFAULT
NULL
.SH PROTOCOLS
All TLS-based protocols
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
struct curl_blob blob;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
blob.data = certificateData;
blob.len = filesize;
blob.flags = CURL_BLOB_COPY;
curl_easy_setopt(curl, CURLOPT_ISSUERCERT_BLOB, &blob);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.71.0. This option is supported by the OpenSSL backends.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_ISSUERCERT "(3),"
.BR CURLOPT_CRLFILE "(3), " CURLOPT_SSL_VERIFYPEER "(3), "
share/man/man3/CURLINFO_REDIRECT_TIME.3 0000644 00000004616 14751150700 0012672 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_REDIRECT_TIME 3 "September 22, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_REDIRECT_TIME \- get the time for all redirection steps
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_REDIRECT_TIME,
double *timep);
.fi
.SH DESCRIPTION
Pass a pointer to a double to receive the total time, in seconds, it took for
all redirection steps include name lookup, connect, pretransfer and transfer
before final transaction was started. \fICURLINFO_REDIRECT_TIME(3)\fP contains
the complete execution time for multiple redirections.
See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
double redirect;
curl_easy_setopt(curl, CURLOPT_URL, url);
res = curl_easy_perform(curl);
if(CURLE_OK == res) {
res = curl_easy_getinfo(curl, CURLINFO_REDIRECT_TIME, &redirect);
if(CURLE_OK == res) {
printf("Time: %.1f", redirect);
}
}
/* always cleanup */
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.9.7
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), " CURLINFO_REDIRECT_TIME_T "(3)"
share/man/man3/CURLOPT_RTSP_TRANSPORT.3 0000644 00000004645 14751150700 0013030 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_RTSP_TRANSPORT 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_RTSP_TRANSPORT \- RTSP Transport: header
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_TRANSPORT,
char *transport);
.SH DESCRIPTION
Pass a char * to tell libcurl what to pass for the Transport: header for this
RTSP session. This is mainly a convenience method to avoid needing to set a
custom Transport: header for every SETUP request. The application must set a
Transport: header before issuing a SETUP request.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL
.SH PROTOCOLS
RTSP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/");
curl_easy_setopt(curl, CURLOPT_RTSP_REQUEST, CURL_RTSPREQ_SETUP);
curl_easy_setopt(curl, CURLOPT_RTSP_TRANSPORT,
"RTP/AVP;unicast;client_port=4588-4589");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.20.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_RTSP_REQUEST "(3), " CURLOPT_RTSP_SESSION_ID "(3), "
share/man/man3/CURLOPT_PUT.3 0000644 00000004723 14751150700 0011231 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PUT 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PUT \- make an HTTP PUT request
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PUT, long put);
.fi
.SH DESCRIPTION
A parameter set to 1 tells the library to use HTTP PUT to transfer data. The
data should be set with \fICURLOPT_READDATA(3)\fP and
\fICURLOPT_INFILESIZE(3)\fP.
This option is \fBdeprecated\fP since version 7.12.1. Use
\fICURLOPT_UPLOAD(3)\fP!
.SH DEFAULT
0, disabled
.SH PROTOCOLS
HTTP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
/* we want to use our own read function */
curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_callback);
/* enable PUT */
curl_easy_setopt(curl, CURLOPT_PUT, 1L);
/* specify target */
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/to/newfile");
/* now specify which pointer to pass to our callback */
curl_easy_setopt(curl, CURLOPT_READDATA, hd_src);
/* Set the size of the file to upload */
curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, (curl_off_t)fsize);
/* Now run off and do what you have been told! */
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Deprecated since 7.12.1. Do not use.
.SH RETURN VALUE
Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_UPLOAD "(3), " CURLOPT_HTTPGET "(3), "
share/man/man3/CURLINFO_SCHEME.3 0000644 00000004600 14751150700 0011610 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_SCHEME 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_SCHEME \- get the URL scheme (sometimes called protocol) used in the connection
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SCHEME, char **scheme);
.fi
.SH DESCRIPTION
Pass a pointer to a char pointer to receive the pointer to a null-terminated
string holding the URL scheme used for the most recent connection done with
this CURL \fBhandle\fP.
The \fBscheme\fP pointer will be NULL or pointing to private memory you MUST
NOT free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the
corresponding CURL handle.
.SH PROTOCOLS
All
.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);
if(res == CURLE_OK) {
char *scheme = NULL;
curl_easy_getinfo(curl, CURLINFO_SCHEME, &scheme);
if(scheme)
printf("scheme: %s\\n", scheme); /* scheme: HTTP */
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.52.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLINFO_RESPONSE_CODE "(3), "
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
share/man/man3/CURLOPT_SSL_VERIFYSTATUS.3 0000644 00000004655 14751150700 0013256 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SSL_VERIFYSTATUS 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSL_VERIFYSTATUS \- verify the certificate's status
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_VERIFYSTATUS, long verify);
.fi
.SH DESCRIPTION
Pass a long as parameter set to 1 to enable or 0 to disable.
This option determines whether libcurl verifies the status of the server cert
using the "Certificate Status Request" TLS extension (aka. OCSP stapling).
Note that if this option is enabled but the server does not support the TLS
extension, the verification will fail.
.SH DEFAULT
0
.SH PROTOCOLS
All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
/* ask for OCSP stapling! */
curl_easy_setopt(curl, CURLOPT_SSL_VERIFYSTATUS, 1L);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.41.0. This option is currently only supported by the OpenSSL, GnuTLS
and NSS TLS backends.
.SH RETURN VALUE
Returns CURLE_OK if OCSP stapling is supported by the SSL backend, otherwise
returns CURLE_NOT_BUILT_IN.
.SH "SEE ALSO"
.BR CURLOPT_SSL_VERIFYHOST "(3), "
.BR CURLOPT_SSL_VERIFYPEER "(3), "
.BR CURLOPT_CAINFO "(3), "
share/man/man3/CURLOPT_COPYPOSTFIELDS.3 0000644 00000005632 14751150700 0012730 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_COPYPOSTFIELDS 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_COPYPOSTFIELDS \- have libcurl copy data to POST
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COPYPOSTFIELDS, char *data);
.fi
.SH DESCRIPTION
Pass a char * as parameter, which should be the full \fIdata\fP to post in a
HTTP POST operation. It behaves as the \fICURLOPT_POSTFIELDS(3)\fP option, but
the original data is instead copied by the library, allowing the application
to overwrite the original data after setting this option.
Because data are copied, care must be taken when using this option in
conjunction with \fICURLOPT_POSTFIELDSIZE(3)\fP or
\fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP: If the size has not been set prior to
\fICURLOPT_COPYPOSTFIELDS(3)\fP, the data is assumed to be a null-terminated
string; else the stored size informs the library about the byte count to
copy. In any case, the size must not be changed after
\fICURLOPT_COPYPOSTFIELDS(3)\fP, unless another \fICURLOPT_POSTFIELDS(3)\fP or
\fICURLOPT_COPYPOSTFIELDS(3)\fP option is issued.
.SH DEFAULT
NULL
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
char local_buffer[1024]="data to send";
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* size of the data to copy from the buffer and send in the request */
curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, 12L);
/* send data from the local stack */
curl_easy_setopt(curl, CURLOPT_COPYPOSTFIELDS, local_buffer);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.17.1
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_POSTFIELDS "(3), " CURLOPT_POSTFIELDSIZE "(3), "
share/man/man3/CURLOPT_RESUME_FROM.3 0000644 00000005242 14751150700 0012401 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_RESUME_FROM 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_RESUME_FROM \- offset to resume transfer from
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RESUME_FROM, long from);
.fi
.SH DESCRIPTION
Pass a long as parameter. It contains the offset in number of bytes that you
want the transfer to start from. Set this option to 0 to make the transfer
start from the beginning (effectively disabling resume). For FTP, set this
option to -1 to make the transfer start from the end of the target file
(useful to continue an interrupted upload).
When doing uploads with FTP, the resume position is where in the local/source
file libcurl should try to resume the upload from and it will then append the
source file to the remote target file.
If you need to resume a transfer beyond the 2GB limit, use
\fICURLOPT_RESUME_FROM_LARGE(3)\fP instead.
.SH DEFAULT
0, not used
.SH PROTOCOLS
HTTP, FTP, SFTP, FILE
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com");
/* resume upload at byte index 200 */
curl_easy_setopt(curl, CURLOPT_RESUME_FROM, 200L);
/* ask for upload */
curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L);
/* set total data amount to expect */
curl_easy_setopt(curl, CURLOPT_INFILESIZE, size_of_file);
/* Perform the request */
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_RESUME_FROM_LARGE "(3), " CURLOPT_RANGE "(3), "
.BR CURLOPT_INFILESIZE "(3), "
share/man/man3/CURLINFO_SIZE_UPLOAD.3 0000644 00000004367 14751150700 0012474 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_SIZE_UPLOAD 3 "October 12, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_SIZE_UPLOAD \- get the number of uploaded bytes
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_SIZE_UPLOAD,
double *uploadp);
.fi
.SH DESCRIPTION
Pass a pointer to a double to receive the total amount of bytes that were
uploaded.
\fICURLINFO_SIZE_UPLOAD_T(3)\fP is a newer replacement that returns a more
sensible variable type.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
/* Perform the request */
res = curl_easy_perform(curl);
if(!res) {
double ul;
res = curl_easy_getinfo(curl, CURLINFO_SIZE_UPLOAD, &ul);
if(!res) {
printf("Uploaded %.0f bytes\\n", ul);
}
}
}
.fi
.SH AVAILABILITY
Added in 7.4.1. Deprecated since 7.55.0.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
.BR CURLINFO_SIZE_DOWNLOAD_T "(3), " CURLINFO_SIZE_UPLOAD_T "(3), "
share/man/man3/CURLOPT_RESOLVER_START_DATA.3 0000644 00000004475 14751150700 0013574 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_RESOLVER_START_DATA 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_RESOLVER_START_DATA \- pointer passed to the resolver start callback
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RESOLVER_START_DATA,
void *pointer);
.fi
.SH DESCRIPTION
Pass a \fIpointer\fP that will be untouched by libcurl and passed as the third
argument in the resolver start callback set with
\fICURLOPT_RESOLVER_START_FUNCTION(3)\fP.
.SH DEFAULT
NULL
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
static int resolver_start_cb(void *resolver_state, void *reserved,
void *userdata)
{
(void)reserved;
printf("Received resolver_state=%p userdata=%p\\n",
resolver_state, userdata);
return 0;
}
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_RESOLVER_START_FUNCTION, resolver_start_cb);
curl_easy_setopt(curl, CURLOPT_RESOLVER_START_DATA, curl);
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.59.0
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_RESOLVER_START_FUNCTION "(3) "
share/man/man3/curl_formfree.3 0000644 00000005017 14751150700 0012200 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_formfree 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_formfree - free a previously build multipart form post chain
.SH SYNOPSIS
.nf
#include <curl/curl.h>
void curl_formfree(struct curl_httppost *form);
.fi
.SH DESCRIPTION
This function is deprecated. Do not use. See \fIcurl_mime_init(3)\fP instead!
curl_formfree() is used to clean up data previously built/appended with
\fIcurl_formadd(3)\fP. This must be called when the data has been used, which
typically means after \fIcurl_easy_perform(3)\fP has been called.
The pointer to free is the same pointer you passed to the
\fICURLOPT_HTTPPOST(3)\fP option, which is the \fIfirstitem\fP pointer from
the \fIcurl_formadd(3)\fP invoke(s).
\fBform\fP is the pointer as returned from a previous call to
\fIcurl_formadd(3)\fP and may be NULL.
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
None
.SH "SEE ALSO"
.BR curl_formadd "(3), " curl_mime_init "(3), " curl_mime_free "(3)"
share/man/man3/CURLOPT_PROGRESSFUNCTION.3 0000644 00000010437 14751150700 0013172 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROGRESSFUNCTION 3 "October 12, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROGRESSFUNCTION \- progress meter callback
.SH SYNOPSIS
.nf
#include <curl/curl.h>
int progress_callback(void *clientp,
double dltotal,
double dlnow,
double ultotal,
double ulnow);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROGRESSFUNCTION,
progress_callback);
.fi
.SH DESCRIPTION
Pass a pointer to your callback function, which should match the prototype
shown above.
This option is deprecated and we encourage users to use the
newer \fICURLOPT_XFERINFOFUNCTION(3)\fP instead, if you can.
This function gets called by libcurl instead of its internal equivalent with a
frequent interval. While data is being transferred it will be called
frequently, and during slow periods like when nothing is being transferred it
can slow down to about one call per second.
\fIclientp\fP is the pointer set with \fICURLOPT_PROGRESSDATA(3)\fP, it is not
used by libcurl but is only passed along from the application to the callback.
The callback gets told how much data libcurl will transfer and has
transferred, in number of bytes. \fIdltotal\fP is the total number of bytes
libcurl expects to download in this transfer. \fIdlnow\fP is the number of
bytes downloaded so far. \fIultotal\fP is the total number of bytes libcurl
expects to upload in this transfer. \fIulnow\fP is the number of bytes
uploaded so far.
Unknown/unused argument values passed to the callback will be set to zero
(like if you only download data, the upload size will remain 0). Many times
the callback will be called one or more times first, before it knows the data
sizes so a program must be made to handle that.
If your callback function returns CURL_PROGRESSFUNC_CONTINUE it will cause
libcurl to continue executing the default progress function.
Returning any other non-zero value from this callback will cause libcurl to
abort the transfer and return \fICURLE_ABORTED_BY_CALLBACK\fP.
If you transfer data with the multi interface, this function will not be
called during periods of idleness unless you call the appropriate libcurl
function that performs transfers.
\fICURLOPT_NOPROGRESS(3)\fP must be set to 0 to make this function actually
get called.
.SH DEFAULT
By default, libcurl has an internal progress meter. That is rarely wanted by
users.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
struct progress {
char *private;
size_t size;
};
static size_t progress_callback(void *clientp,
double dltotal,
double dlnow,
double ultotal,
double ulnow)
{
struct progress *memory = (struct progress *)clientp;
/* use the values */
return 0; /* all is good */
}
struct progress data;
/* pass struct to callback */
curl_easy_setopt(curl_handle, CURLOPT_PROGRESSDATA, &data);
curl_easy_setopt(curl_handle, CURLOPT_PROGRESSFUNCTION, progress_callback);
.fi
.SH AVAILABILITY
Deprecated in 7.32.0.
.SH RETURN VALUE
Returns CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_VERBOSE "(3), " CURLOPT_NOPROGRESS "(3), "
share/man/man3/CURLOPT_SEEKDATA.3 0000644 00000004126 14751150700 0011737 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SEEKDATA 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SEEKDATA \- pointer passed to the seek callback
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SEEKDATA, void *pointer);
.fi
.SH DESCRIPTION
Data \fIpointer\fP to pass to the seek callback function. If you use the
\fICURLOPT_SEEKFUNCTION(3)\fP option, this is the pointer you will get as
input.
.SH DEFAULT
If you do not set this, NULL is passed to the callback.
.SH PROTOCOLS
HTTP, FTP, SFTP
.SH EXAMPLE
.nf
static int seek_cb(void *userp, curl_off_t offset, int origin)
{
struct data *d = (struct data *)userp;
lseek(d->our_fd, offset, origin);
return CURL_SEEKFUNC_OK;
}
{
struct data seek_data;
curl_easy_setopt(CURL *handle, CURLOPT_SEEKFUNCTION, seek_cb);
curl_easy_setopt(CURL *handle, CURLOPT_SEEKDATA, &seek_data);
}
.fi
.SH AVAILABILITY
Added in 7.18.0
.SH RETURN VALUE
.SH "SEE ALSO"
.BR CURLOPT_STDERR "(3), " CURLOPT_DEBUGFUNCTION "(3), "
share/man/man3/curl_multi_perform.3 0000644 00000010403 14751150700 0013252 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_multi_perform 3 "August 15, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_multi_perform - reads/writes available data from easy handles
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_perform(CURLM *multi_handle, int *running_handles);
.fi
.SH DESCRIPTION
This function performs transfers on all the added handles that need attention
in a non-blocking fashion. The easy handles have previously been added to the
multi handle with \fIcurl_multi_add_handle(3)\fP.
When an application has found out there's data available for the multi_handle
or a timeout has elapsed, the application should call this function to
read/write whatever there is to read or write right now etc.
\fIcurl_multi_perform(3)\fP returns as soon as the reads/writes are done. This
function does not require that there actually is any data available for
reading or that data can be written, it can be called just in case. It will
store the number of handles that still transfer data in the second argument's
integer-pointer.
If the amount of \fIrunning_handles\fP is changed from the previous call (or
is less than the amount of easy handles you have added to the multi handle),
you know that there is one or more transfers less "running". You can then call
\fIcurl_multi_info_read(3)\fP to get information about each individual
completed transfer, and that returned info includes CURLcode and more. If an
added handle fails quickly, it may never be counted as a running_handle. You
could use \fIcurl_multi_info_read(3)\fP to track actual status of the added
handles in that case.
When \fIrunning_handles\fP is set to zero (0) on the return of this function,
there is no longer any transfers in progress.
When this function returns error, the state of all transfers are uncertain and
they cannot be continued. \fIcurl_multi_perform(3)\fP should not be called
again on the same multi handle after an error has been returned, unless first
removing all the handles and adding new ones.
.SH EXAMPLE
.nf
int still_running;
do {
CURLMcode mc = curl_multi_perform(multi_handle, &still_running);
if(!mc && still_running)
/* wait for activity, timeout or "nothing" */
mc = curl_multi_poll(multi_handle, NULL, 0, 1000, NULL);
if(mc) {
fprintf(stderr, "curl_multi_poll() failed, code %d.\\n", (int)mc);
break;
}
/* if there are still transfers, loop! */
} while(still_running);
.fi
.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
individual transfers may have occurred even when this function returns
\fICURLM_OK\fP. Use \fIcurl_multi_info_read(3)\fP to figure out how individual
transfers did.
.SH "TYPICAL USAGE"
Most applications will use \fIcurl_multi_poll(3)\fP to make libcurl wait for
activity on any of the ongoing transfers. As soon as one or more file
descriptor has activity or the function times out, the application calls
\fIcurl_multi_perform(3)\fP.
.SH "SEE ALSO"
.BR curl_multi_cleanup "(3), " curl_multi_init "(3), "
.BR curl_multi_wait "(3), " curl_multi_add_handle "(3), "
.BR curl_multi_fdset "(3), " curl_multi_info_read "(3), "
.BR libcurl-errors "(3)"
share/man/man3/libcurl-errors.3 0000644 00000044206 14751150700 0012317 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH libcurl-errors 3 "September 20, 2022" "libcurl 7.86.0" "libcurl errors"
.SH NAME
libcurl-errors \- error codes in libcurl
.SH DESCRIPTION
This man page includes most, if not all, available error codes in libcurl.
Why they occur and possibly what you can do to fix the problem are also included.
.SH "CURLcode"
Almost all "easy" interface functions return a CURLcode error code. No matter
what, using the \fIcurl_easy_setopt(3)\fP option \fICURLOPT_ERRORBUFFER(3)\fP
is a good idea as it will give you a human readable error string that may
offer more details about the cause of the error than just the error code.
\fIcurl_easy_strerror(3)\fP can be called to get an error string from a given
CURLcode number.
CURLcode is one of the following:
.IP "CURLE_OK (0)"
All fine. Proceed as usual.
.IP "CURLE_UNSUPPORTED_PROTOCOL (1)"
The URL you passed to libcurl used a protocol that this libcurl does not
support. The support might be a compile-time option that you did not use, it
can be a misspelled protocol string or just a protocol libcurl has no code
for.
.IP "CURLE_FAILED_INIT (2)"
Early initialization code failed. This is likely to be an internal error or
problem, or a resource problem where something fundamental could not get done
at init time.
.IP "CURLE_URL_MALFORMAT (3)"
The URL was not properly formatted.
.IP "CURLE_NOT_BUILT_IN (4)"
A requested feature, protocol or option was not found built-in in this libcurl
due to a build-time decision. This means that a feature or option was not
enabled or explicitly disabled when libcurl was built and in order to get it
to function you have to get a rebuilt libcurl.
.IP "CURLE_COULDNT_RESOLVE_PROXY (5)"
Could not resolve proxy. The given proxy host could not be resolved.
.IP "CURLE_COULDNT_RESOLVE_HOST (6)"
Could not resolve host. The given remote host was not resolved.
.IP "CURLE_COULDNT_CONNECT (7)"
Failed to connect() to host or proxy.
.IP "CURLE_WEIRD_SERVER_REPLY (8)"
The server sent data libcurl could not parse. This error code was known as as
\fICURLE_FTP_WEIRD_SERVER_REPLY\fP before 7.51.0.
.IP "CURLE_REMOTE_ACCESS_DENIED (9)"
We were denied access to the resource given in the URL. For FTP, this occurs
while trying to change to the remote directory.
.IP "CURLE_FTP_ACCEPT_FAILED (10)"
While waiting for the server to connect back when an active FTP session is
used, an error code was sent over the control connection or similar.
.IP "CURLE_FTP_WEIRD_PASS_REPLY (11)"
After having sent the FTP password to the server, libcurl expects a proper
reply. This error code indicates that an unexpected code was returned.
.IP "CURLE_FTP_ACCEPT_TIMEOUT (12)"
During an active FTP session while waiting for the server to connect, the
\fICURLOPT_ACCEPTTIMEOUT_MS(3)\fP (or the internal default) timeout expired.
.IP "CURLE_FTP_WEIRD_PASV_REPLY (13)"
libcurl failed to get a sensible result back from the server as a response to
either a PASV or a EPSV command. The server is flawed.
.IP "CURLE_FTP_WEIRD_227_FORMAT (14)"
FTP servers return a 227-line as a response to a PASV command. If libcurl
fails to parse that line, this return code is passed back.
.IP "CURLE_FTP_CANT_GET_HOST (15)"
An internal failure to lookup the host used for the new connection.
.IP "CURLE_HTTP2 (16)"
A problem was detected in the HTTP2 framing layer. This is somewhat generic
and can be one out of several problems, see the error buffer for details.
.IP "CURLE_FTP_COULDNT_SET_TYPE (17)"
Received an error when trying to set the transfer mode to binary or ASCII.
.IP "CURLE_PARTIAL_FILE (18)"
A file transfer was shorter or larger than expected. This happens when the
server first reports an expected transfer size, and then delivers data that
does not match the previously given size.
.IP "CURLE_FTP_COULDNT_RETR_FILE (19)"
This was either a weird reply to a 'RETR' command or a zero byte transfer
complete.
.IP "Obsolete error (20)"
Not used in modern versions.
.IP "CURLE_QUOTE_ERROR (21)"
When sending custom "QUOTE" commands to the remote server, one of the commands
returned an error code that was 400 or higher (for FTP) or otherwise
indicated unsuccessful completion of the command.
.IP "CURLE_HTTP_RETURNED_ERROR (22)"
This is returned if \fICURLOPT_FAILONERROR(3)\fP is set TRUE and the HTTP
server returns an error code that is >= 400.
.IP "CURLE_WRITE_ERROR (23)"
An error occurred when writing received data to a local file, or an error was
returned to libcurl from a write callback.
.IP "Obsolete error (24)"
Not used in modern versions.
.IP "CURLE_UPLOAD_FAILED (25)"
Failed starting the upload. For FTP, the server typically denied the STOR
command. The error buffer usually contains the server's explanation for this.
.IP "CURLE_READ_ERROR (26)"
There was a problem reading a local file or an error returned by the read
callback.
.IP "CURLE_OUT_OF_MEMORY (27)"
A memory allocation request failed. This is serious badness and
things are severely screwed up if this ever occurs.
.IP "CURLE_OPERATION_TIMEDOUT (28)"
Operation timeout. The specified time-out period was reached according to the
conditions.
.IP "Obsolete error (29)"
Not used in modern versions.
.IP "CURLE_FTP_PORT_FAILED (30)"
The FTP PORT command returned error. This mostly happens when you have not
specified a good enough address for libcurl to use. See
\fICURLOPT_FTPPORT(3)\fP.
.IP "CURLE_FTP_COULDNT_USE_REST (31)"
The FTP REST command returned error. This should never happen if the server is
sane.
.IP "Obsolete error (32)"
Not used in modern versions.
.IP "CURLE_RANGE_ERROR (33)"
The server does not support or accept range requests.
.IP "CURLE_HTTP_POST_ERROR (34)"
This is an odd error that mainly occurs due to internal confusion.
.IP "CURLE_SSL_CONNECT_ERROR (35)"
A problem occurred somewhere in the SSL/TLS handshake. You really want the
error buffer and read the message there as it pinpoints the problem slightly
more. Could be certificates (file formats, paths, permissions), passwords, and
others.
.IP "CURLE_BAD_DOWNLOAD_RESUME (36)"
The download could not be resumed because the specified offset was out of the
file boundary.
.IP "CURLE_FILE_COULDNT_READ_FILE (37)"
A file given with FILE:// could not be opened. Most likely because the file
path does not identify an existing file. Did you check file permissions?
.IP "CURLE_LDAP_CANNOT_BIND (38)"
LDAP cannot bind. LDAP bind operation failed.
.IP "CURLE_LDAP_SEARCH_FAILED (39)"
LDAP search failed.
.IP "Obsolete error (40)"
Not used in modern versions.
.IP "CURLE_FUNCTION_NOT_FOUND (41)"
Function not found. A required zlib function was not found.
.IP "CURLE_ABORTED_BY_CALLBACK (42)"
Aborted by callback. A callback returned "abort" to libcurl.
.IP "CURLE_BAD_FUNCTION_ARGUMENT (43)"
A function was called with a bad parameter.
.IP "Obsolete error (44)"
Not used in modern versions.
.IP "CURLE_INTERFACE_FAILED (45)"
Interface error. A specified outgoing interface could not be used. Set which
interface to use for outgoing connections' source IP address with
\fICURLOPT_INTERFACE(3)\fP.
.IP "Obsolete error (46)"
Not used in modern versions.
.IP "CURLE_TOO_MANY_REDIRECTS (47)"
Too many redirects. When following redirects, libcurl hit the maximum amount.
Set your limit with \fICURLOPT_MAXREDIRS(3)\fP.
.IP "CURLE_UNKNOWN_OPTION (48)"
An option passed to libcurl is not recognized/known. Refer to the appropriate
documentation. This is most likely a problem in the program that uses
libcurl. The error buffer might contain more specific information about which
exact option it concerns.
.IP "CURLE_SETOPT_OPTION_SYNTAX (49)"
An option passed in to a setopt was wrongly formatted. See error message for
details about what option.
.IP "Obsolete errors (50-51)"
Not used in modern versions.
.IP "CURLE_GOT_NOTHING (52)"
Nothing was returned from the server, and under the circumstances, getting
nothing is considered an error.
.IP "CURLE_SSL_ENGINE_NOTFOUND (53)"
The specified crypto engine was not found.
.IP "CURLE_SSL_ENGINE_SETFAILED (54)"
Failed setting the selected SSL crypto engine as default.
.IP "CURLE_SEND_ERROR (55)"
Failed sending network data.
.IP "CURLE_RECV_ERROR (56)"
Failure with receiving network data.
.IP "Obsolete error (57)"
Not used in modern versions.
.IP "CURLE_SSL_CERTPROBLEM (58)"
problem with the local client certificate.
.IP "CURLE_SSL_CIPHER (59)"
Could not use specified cipher.
.IP "CURLE_PEER_FAILED_VERIFICATION (60)"
The remote server's SSL certificate or SSH fingerprint was deemed not OK.
This error code has been unified with CURLE_SSL_CACERT since 7.62.0. Its
previous value was 51.
.IP "CURLE_BAD_CONTENT_ENCODING (61)"
Unrecognized transfer encoding.
.IP "Obsolete error (62)"
Not used in modern versions.
.IP "CURLE_FILESIZE_EXCEEDED (63)"
Maximum file size exceeded.
.IP "CURLE_USE_SSL_FAILED (64)"
Requested FTP SSL level failed.
.IP "CURLE_SEND_FAIL_REWIND (65)"
When doing a send operation curl had to rewind the data to retransmit, but the
rewinding operation failed.
.IP "CURLE_SSL_ENGINE_INITFAILED (66)"
Initiating the SSL Engine failed.
.IP "CURLE_LOGIN_DENIED (67)"
The remote server denied curl to login (Added in 7.13.1)
.IP "CURLE_TFTP_NOTFOUND (68)"
File not found on TFTP server.
.IP "CURLE_TFTP_PERM (69)"
Permission problem on TFTP server.
.IP "CURLE_REMOTE_DISK_FULL (70)"
Out of disk space on the server.
.IP "CURLE_TFTP_ILLEGAL (71)"
Illegal TFTP operation.
.IP "CURLE_TFTP_UNKNOWNID (72)"
Unknown TFTP transfer ID.
.IP "CURLE_REMOTE_FILE_EXISTS (73)"
File already exists and will not be overwritten.
.IP "CURLE_TFTP_NOSUCHUSER (74)"
This error should never be returned by a properly functioning TFTP server.
.IP "Obsolete error (75-76)"
Not used in modern versions.
.IP "CURLE_SSL_CACERT_BADFILE (77)"
Problem with reading the SSL CA cert (path? access rights?)
.IP "CURLE_REMOTE_FILE_NOT_FOUND (78)"
The resource referenced in the URL does not exist.
.IP "CURLE_SSH (79)"
An unspecified error occurred during the SSH session.
.IP "CURLE_SSL_SHUTDOWN_FAILED (80)"
Failed to shut down the SSL connection.
.IP "CURLE_AGAIN (81)"
Socket is not ready for send/recv wait till it's ready and try again. This
return code is only returned from \fIcurl_easy_recv(3)\fP and
\fIcurl_easy_send(3)\fP (Added in 7.18.2)
.IP "CURLE_SSL_CRL_BADFILE (82)"
Failed to load CRL file (Added in 7.19.0)
.IP "CURLE_SSL_ISSUER_ERROR (83)"
Issuer check failed (Added in 7.19.0)
.IP "CURLE_FTP_PRET_FAILED (84)"
The FTP server does not understand the PRET command at all or does not support
the given argument. Be careful when using \fICURLOPT_CUSTOMREQUEST(3)\fP, a
custom LIST command will be sent with the PRET command before PASV as
well. (Added in 7.20.0)
.IP "CURLE_RTSP_CSEQ_ERROR (85)"
Mismatch of RTSP CSeq numbers.
.IP "CURLE_RTSP_SESSION_ERROR (86)"
Mismatch of RTSP Session Identifiers.
.IP "CURLE_FTP_BAD_FILE_LIST (87)"
Unable to parse FTP file list (during FTP wildcard downloading).
.IP "CURLE_CHUNK_FAILED (88)"
Chunk callback reported error.
.IP "CURLE_NO_CONNECTION_AVAILABLE (89)"
(For internal use only, will never be returned by libcurl) No connection
available, the session will be queued. (added in 7.30.0)
.IP "CURLE_SSL_PINNEDPUBKEYNOTMATCH (90)"
Failed to match the pinned key specified with \fICURLOPT_PINNEDPUBLICKEY(3)\fP.
.IP "CURLE_SSL_INVALIDCERTSTATUS (91)"
Status returned failure when asked with \fICURLOPT_SSL_VERIFYSTATUS(3)\fP.
.IP "CURLE_HTTP2_STREAM (92)"
Stream error in the HTTP/2 framing layer.
.IP "CURLE_RECURSIVE_API_CALL (93)"
An API function was called from inside a callback.
.IP "CURLE_AUTH_ERROR (94)"
An authentication function returned an error.
.IP "CURLE_HTTP3 (95)"
A problem was detected in the HTTP/3 layer. This is somewhat generic and can
be one out of several problems, see the error buffer for details.
.IP "CURLE_QUIC_CONNECT_ERROR (96)"
QUIC connection error. This error may be caused by an SSL library error. QUIC
is the protocol used for HTTP/3 transfers.
.IP "CURLE_PROXY (97)"
Proxy handshake error. \fICURLINFO_PROXY_ERROR(3)\fP provides extra details on
the specific problem.
.IP "CURLE_SSL_CLIENTCERT (98)"
SSL Client Certificate required.
.IP "CURLE_UNRECOVERABLE_POLL (99)"
An internal call to poll() or select() returned error that is not recoverable.
.IP "CURLE_OBSOLETE*"
These error codes will never be returned. They were used in an old libcurl
version and are currently unused.
.SH "CURLMcode"
This is the generic return code used by functions in the libcurl multi
interface. Also consider \fIcurl_multi_strerror(3)\fP.
.IP "CURLM_CALL_MULTI_PERFORM (-1)"
This is not really an error. It means you should call
\fIcurl_multi_perform(3)\fP again without doing select() or similar in
between. Before version 7.20.0 (released on February 9 2010) this could be returned by
\fIcurl_multi_perform(3)\fP, but in later versions this return code is never
used.
.IP "CURLM_CALL_MULTI_SOCKET (-1)"
An alias for \fICURLM_CALL_MULTI_PERFORM\fP. Never returned by modern libcurl
versions.
.IP "CURLM_OK (0)"
Things are fine.
.IP "CURLM_BAD_HANDLE (1)"
The passed-in handle is not a valid \fICURLM\fP handle.
.IP "CURLM_BAD_EASY_HANDLE (2)"
An easy handle was not good/valid. It could mean that it is not an easy handle
at all, or possibly that the handle already is in use by this or another multi
handle.
.IP "CURLM_OUT_OF_MEMORY (3)"
You are doomed.
.IP "CURLM_INTERNAL_ERROR (4)"
This can only be returned if libcurl bugs. Please report it to us!
.IP "CURLM_BAD_SOCKET (5)"
The passed-in socket is not a valid one that libcurl already knows about.
(Added in 7.15.4)
.IP "CURLM_UNKNOWN_OPTION (6)"
curl_multi_setopt() with unsupported option
(Added in 7.15.4)
.IP "CURLM_ADDED_ALREADY (7)"
An easy handle already added to a multi handle was attempted to get added a
second time. (Added in 7.32.1)
.IP "CURLM_RECURSIVE_API_CALL (8)"
An API function was called from inside a callback.
.IP "CURLM_WAKEUP_FAILURE (9)"
Wake up is unavailable or failed.
.IP "CURLM_BAD_FUNCTION_ARGUMENT (10)"
A function was called with a bad parameter.
.IP "CURLM_ABORTED_BY_CALLBACK (11)"
A multi handle callback returned error.
.IP "CURLM_UNRECOVERABLE_POLL (12)"
An internal call to poll() or select() returned error that is not recoverable.
.SH "CURLSHcode"
The "share" interface will return a \fBCURLSHcode\fP to indicate when an error
has occurred. Also consider \fIcurl_share_strerror(3)\fP.
.IP "CURLSHE_OK (0)"
All fine. Proceed as usual.
.IP "CURLSHE_BAD_OPTION (1)"
An invalid option was passed to the function.
.IP "CURLSHE_IN_USE (2)"
The share object is currently in use.
.IP "CURLSHE_INVALID (3)"
An invalid share object was passed to the function.
.IP "CURLSHE_NOMEM (4)"
Not enough memory was available.
(Added in 7.12.0)
.IP "CURLSHE_NOT_BUILT_IN (5)"
The requested sharing could not be done because the library you use do not have
that particular feature enabled. (Added in 7.23.0)
.SH "CURLUcode"
The URL interface will return a \fICURLUcode\fP to indicate when an error has
occurred. Also consider \fIcurl_url_strerror(3)\fP.
.IP "CURLUE_BAD_HANDLE (1)"
An invalid URL handle was passed as argument.
.IP "CURLUE_BAD_PARTPOINTER (2)"
An invalid 'part' argument was passed as argument.
.IP "CURLUE_MALFORMED_INPUT (3)"
A malformed input was passed to a URL API function.
.IP "CURLUE_BAD_PORT_NUMBER (4)"
The port number was not a decimal number between 0 and 65535.
.IP "CURLUE_UNSUPPORTED_SCHEME (5)"
This libcurl build does not support the given URL scheme.
.IP "CURLUE_URLDECODE (6)"
URL decode error, most likely because of rubbish in the input.
.IP "CURLUE_OUT_OF_MEMORY (7)"
A memory function failed.
.IP "CURLUE_USER_NOT_ALLOWED (8)"
Credentials was passed in the URL when prohibited.
.IP "CURLUE_UNKNOWN_PART (9)"
An unknown part ID was passed to a URL API function.
.IP "CURLUE_NO_SCHEME (10)"
There is no scheme part in the URL.
.IP "CURLUE_NO_USER (11)"
There is no user part in the URL.
.IP "CURLUE_NO_PASSWORD (12)"
There is no password part in the URL.
.IP "CURLUE_NO_OPTIONS (13)"
There is no options part in the URL.
.IP "CURLUE_NO_HOST (14)"
There is no host part in the URL.
.IP "CURLUE_NO_PORT (15)"
There is no port part in the URL.
.IP "CURLUE_NO_QUERY (16)"
There is no query part in the URL.
.IP "CURLUE_NO_FRAGMENT (17)"
There is no fragment part in the URL.
.IP "CURLUE_NO_ZONEID (18)"
There is no zone id set in the URL.
.IP "CURLUE_BAD_FILE_URL (19)"
The file:// URL is invalid.
.IP "CURLUE_BAD_FRAGMENT (20)"
The fragment part of the URL contained bad or invalid characters.
.IP "CURLUE_BAD_HOSTNAME (21)"
The hostname contained bad or invalid characters.
.IP "CURLUE_BAD_IPV6 (22)"
The IPv6 address hostname contained bad or invalid characters.
.IP "CURLUE_BAD_LOGIN (23)"
The login part of the URL contained bad or invalid characters.
.IP "CURLUE_BAD_PASSWORD (24)"
The password part of the URL contained bad or invalid characters.
.IP "CURLUE_BAD_PATH (25)"
The path part of the URL contained bad or invalid characters.
.IP "CURLUE_BAD_QUERY (26)"
The query part of the URL contained bad or invalid characters.
.IP "CURLUE_BAD_SCHEME (27)"
The scheme part of the URL contained bad or invalid characters.
.IP "CURLUE_BAD_SLASHES (28)"
The URL contained an invalid number of slashes.
.IP "CURLUE_BAD_USER (29)"
The user part of the URL contained bad or invalid characters.
.SH "SEE ALSO"
.BR curl_easy_strerror "(3), " curl_multi_strerror "(3), "
.BR curl_share_strerror "(3), " curl_url_strerror "(3), "
.BR CURLOPT_ERRORBUFFER "(3), " CURLOPT_VERBOSE "(3), "
.BR CURLOPT_DEBUGFUNCTION "(3)"
share/man/man3/CURLMOPT_TIMERDATA.3 0000644 00000005071 14751150700 0012205 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLMOPT_TIMERDATA 3 "May 17, 2022" "libcurl 7.86.0" "curl_multi_setopt options"
.SH NAME
CURLMOPT_TIMERDATA \- custom pointer to pass to timer callback
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_TIMERDATA, void *pointer);
.SH DESCRIPTION
A data \fBpointer\fP to pass to the timer callback set with the
\fICURLMOPT_TIMERFUNCTION(3)\fP option.
This pointer will not be touched by libcurl but will only be passed in to the
timer callbacks's \fBuserp\fP argument.
.SH DEFAULT
NULL
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
static gboolean timeout_cb(gpointer user_data)
{
int running;
if(user_data) {
g_free(user_data);
curl_multi_setopt(curl_handle, CURLMOPT_TIMERDATA, NULL);
}
curl_multi_socket_action(multi, CURL_SOCKET_TIMEOUT, 0, &running);
return G_SOURCE_REMOVE;
}
static int timerfunc(CURLM *multi, long timeout_ms, void *userp)
{
guint *id = userp;
if(id)
g_source_remove(*id);
/* -1 means we should just delete our timer. */
if(timeout_ms == -1) {
g_free(id);
id = NULL;
}
else {
if(!id)
id = g_new(guint, 1);
*id = g_timeout_add(timeout_ms, timeout_cb, id);
}
current_timer = id;
return 0;
}
curl_multi_setopt(multi, CURLMOPT_TIMERFUNCTION, timerfunc);
.fi
.SH AVAILABILITY
Added in 7.16.0
.SH RETURN VALUE
Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLMOPT_TIMERFUNCTION "(3), " CURLMOPT_SOCKETFUNCTION "(3), "
share/man/man3/CURLOPT_TLSAUTH_USERNAME.3 0000644 00000005002 14751150700 0013173 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_TLSAUTH_USERNAME 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_TLSAUTH_USERNAME \- user name to use for TLS authentication
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TLSAUTH_USERNAME, char *user);
.fi
.SH DESCRIPTION
Pass a char * as parameter, which should point to the null-terminated username
to use for the TLS authentication method specified with the
\fICURLOPT_TLSAUTH_TYPE(3)\fP option. Requires that the
\fICURLOPT_TLSAUTH_PASSWORD(3)\fP option also be set.
The application does not have to keep the string around after setting this
option.
This feature relies in TLS SRP which does not work with TLS 1.3.
.SH DEFAULT
NULL
.SH PROTOCOLS
All TLS-based protocols
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_TLSAUTH_TYPE, "SRP");
curl_easy_setopt(curl, CURLOPT_TLSAUTH_USERNAME, "user");
curl_easy_setopt(curl, CURLOPT_TLSAUTH_PASSWORD, "secret");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.21.4, with the OpenSSL and GnuTLS backends only
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_TLSAUTH_TYPE "(3), " CURLOPT_TLSAUTH_PASSWORD "(3), "
share/man/man3/CURLOPT_OPENSOCKETDATA.3 0000644 00000006035 14751150700 0012663 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_OPENSOCKETDATA 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_OPENSOCKETDATA \- pointer passed to open socket callback
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_OPENSOCKETDATA, void *pointer);
.fi
.SH DESCRIPTION
Pass a \fIpointer\fP that will be untouched by libcurl and passed as the first
argument in the open socket callback set with
\fICURLOPT_OPENSOCKETFUNCTION(3)\fP.
.SH DEFAULT
The default value of this parameter is NULL.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
/* make libcurl use the already established socket 'sockfd' */
static curl_socket_t opensocket(void *clientp,
curlsocktype purpose,
struct curl_sockaddr *address)
{
curl_socket_t sockfd;
sockfd = *(curl_socket_t *)clientp;
/* the actual externally set socket is passed in via the OPENSOCKETDATA
option */
return sockfd;
}
static int sockopt_callback(void *clientp, curl_socket_t curlfd,
curlsocktype purpose)
{
/* This return code was added in libcurl 7.21.5 */
return CURL_SOCKOPT_ALREADY_CONNECTED;
}
curl = curl_easy_init();
if(curl) {
/* libcurl will internally think that you connect to the host
* and port that you specify in the URL option. */
curl_easy_setopt(curl, CURLOPT_URL, "http://99.99.99.99:9999");
/* call this function to get a socket */
curl_easy_setopt(curl, CURLOPT_OPENSOCKETFUNCTION, opensocket);
curl_easy_setopt(curl, CURLOPT_OPENSOCKETDATA, &sockfd);
/* call this function to set options for the socket */
curl_easy_setopt(curl, CURLOPT_SOCKOPTFUNCTION, sockopt_callback);
res = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.17.1
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_OPENSOCKETFUNCTION "(3), " CURLOPT_SOCKOPTFUNCTION "(3), "
share/man/man3/CURLOPT_RTSP_REQUEST.3 0000644 00000012667 14751150700 0012567 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_RTSP_REQUEST 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_RTSP_REQUEST \- RTSP request
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_REQUEST, long request);
.fi
.SH DESCRIPTION
Tell libcurl what kind of RTSP request to make. Pass one of the following RTSP
enum values as a long in the \fIrequest\fP argument. Unless noted otherwise,
commands require the Session ID to be initialized.
.IP CURL_RTSPREQ_OPTIONS
Used to retrieve the available methods of the server. The application is
responsible for parsing and obeying the response. The session ID is not needed
for this method.
.IP CURL_RTSPREQ_DESCRIBE
Used to get the low level description of a stream. The application should note
what formats it understands in the \fI'Accept:'\fP header. Unless set
manually, libcurl will automatically fill in \fI'Accept: application/sdp'\fP.
Time-condition headers will be added to Describe requests if the
\fICURLOPT_TIMECONDITION(3)\fP option is active. \fB(The session ID is not
needed for this method)\fP
.IP CURL_RTSPREQ_ANNOUNCE
When sent by a client, this method changes the description of the session. For
example, if a client is using the server to record a meeting, the client can
use Announce to inform the server of all the meta-information about the
session. ANNOUNCE acts like an HTTP PUT or POST just like
\fICURL_RTSPREQ_SET_PARAMETER\fP
.IP CURL_RTSPREQ_SETUP
Setup is used to initialize the transport layer for the session. The
application must set the desired Transport options for a session by using the
\fICURLOPT_RTSP_TRANSPORT(3)\fP option prior to calling setup. If no session
ID is currently set with \fICURLOPT_RTSP_SESSION_ID(3)\fP, libcurl will
extract and use the session ID in the response to this request. The session ID
is not needed for this method.
.IP CURL_RTSPREQ_PLAY
Send a Play command to the server. Use the \fICURLOPT_RANGE(3)\fP option to
modify the playback time (e.g. \fInpt=10-15\fP).
.IP CURL_RTSPREQ_PAUSE
Send a Pause command to the server. Use the \fICURLOPT_RANGE(3)\fP option with
a single value to indicate when the stream should be
halted. (e.g. \fInpt=25\fP)
.IP CURL_RTSPREQ_TEARDOWN
This command terminates an RTSP session. Simply closing a connection does not
terminate the RTSP session since it is valid to control an RTSP session over
different connections.
.IP CURL_RTSPREQ_GET_PARAMETER
Retrieve a parameter from the server. By default, libcurl will automatically
include a \fIContent-Type: text/parameters\fP header on all non-empty requests
unless a custom one is set. GET_PARAMETER acts just like an HTTP PUT or POST
(see \fICURL_RTSPREQ_SET_PARAMETER\fP).
Applications wishing to send a heartbeat message (e.g. in the presence of a
server-specified timeout) should send use an empty GET_PARAMETER request.
.IP CURL_RTSPREQ_SET_PARAMETER
Set a parameter on the server. By default, libcurl will automatically include
a \fIContent-Type: text/parameters\fP header unless a custom one is set. The
interaction with SET_PARAMETER is much like an HTTP PUT or POST. An application
may either use \fICURLOPT_UPLOAD(3)\fP with \fICURLOPT_READDATA(3)\fP like a
HTTP PUT, or it may use \fICURLOPT_POSTFIELDS(3)\fP like an HTTP POST. No
chunked transfers are allowed, so the application must set the
\fICURLOPT_INFILESIZE(3)\fP in the former and \fICURLOPT_POSTFIELDSIZE(3)\fP
in the latter. Also, there is no use of multi-part POSTs within RTSP.
.IP CURL_RTSPREQ_RECORD
Used to tell the server to record a session. Use the \fICURLOPT_RANGE(3)\fP
option to modify the record time.
.IP CURL_RTSPREQ_RECEIVE
This is a special request because it does not send any data to the server. The
application may call this function in order to receive interleaved RTP
data. It will return after processing one read buffer of data in order to give
the application a chance to run.
.SH DEFAULT
.SH PROTOCOLS
RTSP
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/");
/* ask for options! */
curl_easy_setopt(curl, CURLOPT_RTSP_REQUEST, CURL_RTSPREQ_OPTIONS);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.20.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_RTSP_SESSION_ID "(3), " CURLOPT_RTSP_STREAM_URI "(3), "
share/man/man3/CURLOPT_LOCALPORTRANGE.3 0000644 00000004713 14751150700 0012674 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_LOCALPORTRANGE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_LOCALPORTRANGE \- number of additional local ports to try
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_LOCALPORTRANGE,
long range);
.fi
.SH DESCRIPTION
Pass a long. The \fIrange\fP argument is the number of attempts libcurl will
make to find a working local port number. It starts with the given
\fICURLOPT_LOCALPORT(3)\fP and adds one to the number for each retry. Setting
this option to 1 or below will make libcurl do only one try for the exact port
number. Port numbers by nature are scarce resources that will be busy at times
so setting this value to something too low might cause unnecessary connection
setup failures.
.SH DEFAULT
1
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
curl_easy_setopt(curl, CURLOPT_LOCALPORT, 49152L);
/* and try 20 more ports following that */
curl_easy_setopt(curl, CURLOPT_LOCALPORTRANGE, 20L);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.15.2
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_LOCALPORT "(3), " CURLOPT_INTERFACE "(3), "
share/man/man3/curl_easy_init.3 0000644 00000005020 14751150700 0012351 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_easy_init 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_easy_init - Start a libcurl easy session
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURL *curl_easy_init();
.fi
.SH DESCRIPTION
This function must be the first function to call, and it returns a CURL easy
handle that you must use as input to other functions in the easy
interface. This call \fBMUST\fP have a corresponding call to
\fIcurl_easy_cleanup(3)\fP when the operation is complete.
If you did not already call \fIcurl_global_init(3)\fP, \fIcurl_easy_init(3)\fP
does it automatically. This may be lethal in multi-threaded cases, since
\fIcurl_global_init(3)\fP is not thread-safe, and it may result in resource
problems because there is no corresponding cleanup.
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 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
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) "
share/man/man3/CURLOPT_SEEKFUNCTION.3 0000644 00000007304 14751150700 0012454 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SEEKFUNCTION 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SEEKFUNCTION \- user callback for seeking in input stream
.SH SYNOPSIS
.nf
#include <curl/curl.h>
/* These are the return codes for the seek callbacks */
#define CURL_SEEKFUNC_OK 0
#define CURL_SEEKFUNC_FAIL 1 /* fail the entire transfer */
#define CURL_SEEKFUNC_CANTSEEK 2 /* tell libcurl seeking cannot be done, so
libcurl might try other means instead */
int seek_callback(void *userp, curl_off_t offset, int origin);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SEEKFUNCTION, seek_callback);
.SH DESCRIPTION
Pass a pointer to your callback function, which should match the prototype
shown above.
This function gets called by libcurl to seek to a certain position in the
input stream and can be used to fast forward a file in a resumed upload
(instead of reading all uploaded bytes with the normal read
function/callback). It is also called to rewind a stream when data has already
been sent to the server and needs to be sent again. This may happen when doing
an HTTP PUT or POST with a multi-pass authentication method, or when an
existing HTTP connection is reused too late and the server closes the
connection. The function shall work like fseek(3) or lseek(3) and it gets
SEEK_SET, SEEK_CUR or SEEK_END as argument for \fIorigin\fP, although libcurl
currently only passes SEEK_SET.
\fIuserp\fP is the pointer you set with \fICURLOPT_SEEKDATA(3)\fP.
The callback function must return \fICURL_SEEKFUNC_OK\fP on success,
\fICURL_SEEKFUNC_FAIL\fP to cause the upload operation to fail or
\fICURL_SEEKFUNC_CANTSEEK\fP to indicate that while the seek failed, libcurl
is free to work around the problem if possible. The latter can sometimes be
done by instead reading from the input or similar.
If you forward the input arguments directly to fseek(3) or lseek(3), note that
the data type for \fIoffset\fP is not the same as defined for curl_off_t on
many systems!
.SH DEFAULT
By default, this is NULL and unused.
.SH PROTOCOLS
HTTP, FTP, SFTP
.SH EXAMPLE
.nf
static int seek_cb(void *userp, curl_off_t offset, int origin)
{
struct data *d = (struct data *)userp;
lseek(our_fd, offset, origin);
return CURL_SEEKFUNC_OK;
}
{
struct data seek_data;
curl_easy_setopt(CURL *handle, CURLOPT_SEEKFUNCTION, seek_cb);
curl_easy_setopt(CURL *handle, CURLOPT_SEEKDATA, &seek_data);
}
.fi
.SH AVAILABILITY
Added in 7.18.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_SEEKDATA "(3), " CURLOPT_IOCTLFUNCTION "(3), "
share/man/man3/CURLOPT_LOW_SPEED_LIMIT.3 0000644 00000004347 14751150700 0013102 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_LOW_SPEED_LIMIT 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_LOW_SPEED_LIMIT \- low speed limit in bytes per second
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_LOW_SPEED_LIMIT,
long speedlimit);
.fi
.SH DESCRIPTION
Pass a long as parameter. It contains the average transfer speed in bytes per
second that the transfer should be below during
\fICURLOPT_LOW_SPEED_TIME(3)\fP seconds for libcurl to consider it to be too
slow and abort.
.SH DEFAULT
0, disabled
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, url);
/* abort if slower than 30 bytes/sec during 60 seconds */
curl_easy_setopt(curl, CURLOPT_LOW_SPEED_TIME, 60L);
curl_easy_setopt(curl, CURLOPT_LOW_SPEED_LIMIT, 30L);
res = curl_easy_perform(curl);
if(CURLE_OPERATION_TIMEDOUT == res) {
printf("Timeout!\\n");
}
/* always cleanup */
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
Returns CURLE_OK
.SH "SEE ALSO"
.BR CURLOPT_LOW_SPEED_TIME "(3), " CURLOPT_TIMEOUT "(3), "
share/man/man3/CURLINFO_PROTOCOL.3 0000644 00000005334 14751150700 0012112 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_PROTOCOL 3 "October 12, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_PROTOCOL \- get the protocol used in the connection
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PROTOCOL, long *p);
.fi
.SH DESCRIPTION
This option is deprecated. We strongly recommend using
\fICURLINFO_SCHEME(3)\fP instead, because this option cannot return all
possible protocols!
Pass a pointer to a long to receive the version used in the last http
connection. The returned value will be exactly one of the CURLPROTO_* values:
.nf
CURLPROTO_DICT, CURLPROTO_FILE, CURLPROTO_FTP, CURLPROTO_FTPS,
CURLPROTO_GOPHER, CURLPROTO_HTTP, CURLPROTO_HTTPS, CURLPROTO_IMAP,
CURLPROTO_IMAPS, CURLPROTO_LDAP, CURLPROTO_LDAPS, CURLPROTO_POP3,
CURLPROTO_POP3S, CURLPROTO_RTMP, CURLPROTO_RTMPE, CURLPROTO_RTMPS,
CURLPROTO_RTMPT, CURLPROTO_RTMPTE, CURLPROTO_RTMPTS, CURLPROTO_RTSP,
CURLPROTO_SCP, CURLPROTO_SFTP, CURLPROTO_SMB, CURLPROTO_SMBS, CURLPROTO_SMTP,
CURLPROTO_SMTPS, CURLPROTO_TELNET, CURLPROTO_TFTP, CURLPROTO_MQTT
.SH PROTOCOLS
All
.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);
if(res == CURLE_OK) {
long protocol;
curl_easy_getinfo(curl, CURLINFO_PROTOCOL, &protocol);
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.52.0. Deprecated since 7.85.0.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLINFO_RESPONSE_CODE "(3), "
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
share/man/man3/CURLOPT_PROXY_TLS13_CIPHERS.3 0000644 00000005473 14751150700 0013550 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXY_TLS13_CIPHERS 3 "September 22, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXY_TLS13_CIPHERS \- ciphers suites for proxy TLS 1.3
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_TLS13_CIPHERS,
char *list);
.fi
.SH DESCRIPTION
Pass a char *, pointing to a null-terminated string holding the list of cipher
suites to use for the TLS 1.3 connection to a proxy. The list must be
syntactically correct, it consists of one or more cipher suite strings
separated by colons.
you will find more details about cipher lists on this URL:
https://curl.se/docs/ssl-ciphers.html
This option is currently used only when curl is built to use OpenSSL 1.1.1 or
later. If you are using a different SSL backend you can try setting TLS 1.3
cipher suites by using the \fICURLOPT_PROXY_SSL_CIPHER_LIST(3)\fP option.
The application does not have to keep the string around after setting this
option.
.SH DEFAULT
NULL, use internal default
.SH PROTOCOLS
All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
curl_easy_setopt(curl, CURLOPT_PROXY_TLS13_CIPHERS,
"TLS_CHACHA20_POLY1305_SHA256");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.61.0.
Available when built with OpenSSL >= 1.1.1.
.SH RETURN VALUE
Returns CURLE_OK if supported, CURLE_NOT_BUILT_IN otherwise.
.SH "SEE ALSO"
.BR CURLOPT_PROXY_SSL_CIPHER_LIST "(3), " CURLOPT_PROXY_SSLVERSION "(3), "
.BR CURLOPT_SSL_CIPHER_LIST "(3), " CURLOPT_TLS13_CIPHERS "(3), "
.BR CURLOPT_SSLVERSION "(3), "
share/man/man3/curl_escape.3 0000644 00000004413 14751150700 0011632 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_escape 3 "October 11, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_escape - URL encodes the given string
.SH SYNOPSIS
.nf
#include <curl/curl.h>
char *curl_escape(const char *url, int length);
.fi
.SH DESCRIPTION
Obsolete function. Use \fIcurl_easy_escape(3)\fP instead!
This function will convert the given input string to a URL encoded string and
return that as a new allocated string. All input characters that are not a-z,
A-Z or 0-9 will be converted to their "URL escaped" version (\fB%NN\fP where
\fBNN\fP is a two-digit hexadecimal number).
If the \fBlength\fP argument is set to 0, \fIcurl_escape(3)\fP will use
strlen() on the input \fBurl\fP string to find out the size.
You must \fIcurl_free(3)\fP the returned string when you are 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.
.SH RETURN VALUE
A pointer to a null-terminated string or NULL if it failed.
.SH "SEE ALSO"
.BR curl_unescape "(3), " curl_free "(3), " RFC 2396
share/man/man3/CURLOPT_PROXY_CAINFO_BLOB.3 0000644 00000006072 14751150700 0013316 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXY_CAINFO_BLOB 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXY_CAINFO_BLOB \- proxy Certificate Authority (CA) bundle in PEM format
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_CAINFO_BLOB,
struct curl_blob *stblob);
.fi
.SH DESCRIPTION
This option is for connecting to an HTTPS proxy, not an HTTPS server.
Pass a pointer to a curl_blob structure, which contains information (pointer
and size) about a memory block with binary data of PEM encoded content holding
one or more certificates to verify the HTTPS proxy with.
If \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP is zero and you avoid verifying the
server's certificate, \fICURLOPT_PROXY_CAINFO_BLOB(3)\fP is not needed.
This option overrides \fICURLOPT_PROXY_CAINFO(3)\fP.
.SH DEFAULT
NULL
.SH PROTOCOLS
Used with HTTPS proxy
.SH EXAMPLE
.nf
char *strpem; /* strpem must point to a PEM string */
CURL *curl = curl_easy_init();
if(curl) {
struct curl_blob blob;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
/* using an HTTPS proxy */
curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost:443");
blob.data = strpem;
blob.len = strlen(strpem);
blob.flags = CURL_BLOB_COPY;
curl_easy_setopt(curl, CURLOPT_PROXY_CAINFO_BLOB, &blob);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.77.0.
This option is supported by the rustls (since 7.82.0), OpenSSL, Secure
Transport and Schannel backends.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_PROXY_CAINFO "(3), " CURLOPT_PROXY_CAPATH "(3), "
.BR CURLOPT_PROXY_SSL_VERIFYPEER "(3), " CURLOPT_PROXY_SSL_VERIFYHOST "(3), "
.BR CURLOPT_CAINFO "(3), " CURLOPT_CAINFO_BLOB "(3), "
.BR CURLOPT_CAPATH "(3), "
.BR CURLOPT_SSL_VERIFYPEER "(3), " CURLOPT_SSL_VERIFYHOST "(3), "
share/man/man3/CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 0000644 00000007613 14751150700 0014670 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_CONV_FROM_NETWORK_FUNCTION 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_CONV_FROM_NETWORK_FUNCTION \- convert data from network to host encoding
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode conv_callback(char *ptr, size_t length);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONV_FROM_NETWORK_FUNCTION,
conv_callback);
.SH DESCRIPTION
Pass a pointer to your callback function, which should match the prototype
shown above.
Applies to non-ASCII platforms. \fIcurl_version_info(3)\fP will return the
\fBCURL_VERSION_CONV\fP feature bit set if this option is provided.
The data to be converted is in a buffer pointed to by the \fIptr\fP parameter.
The amount of data to convert is indicated by the \fIlength\fP parameter. The
converted data overlays the input data in the buffer pointed to by the ptr
parameter. \fICURLE_OK\fP must be returned upon successful conversion. A
CURLcode return value defined by curl.h, such as \fICURLE_CONV_FAILED\fP,
should be returned if an error was encountered.
\fBCURLOPT_CONV_FROM_NETWORK_FUNCTION\fP converts to host encoding from the
network encoding. It is used when commands or ASCII data are received over
the network.
If you set a callback pointer to NULL, or do not set it at all, the built-in
libcurl iconv functions will be used. If HAVE_ICONV was not defined when
libcurl was built, and no callback has been established, conversion will
return the \fBCURLE_CONV_REQD\fP error code.
If \fBHAVE_ICONV\fP is defined, \fBCURL_ICONV_CODESET_OF_HOST\fP must also be
defined. For example:
\&#define CURL_ICONV_CODESET_OF_HOST "IBM-1047"
The iconv code in libcurl will default the network and UTF8 codeset names as
follows:
\&#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1"
\&#define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8"
You will need to override these definitions if they are different on your
system.
.SH DEFAULT
NULL
.SH PROTOCOLS
FTP, SMTP, IMAP, POP3
.SH EXAMPLE
.nf
static CURLcode my_conv_from_ascii_to_ebcdic(char *buffer, size_t length)
{
char *tempptrin, *tempptrout;
size_t bytes = length;
int rc;
tempptrin = tempptrout = buffer;
rc = platform_a2e(&tempptrin, &bytes, &tempptrout, &bytes);
if(rc == PLATFORM_CONV_OK) {
return CURLE_OK;
}
else {
return CURLE_CONV_FAILED;
}
}
/* use platform-specific functions for codeset conversions */
curl_easy_setopt(curl, CURLOPT_CONV_FROM_NETWORK_FUNCTION,
my_conv_from_ascii_to_ebcdic);
.fi
.SH AVAILABILITY
Not available since 7.82.0
Available only if \fBCURL_DOES_CONVERSIONS\fP was defined when libcurl was
built.
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_CONV_TO_NETWORK_FUNCTION "(3), " CURLOPT_CONV_FROM_UTF8_FUNCTION "(3), "
share/man/man3/curl_multi_init.3 0000644 00000004041 14751150700 0012544 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_multi_init 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_multi_init - create a multi handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLM *curl_multi_init();
.fi
.SH DESCRIPTION
This function returns a pointer to a \fICURLM\fP 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
.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
If this function returns NULL, something went wrong and you cannot use the
other curl functions.
.SH "SEE ALSO"
.BR curl_multi_cleanup "(3)," curl_global_init "(3)," curl_easy_init "(3)"
share/man/man3/CURLINFO_NAMELOOKUP_TIME.3 0000644 00000004454 14751150700 0013143 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_NAMELOOKUP_TIME 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_NAMELOOKUP_TIME \- get the name lookup time
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_NAMELOOKUP_TIME,
double *timep);
.fi
.SH DESCRIPTION
Pass a pointer to a double to receive the total time in seconds from the start
until the name resolving was completed.
When a redirect is followed, the time from each request is added together.
See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
curl = curl_easy_init();
if(curl) {
double namelookup;
curl_easy_setopt(curl, CURLOPT_URL, url);
res = curl_easy_perform(curl);
if(CURLE_OK == res) {
res = curl_easy_getinfo(curl, CURLINFO_NAMELOOKUP_TIME, &namelookup);
if(CURLE_OK == res) {
printf("Time: %.1f", namelookup);
}
}
/* always cleanup */
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.4.1
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), " CURLINFO_NAMELOOKUP_TIME_T "(3)"
share/man/man3/curl_url.3 0000644 00000004007 14751150700 0011173 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_url 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_url - returns a new URL handle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLU *curl_url();
.fi
.SH DESCRIPTION
This function will allocates and returns a pointer to a fresh \fICURLU\fP
handle, to be used for further use of the URL API.
.SH EXAMPLE
.nf
CURLUcode rc;
CURLU *url = curl_url();
rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
if(!rc) {
char *scheme;
rc = curl_url_get(url, CURLUPART_SCHEME, &scheme, 0);
if(!rc) {
printf("the scheme is %s\\n", scheme);
curl_free(scheme);
}
curl_url_cleanup(url);
}
.fi
.SH AVAILABILITY
Added in 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)"
share/man/man3/CURLINFO_PROXY_ERROR.3 0000644 00000006466 14751150700 0012552 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_PROXY_ERROR 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_PROXY_ERROR \- get the detailed (SOCKS) proxy error
.SH SYNOPSIS
.nf
#include <curl/curl.h>
typedef enum {
CURLPX_OK,
CURLPX_BAD_ADDRESS_TYPE,
CURLPX_BAD_VERSION,
CURLPX_CLOSED,
CURLPX_GSSAPI,
CURLPX_GSSAPI_PERMSG,
CURLPX_GSSAPI_PROTECTION,
CURLPX_IDENTD,
CURLPX_IDENTD_DIFFER,
CURLPX_LONG_HOSTNAME,
CURLPX_LONG_PASSWD,
CURLPX_LONG_USER,
CURLPX_NO_AUTH,
CURLPX_RECV_ADDRESS,
CURLPX_RECV_AUTH,
CURLPX_RECV_CONNECT,
CURLPX_RECV_REQACK,
CURLPX_REPLY_ADDRESS_TYPE_NOT_SUPPORTED,
CURLPX_REPLY_COMMAND_NOT_SUPPORTED,
CURLPX_REPLY_CONNECTION_REFUSED,
CURLPX_REPLY_GENERAL_SERVER_FAILURE,
CURLPX_REPLY_HOST_UNREACHABLE,
CURLPX_REPLY_NETWORK_UNREACHABLE,
CURLPX_REPLY_NOT_ALLOWED,
CURLPX_REPLY_TTL_EXPIRED,
CURLPX_REPLY_UNASSIGNED,
CURLPX_REQUEST_FAILED,
CURLPX_RESOLVE_HOST,
CURLPX_SEND_AUTH,
CURLPX_SEND_CONNECT,
CURLPX_SEND_REQUEST,
CURLPX_UNKNOWN_FAIL,
CURLPX_UNKNOWN_MODE,
CURLPX_USER_REJECTED,
CURLPX_LAST /* never use */
} CURLproxycode;
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_PROXY_ERROR, long *detail);
.fi
.SH DESCRIPTION
Pass a pointer to a long to receive a detailed error code when the most recent
transfer returned a \fBCURLE_PROXY\fP error. That error code will match the
\fBCURLproxycode\fP set.
The error code will be zero (\fBCURLPX_OK\fP) if no response code was
available.
.SH PROTOCOLS
All that can be done over SOCKS
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_PROXY, "socks5://127.0.0.1");
res = curl_easy_perform(curl);
if(res == CURLE_PROXY) {
long proxycode;
res = curl_easy_getinfo(curl, CURLINFO_PROXY_ERROR, &proxycode);
if(!res && proxycode)
printf("The detailed proxy error: %ld\\n", proxycode);
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.73.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLINFO_RESPONSE_CODE "(3), " libcurl-errors "(3), "
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
share/man/man3/curl_unescape.3 0000644 00000004665 14751150700 0012206 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_unescape 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_unescape - URL decodes the given string
.SH SYNOPSIS
.nf
#include <curl/curl.h>
char *curl_unescape( const char *url, int length);
.fi
.SH DESCRIPTION
Obsolete function. Use \fIcurl_easy_unescape(3)\fP instead!
This function will convert the given URL encoded input string to a "plain
string" and return that as a new allocated string. All input characters that
are URL encoded (%XX where XX is a two-digit hexadecimal number) will be
converted to their plain text versions.
If the 'length' argument is set to 0, \fIcurl_unescape(3)\fP will use strlen()
on the input \fBurl\fP string to find out the size.
You must \fIcurl_free(3)\fP the returned string when you are 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) {
/* do not 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 RETURN VALUE
A pointer to a null-terminated string or NULL if it failed.
.SH "SEE ALSO"
.BR curl_easy_escape "(3)," curl_easy_unescape "(3)," curl_free "(3)," RFC 2396
share/man/man3/curl_getenv.3 0000644 00000004147 14751150700 0011666 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_getenv 3 "September 20, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_getenv - return value for environment name
.SH SYNOPSIS
.nf
#include <curl/curl.h>
char *curl_getenv(const char *name);
.fi
.SH DESCRIPTION
curl_getenv() is a portable wrapper for the getenv() function, meant to
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 are done with it.
.SH EXAMPLE
.nf
char *width = curl_getenv("COLUMNS");
if(width) {
/* it was set! */
curl_free(width);
}
.fi
.SH AVAILABILITY
Always
.SH RETURN VALUE
A pointer to a null-terminated string or NULL if it failed to find the
specified name.
.SH NOTE
Under unix operating systems, there is no point in returning an allocated
memory, although other systems will not work properly if this is not done. The
unix implementation thus has to suffer slightly from the drawbacks of other
systems.
.SH "SEE ALSO"
.BR getenv "(3C), "
share/man/man3/curl_url_set.3 0000644 00000017260 14751150700 0012053 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_url_set 3 "September 30, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_url_set - set a URL part
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLUcode curl_url_set(CURLU *url,
CURLUPart part,
const char *content,
unsigned int flags)
.fi
.SH DESCRIPTION
Given the \fIurl\fP handle of an already parsed URL, this function lets the
user set/update individual pieces of it.
The \fIpart\fP argument should identify the particular URL part (see list
below) to set or change, with \fIcontent\fP pointing to a null-terminated
string with the new contents for that URL part. The contents should be in the
form and encoding they'd use in a URL: URL encoded.
The application does not have to keep \fIcontent\fP around after a successful
call.
Setting a part to a NULL pointer will effectively remove that part's contents
from the \fICURLU\fP handle.
By default, this API only accepts URLs using schemes for protocols that are
supported built-in. To make libcurl parse URLs generically even for schemes it
does not know about, the \fBCURLU_NON_SUPPORT_SCHEME\fP flags bit must be
set. Otherwise, this function returns \fICURLUE_UNSUPPORTED_SCHEME\fP on URL
schemes it does not recognize.
The \fIflags\fP argument is a bitmask with independent features.
.SH PARTS
.IP CURLUPART_URL
Allows the full URL of the handle to be replaced. If the handle already is
populated with a URL, the new URL can be relative to the previous.
When successfully setting a new URL, relative or absolute, the handle contents
will be replaced with the information of the newly set URL.
Pass a pointer to a null-terminated string to the \fIurl\fP parameter. The
string must point to a correctly formatted "RFC 3986+" URL or be a NULL
pointer.
.IP CURLUPART_SCHEME
Scheme cannot be URL decoded on set. libcurl only accepts setting schemes up
to 40 bytes long.
.IP CURLUPART_USER
.IP CURLUPART_PASSWORD
.IP CURLUPART_OPTIONS
.IP CURLUPART_HOST
The host name. If it is IDNA the string must then be encoded as your locale
says or UTF-8 (when WinIDN is used). If it is a bracketed IPv6 numeric address
it may contain a zone id (or you can use CURLUPART_ZONEID).
.IP CURLUPART_ZONEID
If the host name is a numeric IPv6 address, this field can also be set.
.IP CURLUPART_PORT
Port cannot be URL encoded on set. The given port number is provided as a
string and the decimal number must be between 1 and 65535. Anything else will
return an error.
.IP CURLUPART_PATH
If a path is set in the URL without a leading slash, a slash will be inserted
automatically when this URL is read from the handle.
.IP CURLUPART_QUERY
The query part will also get spaces converted to pluses when asked to URL
encode on set with the \fICURLU_URLENCODE\fP bit.
If used together with the \fICURLU_APPENDQUERY\fP bit, the provided part is
appended on the end of the existing query.
The question mark in the URL is not part of the actual query contents.
.IP CURLUPART_FRAGMENT
The hash sign in the URL is not part of the actual fragment contents.
.SH FLAGS
The flags argument is zero, one or more bits set in a bitmask.
.IP CURLU_APPENDQUERY
Can be used when setting the \fICURLUPART_QUERY\fP component. The provided new
part will then instead be appended at the end of the existing query - and if
the previous part did not end with an ampersand (&), an ampersand gets
inserted before the new appended part.
When \fICURLU_APPENDQUERY\fP is used together with \fICURLU_URLENCODE\fP, the
first '=' symbol will not be URL encoded.
.IP CURLU_NON_SUPPORT_SCHEME
If set, allows \fIcurl_url_set(3)\fP to set a non-supported scheme.
.IP CURLU_URLENCODE
When set, \fIcurl_url_set(3)\fP URL encodes the part on entry, except for
scheme, port and URL.
When setting the path component with URL encoding enabled, the slash character
will be skipped.
The query part gets space-to-plus conversion before the URL conversion.
This URL encoding is charset unaware and will convert the input on a
byte-by-byte manner.
.IP CURLU_DEFAULT_SCHEME
If set, will make libcurl allow the URL to be set without a scheme and then
sets that to the default scheme: HTTPS. Overrides the \fICURLU_GUESS_SCHEME\fP
option if both are set.
.IP CURLU_GUESS_SCHEME
If set, will make libcurl allow the URL to be set without a scheme and it
instead "guesses" which scheme that was intended based on the host name. If
the outermost sub-domain name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then
that scheme will be used, otherwise it picks HTTP. Conflicts with the
\fICURLU_DEFAULT_SCHEME\fP option which takes precedence if both are set.
.IP CURLU_NO_AUTHORITY
If set, skips authority checks. The RFC allows individual schemes to omit the
host part (normally the only mandatory part of the authority), but libcurl
cannot know whether this is permitted for custom schemes. Specifying the flag
permits empty authority sections, similar to how file scheme is handled.
.IP CURLU_PATH_AS_IS
When set for \fBCURLUPART_URL\fP, this makes libcurl skip the normalization of
the path. That is the procedure where curl otherwise removes sequences of
dot-slash and dot-dot etc. The same option used for transfers is called
\fICURLOPT_PATH_AS_IS(3)\fP.
.IP CURLU_ALLOW_SPACE
If set, a the URL parser allows space (ASCII 32) where possible. The URL
syntax does normally not allow spaces anywhere, but they should be encoded as
%20 or '+'. When spaces are allowed, they are still not allowed in the scheme.
When space is used and allowed in a URL, it will be stored as-is unless
\fICURLU_URLENCODE\fP is also set, which then makes libcurl URL-encode the
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. (Added in 7.78.0)
.SH EXAMPLE
.nf
CURLUcode rc;
CURLU *url = curl_url();
rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
if(!rc) {
char *scheme;
/* change it to an FTP URL */
rc = curl_url_set(url, CURLUPART_SCHEME, "ftp", 0);
}
curl_url_cleanup(url);
.fi
.SH AVAILABILITY
Added in 7.62.0. CURLUPART_ZONEID was added in 7.65.0.
.SH RETURN VALUE
Returns a \fICURLUcode\fP 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)"
share/man/man3/curl_multi_wakeup.3 0000644 00000005407 14751150700 0013104 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_multi_wakeup 3 "May 17, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_multi_wakeup - wakes up a sleeping curl_multi_poll call
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLMcode curl_multi_wakeup(CURLM *multi_handle);
.fi
.SH DESCRIPTION
This function can be called from any thread and it wakes up a
sleeping \fIcurl_multi_poll(3)\fP call that is currently (or will be)
waiting for activity or a timeout.
If the function is called when there is no \fIcurl_multi_poll(3)\fP call,
it will cause the next call to return immediately.
Calling this function only guarantees to wake up the current (or the next
if there is no current) \fIcurl_multi_poll(3)\fP call, which means it is
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 EXAMPLE
.nf
CURL *easy_handle;
CURLM *multi_handle;
/* add the individual easy handle */
curl_multi_add_handle(multi_handle, easy_handle);
/* this is thread 1 */
do {
CURLMcode mc;
int numfds;
mc = curl_multi_perform(multi_handle, &still_running);
if(mc == CURLM_OK) {
/* wait for activity, timeout or wakeup */
mc = curl_multi_poll(multi_handle, NULL, 0, 10000, &numfds);
}
if(time_to_die())
exit(1);
} while(still_running);
curl_multi_remove_handle(multi_handle, easy_handle);
/* this is thread 2 */
if(something makes us decide to stop thread 1) {
set_something_to_signal_thread_1_to_exit();
curl_multi_wakeup(multi_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)"
share/man/man3/CURLOPT_SSLKEY_BLOB.3 0000644 00000005614 14751150700 0012371 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_SSLKEY_BLOB 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_SSLKEY_BLOB \- private key for client cert from memory blob
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLKEY_BLOB,
struct curl_blob *blob);
.fi
.SH DESCRIPTION
Pass a pointer to a curl_blob structure, which contains information (pointer
and size) for a private key. Compatible with OpenSSL. The format (like "PEM")
must be specified with \fICURLOPT_SSLKEYTYPE(3)\fP.
If the blob is initialized with the flags member of struct curl_blob set to
CURL_BLOB_COPY, the application does not have to keep the buffer around after
setting this.
This option is an alternative to \fICURLOPT_SSLKEY(3)\fP which instead expects
a file name as input.
.SH DEFAULT
NULL
.SH PROTOCOLS
All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
struct curl_blob blob;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
blob.data = certificateData;
blob.len = filesize;
blob.flags = CURL_BLOB_COPY;
curl_easy_setopt(curl, CURLOPT_SSLCERT_BLOB, &blob);
curl_easy_setopt(curl, CURLOPT_SSLCERTTYPE, "PEM");
blob.data = privateKeyData;
blob.len = privateKeySize;
curl_easy_setopt(curl, CURLOPT_SSLKEY_BLOB, &blob);
curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "s3cret");
curl_easy_setopt(curl, CURLOPT_SSLKEYTYPE, "PEM");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.71.0. This option is supported by the OpenSSL backends.
.SH RETURN VALUE
Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_SSLKEYTYPE "(3), " CURLOPT_SSLKEY "(3), "
share/man/man3/CURLOPT_PROXY_TRANSFER_MODE.3 0000644 00000004723 14751150700 0013612 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXY_TRANSFER_MODE 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXY_TRANSFER_MODE \- append FTP transfer mode to URL for proxy
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_TRANSFER_MODE,
long enabled);
.fi
.SH DESCRIPTION
Pass a long. If the value is set to 1 (one), it tells libcurl to set the
transfer mode (binary or ASCII) for FTP transfers done via an HTTP proxy, by
appending ;type=a or ;type=i to the URL. Without this setting, or it being set
to 0 (zero, the default), \fICURLOPT_TRANSFERTEXT(3)\fP has no effect when
doing FTP via a proxy. Beware that not all proxies support this feature.
.SH DEFAULT
0, disabled
.SH PROTOCOLS
FTP over proxy
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/old-server/file.txt");
curl_easy_setopt(curl, CURLOPT_PROXY, "http://localhost:80");
curl_easy_setopt(curl, CURLOPT_PROXY_TRANSFER_MODE, 1L);
curl_easy_setopt(curl, CURLOPT_TRANSFERTEXT, 1L);
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.18.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if the
enabled value is not supported.
.SH "SEE ALSO"
.BR CURLOPT_PROXY "(3), " CURLOPT_HTTPPROXYTUNNEL "(3), "
share/man/man3/CURLOPT_INTERLEAVEFUNCTION.3 0000644 00000007144 14751150700 0013365 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_INTERLEAVEFUNCTION 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_INTERLEAVEFUNCTION \- callback for RTSP interleaved data
.SH SYNOPSIS
.nf
#include <curl/curl.h>
size_t interleave_callback(void *ptr, size_t size, size_t nmemb,
void *userdata);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_INTERLEAVEFUNCTION,
interleave_callback);
.SH DESCRIPTION
Pass a pointer to your callback function, which should match the prototype
shown above.
This callback function gets called by libcurl as soon as it has received
interleaved RTP data. This function gets called for each $ block and therefore
contains exactly one upper-layer protocol unit (e.g. one RTP packet). Curl
writes the interleaved header as well as the included data for each call. The
first byte is always an ASCII dollar sign. The dollar sign is followed by a
one byte channel identifier and then a 2 byte integer length in network byte
order. See \fIRFC2326 Section 10.12\fP for more information on how RTP
interleaving behaves. If unset or set to NULL, curl will use the default write
function.
Interleaved RTP poses some challenges for the client application. Since the
stream data is sharing the RTSP control connection, it is critical to service
the RTP in a timely fashion. If the RTP data is not handled quickly,
subsequent response processing may become unreasonably delayed and the
connection may close. The application may use \fICURL_RTSPREQ_RECEIVE\fP to
service RTP data when no requests are desired. If the application makes a
request, (e.g. \fICURL_RTSPREQ_PAUSE\fP) then the response handler will
process any pending RTP data before marking the request as finished.
The \fICURLOPT_INTERLEAVEDATA(3)\fP is passed in the \fIuserdata\fP argument in
the callback.
.SH DEFAULT
NULL, the interleave data is then passed to the regular write function:
\fICURLOPT_WRITEFUNCTION(3)\fP.
.SH PROTOCOLS
RTSP
.SH EXAMPLE
.nf
static size_t rtp_write(void *ptr, size_t size, size_t nmemb, void *user)
{
struct local *l = (struct local *)user;
/* take care of the packet in 'ptr', then return... */
return size * nmemb;
}
{
struct local rtp_data;
curl_easy_setopt(curl, CURLOPT_INTERLEAVEFUNCTION, rtp_write);
curl_easy_setopt(curl, CURLOPT_INTERLEAVEDATA, &rtp_data);
}
.fi
.SH AVAILABILITY
Added in 7.20.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR CURLOPT_INTERLEAVEDATA "(3), " CURLOPT_RTSP_REQUEST "(3), "
share/man/man3/curl_mime_data.3 0000644 00000005223 14751150700 0012312 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_mime_data 3 "June 28, 2022" "libcurl 7.86.0" "libcurl Manual"
.SH NAME
curl_mime_data - set a mime part's body data from memory
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_mime_data(curl_mimepart *part, const char *data,
size_t datasize);
.fi
.SH DESCRIPTION
\fIcurl_mime_data(3)\fP sets a mime part's body content from memory data.
\fIpart\fP is the mime part to assign contents to, created with
\fIcurl_mime_addpart(3)\fP.
\fIdata\fP points to the data that gets copied by this function. The storage
may safely be reused after the call.
\fIdatasize\fP is the number of bytes \fIdata\fP points to. It can be set to
\fICURL_ZERO_TERMINATED\fP to indicate \fIdata\fP is a null-terminated
character string.
Setting a part's contents multiple times is valid: only the value set by the
last call is retained. It is possible to unassign part's contents by setting
\fIdata\fP to NULL.
Setting large data is memory consuming: one might consider using
\fIcurl_mime_data_cb(3)\fP in such a case.
.SH EXAMPLE
.nf
curl_mime *mime;
curl_mimepart *part;
/* create a mime handle */
mime = curl_mime_init(easy);
/* add a part */
part = curl_mime_addpart(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),"
.BR curl_mime_name "(3),"
.BR curl_mime_type "(3)"
share/man/man3/CURLOPT_PROXY_CAINFO.3 0000644 00000007154 14751150700 0012522 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_PROXY_CAINFO 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_PROXY_CAINFO \- path to proxy Certificate Authority (CA) bundle
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_CAINFO, char *path);
.fi
.SH DESCRIPTION
This option is for connecting to an HTTPS proxy, not an HTTPS server.
Pass a char * to a null-terminated string naming a file holding one or more
certificates to verify the HTTPS proxy with.
If \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP is zero and you avoid verifying the
server's certificate, \fICURLOPT_PROXY_CAINFO(3)\fP need not even indicate an
accessible file.
This option is by default set to the system path where libcurl's CA
certificate bundle is assumed to be stored, as established at build time.
If curl is built against the NSS SSL library, the NSS PEM PKCS#11 module
(libnsspem.so) needs to be available for this option to work properly.
(iOS and macOS only) If curl is built against Secure Transport, then this
option is supported for backward compatibility with other SSL engines, but it
should not be set. If the option is not set, then curl will use the
certificates in the system and user Keychain to verify the peer, which is the
preferred method of verifying the peer's certificate chain.
The application does not have to keep the string around after setting this
option.
The default value for this can be figured out with \fICURLINFO_CAINFO(3)\fP.
.SH DEFAULT
Built-in system specific
.SH PROTOCOLS
Used with HTTPS proxy
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
/* using an HTTPS proxy */
curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost:443");
curl_easy_setopt(curl, CURLOPT_PROXY_CAINFO, "/etc/certs/cabundle.pem");
ret = curl_easy_perform(curl);
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.52.0
For TLS backends that do not support certificate files, the
\fICURLOPT_PROXY_CAINFO(3)\fP option is ignored. Refer to
https://curl.se/docs/ssl-compared.html
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
CURLE_OUT_OF_MEMORY if there was insufficient heap space.
.SH "SEE ALSO"
.BR CURLOPT_PROXY_CAINFO_BLOB "(3), " CURLOPT_PROXY_CAPATH "(3), "
.BR CURLOPT_PROXY_SSL_VERIFYPEER "(3), " CURLOPT_PROXY_SSL_VERIFYHOST "(3), "
.BR CURLOPT_CAINFO "(3), " CURLOPT_CAINFO_BLOB "(3), "
.BR CURLOPT_CAPATH "(3), "
.BR CURLOPT_SSL_VERIFYPEER "(3), " CURLOPT_SSL_VERIFYHOST "(3), "
share/man/man3/CURLOPT_TCP_FASTOPEN.3 0000644 00000004235 14751150700 0012504 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_TCP_FASTOPEN 3 "September 20, 2022" "libcurl 7.86.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_TCP_FASTOPEN \- TCP Fast Open
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_FASTOPEN, long enable);
.fi
.SH DESCRIPTION
Pass a long as parameter set to 1L to enable or 0 to disable.
TCP Fast Open (RFC7413) is a mechanism that allows data to be carried in the
SYN and SYN-ACK packets and consumed by the receiving end during the initial
connection handshake, saving up to one full round-trip time (RTT).
.SH DEFAULT
0
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_TCP_FASTOPEN, 1L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.49.0. This option is currently only supported on Linux and macOS
10.11 or later.
.SH RETURN VALUE
Returns CURLE_OK if fast open is supported by the operating system, otherwise
returns CURLE_NOT_BUILT_IN.
.SH SEE ALSO
.BR CURLOPT_SSL_FALSESTART "(3), "
share/man/man3/CURLINFO_EFFECTIVE_METHOD.3 0000644 00000005003 14751150700 0013202 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLINFO_EFFECTIVE_METHOD 3 "May 17, 2022" "libcurl 7.86.0" "curl_easy_getinfo options"
.SH NAME
CURLINFO_EFFECTIVE_METHOD \- get the last used HTTP method
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_EFFECTIVE_METHOD,
char **methodp);
.fi
.SH DESCRIPTION
Pass in a pointer to a char pointer and get the last used effective HTTP
method.
In cases when you have asked libcurl to follow redirects, the method may not be
the same method the first request would use.
The \fBmethodp\fP pointer will be NULL or pointing to private memory you MUST
NOT free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the
corresponding CURL handle.
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res;
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "data");
curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
res = curl_easy_perform(curl);
if(res == CURLE_OK) {
char *method = NULL;
curl_easy_getinfo(curl, CURLINFO_EFFECTIVE_METHOD, &method);
if(method)
printf("Redirected to method: %s\\n", method);
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.72.0
.SH RETURN VALUE
Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
.SH "SEE ALSO"
.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), "
share/man/man1/curl-config.1 0000644 00000010611 14751150700 0011546 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH curl-config 1 "September 20, 2022" "Curl 7.86.0" "curl-config manual"
.SH NAME
curl-config \- Get information about a libcurl installation
.SH SYNOPSIS
.B curl-config [options]
.SH DESCRIPTION
.B curl-config
displays information about the curl and libcurl installation.
.SH OPTIONS
.IP "--ca"
Displays the built-in path to the CA cert bundle this libcurl uses.
.IP "--cc"
Displays the compiler used to build libcurl.
.IP "--cflags"
Set of compiler options (CFLAGS) to use when compiling files that use
libcurl. Currently that is only the include path to the curl include files.
.IP "--checkfor [version]"
Specify the oldest possible libcurl version string you want, and this
script will return 0 if the current installation is new enough or it
returns 1 and outputs a text saying that the current version is not new
enough. (Added in 7.15.4)
.IP "--configure"
Displays the arguments given to configure when building curl.
.IP "--feature"
Lists what particular main features the installed libcurl was built with. At
the time of writing, this list may include SSL, KRB4 or IPv6. Do not assume
any particular order. The keywords will be separated by newlines. There may be
none, one, or several keywords in the list.
.IP "--help"
Displays the available options.
.IP "--libs"
Shows the complete set of libs and other linker options you will need in order
to link your application with libcurl.
.IP "--prefix"
This is the prefix used when libcurl was installed. Libcurl is then installed
in $prefix/lib and its header files are installed in $prefix/include and so
on. The prefix is set with "configure --prefix".
.IP "--protocols"
Lists what particular protocols the installed libcurl was built to support. At
the time of writing, this list may include HTTP, HTTPS, FTP, FTPS, FILE,
TELNET, LDAP, DICT and many more. Do not assume any particular order. The
protocols will be listed using uppercase and are separated by newlines. There
may be none, one, or several protocols in the list. (Added in 7.13.0)
.IP "--ssl-backends"
Lists the SSL backends that were enabled when libcurl was built. It might be
no, one or several names. If more than one name, they will appear
comma-separated. (Added in 7.58.0)
.IP "--static-libs"
Shows the complete set of libs and other linker options you will need in order
to link your application with libcurl statically. (Added in 7.17.1)
.IP "--version"
Outputs version information about the installed libcurl.
.IP "--vernum"
Outputs version information about the installed libcurl, in numerical mode.
This outputs the version number, in hexadecimal, with 8 bits for each part:
major, minor, and patch. So that libcurl 7.7.4 would appear as 070704 and libcurl
12.13.14 would appear as 0c0d0e... Note that the initial zero might be
omitted. (This option was broken in the 7.15.0 release.)
.SH "EXAMPLES"
What linker options do I need when I link with libcurl?
.nf
$ curl-config --libs
.fi
What compiler options do I need when I compile using libcurl functions?
.nf
$ curl-config --cflags
.fi
How do I know if libcurl was built with SSL support?
.nf
$ curl-config --feature | grep SSL
.fi
What's the installed libcurl version?
.nf
$ curl-config --version
.fi
How do I build a single file with a one-line command?
.nf
$ `curl-config --cc --cflags` -o example example.c `curl-config --libs`
.fi
.SH "SEE ALSO"
.BR curl (1)
share/man/man1/curl.1 0000644 00000614313 14751150700 0010314 0 ustar 00 .\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 \- 2022, 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
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.\" DO NOT EDIT. Generated by the curl project gen.pl man page generator.
.\"
.TH curl 1 "December 19 2022" "curl 7.86.0" "curl Manual"
.SH NAME
curl \- transfer a URL
.SH SYNOPSIS
.B curl [options / URLs]
.SH DESCRIPTION
\fBcurl\fP is a tool for transferring data from or to a server. It supports these
protocols: DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS,
LDAP, LDAPS, MQTT, POP3, POP3S, RTMP, RTMPS, RTSP, SCP, SFTP, SMB, SMBS, SMTP,
SMTPS, TELNET, TFTP, WS and WSS. The command is designed to work without user
interaction.
curl offers a busload of useful tricks like proxy support, user
authentication, FTP upload, HTTP post, SSL connections, cookies, file transfer
resume and more. As you will see below, the number of features will make your
head spin.
curl is powered by libcurl for all transfer-related features. See
\fIlibcurl(3)\fP for details.
.SH URL
The URL syntax is protocol-dependent. You find a detailed description in
RFC 3986.
You can specify multiple URLs or parts of URLs by writing part sets within
braces and quoting the URL as in:
.nf
\(dqhttp://site.{one,two,three}.com"
.fi
or you can get sequences of alphanumeric series by using [] as in:
.nf
\(dqftp://ftp.example.com/file[1-100].txt"
.fi
.nf
\(dqftp://ftp.example.com/file[001-100].txt" (with leading zeros)
.fi
.nf
\(dqftp://ftp.example.com/file[a-z].txt"
.fi
Nested sequences are not supported, but you can use several ones next to each
other:
.nf
\(dqhttp://example.com/archive[1996-1999]/vol[1-4]/part{a,b,c}.html"
.fi
You can specify any amount of URLs on the command line. They will be fetched
in a sequential manner in the specified order. You can specify command line
options and URLs mixed and in any order on the command line.
You can specify a step counter for the ranges to get every Nth number or
letter:
.nf
\(dqhttp://example.com/file[1-100:10].txt"
.fi
.nf
\(dqhttp://example.com/file[a-z:2].txt"
.fi
When using [] or {} sequences when invoked from a command line prompt, you
probably have to put the full URL within double quotes to avoid the shell from
interfering with it. This also goes for other characters treated special, like
for example '&', '?' and '*'.
Provide the IPv6 zone index in the URL with an escaped percentage sign and the
interface name. Like in
.nf
\(dqhttp://[fe80::3%25eth0]/"
.fi
If you specify URL without protocol:// prefix, curl will attempt to guess what
protocol you might want. It will then default to HTTP but try other protocols
based on often-used host name prefixes. For example, for host names starting
with "ftp." curl will assume you want to speak FTP.
curl will do its best to use what you pass to it as a URL. It is not trying to
validate it as a syntactically correct URL by any means but is fairly liberal
with what it accepts.
curl will attempt to re-use connections for multiple file transfers, so that
getting many files from the same server will not do multiple connects /
handshakes. This improves speed. Of course this is only done on files
specified on a single command line and cannot be used between separate curl
invocations.
.SH OUTPUT
If not told otherwise, curl writes the received data to stdout. It can be
instructed to instead save that data into a local file, using the \-\-output or
\-\-remote-name options. If curl is given multiple URLs to transfer on the
command line, it similarly needs multiple options for where to save them.
curl does not parse or otherwise "understand" the content it gets or writes as
output. It does no encoding or decoding, unless explicitly asked to with
dedicated command line options.
.SH PROTOCOLS
curl supports numerous protocols, or put in URL terms: schemes. Your
particular build may not support them all.
.IP DICT
Lets you lookup words using online dictionaries.
.IP FILE
Read or write local files. curl does not support accessing file:// URL
remotely, but when running on Microsoft Windows using the native UNC approach
will work.
.IP FTP(S)
curl supports the File Transfer Protocol with a lot of tweaks and levers. With
or without using TLS.
.IP GOPHER(S)
Retrieve files.
.IP HTTP(S)
curl supports HTTP with numerous options and variations. It can speak HTTP
version 0.9, 1.0, 1.1, 2 and 3 depending on build options and the correct
command line options.
.IP IMAP(S)
Using the mail reading protocol, curl can "download" emails for you. With or
without using TLS.
.IP LDAP(S)
curl can do directory lookups for you, with or without TLS.
.IP MQTT
curl supports MQTT version 3. Downloading over MQTT equals "subscribe" to a
topic while uploading/posting equals "publish" on a topic. MQTT over TLS is
not supported (yet).
.IP POP3(S)
Downloading from a pop3 server means getting a mail. With or without using
TLS.
.IP RTMP(S)
The Realtime Messaging Protocol is primarily used to server streaming media
and curl can download it.
.IP RTSP
curl supports RTSP 1.0 downloads.
.IP SCP
curl supports SSH version 2 scp transfers.
.IP SFTP
curl supports SFTP (draft 5) done over SSH version 2.
.IP SMB(S)
curl supports SMB version 1 for upload and download.
.IP SMTP(S)
Uploading contents to an SMTP server means sending an email. With or without
TLS.
.IP TELNET
Telling curl to fetch a telnet URL starts an interactive session where it
sends what it reads on stdin and outputs what the server sends it.
.IP TFTP
curl can do TFTP downloads and uploads.
.SH "PROGRESS METER"
curl normally displays a progress meter during operations, indicating the
amount of transferred data, transfer speeds and estimated time left, etc. The
progress meter displays number of bytes and the speeds are in bytes per
second. The suffixes (k, M, G, T, P) are 1024 based. For example 1k is 1024
bytes. 1M is 1048576 bytes.
curl displays this data to the terminal by default, so if you invoke curl to
do an operation and it is about to write data to the terminal, it
\fIdisables\fP the progress meter as otherwise it would mess up the output
mixing progress meter and response data.
If you want a progress meter for HTTP POST or PUT requests, you need to
redirect the response output to a file, using shell redirect (>), \-\-output or
similar.
This does not apply to FTP upload as that operation does not spit out any
response data to the terminal.
If you prefer a progress "bar" instead of the regular meter, \-\-progress-bar is
your friend. You can also disable the progress meter completely with the
\-\-silent option.
.SH OPTIONS
Options start with one or two dashes. Many of the options require an
additional value next to them.
The short "single-dash" form of the options, \-d for example, may be used with
or without a space between it and its value, although a space is a recommended
separator. The long "double-dash" form, \-\-data for example, requires a space
between it and its value.
Short version options that do not need any additional values can be used
immediately next to each other, like for example you can specify all the
options \-O, \-L and \-v at once as \-OLv.
In general, all boolean options are enabled with \-\-\fBoption\fP and yet again
disabled with \-\-\fBno-\fPoption. That is, you use the same option name but
prefix it with "no-". However, in this list we mostly only list and show the
\-\-option version of them.
.IP "\-\-abstract-unix-socket <path>"
(HTTP) Connect through an abstract Unix domain socket, instead of using the network.
Note: netstat shows the path of an abstract socket prefixed with '@', however
the <path> argument should not have this leading character.
If --abstract-unix-socket is provided several times, the last set value will be used.
Example:
.nf
curl --abstract-unix-socket socketpath https://example.com
.fi
See also \fI--unix-socket\fP. Added in 7.53.0.
.IP "\-\-alt-svc <file name>"
(HTTPS) This option enables the alt-svc parser in curl. If the file name points to an
existing alt-svc cache file, that will be used. After a completed transfer,
the cache will be saved to the file name again if it has been modified.
Specify a "" file name (zero length) to avoid loading/saving and make curl
just handle the cache in memory.
If this option is used several times, curl will load contents from all the
files but the last one will be used for saving.
--alt-svc can be used several times in a command line
Example:
.nf
curl --alt-svc svc.txt https://example.com
.fi
See also \fI--resolve\fP and \fI--connect-to\fP. Added in 7.64.1.
.IP "\-\-anyauth"
(HTTP) Tells curl to figure out authentication method by itself, and use the most
secure one the remote site claims to support. This is done by first doing a
request and checking the response-headers, thus possibly inducing an extra
network round-trip. This is used instead of setting a specific authentication
method, which you can do with \fI\-\-basic\fP, \fI\-\-digest\fP, \fI\-\-ntlm\fP, and \fI\-\-negotiate\fP.
Using \-\-anyauth is not recommended if you do uploads from stdin, since it may
require data to be sent twice and then the client must be able to rewind. If
the need should arise when uploading from stdin, the upload operation will
fail.
Used together with \fI\-u, \-\-user\fP.
Providing --anyauth multiple times has no extra effect.
Example:
.nf
curl --anyauth --user me:pwd https://example.com
.fi
See also \fI--proxy-anyauth\fP, \fI--basic\fP and \fI--digest\fP.
.IP "\-a, \-\-append"
(FTP SFTP) When used in an upload, this makes curl append to the target file instead of
overwriting it. If the remote file does not exist, it will be created. Note
that this flag is ignored by some SFTP servers (including OpenSSH).
Providing --append multiple times has no extra effect.
Disable it again with --no-append.
Example:
.nf
curl --upload-file local --append ftp://example.com/
.fi
See also \fI-r, --range\fP and \fI-C, --continue-at\fP.
.IP "\-\-aws-sigv4 <provider1[:provider2[:region[:service]]]>"
Use AWS V4 signature authentication in the transfer.
The provider argument is a string that is used by the algorithm when creating
outgoing authentication headers.
The region argument is a string that points to a geographic area of
a resources collection (region-code) when the region name is omitted from
the endpoint.
The service argument is a string that points to a function provided by a cloud
(service-code) when the service name is omitted from the endpoint.
If --aws-sigv4 is provided several times, the last set value will be used.
Example:
.nf
curl --aws-sigv4 "aws:amz:east-2:es" --user "key:secret" https://example.com
.fi
See also \fI--basic\fP and \fI-u, --user\fP. Added in 7.75.0.
.IP "\-\-basic"
(HTTP) Tells curl to use HTTP Basic authentication with the remote host. This is the
default and this option is usually pointless, unless you use it to override a
previously set option that sets a different authentication method (such as
\fI\-\-ntlm\fP, \fI\-\-digest\fP, or \fI\-\-negotiate\fP).
Used together with \fI\-u, \-\-user\fP.
Providing --basic multiple times has no extra effect.
Example:
.nf
curl -u name:password --basic https://example.com
.fi
See also \fI--proxy-basic\fP.
.IP "\-\-cacert <file>"
(TLS) Tells curl to use the specified certificate file to verify the peer. The file
may contain multiple CA certificates. The certificate(s) must be in PEM
format. Normally curl is built to use a default file for this, so this option
is typically used to alter that default file.
curl recognizes the environment variable named 'CURL_CA_BUNDLE' if it is
set, and uses the given path as a path to a CA cert bundle. This option
overrides that variable.
The windows version of curl will automatically look for a CA certs file named
\(aqcurl-ca-bundle.crt', either in the same directory as curl.exe, or in the
Current Working Directory, or in any folder along your PATH.
If curl is built against the NSS SSL library, the NSS PEM PKCS#11 module
(libnsspem.so) needs to be available for this option to work properly.
(iOS and macOS only) If curl is built against Secure Transport, then this
option is supported for backward compatibility with other SSL engines, but it
should not be set. If the option is not set, then curl will use the
certificates in the system and user Keychain to verify the peer, which is the
preferred method of verifying the peer's certificate chain.
(Schannel only) This option is supported for Schannel in Windows 7 or later
with libcurl 7.60 or later. This option is supported for backward
compatibility with other SSL engines; instead it is recommended to use
Windows' store of root certificates (the default for Schannel).
If --cacert is provided several times, the last set value will be used.
Example:
.nf
curl --cacert CA-file.txt https://example.com
.fi
See also \fI--capath\fP and \fI-k, --insecure\fP.
.IP "\-\-capath <dir>"
(TLS) Tells curl to use the specified certificate directory to verify the
peer. Multiple paths can be provided by separating them with ":" (e.g.
\(dqpath1:path2:path3"). The certificates must be in PEM format, and if curl is
built against OpenSSL, the directory must have been processed using the
c_rehash utility supplied with OpenSSL. Using \-\-capath can allow
OpenSSL-powered curl to make SSL-connections much more efficiently than using
\-\-cacert if the \-\-cacert file contains many CA certificates.
If this option is set, the default capath value will be ignored.
If --capath is provided several times, the last set value will be used.
Example:
.nf
curl --capath /local/directory https://example.com
.fi
See also \fI--cacert\fP and \fI-k, --insecure\fP.
.IP "\-\-cert-status"
(TLS) Tells curl to verify the status of the server certificate by using the
Certificate Status Request (aka. OCSP stapling) TLS extension.
If this option is enabled and the server sends an invalid (e.g. expired)
response, if the response suggests that the server certificate has been
revoked, or no response at all is received, the verification fails.
This is currently only implemented in the OpenSSL, GnuTLS and NSS backends.
Providing --cert-status multiple times has no extra effect.
Disable it again with --no-cert-status.
Example:
.nf
curl --cert-status https://example.com
.fi
See also \fI--pinnedpubkey\fP. Added in 7.41.0.
.IP "\-\-cert-type <type>"
(TLS) Tells curl what type the provided client certificate is using. PEM, DER, ENG
and P12 are recognized types.
The default type depends on the TLS backend and is usually PEM, however for
Secure Transport and Schannel it is P12. If \-\-cert is a pkcs11: URI then ENG is
the default type.
If --cert-type is provided several times, the last set value will be used.
Example:
.nf
curl --cert-type PEM --cert file https://example.com
.fi
See also \fI-E, --cert\fP, \fI--key\fP and \fI--key-type\fP.
.IP "\-E, \-\-cert <certificate[:password]>"
(TLS) Tells curl to use the specified client certificate file when getting a file
with HTTPS, FTPS or another SSL-based protocol. The certificate must be in
PKCS#12 format if using Secure Transport, or PEM format if using any other
engine. If the optional password is not specified, it will be queried for on
the terminal. Note that this option assumes a certificate file that is the
private key and the client certificate concatenated. See \-\-cert and \-\-key to
specify them independently.
In the <certificate> portion of the argument, you must escape the character ":"
as "\\:" so that it is not recognized as the password delimiter. Similarly, you
must escape the character "\\" as "\\\\" so that it is not recognized as an
escape character.
If curl is built against the NSS SSL library then this option can tell
curl the nickname of the certificate to use within the NSS database defined
by the environment variable SSL_DIR (or by default /etc/pki/nssdb). If the
NSS PEM PKCS#11 module (libnsspem.so) is available then PEM files may be
loaded.
If you provide a path relative to the current directory, you must prefix the
path with "./" in order to avoid confusion with an NSS database nickname.
If curl is built against OpenSSL library, and the engine pkcs11 is available,
then a PKCS#11 URI (RFC 7512) can be used to specify a certificate located in
a PKCS#11 device. A string beginning with "pkcs11:" will be interpreted as a
PKCS#11 URI. If a PKCS#11 URI is provided, then the \-\-engine option will be set
as "pkcs11" if none was provided and the \-\-cert-type option will be set as
\(dqENG" if none was provided.
(iOS and macOS only) If curl is built against Secure Transport, then the
certificate string can either be the name of a certificate/private key in the
system or user keychain, or the path to a PKCS#12-encoded certificate and
private key. If you want to use a file from the current directory, please
precede it with "./" prefix, in order to avoid confusion with a nickname.
(Schannel only) Client certificates must be specified by a path
expression to a certificate store. (Loading PFX is not supported; you can
import it to a store first). You can use
\(dq<store location>\\<store name>\\<thumbprint>" to refer to a certificate
in the system certificates store, for example,
\(dqCurrentUser\\MY\\934a7ac6f8a5d579285a74fa61e19f23ddfe8d7a". Thumbprint is
usually a SHA-1 hex string which you can see in certificate details. Following
store locations are supported: CurrentUser, LocalMachine, CurrentService,
Services, CurrentUserGroupPolicy, LocalMachineGroupPolicy,
LocalMachineEnterprise.
If --cert is provided several times, the last set value will be used.
Example:
.nf
curl --cert certfile --key keyfile https://example.com
.fi
See also \fI--cert-type\fP, \fI--key\fP and \fI--key-type\fP.
.IP "\-\-ciphers <list of ciphers>"
(TLS) Specifies which ciphers to use in the connection. The list of ciphers must
specify valid ciphers. Read up on SSL cipher list details on this URL:
.nf
https://curl.se/docs/ssl-ciphers.html
.fi
If --ciphers is provided several times, the last set value will be used.
Example:
.nf
curl --ciphers ECDHE-ECDSA-AES256-CCM8 https://example.com
.fi
See also \fI--tlsv1.3\fP.
.IP "\-\-compressed-ssh"
(SCP SFTP) Enables built-in SSH compression.
This is a request, not an order; the server may or may not do it.
Providing --compressed-ssh multiple times has no extra effect.
Disable it again with --no-compressed-ssh.
Example:
.nf
curl --compressed-ssh sftp://example.com/
.fi
See also \fI--compressed\fP. Added in 7.56.0.
.IP "\-\-compressed"
(HTTP) Request a compressed response using one of the algorithms curl supports, and
automatically decompress the content. Headers are not modified.
If this option is used and the server sends an unsupported encoding, curl will
report an error. This is a request, not an order; the server may or may not
deliver data compressed.
Providing --compressed multiple times has no extra effect.
Disable it again with --no-compressed.
Example:
.nf
curl --compressed https://example.com
.fi
See also \fI--compressed-ssh\fP.
.IP "\-K, \-\-config <file>"
Specify a text file to read curl arguments from. The command line arguments
found in the text file will be used as if they were provided on the command
line.
Options and their parameters must be specified on the same line in the file,
separated by whitespace, colon, or the equals sign. Long option names can
optionally be given in the config file without the initial double dashes and
if so, the colon or equals characters can be used as separators. If the option
is specified with one or two dashes, there can be no colon or equals character
between the option and its parameter.
If the parameter contains whitespace (or starts with : or =), the parameter
must be enclosed within quotes. Within double quotes, the following escape
sequences are available: \\\\, \\", \\t, \\n, \\r and \\v. A backslash
preceding any other letter is ignored.
If the first column of a config line is a '#' character, the rest of the line
will be treated as a comment.
Only write one option per physical line in the config file.
Specify the filename to \-\-config as '-' to make curl read the file from stdin.
Note that to be able to specify a URL in the config file, you need to specify
it using the \-\-url option, and not by simply writing the URL on its own
line. So, it could look similar to this:
url = "https://curl.se/docs/"
.nf
# \-\-\- Example file \-\-\-
# this is a comment
url = "example.com"
output = "curlhere.html"
user-agent = "superagent/1.0"
.fi
.nf
# and fetch another URL too
url = "example.com/docs/manpage.html"
\-O
referer = "http://nowhereatall.example.com/"
# \-\-\- End of example file \-\-\-
.fi
When curl is invoked, it (unless \-\-disable is used) checks for a default
config file and uses it if found, even when \-\-config is used. The default
config file is checked for in the following places in this order:
1) "$CURL_HOME/.curlrc"
2) "$XDG_CONFIG_HOME/.curlrc" (Added in 7.73.0)
3) "$HOME/.curlrc"
4) Windows: "%USERPROFILE%\\.curlrc"
5) Windows: "%APPDATA%\\.curlrc"
6) Windows: "%USERPROFILE%\\Application Data\\.curlrc"
7) Non-Windows: use getpwuid to find the home directory
8) On Windows, if it finds no .curlrc file in the sequence described above, it
checks for one in the same dir the curl executable is placed.
On Windows two filenames are checked per location: .curlrc and _curlrc,
preferring the former. Older versions on Windows checked for _curlrc only.
--config can be used several times in a command line
Example:
.nf
curl --config file.txt https://example.com
.fi
See also \fI-q, --disable\fP.
.IP "\-\-connect-timeout <fractional seconds>"
Maximum time in seconds that you allow curl's connection to take. This only
limits the connection phase, so if curl connects within the given period it
will continue \- if not it will exit. Since version 7.32.0, this option
accepts decimal values.
If --connect-timeout is provided several times, the last set value will be used.
Examples:
.nf
curl --connect-timeout 20 https://example.com
curl --connect-timeout 3.14 https://example.com
.fi
See also \fI-m, --max-time\fP.
.IP "\-\-connect-to <HOST1:PORT1:HOST2:PORT2>"
For a request to the given HOST1:PORT1 pair, connect to HOST2:PORT2 instead.
This option is suitable to direct requests at a specific server, e.g. at a
specific cluster node in a cluster of servers. This option is only used to
establish the network connection. It does NOT affect the hostname/port that is
used for TLS/SSL (e.g. SNI, certificate verification) or for the application
protocols. "HOST1" and "PORT1" may be the empty string, meaning "any
host/port". "HOST2" and "PORT2" may also be the empty string, meaning "use the
request's original host/port".
A "host" specified to this option is compared as a string, so it needs to
match the name used in request URL. It can be either numerical such as
\(dq127.0.0.1" or the full host name such as "example.org".
--connect-to can be used several times in a command line
Example:
.nf
curl --connect-to example.com:443:example.net:8443 https://example.com
.fi
See also \fI--resolve\fP and \fI-H, --header\fP. Added in 7.49.0.
.IP "\-C, \-\-continue-at <offset>"
Continue/Resume a previous file transfer at the given offset. The given offset
is the exact number of bytes that will be skipped, counting from the beginning
of the source file before it is transferred to the destination. If used with
uploads, the FTP server command SIZE will not be used by curl.
Use "-C \-" to tell curl to automatically find out where/how to resume the
transfer. It then uses the given output/input files to figure that out.
If --continue-at is provided several times, the last set value will be used.
Examples:
.nf
curl -C - https://example.com
curl -C 400 https://example.com
.fi
See also \fI-r, --range\fP.
.IP "\-c, \-\-cookie-jar <filename>"
(HTTP) Specify to which file you want curl to write all cookies after a completed
operation. Curl writes all cookies from its in-memory cookie storage to the
given file at the end of operations. If no cookies are known, no data will be
written. The file will be written using the Netscape cookie file format. If
you set the file name to a single dash, "-", the cookies will be written to
stdout.
This command line option will activate the cookie engine that makes curl
record and use cookies. Another way to activate it is to use the \-\-cookie
option.
If the cookie jar cannot be created or written to, the whole curl operation
will not fail or even report an error clearly. Using \-\-verbose will get a
warning displayed, but that is the only visible feedback you get about this
possibly lethal situation.
If --cookie-jar is provided several times, the last set value will be used.
Examples:
.nf
curl -c store-here.txt https://example.com
curl -c store-here.txt -b read-these https://example.com
.fi
See also \fI-b, --cookie\fP.
.IP "\-b, \-\-cookie <data|filename>"
(HTTP) Pass the data to the HTTP server in the Cookie header. It is supposedly the
data previously received from the server in a "Set-Cookie:" line. The data
should be in the format "NAME1=VALUE1; NAME2=VALUE2". This makes curl use the
cookie header with this content explicitly in all outgoing request(s). If
multiple requests are done due to authentication, followed redirects or
similar, they will all get this cookie passed on.
If no '=' symbol is used in the argument, it is instead treated as a filename
to read previously stored cookie from. This option also activates the cookie
engine which will make curl record incoming cookies, which may be handy if
you are using this in combination with the \-\-location option or do multiple URL
transfers on the same invoke. If the file name is exactly a minus ("-"), curl
will instead read the contents from stdin.
The file format of the file to read cookies from should be plain HTTP headers
(Set-Cookie style) or the Netscape/Mozilla cookie file format.
The file specified with \-\-cookie is only used as input. No cookies will be
written to the file. To store cookies, use the \-\-cookie-jar option.
If you use the Set-Cookie file format and do not specify a domain then the
cookie is not sent since the domain will never match. To address this, set a
domain in Set-Cookie line (doing that will include sub-domains) or preferably:
use the Netscape format.
Users often want to both read cookies from a file and write updated cookies
back to a file, so using both \-\-cookie and \-\-cookie-jar in the same command
line is common.
--cookie can be used several times in a command line
Examples:
.nf
curl -b cookiefile https://example.com
curl -b cookiefile -c cookiefile https://example.com
.fi
See also \fI-c, --cookie-jar\fP and \fI-j, --junk-session-cookies\fP.
.IP "\-\-create-dirs"
When used in conjunction with the \-\-output option, curl will create the
necessary local directory hierarchy as needed. This option creates the
directories mentioned with the \-\-output option, nothing else. If the \-\-output
file name uses no directory, or if the directories it mentions already exist,
no directories will be created.
Created dirs are made with mode 0750 on unix style file systems.
To create remote directories when using FTP or SFTP, try \fI\-\-ftp-create-dirs\fP.
Providing --create-dirs multiple times has no extra effect.
Disable it again with --no-create-dirs.
Example:
.nf
curl --create-dirs --output local/dir/file https://example.com
.fi
See also \fI--ftp-create-dirs\fP and \fI--output-dir\fP.
.IP "\-\-create-file-mode <mode>"
(SFTP SCP FILE) When curl is used to create files remotely using one of the supported
protocols, this option allows the user to set which 'mode' to set on the file
at creation time, instead of the default 0644.
This option takes an octal number as argument.
If --create-file-mode is provided several times, the last set value will be used.
Example:
.nf
curl --create-file-mode 0777 -T localfile sftp://example.com/new
.fi
See also \fI--ftp-create-dirs\fP. Added in 7.75.0.
.IP "\-\-crlf"
(FTP SMTP) Convert LF to CRLF in upload. Useful for MVS (OS/390).
(SMTP added in 7.40.0)
Providing --crlf multiple times has no extra effect.
Disable it again with --no-crlf.
Example:
.nf
curl --crlf -T file ftp://example.com/
.fi
See also \fI-B, --use-ascii\fP.
.IP "\-\-crlfile <file>"
(TLS) Provide a file using PEM format with a Certificate Revocation List that may
specify peer certificates that are to be considered revoked.
If --crlfile is provided several times, the last set value will be used.
Example:
.nf
curl --crlfile rejects.txt https://example.com
.fi
See also \fI--cacert\fP and \fI--capath\fP.
.IP "\-\-curves <algorithm list>"
(TLS) Tells curl to request specific curves to use during SSL session establishment
according to RFC 8422, 5.1. Multiple algorithms can be provided by separating
them with ":" (e.g. "X25519:P-521"). The parameter is available identically
in the "openssl s_client/s_server" utilities.
\-\-curves allows a OpenSSL powered curl to make SSL-connections with exactly
the (EC) curve requested by the client, avoiding nontransparent client/server
negotiations.
If this option is set, the default curves list built into openssl will be
ignored.
If --curves is provided several times, the last set value will be used.
Example:
.nf
curl --curves X25519 https://example.com
.fi
See also \fI--ciphers\fP. Added in 7.73.0.
.IP "\-\-data-ascii <data>"
(HTTP) This is just an alias for \fI\-d, \-\-data\fP.
--data-ascii can be used several times in a command line
Example:
.nf
curl --data-ascii @file https://example.com
.fi
See also \fI--data-binary\fP, \fI--data-raw\fP and \fI--data-urlencode\fP.
.IP "\-\-data-binary <data>"
(HTTP) This posts data exactly as specified with no extra processing whatsoever.
If you start the data with the letter @, the rest should be a filename. Data
is posted in a similar manner as \-\-data does, except that newlines and
carriage returns are preserved and conversions are never done.
Like \-\-data the default content-type sent to the server is
application/x-www-form-urlencoded. If you want the data to be treated as
arbitrary binary data by the server then set the content-type to octet-stream:
\-H "Content-Type: application/octet-stream".
If this option is used several times, the ones following the first will append
data as described in \fI\-d, \-\-data\fP.
--data-binary can be used several times in a command line
Example:
.nf
curl --data-binary @filename https://example.com
.fi
See also \fI--data-ascii\fP.
.IP "\-\-data-raw <data>"
(HTTP) This posts data similarly to \-\-data but without the special
interpretation of the @ character.
--data-raw can be used several times in a command line
Examples:
.nf
curl --data-raw "hello" https://example.com
curl --data-raw "@at@at@" https://example.com
.fi
See also \fI-d, --data\fP. Added in 7.43.0.
.IP "\-\-data-urlencode <data>"
(HTTP) This posts data, similar to the other \-\-data options with the exception
that this performs URL-encoding.
To be CGI-compliant, the <data> part should begin with a \fIname\fP followed
by a separator and a content specification. The <data> part can be passed to
curl using one of the following syntaxes:
.RS
.IP "content"
This will make curl URL-encode the content and pass that on. Just be careful
so that the content does not contain any = or @ symbols, as that will then make
the syntax match one of the other cases below!
.IP "=content"
This will make curl URL-encode the content and pass that on. The preceding =
symbol is not included in the data.
.IP "name=content"
This will make curl URL-encode the content part and pass that on. Note that
the name part is expected to be URL-encoded already.
.IP "@filename"
This will make curl load data from the given file (including any newlines),
URL-encode that data and pass it on in the POST.
.IP "name@filename"
This will make curl load data from the given file (including any newlines),
URL-encode that data and pass it on in the POST. The name part gets an equal
sign appended, resulting in \fIname=urlencoded-file-content\fP. Note that the
name is expected to be URL-encoded already.
.RE
--data-urlencode can be used several times in a command line
Examples:
.nf
curl --data-urlencode name=val https://example.com
curl --data-urlencode =encodethis https://example.com
curl --data-urlencode name@file https://example.com
curl --data-urlencode @fileonly https://example.com
.fi
See also \fI-d, --data\fP and \fI--data-raw\fP.
.IP "\-d, \-\-data <data>"
(HTTP MQTT) Sends the specified data in a POST request to the HTTP server, in the same way
that a browser does when a user has filled in an HTML form and presses the
submit button. This will cause curl to pass the data to the server using the
content-type application/x-www-form-urlencoded. Compare to \fI\-F, \-\-form\fP.
\-\-data-raw is almost the same but does not have a special interpretation of
the @ character. To post data purely binary, you should instead use the
\-\-data-binary option. To URL-encode the value of a form field you may use
\fI\-\-data-urlencode\fP.
If any of these options is used more than once on the same command line, the
data pieces specified will be merged with a separating &-symbol. Thus, using
\(aq-d name=daniel \-d skill=lousy' would generate a post chunk that looks like
\(aqname=daniel&skill=lousy'.
If you start the data with the letter @, the rest should be a file name to
read the data from, or \- if you want curl to read the data from stdin. Posting
data from a file named 'foobar' would thus be done with \fI\-d, \-\-data\fP @foobar. When
\-\-data is told to read from a file like that, carriage returns and newlines
will be stripped out. If you do not want the @ character to have a special
interpretation use \-\-data-raw instead.
--data can be used several times in a command line
Examples:
.nf
curl -d "name=curl" https://example.com
curl -d "name=curl" -d "tool=cmdline" https://example.com
curl -d @filename https://example.com
.fi
See also \fI--data-binary\fP, \fI--data-urlencode\fP and \fI--data-raw\fP. This option is mutually exclusive to \fI-F, --form\fP and \fI-I, --head\fP and \fI-T, --upload-file\fP.
.IP "\-\-delegation <LEVEL>"
(GSS/kerberos) Set LEVEL to tell the server what it is allowed to delegate when it
comes to user credentials.
.RS
.IP "none"
Do not allow any delegation.
.IP "policy"
Delegates if and only if the OK-AS-DELEGATE flag is set in the Kerberos
service ticket, which is a matter of realm policy.
.IP "always"
Unconditionally allow the server to delegate.
.RE
If --delegation is provided several times, the last set value will be used.
Example:
.nf
curl --delegation "none" https://example.com
.fi
See also \fI-k, --insecure\fP and \fI--ssl\fP.
.IP "\-\-digest"
(HTTP) Enables HTTP Digest authentication. This is an authentication scheme that
prevents the password from being sent over the wire in clear text. Use this in
combination with the normal \-\-user option to set user name and password.
Providing --digest multiple times has no extra effect.
Disable it again with --no-digest.
Example:
.nf
curl -u name:password --digest https://example.com
.fi
See also \fI-u, --user\fP, \fI--proxy-digest\fP and \fI--anyauth\fP. This option is mutually exclusive to \fI--basic\fP and \fI--ntlm\fP and \fI--negotiate\fP.
.IP "\-\-disable-eprt"
(FTP) Tell curl to disable the use of the EPRT and LPRT commands when doing active
FTP transfers. Curl will normally always first attempt to use EPRT, then LPRT
before using PORT, but with this option, it will use PORT right away. EPRT and
LPRT are extensions to the original FTP protocol, and may not work on all
servers, but they enable more functionality in a better way than the
traditional PORT command.
\-\-eprt can be used to explicitly enable EPRT again and \-\-no-eprt is an alias
for \fI\-\-disable-eprt\fP.
If the server is accessed using IPv6, this option will have no effect as EPRT
is necessary then.
Disabling EPRT only changes the active behavior. If you want to switch to
passive mode you need to not use \-\-ftp-port or force it with \fI\-\-ftp-pasv\fP.
Providing --disable-eprt multiple times has no extra effect.
Disable it again with --no-disable-eprt.
Example:
.nf
curl --disable-eprt ftp://example.com/
.fi
See also \fI--disable-epsv\fP and \fI-P, --ftp-port\fP.
.IP "\-\-disable-epsv"
(FTP) Tell curl to disable the use of the EPSV command when doing passive FTP
transfers. Curl will normally always first attempt to use EPSV before
PASV, but with this option, it will not try using EPSV.
\-\-epsv can be used to explicitly enable EPSV again and \-\-no-epsv is an alias
for \fI\-\-disable-epsv\fP.
If the server is an IPv6 host, this option will have no effect as EPSV is
necessary then.
Disabling EPSV only changes the passive behavior. If you want to switch to
active mode you need to use \fI\-P, \-\-ftp-port\fP.
Providing --disable-epsv multiple times has no extra effect.
Disable it again with --no-disable-epsv.
Example:
.nf
curl --disable-epsv ftp://example.com/
.fi
See also \fI--disable-eprt\fP and \fI-P, --ftp-port\fP.
.IP "\-q, \-\-disable"
If used as the first parameter on the command line, the \fIcurlrc\fP config
file will not be read and used. See the \-\-config for details on the default
config file search path.
Providing --disable multiple times has no extra effect.
Disable it again with --no-disable.
Example:
.nf
curl -q https://example.com
.fi
See also \fI-K, --config\fP.
.IP "\-\-disallow-username-in-url"
(HTTP) This tells curl to exit if passed a URL containing a username. This is probably
most useful when the URL is being provided at runtime or similar.
Providing --disallow-username-in-url multiple times has no extra effect.
Disable it again with --no-disallow-username-in-url.
Example:
.nf
curl --disallow-username-in-url https://example.com
.fi
See also \fI--proto\fP. Added in 7.61.0.
.IP "\-\-dns-interface <interface>"
(DNS) Tell curl to send outgoing DNS requests through <interface>. This option is a
counterpart to \fI\-\-interface\fP (which does not affect DNS). The supplied string
must be an interface name (not an address).
If --dns-interface is provided several times, the last set value will be used.
Example:
.nf
curl --dns-interface eth0 https://example.com
.fi
See also \fI--dns-ipv4-addr\fP and \fI--dns-ipv6-addr\fP. \fI--dns-interface\fP requires that the underlying libcurl was built to support c-ares. Added in 7.33.0.
.IP "\-\-dns-ipv4-addr <address>"
(DNS) Tell curl to bind to <ip-address> when making IPv4 DNS requests, so that
the DNS requests originate from this address. The argument should be a
single IPv4 address.
If --dns-ipv4-addr is provided several times, the last set value will be used.
Example:
.nf
curl --dns-ipv4-addr 10.1.2.3 https://example.com
.fi
See also \fI--dns-interface\fP and \fI--dns-ipv6-addr\fP. \fI--dns-ipv4-addr\fP requires that the underlying libcurl was built to support c-ares. Added in 7.33.0.
.IP "\-\-dns-ipv6-addr <address>"
(DNS) Tell curl to bind to <ip-address> when making IPv6 DNS requests, so that
the DNS requests originate from this address. The argument should be a
single IPv6 address.
If --dns-ipv6-addr is provided several times, the last set value will be used.
Example:
.nf
curl --dns-ipv6-addr 2a04:4e42::561 https://example.com
.fi
See also \fI--dns-interface\fP and \fI--dns-ipv4-addr\fP. \fI--dns-ipv6-addr\fP requires that the underlying libcurl was built to support c-ares. Added in 7.33.0.
.IP "\-\-dns-servers <addresses>"
Set the list of DNS servers to be used instead of the system default.
The list of IP addresses should be separated with commas. Port numbers
may also optionally be given as \fI:<port-number>\fP after each IP
address.
If --dns-servers is provided several times, the last set value will be used.
Example:
.nf
curl --dns-servers 192.168.0.1,192.168.0.2 https://example.com
.fi
See also \fI--dns-interface\fP and \fI--dns-ipv4-addr\fP. \fI--dns-servers\fP requires that the underlying libcurl was built to support c-ares. Added in 7.33.0.
.IP "\-\-doh-cert-status"
Same as \-\-cert-status but used for DoH (DNS-over-HTTPS).
Providing --doh-cert-status multiple times has no extra effect.
Disable it again with --no-doh-cert-status.
Example:
.nf
curl --doh-cert-status --doh-url https://doh.example https://example.com
.fi
See also \fI--doh-insecure\fP. Added in 7.76.0.
.IP "\-\-doh-insecure"
Same as \-\-insecure but used for DoH (DNS-over-HTTPS).
Providing --doh-insecure multiple times has no extra effect.
Disable it again with --no-doh-insecure.
Example:
.nf
curl --doh-insecure --doh-url https://doh.example https://example.com
.fi
See also \fI--doh-url\fP. Added in 7.76.0.
.IP "\-\-doh-url <URL>"
Specifies which DNS-over-HTTPS (DoH) server to use to resolve hostnames,
instead of using the default name resolver mechanism. The URL must be HTTPS.
Some SSL options that you set for your transfer will apply to DoH since the
name lookups take place over SSL. However, the certificate verification
settings are not inherited and can be controlled separately via
\-\-doh-insecure and \fI\-\-doh-cert-status\fP.
This option is unset if an empty string "" is used as the URL. (Added in
7.85.0)
If --doh-url is provided several times, the last set value will be used.
Example:
.nf
curl --doh-url https://doh.example https://example.com
.fi
See also \fI--doh-insecure\fP. Added in 7.62.0.
.IP "\-D, \-\-dump-header <filename>"
(HTTP FTP) Write the received protocol headers to the specified file. If no headers are
received, the use of this option will create an empty file.
When used in FTP, the FTP server response lines are considered being "headers"
and thus are saved there.
If --dump-header is provided several times, the last set value will be used.
Example:
.nf
curl --dump-header store.txt https://example.com
.fi
See also \fI-o, --output\fP.
.IP "\-\-egd-file <file>"
(TLS) Deprecated option. This option is ignored by curl since 7.84.0. Prior to that
it only had an effect on curl if built to use old versions of OpenSSL.
Specify the path name to the Entropy Gathering Daemon socket. The socket is
used to seed the random engine for SSL connections.
If --egd-file is provided several times, the last set value will be used.
Example:
.nf
curl --egd-file /random/here https://example.com
.fi
See also \fI--random-file\fP.
.IP "\-\-engine <name>"
(TLS) Select the OpenSSL crypto engine to use for cipher operations. Use \-\-engine
list to print a list of build-time supported engines. Note that not all (and
possibly none) of the engines may be available at runtime.
If --engine is provided several times, the last set value will be used.
Example:
.nf
curl --engine flavor https://example.com
.fi
See also \fI--ciphers\fP and \fI--curves\fP.
.IP "\-\-etag-compare <file>"
(HTTP) This option makes a conditional HTTP request for the specific ETag read
from the given file by sending a custom If-None-Match header using the
stored ETag.
For correct results, make sure that the specified file contains only a
single line with the desired ETag. An empty file is parsed as an empty
ETag.
Use the option \-\-etag-save to first save the ETag from a response, and
then use this option to compare against the saved ETag in a subsequent
request.
If --etag-compare is provided several times, the last set value will be used.
Example:
.nf
curl --etag-compare etag.txt https://example.com
.fi
See also \fI--etag-save\fP and \fI-z, --time-cond\fP. Added in 7.68.0.
.IP "\-\-etag-save <file>"
(HTTP) This option saves an HTTP ETag to the specified file. An ETag is a
caching related header, usually returned in a response.
If no ETag is sent by the server, an empty file is created.
If --etag-save is provided several times, the last set value will be used.
Example:
.nf
curl --etag-save storetag.txt https://example.com
.fi
See also \fI--etag-compare\fP. Added in 7.68.0.
.IP "\-\-expect100-timeout <seconds>"
(HTTP) Maximum time in seconds that you allow curl to wait for a 100-continue
response when curl emits an Expects: 100-continue header in its request. By
default curl will wait one second. This option accepts decimal values! When
curl stops waiting, it will continue as if the response has been received.
If --expect100-timeout is provided several times, the last set value will be used.
Example:
.nf
curl --expect100-timeout 2.5 -T file https://example.com
.fi
See also \fI--connect-timeout\fP. Added in 7.47.0.
.IP "\-\-fail-early"
Fail and exit on the first detected transfer error.
When curl is used to do multiple transfers on the command line, it will
attempt to operate on each given URL, one by one. By default, it will ignore
errors if there are more URLs given and the last URL's success will determine
the error code curl returns. So early failures will be "hidden" by subsequent
successful transfers.
Using this option, curl will instead return an error on the first transfer
that fails, independent of the amount of URLs that are given on the command
line. This way, no transfer failures go undetected by scripts and similar.
This option is global and does not need to be specified for each use of \fI\-:, \-\-next\fP.
This option does not imply \fI\-f, \-\-fail\fP, which causes transfers to fail due to the
server's HTTP status code. You can combine the two options, however note \-\-fail
is not global and is therefore contained by \fI\-:, \-\-next\fP.
Providing --fail-early multiple times has no extra effect.
Disable it again with --no-fail-early.
Example:
.nf
curl --fail-early https://example.com https://two.example
.fi
See also \fI-f, --fail\fP and \fI--fail-with-body\fP. Added in 7.52.0.
.IP "\-\-fail-with-body"
(HTTP) Return an error on server errors where the HTTP response code is 400 or
greater). In normal cases when an HTTP server fails to deliver a document, it
returns an HTML document stating so (which often also describes why and
more). This flag will still allow curl to output and save that content but
also to return error 22.
This is an alternative option to \-\-fail which makes curl fail for the same
circumstances but without saving the content.
Providing --fail-with-body multiple times has no extra effect.
Disable it again with --no-fail-with-body.
Example:
.nf
curl --fail-with-body https://example.com
.fi
See also \fI-f, --fail\fP. This option is mutually exclusive to \fI-f, --fail\fP. Added in 7.76.0.
.IP "\-f, \-\-fail"
(HTTP) Fail fast with no output at all on server errors. This is useful to enable
scripts and users to better deal with failed attempts. In normal cases when an
HTTP server fails to deliver a document, it returns an HTML document stating
so (which often also describes why and more). This flag will prevent curl from
outputting that and return error 22.
This method is not fail-safe and there are occasions where non-successful
response codes will slip through, especially when authentication is involved
(response codes 401 and 407).
Providing --fail multiple times has no extra effect.
Disable it again with --no-fail.
Example:
.nf
curl --fail https://example.com
.fi
See also \fI--fail-with-body\fP. This option is mutually exclusive to \fI--fail-with-body\fP.
.IP "\-\-false-start"
(TLS) Tells curl to use false start during the TLS handshake. False start is a mode
where a TLS client will start sending application data before verifying the
server's Finished message, thus saving a round trip when performing a full
handshake.
This is currently only implemented in the NSS and Secure Transport (on iOS 7.0
or later, or OS X 10.9 or later) backends.
Providing --false-start multiple times has no extra effect.
Disable it again with --no-false-start.
Example:
.nf
curl --false-start https://example.com
.fi
See also \fI--tcp-fastopen\fP. Added in 7.42.0.
.IP "\-\-form-escape"
(HTTP) Tells curl to pass on names of multipart form fields and files using
backslash-escaping instead of percent-encoding.
If --form-escape is provided several times, the last set value will be used.
Example:
.nf
curl --form-escape -F 'field\\name=curl' -F 'file=@load"this' https://example.com
.fi
See also \fI-F, --form\fP. Added in 7.81.0.
.IP "\-\-form-string <name=string>"
(HTTP SMTP IMAP) Similar to \-\-form except that the value string for the named parameter is used
literally. Leading '@' and '<' characters, and the ';type=' string in
the value have no special meaning. Use this in preference to \-\-form if
there's any possibility that the string value may accidentally trigger the
\(aq@' or '<' features of \fI\-F, \-\-form\fP.
--form-string can be used several times in a command line
Example:
.nf
curl --form-string "data" https://example.com
.fi
See also \fI-F, --form\fP.
.IP "\-F, \-\-form <name=content>"
(HTTP SMTP IMAP) For HTTP protocol family, this lets curl emulate a filled-in form in which a
user has pressed the submit button. This causes curl to POST data using the
Content-Type multipart/form-data according to RFC 2388.
For SMTP and IMAP protocols, this is the means to compose a multipart mail
message to transmit.
This enables uploading of binary files etc. To force the 'content' part to be
a file, prefix the file name with an @ sign. To just get the content part from
a file, prefix the file name with the symbol <. The difference between @ and <
is then that @ makes a file get attached in the post as a file upload, while
the < makes a text field and just get the contents for that text field from a
file.
Tell curl to read content from stdin instead of a file by using \- as
filename. This goes for both @ and < constructs. When stdin is used, the
contents is buffered in memory first by curl to determine its size and allow a
possible resend. Defining a part's data from a named non-regular file (such
as a named pipe or similar) is unfortunately not subject to buffering and will
be effectively read at transmission time; since the full size is unknown
before the transfer starts, such data is sent as chunks by HTTP and rejected
by IMAP.
Example: send an image to an HTTP server, where 'profile' is the name of the
form-field to which the file portrait.jpg will be the input:
.nf
curl \-F profile=@portrait.jpg https://example.com/upload.cgi
.fi
Example: send your name and shoe size in two text fields to the server:
.nf
curl \-F name=John \-F shoesize=11 https://example.com/
.fi
Example: send your essay in a text field to the server. Send it as a plain
text field, but get the contents for it from a local file:
.nf
curl \-F "story=<hugefile.txt" https://example.com/
.fi
You can also tell curl what Content-Type to use by using 'type=', in a manner
similar to:
.nf
curl \-F "web=@index.html;type=text/html" example.com
.fi
or
.nf
curl \-F "name=daniel;type=text/foo" example.com
.fi
You can also explicitly change the name field of a file upload part by setting
filename=, like this:
.nf
curl \-F "file=@localfile;filename=nameinpost" example.com
.fi
If filename/path contains ',' or ';', it must be quoted by double-quotes like:
.nf
curl \-F "file=@\\"local,file\\";filename=\\"name;in;post\\"" example.com
.fi
or
.nf
curl \-F 'file=@"local,file";filename="name;in;post"' example.com
.fi
Note that if a filename/path is quoted by double-quotes, any double-quote
or backslash within the filename must be escaped by backslash.
Quoting must also be applied to non-file data if it contains semicolons,
leading/trailing spaces or leading double quotes:
.nf
curl \-F 'colors="red; green; blue";type=text/x-myapp' example.com
.fi
You can add custom headers to the field by setting headers=, like
.nf
curl \-F "submit=OK;headers=\\"X-submit-type: OK\\"" example.com
.fi
or
.nf
curl \-F "submit=OK;headers=@headerfile" example.com
.fi
The headers= keyword may appear more that once and above notes about quoting
apply. When headers are read from a file, Empty lines and lines starting
with '#' are comments and ignored; each header can be folded by splitting
between two words and starting the continuation line with a space; embedded
carriage-returns and trailing spaces are stripped.
Here is an example of a header file contents:
.nf
# This file contain two headers.
X-header-1: this is a header
.fi
.nf
# The following header is folded.
X-header-2: this is
another header
.fi
To support sending multipart mail messages, the syntax is extended as follows:
.br
\- name can be omitted: the equal sign is the first character of the argument,
.br
\- if data starts with '(', this signals to start a new multipart: it can be
followed by a content type specification.
.br
\- a multipart can be terminated with a '=)' argument.
Example: the following command sends an SMTP mime email consisting in an
inline part in two alternative formats: plain text and HTML. It attaches a
text file:
.nf
curl \-F '=(;type=multipart/alternative' \\
\-F '=plain text message' \\
\-F '= <body>HTML message</body>;type=text/html' \\
\-F '=)' \-F '=@textfile.txt' ... smtp://example.com
.fi
Data can be encoded for transfer using encoder=. Available encodings are
\fIbinary\fP and \fI8bit\fP that do nothing else than adding the corresponding
Content-Transfer-Encoding header, \fI7bit\fP that only rejects 8-bit characters
with a transfer error, \fIquoted-printable\fP and \fIbase64\fP that encodes data
according to the corresponding schemes, limiting lines length to 76
characters.
Example: send multipart mail with a quoted-printable text message and a
base64 attached file:
.nf
curl \-F '=text message;encoder=quoted-printable' \\
\-F '=@localfile;encoder=base64' ... smtp://example.com
.fi
See further examples and details in the MANUAL.
--form can be used several times in a command line
Example:
.nf
curl --form "name=curl" --form "file=@loadthis" https://example.com
.fi
See also \fI-d, --data\fP, \fI--form-string\fP and \fI--form-escape\fP. This option is mutually exclusive to \fI-d, --data\fP and \fI-I, --head\fP and \fI-T, --upload-file\fP.
.IP "\-\-ftp-account <data>"
(FTP) When an FTP server asks for "account data" after user name and password has
been provided, this data is sent off using the ACCT command.
If --ftp-account is provided several times, the last set value will be used.
Example:
.nf
curl --ftp-account "mr.robot" ftp://example.com/
.fi
See also \fI-u, --user\fP.
.IP "\-\-ftp-alternative-to-user <command>"
(FTP) If authenticating with the USER and PASS commands fails, send this command.
When connecting to Tumbleweed's Secure Transport server over FTPS using a
client certificate, using "SITE AUTH" will tell the server to retrieve the
username from the certificate.
If --ftp-alternative-to-user is provided several times, the last set value will be used.
Example:
.nf
curl --ftp-alternative-to-user "U53r" ftp://example.com
.fi
See also \fI--ftp-account\fP and \fI-u, --user\fP.
.IP "\-\-ftp-create-dirs"
(FTP SFTP) When an FTP or SFTP URL/operation uses a path that does not currently exist on
the server, the standard behavior of curl is to fail. Using this option, curl
will instead attempt to create missing directories.
Providing --ftp-create-dirs multiple times has no extra effect.
Disable it again with --no-ftp-create-dirs.
Example:
.nf
curl --ftp-create-dirs -T file ftp://example.com/remote/path/file
.fi
See also \fI--create-dirs\fP.
.IP "\-\-ftp-method <method>"
(FTP) Control what method curl should use to reach a file on an FTP(S)
server. The method argument should be one of the following alternatives:
.RS
.IP multicwd
curl does a single CWD operation for each path part in the given URL. For deep
hierarchies this means many commands. This is how RFC 1738 says it should
be done. This is the default but the slowest behavior.
.IP nocwd
curl does no CWD at all. curl will do SIZE, RETR, STOR etc and give a full
path to the server for all these commands. This is the fastest behavior.
.IP singlecwd
curl does one CWD with the full target directory and then operates on the file
\(dqnormally" (like in the multicwd case). This is somewhat more standards
compliant than 'nocwd' but without the full penalty of 'multicwd'.
.RE
If --ftp-method is provided several times, the last set value will be used.
Examples:
.nf
curl --ftp-method multicwd ftp://example.com/dir1/dir2/file
curl --ftp-method nocwd ftp://example.com/dir1/dir2/file
curl --ftp-method singlecwd ftp://example.com/dir1/dir2/file
.fi
See also \fI-l, --list-only\fP.
.IP "\-\-ftp-pasv"
(FTP) Use passive mode for the data connection. Passive is the internal default
behavior, but using this option can be used to override a previous \-\-ftp-port
option.
Reversing an enforced passive really is not doable but you must then instead
enforce the correct \-\-ftp-port again.
Passive mode means that curl will try the EPSV command first and then PASV,
unless \-\-disable-epsv is used.
Providing --ftp-pasv multiple times has no extra effect.
Disable it again with --no-ftp-pasv.
Example:
.nf
curl --ftp-pasv ftp://example.com/
.fi
See also \fI--disable-epsv\fP.
.IP "\-P, \-\-ftp-port <address>"
(FTP) Reverses the default initiator/listener roles when connecting with FTP. This
option makes curl use active mode. curl then tells the server to connect back
to the client's specified address and port, while passive mode asks the server
to setup an IP address and port for it to connect to. <address> should be one
of:
.RS
.IP interface
e.g. "eth0" to specify which interface's IP address you want to use (Unix only)
.IP "IP address"
e.g. "192.168.10.1" to specify the exact IP address
.IP "host name"
e.g. "my.host.domain" to specify the machine
.IP "-"
make curl pick the same IP address that is already used for the control
connection
.RE
Disable the use of PORT with \fI\-\-ftp-pasv\fP. Disable the attempt to use the EPRT
command instead of PORT by using \fI\-\-disable-eprt\fP. EPRT is really PORT++.
You can also append ":[start]-[end]\&" to the right of the address, to tell
curl what TCP port range to use. That means you specify a port range, from a
lower to a higher number. A single number works as well, but do note that it
increases the risk of failure since the port may not be available.
If --ftp-port is provided several times, the last set value will be used.
Examples:
.nf
curl -P - ftp:/example.com
curl -P eth0 ftp:/example.com
curl -P 192.168.0.2 ftp:/example.com
.fi
See also \fI--ftp-pasv\fP and \fI--disable-eprt\fP.
.IP "\-\-ftp-pret"
(FTP) Tell curl to send a PRET command before PASV (and EPSV). Certain FTP servers,
mainly drftpd, require this non-standard command for directory listings as
well as up and downloads in PASV mode.
Providing --ftp-pret multiple times has no extra effect.
Disable it again with --no-ftp-pret.
Example:
.nf
curl --ftp-pret ftp://example.com/
.fi
See also \fI-P, --ftp-port\fP and \fI--ftp-pasv\fP.
.IP "\-\-ftp-skip-pasv-ip"
(FTP) Tell curl to not use the IP address the server suggests in its response
to curl's PASV command when curl connects the data connection. Instead curl
will re-use the same IP address it already uses for the control
connection.
Since curl 7.74.0 this option is enabled by default.
This option has no effect if PORT, EPRT or EPSV is used instead of PASV.
Providing --ftp-skip-pasv-ip multiple times has no extra effect.
Disable it again with --no-ftp-skip-pasv-ip.
Example:
.nf
curl --ftp-skip-pasv-ip ftp://example.com/
.fi
See also \fI--ftp-pasv\fP.
.IP "\-\-ftp-ssl-ccc-mode <active/passive>"
(FTP) Sets the CCC mode. The passive mode will not initiate the shutdown, but
instead wait for the server to do it, and will not reply to the shutdown from
the server. The active mode initiates the shutdown and waits for a reply from
the server.
Providing --ftp-ssl-ccc-mode multiple times has no extra effect.
Disable it again with --no-ftp-ssl-ccc-mode.
Example:
.nf
curl --ftp-ssl-ccc-mode active --ftp-ssl-ccc ftps://example.com/
.fi
See also \fI--ftp-ssl-ccc\fP.
.IP "\-\-ftp-ssl-ccc"
(FTP) Use CCC (Clear Command Channel) Shuts down the SSL/TLS layer after
authenticating. The rest of the control channel communication will be
unencrypted. This allows NAT routers to follow the FTP transaction. The
default mode is passive.
Providing --ftp-ssl-ccc multiple times has no extra effect.
Disable it again with --no-ftp-ssl-ccc.
Example:
.nf
curl --ftp-ssl-ccc ftps://example.com/
.fi
See also \fI--ssl\fP and \fI--ftp-ssl-ccc-mode\fP.
.IP "\-\-ftp-ssl-control"
(FTP) Require SSL/TLS for the FTP login, clear for transfer. Allows secure
authentication, but non-encrypted data transfers for efficiency. Fails the
transfer if the server does not support SSL/TLS.
Providing --ftp-ssl-control multiple times has no extra effect.
Disable it again with --no-ftp-ssl-control.
Example:
.nf
curl --ftp-ssl-control ftp://example.com
.fi
See also \fI--ssl\fP.
.IP "\-G, \-\-get"
When used, this option will make all data specified with \fI\-d, \-\-data\fP, \-\-data-binary
or \-\-data-urlencode to be used in an HTTP GET request instead of the POST
request that otherwise would be used. The data will be appended to the URL
with a '?' separator.
If used in combination with \fI\-I, \-\-head\fP, the POST data will instead be appended to
the URL with a HEAD request.
Providing --get multiple times has no extra effect.
Disable it again with --no-get.
Examples:
.nf
curl --get https://example.com
curl --get -d "tool=curl" -d "age=old" https://example.com
curl --get -I -d "tool=curl" https://example.com
.fi
See also \fI-d, --data\fP and \fI-X, --request\fP.
.IP "\-g, \-\-globoff"
This option switches off the "URL globbing parser". When you set this option,
you can specify URLs that contain the letters {}[] without having curl itself
interpret them. Note that these letters are not normal legal URL contents but
they should be encoded according to the URI standard.
Providing --globoff multiple times has no extra effect.
Disable it again with --no-globoff.
Example:
.nf
curl -g "https://example.com/{[]}}}}"
.fi
See also \fI-K, --config\fP and \fI-q, --disable\fP.
.IP "\-\-happy-eyeballs-timeout-ms <milliseconds>"
Happy Eyeballs is an algorithm that attempts to connect to both IPv4 and IPv6
addresses for dual-stack hosts, giving IPv6 a head-start of the specified
number of milliseconds. If the IPv6 address cannot be connected to within that
time, then a connection attempt is made to the IPv4 address in parallel. The
first connection to be established is the one that is used.
The range of suggested useful values is limited. Happy Eyeballs RFC 6555 says
\(dqIt is RECOMMENDED that connection attempts be paced 150-250 ms apart to
balance human factors against network load." libcurl currently defaults to
200 ms. Firefox and Chrome currently default to 300 ms.
If --happy-eyeballs-timeout-ms is provided several times, the last set value will be used.
Example:
.nf
curl --happy-eyeballs-timeout-ms 500 https://example.com
.fi
See also \fI-m, --max-time\fP and \fI--connect-timeout\fP. Added in 7.59.0.
.IP "\-\-haproxy-protocol"
(HTTP) Send a HAProxy PROXY protocol v1 header at the beginning of the
connection. This is used by some load balancers and reverse proxies to
indicate the client's true IP address and port.
This option is primarily useful when sending test requests to a service that
expects this header.
Providing --haproxy-protocol multiple times has no extra effect.
Disable it again with --no-haproxy-protocol.
Example:
.nf
curl --haproxy-protocol https://example.com
.fi
See also \fI-x, --proxy\fP. Added in 7.60.0.
.IP "\-I, \-\-head"
(HTTP FTP FILE) Fetch the headers only! HTTP-servers feature the command HEAD which this uses
to get nothing but the header of a document. When used on an FTP or FILE file,
curl displays the file size and last modification time only.
Providing --head multiple times has no extra effect.
Disable it again with --no-head.
Example:
.nf
curl -I https://example.com
.fi
See also \fI-G, --get\fP, \fI-v, --verbose\fP and \fI--trace-ascii\fP.
.IP "\-H, \-\-header <header/@file>"
(HTTP IMAP SMTP) Extra header to include in information sent. When used within an HTTP request,
it is added to the regular request headers.
For an IMAP or SMTP MIME uploaded mail built with \-\-form options, it is
prepended to the resulting MIME document, effectively including it at the mail
global level. It does not affect raw uploaded mails (Added in 7.56.0).
You may specify any number of extra headers. Note that if you should add a
custom header that has the same name as one of the internal ones curl would
use, your externally set header will be used instead of the internal one.
This allows you to make even trickier stuff than curl would normally do. You
should not replace internally set headers without knowing perfectly well what
you are doing. Remove an internal header by giving a replacement without
content on the right side of the colon, as in: \-H "Host:". If you send the
custom header with no-value then its header must be terminated with a
semicolon, such as \-H "X-Custom-Header;" to send "X-Custom-Header:".
curl will make sure that each header you add/replace is sent with the proper
end-of-line marker, you should thus \fBnot\fP add that as a part of the header
content: do not add newlines or carriage returns, they will only mess things
up for you.
This option can take an argument in @filename style, which then adds a header
for each line in the input file. Using @- will make curl read the header file
from stdin. Added in 7.55.0.
Please note that most anti-spam utilities check the presence and value of
several MIME mail headers: these are "From:", "To:", "Date:" and "Subject:"
among others and should be added with this option.
You need \-\-proxy-header to send custom headers intended for an HTTP
proxy. Added in 7.37.0.
Passing on a "Transfer-Encoding: chunked" header when doing an HTTP request
with a request body, will make curl send the data using chunked encoding.
\fBWARNING\fP: headers set with this option will be set in all HTTP requests
\- even after redirects are followed, like when told with \fI\-L, \-\-location\fP. This can
lead to the header being sent to other hosts than the original host, so
sensitive headers should be used with caution combined with following
redirects.
--header can be used several times in a command line
Examples:
.nf
curl -H "X-First-Name: Joe" https://example.com
curl -H "User-Agent: yes-please/2000" https://example.com
curl -H "Host:" https://example.com
.fi
See also \fI-A, --user-agent\fP and \fI-e, --referer\fP.
.IP "\-h, \-\-help <category>"
Usage help. This lists all commands of the <category>.
If no arg was provided, curl will display the most important
command line arguments.
If the argument "all" was provided, curl will display all options available.
If the argument "category" was provided, curl will display all categories and
their meanings.
Providing --help multiple times has no extra effect.
Disable it again with --no-help.
Example:
.nf
curl --help all
.fi
See also \fI-v, --verbose\fP.
.IP "\-\-hostpubmd5 <md5>"
(SFTP SCP) Pass a string containing 32 hexadecimal digits. The string should
be the 128 bit MD5 checksum of the remote host's public key, curl will refuse
the connection with the host unless the md5sums match.
If --hostpubmd5 is provided several times, the last set value will be used.
Example:
.nf
curl --hostpubmd5 e5c1c49020640a5ab0f2034854c321a8 sftp://example.com/
.fi
See also \fI--hostpubsha256\fP.
.IP "\-\-hostpubsha256 <sha256>"
(SFTP SCP) Pass a string containing a Base64-encoded SHA256 hash of the remote
host's public key. Curl will refuse the connection with the host
unless the hashes match.
If --hostpubsha256 is provided several times, the last set value will be used.
Example:
.nf
curl --hostpubsha256 NDVkMTQxMGQ1ODdmMjQ3MjczYjAyOTY5MmRkMjVmNDQ= sftp://example.com/
.fi
See also \fI--hostpubmd5\fP. Added in 7.80.0.
.IP "\-\-hsts <file name>"
(HTTPS) This option enables HSTS for the transfer. If the file name points to an
existing HSTS cache file, that will be used. After a completed transfer, the
cache will be saved to the file name again if it has been modified.
Specify a "" file name (zero length) to avoid loading/saving and make curl
just handle HSTS in memory.
If this option is used several times, curl will load contents from all the
files but the last one will be used for saving.
--hsts can be used several times in a command line
Example:
.nf
curl --hsts cache.txt https://example.com
.fi
See also \fI--proto\fP. Added in 7.74.0.
.IP "\-\-http0.9"
(HTTP) Tells curl to be fine with HTTP version 0.9 response.
HTTP/0.9 is a completely headerless response and therefore you can also
connect with this to non-HTTP servers and still get a response since curl will
simply transparently downgrade \- if allowed.
Since curl 7.66.0, HTTP/0.9 is disabled by default.
Providing --http0.9 multiple times has no extra effect.
Disable it again with --no-http0.9.
Example:
.nf
curl --http0.9 https://example.com
.fi
See also \fI--http1.1\fP, \fI--http2\fP and \fI--http3\fP. Added in 7.64.0.
.IP "\-0, \-\-http1.0"
(HTTP) Tells curl to use HTTP version 1.0 instead of using its internally preferred
HTTP version.
Providing --http1.0 multiple times has no extra effect.
Example:
.nf
curl --http1.0 https://example.com
.fi
See also \fI--http0.9\fP and \fI--http1.1\fP. This option is mutually exclusive to \fI--http1.1\fP and \fI--http2\fP and \fI--http2-prior-knowledge\fP and \fI--http3\fP.
.IP "\-\-http1.1"
(HTTP) Tells curl to use HTTP version 1.1.
Providing --http1.1 multiple times has no extra effect.
Example:
.nf
curl --http1.1 https://example.com
.fi
See also \fI-0, --http1.0\fP and \fI--http0.9\fP. This option is mutually exclusive to \fI-0, --http1.0\fP and \fI--http2\fP and \fI--http2-prior-knowledge\fP and \fI--http3\fP. Added in 7.33.0.
.IP "\-\-http2-prior-knowledge"
(HTTP) Tells curl to issue its non-TLS HTTP requests using HTTP/2 without HTTP/1.1
Upgrade. It requires prior knowledge that the server supports HTTP/2 straight
away. HTTPS requests will still do HTTP/2 the standard way with negotiated
protocol version in the TLS handshake.
Providing --http2-prior-knowledge multiple times has no extra effect.
Disable it again with --no-http2-prior-knowledge.
Example:
.nf
curl --http2-prior-knowledge https://example.com
.fi
See also \fI--http2\fP and \fI--http3\fP. \fI--http2-prior-knowledge\fP requires that the underlying libcurl was built to support HTTP/2. This option is mutually exclusive to \fI--http1.1\fP and \fI-0, --http1.0\fP and \fI--http2\fP and \fI--http3\fP. Added in 7.49.0.
.IP "\-\-http2"
(HTTP) Tells curl to use HTTP version 2.
For HTTPS, this means curl will attempt to negotiate HTTP/2 in the TLS
handshake. curl does this by default.
For HTTP, this means curl will attempt to upgrade the request to HTTP/2 using
the Upgrade: request header.
When curl uses HTTP/2 over HTTPS, it does not itself insist on TLS 1.2 or
higher even though that is required by the specification. A user can add this
version requirement with \fI\-\-tlsv1.2\fP.
Providing --http2 multiple times has no extra effect.
Example:
.nf
curl --http2 https://example.com
.fi
See also \fI--http1.1\fP and \fI--http3\fP. \fI--http2\fP requires that the underlying libcurl was built to support HTTP/2. This option is mutually exclusive to \fI--http1.1\fP and \fI-0, --http1.0\fP and \fI--http2-prior-knowledge\fP and \fI--http3\fP. Added in 7.33.0.
.IP "\-\-http3"
(HTTP) **WARNING**: this option is experimental. Do not use in production.
Tells curl to use HTTP version 3 directly to the host and port number used in
the URL. A normal HTTP/3 transaction will be done to a host and then get
redirected via Alt-Svc, but this option allows a user to circumvent that when
you know that the target speaks HTTP/3 on the given host and port.
This option will make curl fail if a QUIC connection cannot be established, it
cannot fall back to a lower HTTP version on its own.
Providing --http3 multiple times has no extra effect.
Example:
.nf
curl --http3 https://example.com
.fi
See also \fI--http1.1\fP and \fI--http2\fP. \fI--http3\fP requires that the underlying libcurl was built to support HTTP/3. This option is mutually exclusive to \fI--http1.1\fP and \fI-0, --http1.0\fP and \fI--http2\fP and \fI--http2-prior-knowledge\fP. Added in 7.66.0.
.IP "\-\-ignore-content-length"
(FTP HTTP) For HTTP, Ignore the Content-Length header. This is particularly useful for
servers running Apache 1.x, which will report incorrect Content-Length for
files larger than 2 gigabytes.
For FTP (since 7.46.0), skip the RETR command to figure out the size before
downloading a file.
This option does not work for HTTP if libcurl was built to use hyper.
Providing --ignore-content-length multiple times has no extra effect.
Disable it again with --no-ignore-content-length.
Example:
.nf
curl --ignore-content-length https://example.com
.fi
See also \fI--ftp-skip-pasv-ip\fP.
.IP "\-i, \-\-include"
Include the HTTP response headers in the output. The HTTP response headers can
include things like server name, cookies, date of the document, HTTP version
and more...
To view the request headers, consider the \-\-verbose option.
Providing --include multiple times has no extra effect.
Disable it again with --no-include.
Example:
.nf
curl -i https://example.com
.fi
See also \fI-v, --verbose\fP.
.IP "\-k, \-\-insecure"
(TLS SFTP SCP) By default, every secure connection curl makes is verified to be secure before
the transfer takes place. This option makes curl skip the verification step
and proceed without checking.
When this option is not used for protocols using TLS, curl verifies the
server's TLS certificate before it continues: that the certificate contains
the right name which matches the host name used in the URL and that the
certificate has been signed by a CA certificate present in the cert store.
See this online resource for further details:
.nf
https://curl.se/docs/sslcerts.html
.fi
For SFTP and SCP, this option makes curl skip the \fIknown_hosts\fP verification.
\fIknown_hosts\fP is a file normally stored in the user's home directory in the
\(dq.ssh" subdirectory, which contains host names and their public keys.
\fBWARNING\fP: using this option makes the transfer insecure.
Providing --insecure multiple times has no extra effect.
Disable it again with --no-insecure.
Example:
.nf
curl --insecure https://example.com
.fi
See also \fI--proxy-insecure\fP, \fI--cacert\fP and \fI--capath\fP.
.IP "\-\-interface <name>"
Perform an operation using a specified interface. You can enter interface
name, IP address or host name. An example could look like:
.nf
curl \-\-interface eth0:1 https://www.example.com/
.fi
On Linux it can be used to specify a VRF, but the binary needs to either
have CAP_NET_RAW or to be run as root. More information about Linux VRF:
https://www.kernel.org/doc/Documentation/networking/vrf.txt
If --interface is provided several times, the last set value will be used.
Example:
.nf
curl --interface eth0 https://example.com
.fi
See also \fI--dns-interface\fP.
.IP "\-4, \-\-ipv4"
This option tells curl to use IPv4 addresses only, and not for example try
IPv6.
Providing --ipv4 multiple times has no extra effect.
Disable it again with --no-ipv4.
Example:
.nf
curl --ipv4 https://example.com
.fi
See also \fI--http1.1\fP and \fI--http2\fP. This option is mutually exclusive to \fI-6, --ipv6\fP.
.IP "\-6, \-\-ipv6"
This option tells curl to use IPv6 addresses only, and not for example try
IPv4.
Providing --ipv6 multiple times has no extra effect.
Disable it again with --no-ipv6.
Example:
.nf
curl --ipv6 https://example.com
.fi
See also \fI--http1.1\fP and \fI--http2\fP. This option is mutually exclusive to \fI-4, --ipv4\fP.
.IP "\-\-json <data>"
(HTTP) Sends the specified JSON data in a POST request to the HTTP server. \-\-json
works as a shortcut for passing on these three options:
.nf
\-\-data [arg]
\-\-header "Content-Type: application/json"
\-\-header "Accept: application/json"
.fi
There is \fI\fPno verification\fI\fP that the passed in data is actual JSON or that
the syntax is correct.
If you start the data with the letter @, the rest should be a file name to
read the data from, or a single dash (-) if you want curl to read the data
from stdin. Posting data from a file named 'foobar' would thus be done with
\fI\-\-json\fP @foobar and to instead read the data from stdin, use \-\-json @-.
If this option is used more than once on the same command line, the additional
data pieces will be concatenated to the previous before sending.
The headers this option sets can be overridden with \-\-header as usual.
--json can be used several times in a command line
Examples:
.nf
curl --json '{ "drink": "coffe" }' https://example.com
curl --json '{ "drink":' --json ' "coffe" }' https://example.com
curl --json @prepared https://example.com
curl --json @- https://example.com < json.txt
.fi
See also \fI--data-binary\fP and \fI--data-raw\fP. This option is mutually exclusive to \fI-F, --form\fP and \fI-I, --head\fP and \fI-T, --upload-file\fP. Added in 7.82.0.
.IP "\-j, \-\-junk-session-cookies"
(HTTP) When curl is told to read cookies from a given file, this option will make it
discard all "session cookies". This will basically have the same effect as if
a new session is started. Typical browsers always discard session cookies when
they are closed down.
Providing --junk-session-cookies multiple times has no extra effect.
Disable it again with --no-junk-session-cookies.
Example:
.nf
curl --junk-session-cookies -b cookies.txt https://example.com
.fi
See also \fI-b, --cookie\fP and \fI-c, --cookie-jar\fP.
.IP "\-\-keepalive-time <seconds>"
This option sets the time a connection needs to remain idle before sending
keepalive probes and the time between individual keepalive probes. It is
currently effective on operating systems offering the TCP_KEEPIDLE and
TCP_KEEPINTVL socket options (meaning Linux, recent AIX, HP-UX and more).
Keepalives are used by the TCP stack to detect broken networks on idle
connections. The number of missed keepalive probes before declaring the
connection down is OS dependent and is commonly 9 or 10. This option has no
effect if \-\-no-keepalive is used.
If unspecified, the option defaults to 60 seconds.
If --keepalive-time is provided several times, the last set value will be used.
Example:
.nf
curl --keepalive-time 20 https://example.com
.fi
See also \fI--no-keepalive\fP and \fI-m, --max-time\fP.
.IP "\-\-key-type <type>"
(TLS) Private key file type. Specify which type your \-\-key provided private key
is. DER, PEM, and ENG are supported. If not specified, PEM is assumed.
If --key-type is provided several times, the last set value will be used.
Example:
.nf
curl --key-type DER --key here https://example.com
.fi
See also \fI--key\fP.
.IP "\-\-key <key>"
(TLS SSH) Private key file name. Allows you to provide your private key in this separate
file. For SSH, if not specified, curl tries the following candidates in order:
\(aq~/.ssh/id_rsa', '~/.ssh/id_dsa', './id_rsa', './id_dsa'.
If curl is built against OpenSSL library, and the engine pkcs11 is available,
then a PKCS#11 URI (RFC 7512) can be used to specify a private key located in a
PKCS#11 device. A string beginning with "pkcs11:" will be interpreted as a
PKCS#11 URI. If a PKCS#11 URI is provided, then the \-\-engine option will be set
as "pkcs11" if none was provided and the \-\-key-type option will be set as
\(dqENG" if none was provided.
If curl is built against Secure Transport or Schannel then this option is
ignored for TLS protocols (HTTPS, etc). Those backends expect the private key
to be already present in the keychain or PKCS#12 file containing the
certificate.
If --key is provided several times, the last set value will be used.
Example:
.nf
curl --cert certificate --key here https://example.com
.fi
See also \fI--key-type\fP and \fI-E, --cert\fP.
.IP "\-\-krb <level>"
(FTP) Enable Kerberos authentication and use. The level must be entered and should
be one of 'clear', 'safe', 'confidential', or 'private'. Should you use a
level that is not one of these, 'private' will instead be used.
If --krb is provided several times, the last set value will be used.
Example:
.nf
curl --krb clear ftp://example.com/
.fi
See also \fI--delegation\fP and \fI--ssl\fP. \fI--krb\fP requires that the underlying libcurl was built to support Kerberos.
.IP "\-\-libcurl <file>"
Append this option to any ordinary curl command line, and you will get
libcurl-using C source code written to the file that does the equivalent
of what your command-line operation does!
This option is global and does not need to be specified for each use of
\fI\-:, \-\-next\fP.
If --libcurl is provided several times, the last set value will be used.
Example:
.nf
curl --libcurl client.c https://example.com
.fi
See also \fI-v, --verbose\fP.
.IP "\-\-limit-rate <speed>"
Specify the maximum transfer rate you want curl to use \- for both downloads
and uploads. This feature is useful if you have a limited pipe and you would like
your transfer not to use your entire bandwidth. To make it slower than it
otherwise would be.
The given speed is measured in bytes/second, unless a suffix is appended.
Appending 'k' or 'K' will count the number as kilobytes, 'm' or 'M' makes it
megabytes, while 'g' or 'G' makes it gigabytes. The suffixes (k, M, G, T, P)
are 1024 based. For example 1k is 1024. Examples: 200K, 3m and 1G.
The rate limiting logic works on averaging the transfer speed to no more than
the set threshold over a period of multiple seconds.
If you also use the \-\-speed-limit option, that option will take precedence and
might cripple the rate-limiting slightly, to help keeping the speed-limit
logic working.
If --limit-rate is provided several times, the last set value will be used.
Examples:
.nf
curl --limit-rate 100K https://example.com
curl --limit-rate 1000 https://example.com
curl --limit-rate 10M https://example.com
.fi
See also \fI-Y, --speed-limit\fP and \fI-y, --speed-time\fP.
.IP "\-l, \-\-list-only"
(FTP POP3) (FTP)
When listing an FTP directory, this switch forces a name-only view. This is
especially useful if the user wants to machine-parse the contents of an FTP
directory since the normal directory view does not use a standard look or
format. When used like this, the option causes an NLST command to be sent to
the server instead of LIST.
Note: Some FTP servers list only files in their response to NLST; they do not
include sub-directories and symbolic links.
(POP3)
When retrieving a specific email from POP3, this switch forces a LIST command
to be performed instead of RETR. This is particularly useful if the user wants
to see if a specific message-id exists on the server and what size it is.
Note: When combined with \fI\-X, \-\-request\fP, this option can be used to send a UIDL
command instead, so the user may use the email's unique identifier rather than
its message-id to make the request.
Providing --list-only multiple times has no extra effect.
Disable it again with --no-list-only.
Example:
.nf
curl --list-only ftp://example.com/dir/
.fi
See also \fI-Q, --quote\fP and \fI-X, --request\fP.
.IP "\-\-local-port <num/range>"
Set a preferred single number or range (FROM-TO) of local port numbers to use
for the connection(s). Note that port numbers by nature are a scarce resource
that will be busy at times so setting this range to something too narrow might
cause unnecessary connection setup failures.
If --local-port is provided several times, the last set value will be used.
Example:
.nf
curl --local-port 1000-3000 https://example.com
.fi
See also \fI-g, --globoff\fP.
.IP "\-\-location-trusted"
(HTTP) Like \fI\-L, \-\-location\fP, but will allow sending the name + password to all hosts that
the site may redirect to. This may or may not introduce a security breach if
the site redirects you to a site to which you will send your authentication
info (which is plaintext in the case of HTTP Basic authentication).
Providing --location-trusted multiple times has no extra effect.
Disable it again with --no-location-trusted.
Example:
.nf
curl --location-trusted -u user:password https://example.com
.fi
See also \fI-u, --user\fP.
.IP "\-L, \-\-location"
(HTTP) If the server reports that the requested page has moved to a different
location (indicated with a Location: header and a 3XX response code), this
option will make curl redo the request on the new place. If used together with
\-\-include or \fI\-I, \-\-head\fP, headers from all requested pages will be shown. When
authentication is used, curl only sends its credentials to the initial
host. If a redirect takes curl to a different host, it will not be able to
intercept the user+password. See also \-\-location-trusted on how to change
this. You can limit the amount of redirects to follow by using the
\-\-max-redirs option.
When curl follows a redirect and if the request is a POST, it will send the
following request with a GET if the HTTP response was 301, 302, or 303. If the
response code was any other 3xx code, curl will re-send the following request
using the same unmodified method.
You can tell curl to not change POST requests to GET after a 30x response by
using the dedicated options for that: \fI\-\-post301\fP, \-\-post302 and \fI\-\-post303\fP.
The method set with \-\-request overrides the method curl would otherwise select
to use.
Providing --location multiple times has no extra effect.
Disable it again with --no-location.
Example:
.nf
curl -L https://example.com
.fi
See also \fI--resolve\fP and \fI--alt-svc\fP.
.IP "\-\-login-options <options>"
(IMAP LDAP POP3 SMTP) Specify the login options to use during server authentication.
You can use login options to specify protocol specific options that may be
used during authentication. At present only IMAP, POP3 and SMTP support
login options. For more information about login options please see RFC
2384, RFC 5092 and IETF draft draft-earhart-url-smtp-00.txt
If --login-options is provided several times, the last set value will be used.
Example:
.nf
curl --login-options 'AUTH=*' imap://example.com
.fi
See also \fI-u, --user\fP. Added in 7.34.0.
.IP "\-\-mail-auth <address>"
(SMTP) Specify a single address. This will be used to specify the authentication
address (identity) of a submitted message that is being relayed to another
server.
If --mail-auth is provided several times, the last set value will be used.
Example:
.nf
curl --mail-auth user@example.come -T mail smtp://example.com/
.fi
See also \fI--mail-rcpt\fP and \fI--mail-from\fP.
.IP "\-\-mail-from <address>"
(SMTP) Specify a single address that the given mail should get sent from.
If --mail-from is provided several times, the last set value will be used.
Example:
.nf
curl --mail-from user@example.com -T mail smtp://example.com/
.fi
See also \fI--mail-rcpt\fP and \fI--mail-auth\fP.
.IP "\-\-mail-rcpt-allowfails"
(SMTP) When sending data to multiple recipients, by default curl will abort SMTP
conversation if at least one of the recipients causes RCPT TO command to
return an error.
The default behavior can be changed by passing \-\-mail-rcpt-allowfails
command-line option which will make curl ignore errors and proceed with the
remaining valid recipients.
If all recipients trigger RCPT TO failures and this flag is specified, curl
will still abort the SMTP conversation and return the error received from to
the last RCPT TO command.
Providing --mail-rcpt-allowfails multiple times has no extra effect.
Disable it again with --no-mail-rcpt-allowfails.
Example:
.nf
curl --mail-rcpt-allowfails --mail-rcpt dest@example.com smtp://example.com
.fi
See also \fI--mail-rcpt\fP. Added in 7.69.0.
.IP "\-\-mail-rcpt <address>"
(SMTP) Specify a single email address, user name or mailing list name. Repeat this
option several times to send to multiple recipients.
When performing an address verification (VRFY command), the recipient should be
specified as the user name or user name and domain (as per Section 3.5 of
RFC5321). (Added in 7.34.0)
When performing a mailing list expand (EXPN command), the recipient should be
specified using the mailing list name, such as "Friends" or "London-Office".
(Added in 7.34.0)
--mail-rcpt can be used several times in a command line
Example:
.nf
curl --mail-rcpt user@example.net smtp://example.com
.fi
See also \fI--mail-rcpt-allowfails\fP.
.IP "\-M, \-\-manual"
Manual. Display the huge help text.
Providing --manual multiple times has no extra effect.
Disable it again with --no-manual.
Example:
.nf
curl --manual
.fi
See also \fI-v, --verbose\fP, \fI--libcurl\fP and \fI--trace\fP.
.IP "\-\-max-filesize <bytes>"
(FTP HTTP MQTT) Specify the maximum size (in bytes) of a file to download. If the file
requested is larger than this value, the transfer will not start and curl will
return with exit code 63.
A size modifier may be used. For example, Appending 'k' or 'K' will count the
number as kilobytes, 'm' or 'M' makes it megabytes, while 'g' or 'G' makes it
gigabytes. Examples: 200K, 3m and 1G. (Added in 7.58.0)
\fBNOTE\fP: The file size is not always known prior to download, and for such
files this option has no effect even if the file transfer ends up being larger
than this given limit.
If --max-filesize is provided several times, the last set value will be used.
Example:
.nf
curl --max-filesize 100K https://example.com
.fi
See also \fI--limit-rate\fP.
.IP "\-\-max-redirs <num>"
(HTTP) Set maximum number of redirections to follow. When \-\-location is used, to
prevent curl from following too many redirects, by default, the limit is
set to 50 redirects. Set this option to \-1 to make it unlimited.
If --max-redirs is provided several times, the last set value will be used.
Example:
.nf
curl --max-redirs 3 --location https://example.com
.fi
See also \fI-L, --location\fP.
.IP "\-m, \-\-max-time <fractional seconds>"
Maximum time in seconds that you allow each transfer to take. This is
useful for preventing your batch jobs from hanging for hours due to slow
networks or links going down. Since 7.32.0, this option accepts decimal
values, but the actual timeout will decrease in accuracy as the specified
timeout increases in decimal precision.
If you enable retrying the transfer (\fI\-\-retry\fP) then the maximum time counter is
reset each time the transfer is retried. You can use \-\-retry-max-time to limit
the retry time.
If --max-time is provided several times, the last set value will be used.
Examples:
.nf
curl --max-time 10 https://example.com
curl --max-time 2.92 https://example.com
.fi
See also \fI--connect-timeout\fP and \fI--retry-max-time\fP.
.IP "\-\-metalink"
This option was previously used to specify a metalink resource. Metalink
support has been disabled in curl since 7.78.0 for security reasons.
If --metalink is provided several times, the last set value will be used.
Example:
.nf
curl --metalink file https://example.com
.fi
See also \fI-Z, --parallel\fP.
.IP "\-\-negotiate"
(HTTP) Enables Negotiate (SPNEGO) authentication.
This option requires a library built with GSS-API or SSPI support. Use
\-\-version to see if your curl supports GSS-API/SSPI or SPNEGO.
When using this option, you must also provide a fake \-\-user option to activate
the authentication code properly. Sending a '-u :' is enough as the user name
and password from the \-\-user option are not actually used.
If this option is used several times, only the first one is used.
Providing --negotiate multiple times has no extra effect.
Example:
.nf
curl --negotiate -u : https://example.com
.fi
See also \fI--basic\fP, \fI--ntlm\fP, \fI--anyauth\fP and \fI--proxy-negotiate\fP.
.IP "\-\-netrc-file <filename>"
This option is similar to \fI\-n, \-\-netrc\fP, except that you provide the path (absolute
or relative) to the netrc file that curl should use. You can only specify one
netrc file per invocation.
It will abide by \-\-netrc-optional if specified.
If --netrc-file is provided several times, the last set value will be used.
Example:
.nf
curl --netrc-file netrc https://example.com
.fi
See also \fI-n, --netrc\fP, \fI-u, --user\fP and \fI-K, --config\fP. This option is mutually exclusive to \fI-n, --netrc\fP.
.IP "\-\-netrc-optional"
Similar to \fI\-n, \-\-netrc\fP, but this option makes the .netrc usage \fBoptional\fP
and not mandatory as the \-\-netrc option does.
Providing --netrc-optional multiple times has no extra effect.
Disable it again with --no-netrc-optional.
Example:
.nf
curl --netrc-optional https://example.com
.fi
See also \fI--netrc-file\fP. This option is mutually exclusive to \fI-n, --netrc\fP.
.IP "\-n, \-\-netrc"
Makes curl scan the \fI.netrc\fP (\fI_netrc\fP on Windows) file in the user's home
directory for login name and password. This is typically used for FTP on
Unix. If used with HTTP, curl will enable user authentication. See
\fInetrc(5)\fP and \fIftp(1)\fP for details on the file format. Curl will not
complain if that file does not have the right permissions (it should be
neither world- nor group-readable). The environment variable "HOME" is used
to find the home directory.
A quick and simple example of how to setup a \fI.netrc\fP to allow curl to FTP to
the machine host.domain.com with user name 'myself' and password 'secret'
could look similar to:
.nf
machine host.domain.com
login myself
password secret
.fi
Providing --netrc multiple times has no extra effect.
Disable it again with --no-netrc.
Example:
.nf
curl --netrc https://example.com
.fi
See also \fI--netrc-file\fP, \fI-K, --config\fP and \fI-u, --user\fP.
.IP "\-:, \-\-next"
Tells curl to use a separate operation for the following URL and associated
options. This allows you to send several URL requests, each with their own
specific options, for example, such as different user names or custom requests
for each.
\-\-next will reset all local options and only global ones will have their
values survive over to the operation following the \-\-next instruction. Global
options include \fI\-v, \-\-verbose\fP, \fI\-\-trace\fP, \-\-trace-ascii and \fI\-\-fail-early\fP.
For example, you can do both a GET and a POST in a single command line:
.nf
curl www1.example.com \-\-next \-d postthis www2.example.com
.fi
--next can be used several times in a command line
Examples:
.nf
curl https://example.com --next -d postthis www2.example.com
curl -I https://example.com --next https://example.net/
.fi
See also \fI-Z, --parallel\fP and \fI-K, --config\fP. Added in 7.36.0.
.IP "\-\-no-alpn"
(HTTPS) Disable the ALPN TLS extension. ALPN is enabled by default if libcurl was built
with an SSL library that supports ALPN. ALPN is used by a libcurl that supports
HTTP/2 to negotiate HTTP/2 support with the server during https sessions.
Providing --no-alpn multiple times has no extra effect.
Disable it again with --alpn.
Example:
.nf
curl --no-alpn https://example.com
.fi
See also \fI--no-npn\fP and \fI--http2\fP. \fI--no-alpn\fP requires that the underlying libcurl was built to support TLS. Added in 7.36.0.
.IP "\-N, \-\-no-buffer"
Disables the buffering of the output stream. In normal work situations, curl
will use a standard buffered output stream that will have the effect that it
will output the data in chunks, not necessarily exactly when the data arrives.
Using this option will disable that buffering.
Providing --no-buffer multiple times has no extra effect.
Disable it again with --buffer.
Example:
.nf
curl --no-buffer https://example.com
.fi
See also \fI-#, --progress-bar\fP.
.IP "\-\-no-clobber"
When used in conjunction with the \fI\-o, \-\-output\fP, \fI\-J, \-\-remote-header-name\fP,
\fI\-O, \-\-remote-name\fP, or \-\-remote-name-all options, curl avoids overwriting files
that already exist. Instead, a dot and a number gets appended to the name
of the file that would be created, up to filename.100 after which it will not
create any file.
Note that this is the negated option name documented. You can thus use
\-\-clobber to enforce the clobbering, even if \-\-remote-header-name or \-J is
specified.
Providing --no-clobber multiple times has no extra effect.
Disable it again with --clobber.
Example:
.nf
curl --no-clobber --output local/dir/file https://example.com
.fi
See also \fI-o, --output\fP and \fI-O, --remote-name\fP. Added in 7.83.0.
.IP "\-\-no-keepalive"
Disables the use of keepalive messages on the TCP connection. curl otherwise
enables them by default.
Note that this is the negated option name documented. You can thus use
\-\-keepalive to enforce keepalive.
Providing --no-keepalive multiple times has no extra effect.
Disable it again with --keepalive.
Example:
.nf
curl --no-keepalive https://example.com
.fi
See also \fI--keepalive-time\fP.
.IP "\-\-no-npn"
(HTTPS) In curl 7.86.0 and later, curl never uses NPN.
Disable the NPN TLS extension. NPN is enabled by default if libcurl was built
with an SSL library that supports NPN. NPN is used by a libcurl that supports
HTTP/2 to negotiate HTTP/2 support with the server during https sessions.
Providing --no-npn multiple times has no extra effect.
Disable it again with --npn.
Example:
.nf
curl --no-npn https://example.com
.fi
See also \fI--no-alpn\fP and \fI--http2\fP. \fI--no-npn\fP requires that the underlying libcurl was built to support TLS. Added in 7.36.0.
.IP "\-\-no-progress-meter"
Option to switch off the progress meter output without muting or otherwise
affecting warning and informational messages like \-\-silent does.
Note that this is the negated option name documented. You can thus use
\-\-progress-meter to enable the progress meter again.
Providing --no-progress-meter multiple times has no extra effect.
Disable it again with --progress-meter.
Example:
.nf
curl --no-progress-meter -o store https://example.com
.fi
See also \fI-v, --verbose\fP and \fI-s, --silent\fP. Added in 7.67.0.
.IP "\-\-no-sessionid"
(TLS) Disable curl's use of SSL session-ID caching. By default all transfers are
done using the cache. Note that while nothing should ever get hurt by
attempting to reuse SSL session-IDs, there seem to be broken SSL
implementations in the wild that may require you to disable this in order for
you to succeed.
Note that this is the negated option name documented. You can thus use
\-\-sessionid to enforce session-ID caching.
Providing --no-sessionid multiple times has no extra effect.
Disable it again with --sessionid.
Example:
.nf
curl --no-sessionid https://example.com
.fi
See also \fI-k, --insecure\fP.
.IP "\-\-noproxy <no-proxy-list>"
Comma-separated list of hosts for which not to use a proxy, if one is
specified. The only wildcard is a single * character, which matches all hosts,
and effectively disables the proxy. Each name in this list is matched as
either a domain which contains the hostname, or the hostname itself. For
example, local.com would match local.com, local.com:80, and www.local.com, but
not www.notlocal.com.
Since 7.53.0, This option overrides the environment variables that disable the
proxy ('no_proxy' and 'NO_PROXY'). If there's an environment variable
disabling a proxy, you can set the noproxy list to "" to override it.
If --noproxy is provided several times, the last set value will be used.
Example:
.nf
curl --noproxy "www.example" https://example.com
.fi
See also \fI-x, --proxy\fP.
.IP "\-\-ntlm-wb"
(HTTP) Enables NTLM much in the style \-\-ntlm does, but hand over the authentication
to the separate binary ntlmauth application that is executed when needed.
Providing --ntlm-wb multiple times has no extra effect.
Example:
.nf
curl --ntlm-wb -u user:password https://example.com
.fi
See also \fI--ntlm\fP and \fI--proxy-ntlm\fP.
.IP "\-\-ntlm"
(HTTP) Enables NTLM authentication. The NTLM authentication method was designed by
Microsoft and is used by IIS web servers. It is a proprietary protocol,
reverse-engineered by clever people and implemented in curl based on their
efforts. This kind of behavior should not be endorsed, you should encourage
everyone who uses NTLM to switch to a public and documented authentication
method instead, such as Digest.
If you want to enable NTLM for your proxy authentication, then use
\fI\-\-proxy-ntlm\fP.
If this option is used several times, only the first one is used.
Providing --ntlm multiple times has no extra effect.
Example:
.nf
curl --ntlm -u user:password https://example.com
.fi
See also \fI--proxy-ntlm\fP. \fI--ntlm\fP requires that the underlying libcurl was built to support TLS. This option is mutually exclusive to \fI--basic\fP and \fI--negotiate\fP and \fI--digest\fP and \fI--anyauth\fP.
.IP "\-\-oauth2-bearer <token>"
(IMAP LDAP POP3 SMTP HTTP) Specify the Bearer Token for OAUTH 2.0 server authentication. The Bearer Token
is used in conjunction with the user name which can be specified as part of
the \-\-url or \-\-user options.
The Bearer Token and user name are formatted according to RFC 6750.
If --oauth2-bearer is provided several times, the last set value will be used.
Example:
.nf
curl --oauth2-bearer "mF_9.B5f-4.1JqM" https://example.com
.fi
See also \fI--basic\fP, \fI--ntlm\fP and \fI--digest\fP. Added in 7.33.0.
.IP "\-\-output-dir <dir>"
This option specifies the directory in which files should be stored, when
\-\-remote-name or \-\-output are used.
The given output directory is used for all URLs and output options on the
command line, up until the first \fI\-:, \-\-next\fP.
If the specified target directory does not exist, the operation will fail
unless \-\-create-dirs is also used.
If --output-dir is provided several times, the last set value will be used.
Example:
.nf
curl --output-dir "tmp" -O https://example.com
.fi
See also \fI-O, --remote-name\fP and \fI-J, --remote-header-name\fP. Added in 7.73.0.
.IP "\-o, \-\-output <file>"
Write output to <file> instead of stdout. If you are using {} or [] to fetch
multiple documents, you should quote the URL and you can use '#' followed by a
number in the <file> specifier. That variable will be replaced with the current
string for the URL being fetched. Like in:
.nf
curl "http://{one,two}.example.com" \-o "file_#1.txt"
.fi
or use several variables like:
.nf
curl "http://{site,host}.host[1-5].com" \-o "#1_#2"
.fi
You may use this option as many times as the number of URLs you have. For
example, if you specify two URLs on the same command line, you can use it like
this:
.nf
curl \-o aa example.com \-o bb example.net
.fi
and the order of the \-o options and the URLs does not matter, just that the
first \-o is for the first URL and so on, so the above command line can also be
written as
.nf
curl example.com example.net \-o aa \-o bb
.fi
See also the \-\-create-dirs option to create the local directories
dynamically. Specifying the output as '-' (a single dash) will force the
output to be done to stdout.
To suppress response bodies, you can redirect output to /dev/null:
.nf
curl example.com \-o /dev/null
.fi
Or for Windows use nul:
.nf
curl example.com \-o nul
.fi
--output can be used several times in a command line
Examples:
.nf
curl -o file https://example.com
curl "http://{one,two}.example.com" -o "file_#1.txt"
curl "http://{site,host}.host[1-5].com" -o "#1_#2"
curl -o file https://example.com -o file2 https://example.net
.fi
See also \fI-O, --remote-name\fP, \fI--remote-name-all\fP and \fI-J, --remote-header-name\fP.
.IP "\-\-parallel-immediate"
When doing parallel transfers, this option will instruct curl that it should
rather prefer opening up more connections in parallel at once rather than
waiting to see if new transfers can be added as multiplexed streams on another
connection.
This option is global and does not need to be specified for each use of
\fI\-:, \-\-next\fP.
Providing --parallel-immediate multiple times has no extra effect.
Disable it again with --no-parallel-immediate.
Example:
.nf
curl --parallel-immediate -Z https://example.com -o file1 https://example.com -o file2
.fi
See also \fI-Z, --parallel\fP and \fI--parallel-max\fP. Added in 7.68.0.
.IP "\-\-parallel-max <num>"
When asked to do parallel transfers, using \fI\-Z, \-\-parallel\fP, this option controls
the maximum amount of transfers to do simultaneously.
This option is global and does not need to be specified for each use of
\fI\-:, \-\-next\fP.
The default is 50.
If --parallel-max is provided several times, the last set value will be used.
Example:
.nf
curl --parallel-max 100 -Z https://example.com ftp://example.com/
.fi
See also \fI-Z, --parallel\fP. Added in 7.66.0.
.IP "\-Z, \-\-parallel"
Makes curl perform its transfers in parallel as compared to the regular serial
manner.
This option is global and does not need to be specified for each use of
\fI\-:, \-\-next\fP.
Providing --parallel multiple times has no extra effect.
Disable it again with --no-parallel.
Example:
.nf
curl --parallel https://example.com -o file1 https://example.com -o file2
.fi
See also \fI-:, --next\fP and \fI-v, --verbose\fP. Added in 7.66.0.
.IP "\-\-pass <phrase>"
(SSH TLS) Passphrase for the private key.
If --pass is provided several times, the last set value will be used.
Example:
.nf
curl --pass secret --key file https://example.com
.fi
See also \fI--key\fP and \fI-u, --user\fP.
.IP "\-\-path-as-is"
Tell curl to not handle sequences of /../ or /./ in the given URL
path. Normally curl will squash or merge them according to standards but with
this option set you tell it not to do that.
Providing --path-as-is multiple times has no extra effect.
Disable it again with --no-path-as-is.
Example:
.nf
curl --path-as-is https://example.com/../../etc/passwd
.fi
See also \fI--request-target\fP. Added in 7.42.0.
.IP "\-\-pinnedpubkey <hashes>"
(TLS) Tells curl to use the specified public key file (or hashes) to verify the
peer. This can be a path to a file which contains a single public key in PEM
or DER format, or any number of base64 encoded sha256 hashes preceded by
\(aqsha256//' and separated by ';'.
When negotiating a TLS or SSL connection, the server sends a certificate
indicating its identity. A public key is extracted from this certificate and
if it does not exactly match the public key provided to this option, curl will
abort the connection before sending or receiving any data.
PEM/DER support:
7.39.0: OpenSSL, GnuTLS and GSKit
7.43.0: NSS and wolfSSL
7.47.0: mbedtls
sha256 support:
7.44.0: OpenSSL, GnuTLS, NSS and wolfSSL
7.47.0: mbedtls
Other SSL backends not supported.
If --pinnedpubkey is provided several times, the last set value will be used.
Examples:
.nf
curl --pinnedpubkey keyfile https://example.com
curl --pinnedpubkey 'sha256//ce118b51897f4452dc' https://example.com
.fi
See also \fI--hostpubsha256\fP. Added in 7.39.0.
.IP "\-\-post301"
(HTTP) Tells curl to respect RFC 7231/6.4.2 and not convert POST requests into GET
requests when following a 301 redirection. The non-RFC behavior is ubiquitous
in web browsers, so curl does the conversion by default to maintain
consistency. However, a server may require a POST to remain a POST after such
a redirection. This option is meaningful only when using \fI\-L, \-\-location\fP.
Providing --post301 multiple times has no extra effect.
Disable it again with --no-post301.
Example:
.nf
curl --post301 --location -d "data" https://example.com
.fi
See also \fI--post302\fP, \fI--post303\fP and \fI-L, --location\fP.
.IP "\-\-post302"
(HTTP) Tells curl to respect RFC 7231/6.4.3 and not convert POST requests into GET
requests when following a 302 redirection. The non-RFC behavior is ubiquitous
in web browsers, so curl does the conversion by default to maintain
consistency. However, a server may require a POST to remain a POST after such
a redirection. This option is meaningful only when using \fI\-L, \-\-location\fP.
Providing --post302 multiple times has no extra effect.
Disable it again with --no-post302.
Example:
.nf
curl --post302 --location -d "data" https://example.com
.fi
See also \fI--post301\fP, \fI--post303\fP and \fI-L, --location\fP.
.IP "\-\-post303"
(HTTP) Tells curl to violate RFC 7231/6.4.4 and not convert POST requests into GET
requests when following 303 redirections. A server may require a POST to
remain a POST after a 303 redirection. This option is meaningful only when
using \fI\-L, \-\-location\fP.
Providing --post303 multiple times has no extra effect.
Disable it again with --no-post303.
Example:
.nf
curl --post303 --location -d "data" https://example.com
.fi
See also \fI--post302\fP, \fI--post301\fP and \fI-L, --location\fP.
.IP "\-\-preproxy [protocol://]host[:port]"
Use the specified SOCKS proxy before connecting to an HTTP or HTTPS \fI\-x, \-\-proxy\fP. In
such a case curl first connects to the SOCKS proxy and then connects (through
SOCKS) to the HTTP or HTTPS proxy. Hence pre proxy.
The pre proxy string should be specified with a protocol:// prefix to specify
alternative proxy protocols. Use socks4://, socks4a://, socks5:// or
socks5h:// to request the specific SOCKS version to be used. No protocol
specified will make curl default to SOCKS4.
If the port number is not specified in the proxy string, it is assumed to be
1080.
User and password that might be provided in the proxy string are URL decoded
by curl. This allows you to pass in special characters such as @ by using %40
or pass in a colon with %3a.
If --preproxy is provided several times, the last set value will be used.
Example:
.nf
curl --preproxy socks5://proxy.example -x http://http.example https://example.com
.fi
See also \fI-x, --proxy\fP and \fI--socks5\fP. Added in 7.52.0.
.IP "\-#, \-\-progress-bar"
Make curl display transfer progress as a simple progress bar instead of the
standard, more informational, meter.
This progress bar draws a single line of '#' characters across the screen and
shows a percentage if the transfer size is known. For transfers without a
known size, there will be space ship (-=o=-) that moves back and forth but
only while data is being transferred, with a set of flying hash sign symbols on
top.
This option is global and does not need to be specified for each use of
\fI\-:, \-\-next\fP.
Providing --progress-bar multiple times has no extra effect.
Disable it again with --no-progress-bar.
Example:
.nf
curl -# -O https://example.com
.fi
See also \fI--styled-output\fP.
.IP "\-\-proto-default <protocol>"
Tells curl to use \fIprotocol\fP for any URL missing a scheme name.
An unknown or unsupported protocol causes error
\fICURLE_UNSUPPORTED_PROTOCOL\fP (1).
This option does not change the default proxy protocol (http).
Without this option set, curl guesses protocol based on the host name, see
\-\-url for details.
If --proto-default is provided several times, the last set value will be used.
Example:
.nf
curl --proto-default https ftp.example.com
.fi
See also \fI--proto\fP and \fI--proto-redir\fP. Added in 7.45.0.
.IP "\-\-proto-redir <protocols>"
Tells curl to limit what protocols it may use on redirect. Protocols denied by
\-\-proto are not overridden by this option. See \-\-proto for how protocols are
represented.
Example, allow only HTTP and HTTPS on redirect:
.nf
curl \-\-proto-redir \-all,http,https http://example.com
.fi
By default curl will only allow HTTP, HTTPS, FTP and FTPS on redirect (since
7.65.2). Specifying \fIall\fP or \fI+all\fP enables all protocols on redirects, which
is not good for security.
If --proto-redir is provided several times, the last set value will be used.
Example:
.nf
curl --proto-redir =http,https https://example.com
.fi
See also \fI--proto\fP.
.IP "\-\-proto <protocols>"
Tells curl to limit what protocols it may use for transfers. Protocols are
evaluated left to right, are comma separated, and are each a protocol name or
\(aqall', optionally prefixed by zero or more modifiers. Available modifiers are:
.RS
.TP 3
.B +
Permit this protocol in addition to protocols already permitted (this is
the default if no modifier is used).
.TP
.B \-
Deny this protocol, removing it from the list of protocols already permitted.
.TP
.B =
Permit only this protocol (ignoring the list already permitted), though
subject to later modification by subsequent entries in the comma separated
list.
.RE
.IP
For example:
.RS
.TP 15
.B \fI\-\-proto\fP \-ftps
uses the default protocols, but disables ftps
.TP
.B \fI\-\-proto\fP \-all,https,+http
only enables http and https
.TP
.B \fI\-\-proto\fP =http,https
also only enables http and https
.RE
.IP
Unknown and disabled protocols produce a warning. This allows scripts to
safely rely on being able to disable potentially dangerous protocols, without
relying upon support for that protocol being built into curl to avoid an error.
This option can be used multiple times, in which case the effect is the same
as concatenating the protocols into one instance of the option.
If --proto is provided several times, the last set value will be used.
Example:
.nf
curl --proto =http,https,sftp https://example.com
.fi
See also \fI--proto-redir\fP and \fI--proto-default\fP.
.IP "\-\-proxy-anyauth"
Tells curl to pick a suitable authentication method when communicating with
the given HTTP proxy. This might cause an extra request/response round-trip.
Providing --proxy-anyauth multiple times has no extra effect.
Example:
.nf
curl --proxy-anyauth --proxy-user user:passwd -x proxy https://example.com
.fi
See also \fI-x, --proxy\fP, \fI--proxy-basic\fP and \fI--proxy-digest\fP.
.IP "\-\-proxy-basic"
Tells curl to use HTTP Basic authentication when communicating with the given
proxy. Use \-\-basic for enabling HTTP Basic with a remote host. Basic is the
default authentication method curl uses with proxies.
Providing --proxy-basic multiple times has no extra effect.
Example:
.nf
curl --proxy-basic --proxy-user user:passwd -x proxy https://example.com
.fi
See also \fI-x, --proxy\fP, \fI--proxy-anyauth\fP and \fI--proxy-digest\fP.
.IP "\-\-proxy-cacert <file>"
Same as \-\-cacert but used in HTTPS proxy context.
If --proxy-cacert is provided several times, the last set value will be used.
Example:
.nf
curl --proxy-cacert CA-file.txt -x https://proxy https://example.com
.fi
See also \fI--proxy-capath\fP, \fI--cacert\fP, \fI--capath\fP and \fI-x, --proxy\fP. Added in 7.52.0.
.IP "\-\-proxy-capath <dir>"
Same as \-\-capath but used in HTTPS proxy context.
If --proxy-capath is provided several times, the last set value will be used.
Example:
.nf
curl --proxy-capath /local/directory -x https://proxy https://example.com
.fi
See also \fI--proxy-cacert\fP, \fI-x, --proxy\fP and \fI--capath\fP. Added in 7.52.0.
.IP "\-\-proxy-cert-type <type>"
Same as \-\-cert-type but used in HTTPS proxy context.
If --proxy-cert-type is provided several times, the last set value will be used.
Example:
.nf
curl --proxy-cert-type PEM --proxy-cert file -x https://proxy https://example.com
.fi
See also \fI--proxy-cert\fP. Added in 7.52.0.
.IP "\-\-proxy-cert <cert[:passwd]>"
Same as \-\-cert but used in HTTPS proxy context.
If --proxy-cert is provided several times, the last set value will be used.
Example:
.nf
curl --proxy-cert file -x https://proxy https://example.com
.fi
See also \fI--proxy-cert-type\fP. Added in 7.52.0.
.IP "\-\-proxy-ciphers <list>"
Same as \-\-ciphers but used in HTTPS proxy context.
If --proxy-ciphers is provided several times, the last set value will be used.
Example:
.nf
curl --proxy-ciphers ECDHE-ECDSA-AES256-CCM8 -x https://proxy https://example.com
.fi
See also \fI--ciphers\fP, \fI--curves\fP and \fI-x, --proxy\fP. Added in 7.52.0.
.IP "\-\-proxy-crlfile <file>"
Same as \-\-crlfile but used in HTTPS proxy context.
If --proxy-crlfile is provided several times, the last set value will be used.
Example:
.nf
curl --proxy-crlfile rejects.txt -x https://proxy https://example.com
.fi
See also \fI--crlfile\fP and \fI-x, --proxy\fP. Added in 7.52.0.
.IP "\-\-proxy-digest"
Tells curl to use HTTP Digest authentication when communicating with the given
proxy. Use \-\-digest for enabling HTTP Digest with a remote host.
Providing --proxy-digest multiple times has no extra effect.
Example:
.nf
curl --proxy-digest --proxy-user user:passwd -x proxy https://example.com
.fi
See also \fI-x, --proxy\fP, \fI--proxy-anyauth\fP and \fI--proxy-basic\fP.
.IP "\-\-proxy-header <header/@file>"
(HTTP) Extra header to include in the request when sending HTTP to a proxy. You may
specify any number of extra headers. This is the equivalent option to \-\-header
but is for proxy communication only like in CONNECT requests when you want a
separate header sent to the proxy to what is sent to the actual remote host.
curl will make sure that each header you add/replace is sent with the proper
end-of-line marker, you should thus \fBnot\fP add that as a part of the header
content: do not add newlines or carriage returns, they will only mess things
up for you.
Headers specified with this option will not be included in requests that curl
knows will not be sent to a proxy.
Starting in 7.55.0, this option can take an argument in @filename style, which
then adds a header for each line in the input file. Using @- will make curl
read the header file from stdin.
This option can be used multiple times to add/replace/remove multiple headers.
--proxy-header can be used several times in a command line
Examples:
.nf
curl --proxy-header "X-First-Name: Joe" -x http://proxy https://example.com
curl --proxy-header "User-Agent: surprise" -x http://proxy https://example.com
curl --proxy-header "Host:" -x http://proxy https://example.com
.fi
See also \fI-x, --proxy\fP. Added in 7.37.0.
.IP "\-\-proxy-insecure"
Same as \-\-insecure but used in HTTPS proxy context.
Providing --proxy-insecure multiple times has no extra effect.
Disable it again with --no-proxy-insecure.
Example:
.nf
curl --proxy-insecure -x https://proxy https://example.com
.fi
See also \fI-x, --proxy\fP and \fI-k, --insecure\fP. Added in 7.52.0.
.IP "\-\-proxy-key-type <type>"
Same as \-\-key-type but used in HTTPS proxy context.
If --proxy-key-type is provided several times, the last set value will be used.
Example:
.nf
curl --proxy-key-type DER --proxy-key here -x https://proxy https://example.com
.fi
See also \fI--proxy-key\fP and \fI-x, --proxy\fP. Added in 7.52.0.
.IP "\-\-proxy-key <key>"
Same as \-\-key but used in HTTPS proxy context.
If --proxy-key is provided several times, the last set value will be used.
Example:
.nf
curl --proxy-key here -x https://proxy https://example.com
.fi
See also \fI--proxy-key-type\fP and \fI-x, --proxy\fP. Added in 7.52.0.
.IP "\-\-proxy-negotiate"
Tells curl to use HTTP Negotiate (SPNEGO) authentication when communicating
with the given proxy. Use \-\-negotiate for enabling HTTP Negotiate (SPNEGO)
with a remote host.
Providing --proxy-negotiate multiple times has no extra effect.
Example:
.nf
curl --proxy-negotiate --proxy-user user:passwd -x proxy https://example.com
.fi
See also \fI--proxy-anyauth\fP and \fI--proxy-basic\fP.
.IP "\-\-proxy-ntlm"
Tells curl to use HTTP NTLM authentication when communicating with the given
proxy. Use \-\-ntlm for enabling NTLM with a remote host.
Providing --proxy-ntlm multiple times has no extra effect.
Example:
.nf
curl --proxy-ntlm --proxy-user user:passwd -x http://proxy https://example.com
.fi
See also \fI--proxy-negotiate\fP and \fI--proxy-anyauth\fP.
.IP "\-\-proxy-pass <phrase>"
Same as \-\-pass but used in HTTPS proxy context.
If --proxy-pass is provided several times, the last set value will be used.
Example:
.nf
curl --proxy-pass secret --proxy-key here -x https://proxy https://example.com
.fi
See also \fI-x, --proxy\fP and \fI--proxy-key\fP. Added in 7.52.0.
.IP "\-\-proxy-pinnedpubkey <hashes>"
(TLS) Tells curl to use the specified public key file (or hashes) to verify the
proxy. This can be a path to a file which contains a single public key in PEM
or DER format, or any number of base64 encoded sha256 hashes preceded by
\(aqsha256//' and separated by ';'.
When negotiating a TLS or SSL connection, the server sends a certificate
indicating its identity. A public key is extracted from this certificate and
if it does not exactly match the public key provided to this option, curl will
abort the connection before sending or receiving any data.
If --proxy-pinnedpubkey is provided several times, the last set value will be used.
Examples:
.nf
curl --proxy-pinnedpubkey keyfile https://example.com
curl --proxy-pinnedpubkey 'sha256//ce118b51897f4452dc' https://example.com
.fi
See also \fI--pinnedpubkey\fP and \fI-x, --proxy\fP. Added in 7.59.0.
.IP "\-\-proxy-service-name <name>"
This option allows you to change the service name for proxy negotiation.
If --proxy-service-name is provided several times, the last set value will be used.
Example:
.nf
curl --proxy-service-name "shrubbery" -x proxy https://example.com
.fi
See also \fI--service-name\fP and \fI-x, --proxy\fP. Added in 7.43.0.
.IP "\-\-proxy-ssl-allow-beast"
Same as \-\-ssl-allow-beast but used in HTTPS proxy context.
Providing --proxy-ssl-allow-beast multiple times has no extra effect.
Disable it again with --no-proxy-ssl-allow-beast.
Example:
.nf
curl --proxy-ssl-allow-beast -x https://proxy https://example.com
.fi
See also \fI--ssl-allow-beast\fP and \fI-x, --proxy\fP. Added in 7.52.0.
.IP "\-\-proxy-ssl-auto-client-cert"
Same as \-\-ssl-auto-client-cert but used in HTTPS proxy context.
Providing --proxy-ssl-auto-client-cert multiple times has no extra effect.
Disable it again with --no-proxy-ssl-auto-client-cert.
Example:
.nf
curl --proxy-ssl-auto-client-cert -x https://proxy https://example.com
.fi
See also \fI--ssl-auto-client-cert\fP and \fI-x, --proxy\fP. Added in 7.77.0.
.IP "\-\-proxy-tls13-ciphers <ciphersuite list>"
(TLS) Specifies which cipher suites to use in the connection to your HTTPS proxy
when it negotiates TLS 1.3. The list of ciphers suites must specify valid
ciphers. Read up on TLS 1.3 cipher suite details on this URL:
.nf
https://curl.se/docs/ssl-ciphers.html
.fi
This option is currently used only when curl is built to use OpenSSL 1.1.1 or
later. If you are using a different SSL backend you can try setting TLS 1.3
cipher suites by using the \-\-proxy-ciphers option.
If --proxy-tls13-ciphers is provided several times, the last set value will be used.
Example:
.nf
curl --proxy-tls13-ciphers TLS_AES_128_GCM_SHA256 -x proxy https://example.com
.fi
See also \fI--tls13-ciphers\fP and \fI--curves\fP. Added in 7.61.0.
.IP "\-\-proxy-tlsauthtype <type>"
Same as \-\-tlsauthtype but used in HTTPS proxy context.
If --proxy-tlsauthtype is provided several times, the last set value will be used.
Example:
.nf
curl --proxy-tlsauthtype SRP -x https://proxy https://example.com
.fi
See also \fI-x, --proxy\fP and \fI--proxy-tlsuser\fP. Added in 7.52.0.
.IP "\-\-proxy-tlspassword <string>"
Same as \-\-tlspassword but used in HTTPS proxy context.
If --proxy-tlspassword is provided several times, the last set value will be used.
Example:
.nf
curl --proxy-tlspassword passwd -x https://proxy https://example.com
.fi
See also \fI-x, --proxy\fP and \fI--proxy-tlsuser\fP. Added in 7.52.0.
.IP "\-\-proxy-tlsuser <name>"
Same as \-\-tlsuser but used in HTTPS proxy context.
If --proxy-tlsuser is provided several times, the last set value will be used.
Example:
.nf
curl --proxy-tlsuser smith -x https://proxy https://example.com
.fi
See also \fI-x, --proxy\fP and \fI--proxy-tlspassword\fP. Added in 7.52.0.
.IP "\-\-proxy-tlsv1"
Same as \-\-tlsv1 but used in HTTPS proxy context.
Providing --proxy-tlsv1 multiple times has no extra effect.
Example:
.nf
curl --proxy-tlsv1 -x https://proxy https://example.com
.fi
See also \fI-x, --proxy\fP. Added in 7.52.0.
.IP "\-U, \-\-proxy-user <user:password>"
Specify the user name and password to use for proxy authentication.
If you use a Windows SSPI-enabled curl binary and do either Negotiate or NTLM
authentication then you can tell curl to select the user name and password
from your environment by specifying a single colon with this option: "-U :".
On systems where it works, curl will hide the given option argument from
process listings. This is not enough to protect credentials from possibly
getting seen by other users on the same system as they will still be visible
for a moment before cleared. Such sensitive data should be retrieved from a
file instead or similar and never used in clear text in a command line.
If --proxy-user is provided several times, the last set value will be used.
Example:
.nf
curl --proxy-user name:pwd -x proxy https://example.com
.fi
See also \fI--proxy-pass\fP.
.IP "\-x, \-\-proxy [protocol://]host[:port]"
Use the specified proxy.
The proxy string can be specified with a protocol:// prefix. No protocol
specified or http:// will be treated as HTTP proxy. Use socks4://, socks4a://,
socks5:// or socks5h:// to request a specific SOCKS version to be used.
Unix domain sockets are supported for socks proxy. Set localhost for the host
part. e.g. socks5h://localhost/path/to/socket.sock
HTTPS proxy support via https:// protocol prefix was added in 7.52.0 for
OpenSSL, GnuTLS and NSS.
Unrecognized and unsupported proxy protocols cause an error since 7.52.0.
Prior versions may ignore the protocol and use http:// instead.
If the port number is not specified in the proxy string, it is assumed to be
1080.
This option overrides existing environment variables that set the proxy to
use. If there's an environment variable setting a proxy, you can set proxy to
\(dq" to override it.
All operations that are performed over an HTTP proxy will transparently be
converted to HTTP. It means that certain protocol specific operations might
not be available. This is not the case if you can tunnel through the proxy, as
one with the \-\-proxytunnel option.
User and password that might be provided in the proxy string are URL decoded
by curl. This allows you to pass in special characters such as @ by using %40
or pass in a colon with %3a.
The proxy host can be specified the same way as the proxy environment
variables, including the protocol prefix (http://) and the embedded user +
password.
If --proxy is provided several times, the last set value will be used.
Example:
.nf
curl --proxy http://proxy.example https://example.com
.fi
See also \fI--socks5\fP and \fI--proxy-basic\fP.
.IP "\-\-proxy1.0 <host[:port]>"
Use the specified HTTP 1.0 proxy. If the port number is not specified, it is
assumed at port 1080.
The only difference between this and the HTTP proxy option \fI\-x, \-\-proxy\fP, is that
attempts to use CONNECT through the proxy will specify an HTTP 1.0 protocol
instead of the default HTTP 1.1.
Providing --proxy1.0 multiple times has no extra effect.
Example:
.nf
curl --proxy1.0 -x http://proxy https://example.com
.fi
See also \fI-x, --proxy\fP, \fI--socks5\fP and \fI--preproxy\fP.
.IP "\-p, \-\-proxytunnel"
When an HTTP proxy is used \fI\-x, \-\-proxy\fP, this option will make curl tunnel through
the proxy. The tunnel approach is made with the HTTP proxy CONNECT request and
requires that the proxy allows direct connect to the remote port number curl
wants to tunnel through to.
To suppress proxy CONNECT response headers when curl is set to output headers
use \fI\-\-suppress-connect-headers\fP.
Providing --proxytunnel multiple times has no extra effect.
Disable it again with --no-proxytunnel.
Example:
.nf
curl --proxytunnel -x http://proxy https://example.com
.fi
See also \fI-x, --proxy\fP.
.IP "\-\-pubkey <key>"
(SFTP SCP) Public key file name. Allows you to provide your public key in this separate
file.
(As of 7.39.0, curl attempts to automatically extract the public key from the
private key file, so passing this option is generally not required. Note that
this public key extraction requires libcurl to be linked against a copy of
libssh2 1.2.8 or higher that is itself linked against OpenSSL.)
If --pubkey is provided several times, the last set value will be used.
Example:
.nf
curl --pubkey file.pub sftp://example.com/
.fi
See also \fI--pass\fP.
.IP "\-Q, \-\-quote <command>"
(FTP SFTP) Send an arbitrary command to the remote FTP or SFTP server. Quote commands are
sent BEFORE the transfer takes place (just after the initial PWD command in an
FTP transfer, to be exact). To make commands take place after a successful
transfer, prefix them with a dash '-'.
(FTP only) To make commands be sent after curl has changed the working
directory, just before the file transfer command(s), prefix the command with a
\(aq+'. This is not performed when a directory listing is performed.
You may specify any number of commands.
By default curl will stop at first failure. To make curl continue even if the
command fails, prefix the command with an asterisk (*). Otherwise, if the
server returns failure for one of the commands, the entire operation will be
aborted.
You must send syntactically correct FTP commands as RFC 959 defines to FTP
servers, or one of the commands listed below to SFTP servers.
This option can be used multiple times.
SFTP is a binary protocol. Unlike for FTP, curl interprets SFTP quote commands
itself before sending them to the server. File names may be quoted
shell-style to embed spaces or special characters. Following is the list of
all supported SFTP quote commands:
.RS
.IP "atime date file"
The atime command sets the last access time of the file named by the file
operand. The <date expression> can be all sorts of date strings, see the
\fIcurl_getdate(3)\fP man page for date expression details. (Added in 7.73.0)
.IP "chgrp group file"
The chgrp command sets the group ID of the file named by the file operand to
the group ID specified by the group operand. The group operand is a decimal
integer group ID.
.IP "chmod mode file"
The chmod command modifies the file mode bits of the specified file. The
mode operand is an octal integer mode number.
.IP "chown user file"
The chown command sets the owner of the file named by the file operand to the
user ID specified by the user operand. The user operand is a decimal
integer user ID.
.IP "ln source_file target_file"
The ln and symlink commands create a symbolic link at the target_file location
pointing to the source_file location.
.IP "mkdir directory_name"
The mkdir command creates the directory named by the directory_name operand.
.IP "mtime date file"
The mtime command sets the last modification time of the file named by the
file operand. The <date expression> can be all sorts of date strings, see the
\fIcurl_getdate(3)\fP man page for date expression details. (Added in 7.73.0)
.IP "pwd"
The pwd command returns the absolute pathname of the current working directory.
.IP "rename source target"
The rename command renames the file or directory named by the source
operand to the destination path named by the target operand.
.IP "rm file"
The rm command removes the file specified by the file operand.
.IP "rmdir directory"
The rmdir command removes the directory entry specified by the directory
operand, provided it is empty.
.IP "symlink source_file target_file"
See ln.
.RE
--quote can be used several times in a command line
Example:
.nf
curl --quote "DELE file" ftp://example.com/foo
.fi
See also \fI-X, --request\fP.
.IP "\-\-random-file <file>"
Deprecated option. This option is ignored by curl since 7.84.0. Prior to that
it only had an effect on curl if built to use old versions of OpenSSL.
Specify the path name to file containing what will be considered as random
data. The data may be used to seed the random engine for SSL connections.
If --random-file is provided several times, the last set value will be used.
Example:
.nf
curl --random-file rubbish https://example.com
.fi
See also \fI--egd-file\fP.
.IP "\-r, \-\-range <range>"
(HTTP FTP SFTP FILE) Retrieve a byte range (i.e. a partial document) from an HTTP/1.1, FTP or SFTP
server or a local FILE. Ranges can be specified in a number of ways.
.RS
.TP 10
.B 0-499
specifies the first 500 bytes
.TP
.B 500-999
specifies the second 500 bytes
.TP
.B \-500
specifies the last 500 bytes
.TP
.B 9500-
specifies the bytes from offset 9500 and forward
.TP
.B 0-0,-1
specifies the first and last byte only(*)(HTTP)
.TP
.B 100-199,500-599
specifies two separate 100-byte ranges(*) (HTTP)
.RE
.IP
(*) = NOTE that this will cause the server to reply with a multipart
response, which will be returned as-is by curl! Parsing or otherwise
transforming this response is the responsibility of the caller.
Only digit characters (0-9) are valid in the 'start' and 'stop' fields of the
\(aqstart-stop' range syntax. If a non-digit character is given in the range,
the server's response will be unspecified, depending on the server's
configuration.
You should also be aware that many HTTP/1.1 servers do not have this feature
enabled, so that when you attempt to get a range, you will instead get the
whole document.
FTP and SFTP range downloads only support the simple 'start-stop' syntax
(optionally with one of the numbers omitted). FTP use depends on the extended
FTP command SIZE.
If --range is provided several times, the last set value will be used.
Example:
.nf
curl --range 22-44 https://example.com
.fi
See also \fI-C, --continue-at\fP and \fI-a, --append\fP.
.IP "\-\-rate <max request rate>"
Specify the maximum transfer frequency you allow curl to use \- in number of
transfer starts per time unit (sometimes called request rate). Without this
option, curl will start the next transfer as fast as possible.
If given several URLs and a transfer completes faster than the allowed rate,
curl will wait until the next transfer is started to maintain the requested
rate. This option has no effect when \-\-parallel is used.
The request rate is provided as "N/U" where N is an integer number and U is a
time unit. Supported units are 's' (second), 'm' (minute), 'h' (hour) and 'd'
/(day, as in a 24 hour unit). The default time unit, if no "/U" is provided,
is number of transfers per hour.
If curl is told to allow 10 requests per minute, it will not start the next
request until 6 seconds have elapsed since the previous transfer was started.
This function uses millisecond resolution. If the allowed frequency is set
more than 1000 per second, it will instead run unrestricted.
When retrying transfers, enabled with \fI\-\-retry\fP, the separate retry delay logic
is used and not this setting.
If --rate is provided several times, the last set value will be used.
Examples:
.nf
curl --rate 2/s https://example.com
curl --rate 3/h https://example.com
curl --rate 14/m https://example.com
.fi
See also \fI--limit-rate\fP and \fI--retry-delay\fP. Added in 7.84.0.
.IP "\-\-raw"
(HTTP) When used, it disables all internal HTTP decoding of content or transfer
encodings and instead makes them passed on unaltered, raw.
Providing --raw multiple times has no extra effect.
Disable it again with --no-raw.
Example:
.nf
curl --raw https://example.com
.fi
See also \fI--tr-encoding\fP.
.IP "\-e, \-\-referer <URL>"
(HTTP) Sends the "Referrer Page" information to the HTTP server. This can also be set
with the \-\-header flag of course. When used with \-\-location you can append
\(dq;auto" to the \-\-referer URL to make curl automatically set the previous URL
when it follows a Location: header. The ";auto" string can be used alone,
even if you do not set an initial \fI\-e, \-\-referer\fP.
If --referer is provided several times, the last set value will be used.
Examples:
.nf
curl --referer "https://fake.example" https://example.com
curl --referer "https://fake.example;auto" -L https://example.com
curl --referer ";auto" -L https://example.com
.fi
See also \fI-A, --user-agent\fP and \fI-H, --header\fP.
.IP "\-J, \-\-remote-header-name"
(HTTP) This option tells the \-\-remote-name option to use the server-specified
Content-Disposition filename instead of extracting a filename from the URL. If
the server-provided file name contains a path, that will be stripped off
before the file name is used.
The file is saved in the current directory, or in the directory specified with
\fI\-\-output-dir\fP.
If the server specifies a file name and a file with that name already exists
in the destination directory, it will not be overwritten and an error will
occur. If the server does not specify a file name then this option has no
effect.
There's no attempt to decode %-sequences (yet) in the provided file name, so
this option may provide you with rather unexpected file names.
\fBWARNING\fP: Exercise judicious use of this option, especially on Windows. A
rogue server could send you the name of a DLL or other file that could be
loaded automatically by Windows or some third party software.
Providing --remote-header-name multiple times has no extra effect.
Disable it again with --no-remote-header-name.
Example:
.nf
curl -OJ https://example.com/file
.fi
See also \fI-O, --remote-name\fP.
.IP "\-\-remote-name-all"
This option changes the default action for all given URLs to be dealt with as
if \-\-remote-name were used for each one. So if you want to disable that for a
specific URL after \-\-remote-name-all has been used, you must use "-o \-" or
\-\-no-remote-name.
Providing --remote-name-all multiple times has no extra effect.
Disable it again with --no-remote-name-all.
Example:
.nf
curl --remote-name-all ftp://example.com/file1 ftp://example.com/file2
.fi
See also \fI-O, --remote-name\fP.
.IP "\-O, \-\-remote-name"
Write output to a local file named like the remote file we get. (Only the file
part of the remote file is used, the path is cut off.)
The file will be saved in the current working directory. If you want the file
saved in a different directory, make sure you change the current working
directory before invoking curl with this option or use \fI\-\-output-dir\fP.
The remote file name to use for saving is extracted from the given URL,
nothing else, and if it already exists it will be overwritten. If you want the
server to be able to choose the file name refer to \-\-remote-header-name which
can be used in addition to this option. If the server chooses a file name and
that name already exists it will not be overwritten.
There is no URL decoding done on the file name. If it has %20 or other URL
encoded parts of the name, they will end up as-is as file name.
You may use this option as many times as the number of URLs you have.
--remote-name can be used several times in a command line
Example:
.nf
curl -O https://example.com/filename
.fi
See also \fI--remote-name-all\fP, \fI--output-dir\fP and \fI-J, --remote-header-name\fP.
.IP "\-R, \-\-remote-time"
When used, this will make curl attempt to figure out the timestamp of the
remote file, and if that is available make the local file get that same
timestamp.
Providing --remote-time multiple times has no extra effect.
Disable it again with --no-remote-time.
Example:
.nf
curl --remote-time -o foo https://example.com
.fi
See also \fI-O, --remote-name\fP and \fI-z, --time-cond\fP.
.IP "\-\-remove-on-error"
When curl returns an error when told to save output in a local file, this
option removes that saved file before exiting. This prevents curl from
leaving a partial file in the case of an error during transfer.
If the output is not a file, this option has no effect.
Providing --remove-on-error multiple times has no extra effect.
Disable it again with --no-remove-on-error.
Example:
.nf
curl --remove-on-error -o output https://example.com
.fi
See also \fI-f, --fail\fP. Added in 7.83.0.
.IP "\-\-request-target <path>"
(HTTP) Tells curl to use an alternative "target" (path) instead of using the path as
provided in the URL. Particularly useful when wanting to issue HTTP requests
without leading slash or other data that does not follow the regular URL
pattern, like "OPTIONS *".
If --request-target is provided several times, the last set value will be used.
Example:
.nf
curl --request-target "*" -X OPTIONS https://example.com
.fi
See also \fI-X, --request\fP. Added in 7.55.0.
.IP "\-X, \-\-request <method>"
(HTTP) Specifies a custom request method to use when communicating with the
HTTP server. The specified request method will be used instead of the method
otherwise used (which defaults to GET). Read the HTTP 1.1 specification for
details and explanations. Common additional HTTP requests include PUT and
DELETE, but related technologies like WebDAV offers PROPFIND, COPY, MOVE and
more.
Normally you do not need this option. All sorts of GET, HEAD, POST and PUT
requests are rather invoked by using dedicated command line options.
This option only changes the actual word used in the HTTP request, it does not
alter the way curl behaves. So for example if you want to make a proper HEAD
request, using \-X HEAD will not suffice. You need to use the \-\-head option.
The method string you set with \-\-request will be used for all requests, which
if you for example use \-\-location may cause unintended side-effects when curl
does not change request method according to the HTTP 30x response codes \- and
similar.
(FTP)
Specifies a custom FTP command to use instead of LIST when doing file lists
with FTP.
(POP3)
Specifies a custom POP3 command to use instead of LIST or RETR.
(IMAP)
Specifies a custom IMAP command to use instead of LIST. (Added in 7.30.0)
(SMTP)
Specifies a custom SMTP command to use instead of HELP or VRFY. (Added in 7.34.0)
If --request is provided several times, the last set value will be used.
Examples:
.nf
curl -X "DELETE" https://example.com
curl -X NLST ftp://example.com/
.fi
See also \fI--request-target\fP.
.IP "\-\-resolve <[+]host:port:addr[,addr]...>"
Provide a custom address for a specific host and port pair. Using this, you
can make the curl requests(s) use a specified address and prevent the
otherwise normally resolved address to be used. Consider it a sort of
/etc/hosts alternative provided on the command line. The port number should be
the number used for the specific protocol the host will be used for. It means
you need several entries if you want to provide address for the same host but
different ports.
By specifying '*' as host you can tell curl to resolve any host and specific
port pair to the specified address. Wildcard is resolved last so any \-\-resolve
with a specific host and port will be used first.
The provided address set by this option will be used even if \-\-ipv4 or \-\-ipv6
is set to make curl use another IP version.
By prefixing the host with a '+' you can make the entry time out after curl's
default timeout (1 minute). Note that this will only make sense for long
running parallel transfers with a lot of files. In such cases, if this option
is used curl will try to resolve the host as it normally would once the
timeout has expired.
Support for providing the IP address within [brackets] was added in 7.57.0.
Support for providing multiple IP addresses per entry was added in 7.59.0.
Support for resolving with wildcard was added in 7.64.0.
Support for the '+' prefix was was added in 7.75.0.
This option can be used many times to add many host names to resolve.
--resolve can be used several times in a command line
Example:
.nf
curl --resolve example.com:443:127.0.0.1 https://example.com
.fi
See also \fI--connect-to\fP and \fI--alt-svc\fP.
.IP "\-\-retry-all-errors"
Retry on any error. This option is used together with \fI\-\-retry\fP.
This option is the "sledgehammer" of retrying. Do not use this option by
default (eg in curlrc), there may be unintended consequences such as sending or
receiving duplicate data. Do not use with redirected input or output. You'd be
much better off handling your unique problems in shell script. Please read the
example below.
\fBWARNING\fP: For server compatibility curl attempts to retry failed flaky
transfers as close as possible to how they were started, but this is not
possible with redirected input or output. For example, before retrying it
removes output data from a failed partial transfer that was written to an
output file. However this is not true of data redirected to a | pipe or >
file, which are not reset. We strongly suggest you do not parse or record
output via redirect in combination with this option, since you may receive
duplicate data.
By default curl will not error on an HTTP response code that indicates an HTTP
error, if the transfer was successful. For example, if a server replies 404
Not Found and the reply is fully received then that is not an error. When
\-\-retry is used then curl will retry on some HTTP response codes that indicate
transient HTTP errors, but that does not include most 4xx response codes such
as 404. If you want to retry on all response codes that indicate HTTP errors
(4xx and 5xx) then combine with \fI\-f, \-\-fail\fP.
Providing --retry-all-errors multiple times has no extra effect.
Disable it again with --no-retry-all-errors.
Example:
.nf
curl --retry 5 --retry-all-errors https://example.com
.fi
See also \fI--retry\fP. Added in 7.71.0.
.IP "\-\-retry-connrefused"
In addition to the other conditions, consider ECONNREFUSED as a transient
error too for \fI\-\-retry\fP. This option is used together with \-\-retry.
Providing --retry-connrefused multiple times has no extra effect.
Disable it again with --no-retry-connrefused.
Example:
.nf
curl --retry-connrefused --retry https://example.com
.fi
See also \fI--retry\fP and \fI--retry-all-errors\fP. Added in 7.52.0.
.IP "\-\-retry-delay <seconds>"
Make curl sleep this amount of time before each retry when a transfer has
failed with a transient error (it changes the default backoff time algorithm
between retries). This option is only interesting if \-\-retry is also
used. Setting this delay to zero will make curl use the default backoff time.
If --retry-delay is provided several times, the last set value will be used.
Example:
.nf
curl --retry-delay 5 --retry https://example.com
.fi
See also \fI--retry\fP.
.IP "\-\-retry-max-time <seconds>"
The retry timer is reset before the first transfer attempt. Retries will be
done as usual (see \fI\-\-retry\fP) as long as the timer has not reached this given
limit. Notice that if the timer has not reached the limit, the request will be
made and while performing, it may take longer than this given time period. To
limit a single request's maximum time, use \fI\-m, \-\-max-time\fP. Set this option to
zero to not timeout retries.
If --retry-max-time is provided several times, the last set value will be used.
Example:
.nf
curl --retry-max-time 30 --retry 10 https://example.com
.fi
See also \fI--retry\fP.
.IP "\-\-retry <num>"
If a transient error is returned when curl tries to perform a transfer, it
will retry this number of times before giving up. Setting the number to 0
makes curl do no retries (which is the default). Transient error means either:
a timeout, an FTP 4xx response code or an HTTP 408, 429, 500, 502, 503 or 504
response code.
When curl is about to retry a transfer, it will first wait one second and then
for all forthcoming retries it will double the waiting time until it reaches
10 minutes which then will be the delay between the rest of the retries. By
using \-\-retry-delay you disable this exponential backoff algorithm. See also
\-\-retry-max-time to limit the total time allowed for retries.
Since curl 7.66.0, curl will comply with the Retry-After: response header if
one was present to know when to issue the next retry.
If --retry is provided several times, the last set value will be used.
Example:
.nf
curl --retry 7 https://example.com
.fi
See also \fI--retry-max-time\fP.
.IP "\-\-sasl-authzid <identity>"
Use this authorization identity (authzid), during SASL PLAIN authentication,
in addition to the authentication identity (authcid) as specified by \fI\-u, \-\-user\fP.
If the option is not specified, the server will derive the authzid from the
authcid, but if specified, and depending on the server implementation, it may
be used to access another user's inbox, that the user has been granted access
to, or a shared mailbox for example.
If --sasl-authzid is provided several times, the last set value will be used.
Example:
.nf
curl --sasl-authzid zid imap://example.com/
.fi
See also \fI--login-options\fP. Added in 7.66.0.
.IP "\-\-sasl-ir"
Enable initial response in SASL authentication.
Providing --sasl-ir multiple times has no extra effect.
Disable it again with --no-sasl-ir.
Example:
.nf
curl --sasl-ir imap://example.com/
.fi
See also \fI--sasl-authzid\fP. Added in 7.31.0.
.IP "\-\-service-name <name>"
This option allows you to change the service name for SPNEGO.
Examples: \fI\-\-negotiate\fP \-\-service-name sockd would use sockd/server-name.
If --service-name is provided several times, the last set value will be used.
Example:
.nf
curl --service-name sockd/server https://example.com
.fi
See also \fI--negotiate\fP and \fI--proxy-service-name\fP. Added in 7.43.0.
.IP "\-S, \-\-show-error"
When used with \fI\-s, \-\-silent\fP, it makes curl show an error message if it fails.
This option is global and does not need to be specified for each use of
\fI\-:, \-\-next\fP.
Providing --show-error multiple times has no extra effect.
Disable it again with --no-show-error.
Example:
.nf
curl --show-error --silent https://example.com
.fi
See also \fI--no-progress-meter\fP.
.IP "\-s, \-\-silent"
Silent or quiet mode. Do not show progress meter or error messages. Makes Curl
mute. It will still output the data you ask for, potentially even to the
terminal/stdout unless you redirect it.
Use \-\-show-error in addition to this option to disable progress meter but
still show error messages.
Providing --silent multiple times has no extra effect.
Disable it again with --no-silent.
Example:
.nf
curl -s https://example.com
.fi
See also \fI-v, --verbose\fP, \fI--stderr\fP and \fI--no-progress-meter\fP.
.IP "\-\-socks4 <host[:port]>"
Use the specified SOCKS4 proxy. If the port number is not specified, it is
assumed at port 1080. Using this socket type make curl resolve the host name
and passing the address on to the proxy.
To specify proxy on a unix domain socket, use localhost for host, e.g.
socks4://localhost/path/to/socket.sock
This option overrides any previous use of \fI\-x, \-\-proxy\fP, as they are mutually
exclusive.
This option is superfluous since you can specify a socks4 proxy with \-\-proxy
using a socks4:// protocol prefix.
Since 7.52.0, \-\-preproxy can be used to specify a SOCKS proxy at the same time
\-\-proxy is used with an HTTP/HTTPS proxy. In such a case curl first connects to
the SOCKS proxy and then connects (through SOCKS) to the HTTP or HTTPS proxy.
If --socks4 is provided several times, the last set value will be used.
Example:
.nf
curl --socks4 hostname:4096 https://example.com
.fi
See also \fI--socks4a\fP, \fI--socks5\fP and \fI--socks5-hostname\fP.
.IP "\-\-socks4a <host[:port]>"
Use the specified SOCKS4a proxy. If the port number is not specified, it is
assumed at port 1080. This asks the proxy to resolve the host name.
To specify proxy on a unix domain socket, use localhost for host, e.g.
socks4a://localhost/path/to/socket.sock
This option overrides any previous use of \fI\-x, \-\-proxy\fP, as they are mutually
exclusive.
This option is superfluous since you can specify a socks4a proxy with \-\-proxy
using a socks4a:// protocol prefix.
Since 7.52.0, \-\-preproxy can be used to specify a SOCKS proxy at the same time
\-\-proxy is used with an HTTP/HTTPS proxy. In such a case curl first connects to
the SOCKS proxy and then connects (through SOCKS) to the HTTP or HTTPS proxy.
If --socks4a is provided several times, the last set value will be used.
Example:
.nf
curl --socks4a hostname:4096 https://example.com
.fi
See also \fI--socks4\fP, \fI--socks5\fP and \fI--socks5-hostname\fP.
.IP "\-\-socks5-basic"
Tells curl to use username/password authentication when connecting to a SOCKS5
proxy. The username/password authentication is enabled by default. Use
\-\-socks5-gssapi to force GSS-API authentication to SOCKS5 proxies.
Providing --socks5-basic multiple times has no extra effect.
Example:
.nf
curl --socks5-basic --socks5 hostname:4096 https://example.com
.fi
See also \fI--socks5\fP. Added in 7.55.0.
.IP "\-\-socks5-gssapi-nec"
As part of the GSS-API negotiation a protection mode is negotiated. RFC 1961
says in section 4.3/4.4 it should be protected, but the NEC reference
implementation does not. The option \-\-socks5-gssapi-nec allows the
unprotected exchange of the protection mode negotiation.
Providing --socks5-gssapi-nec multiple times has no extra effect.
Disable it again with --no-socks5-gssapi-nec.
Example:
.nf
curl --socks5-gssapi-nec --socks5 hostname:4096 https://example.com
.fi
See also \fI--socks5\fP.
.IP "\-\-socks5-gssapi-service <name>"
The default service name for a socks server is rcmd/server-fqdn. This option
allows you to change it.
Examples: \-\-socks5 proxy-name \-\-socks5-gssapi-service sockd would use
sockd/proxy-name \-\-socks5 proxy-name \-\-socks5-gssapi-service sockd/real-name
would use sockd/real-name for cases where the proxy-name does not match the
principal name.
If --socks5-gssapi-service is provided several times, the last set value will be used.
Example:
.nf
curl --socks5-gssapi-service sockd --socks5 hostname:4096 https://example.com
.fi
See also \fI--socks5\fP.
.IP "\-\-socks5-gssapi"
Tells curl to use GSS-API authentication when connecting to a SOCKS5 proxy.
The GSS-API authentication is enabled by default (if curl is compiled with
GSS-API support). Use \-\-socks5-basic to force username/password authentication
to SOCKS5 proxies.
Providing --socks5-gssapi multiple times has no extra effect.
Disable it again with --no-socks5-gssapi.
Example:
.nf
curl --socks5-gssapi --socks5 hostname:4096 https://example.com
.fi
See also \fI--socks5\fP. Added in 7.55.0.
.IP "\-\-socks5-hostname <host[:port]>"
Use the specified SOCKS5 proxy (and let the proxy resolve the host name). If
the port number is not specified, it is assumed at port 1080.
To specify proxy on a unix domain socket, use localhost for host, e.g.
socks5h://localhost/path/to/socket.sock
This option overrides any previous use of \fI\-x, \-\-proxy\fP, as they are mutually
exclusive.
This option is superfluous since you can specify a socks5 hostname proxy with
\-\-proxy using a socks5h:// protocol prefix.
Since 7.52.0, \-\-preproxy can be used to specify a SOCKS proxy at the same time
\-\-proxy is used with an HTTP/HTTPS proxy. In such a case curl first connects to
the SOCKS proxy and then connects (through SOCKS) to the HTTP or HTTPS proxy.
If --socks5-hostname is provided several times, the last set value will be used.
Example:
.nf
curl --socks5-hostname proxy.example:7000 https://example.com
.fi
See also \fI--socks5\fP and \fI--socks4a\fP.
.IP "\-\-socks5 <host[:port]>"
Use the specified SOCKS5 proxy \- but resolve the host name locally. If the
port number is not specified, it is assumed at port 1080.
To specify proxy on a unix domain socket, use localhost for host, e.g.
socks5://localhost/path/to/socket.sock
This option overrides any previous use of \fI\-x, \-\-proxy\fP, as they are mutually
exclusive.
This option is superfluous since you can specify a socks5 proxy with \-\-proxy
using a socks5:// protocol prefix.
Since 7.52.0, \-\-preproxy can be used to specify a SOCKS proxy at the same time
\-\-proxy is used with an HTTP/HTTPS proxy. In such a case curl first connects to
the SOCKS proxy and then connects (through SOCKS) to the HTTP or HTTPS proxy.
This option (as well as \fI\-\-socks4\fP) does not work with IPV6, FTPS or LDAP.
If --socks5 is provided several times, the last set value will be used.
Example:
.nf
curl --socks5 proxy.example:7000 https://example.com
.fi
See also \fI--socks5-hostname\fP and \fI--socks4a\fP.
.IP "\-Y, \-\-speed-limit <speed>"
If a transfer is slower than this given speed (in bytes per second) for
speed-time seconds it gets aborted. speed-time is set with \-\-speed-time and is
30 if not set.
If --speed-limit is provided several times, the last set value will be used.
Example:
.nf
curl --speed-limit 300 --speed-time 10 https://example.com
.fi
See also \fI-y, --speed-time\fP, \fI--limit-rate\fP and \fI-m, --max-time\fP.
.IP "\-y, \-\-speed-time <seconds>"
If a transfer runs slower than speed-limit bytes per second during a speed-time
period, the transfer is aborted. If speed-time is used, the default
speed-limit will be 1 unless set with \fI\-Y, \-\-speed-limit\fP.
This option controls transfers (in both directions) but will not affect slow
connects etc. If this is a concern for you, try the \-\-connect-timeout option.
If --speed-time is provided several times, the last set value will be used.
Example:
.nf
curl --speed-limit 300 --speed-time 10 https://example.com
.fi
See also \fI-Y, --speed-limit\fP and \fI--limit-rate\fP.
.IP "\-\-ssl-allow-beast"
This option tells curl to not work around a security flaw in the SSL3 and
TLS1.0 protocols known as BEAST. If this option is not used, the SSL layer
may use workarounds known to cause interoperability problems with some older
SSL implementations.
\fBWARNING\fP: this option loosens the SSL security, and by using this flag you
ask for exactly that.
Providing --ssl-allow-beast multiple times has no extra effect.
Disable it again with --no-ssl-allow-beast.
Example:
.nf
curl --ssl-allow-beast https://example.com
.fi
See also \fI--proxy-ssl-allow-beast\fP and \fI-k, --insecure\fP.
.IP "\-\-ssl-auto-client-cert"
Tell libcurl to automatically locate and use a client certificate for
authentication, when requested by the server. This option is only supported
for Schannel (the native Windows SSL library). Prior to 7.77.0 this was the
default behavior in libcurl with Schannel. Since the server can request any
certificate that supports client authentication in the OS certificate store it
could be a privacy violation and unexpected.
Providing --ssl-auto-client-cert multiple times has no extra effect.
Disable it again with --no-ssl-auto-client-cert.
Example:
.nf
curl --ssl-auto-client-cert https://example.com
.fi
See also \fI--proxy-ssl-auto-client-cert\fP. Added in 7.77.0.
.IP "\-\-ssl-no-revoke"
(Schannel) This option tells curl to disable certificate revocation checks.
WARNING: this option loosens the SSL security, and by using this flag you ask
for exactly that.
Providing --ssl-no-revoke multiple times has no extra effect.
Disable it again with --no-ssl-no-revoke.
Example:
.nf
curl --ssl-no-revoke https://example.com
.fi
See also \fI--crlfile\fP. Added in 7.44.0.
.IP "\-\-ssl-reqd"
(FTP IMAP POP3 SMTP LDAP) Require SSL/TLS for the connection. Terminates the connection if the server
does not support SSL/TLS.
This option is handled in LDAP since version 7.81.0. It is fully supported
by the OpenLDAP backend and rejected by the generic ldap backend if explicit
TLS is required.
This option was formerly known as \-\-ftp-ssl-reqd.
Providing --ssl-reqd multiple times has no extra effect.
Disable it again with --no-ssl-reqd.
Example:
.nf
curl --ssl-reqd ftp://example.com
.fi
See also \fI--ssl\fP and \fI-k, --insecure\fP.
.IP "\-\-ssl-revoke-best-effort"
(Schannel) This option tells curl to ignore certificate revocation checks when
they failed due to missing/offline distribution points for the revocation check
lists.
Providing --ssl-revoke-best-effort multiple times has no extra effect.
Disable it again with --no-ssl-revoke-best-effort.
Example:
.nf
curl --ssl-revoke-best-effort https://example.com
.fi
See also \fI--crlfile\fP and \fI-k, --insecure\fP. Added in 7.70.0.
.IP "\-\-ssl"
(FTP IMAP POP3 SMTP LDAP) Warning: this is considered an insecure option. Consider using \-\-ssl-reqd
instead to be sure curl upgrades to a secure connection.
Try to use SSL/TLS for the connection. Reverts to a non-secure connection if
the server does not support SSL/TLS. See also \-\-ftp-ssl-control and \-\-ssl-reqd
for different levels of encryption required.
This option is handled in LDAP since version 7.81.0. It is fully supported
by the OpenLDAP backend and ignored by the generic ldap backend.
Please note that a server may close the connection if the negotiation does
not succeed.
This option was formerly known as \-\-ftp-ssl. That option
name can still be used but will be removed in a future version.
Providing --ssl multiple times has no extra effect.
Disable it again with --no-ssl.
Example:
.nf
curl --ssl pop3://example.com/
.fi
See also \fI--ssl-reqd\fP, \fI-k, --insecure\fP and \fI--ciphers\fP.
.IP "\-2, \-\-sslv2"
(SSL) This option previously asked curl to use SSLv2, but starting in curl 7.77.0
this instruction is ignored. SSLv2 is widely considered insecure (see RFC
6176).
Providing --sslv2 multiple times has no extra effect.
Example:
.nf
curl --sslv2 https://example.com
.fi
See also \fI--http1.1\fP and \fI--http2\fP. \fI-2, --sslv2\fP requires that the underlying libcurl was built to support TLS. This option is mutually exclusive to \fI-3, --sslv3\fP and \fI-1, --tlsv1\fP and \fI--tlsv1.1\fP and \fI--tlsv1.2\fP.
.IP "\-3, \-\-sslv3"
(SSL) This option previously asked curl to use SSLv3, but starting in curl 7.77.0
this instruction is ignored. SSLv3 is widely considered insecure (see RFC
7568).
Providing --sslv3 multiple times has no extra effect.
Example:
.nf
curl --sslv3 https://example.com
.fi
See also \fI--http1.1\fP and \fI--http2\fP. \fI-3, --sslv3\fP requires that the underlying libcurl was built to support TLS. This option is mutually exclusive to \fI-2, --sslv2\fP and \fI-1, --tlsv1\fP and \fI--tlsv1.1\fP and \fI--tlsv1.2\fP.
.IP "\-\-stderr <file>"
Redirect all writes to stderr to the specified file instead. If the file name
is a plain '-', it is instead written to stdout.
This option is global and does not need to be specified for each use of
\fI\-:, \-\-next\fP.
If --stderr is provided several times, the last set value will be used.
Example:
.nf
curl --stderr output.txt https://example.com
.fi
See also \fI-v, --verbose\fP and \fI-s, --silent\fP.
.IP "\-\-styled-output"
Enables the automatic use of bold font styles when writing HTTP headers to the
terminal. Use \-\-no-styled-output to switch them off.
This option is global and does not need to be specified for each use of
\fI\-:, \-\-next\fP.
Providing --styled-output multiple times has no extra effect.
Disable it again with --no-styled-output.
Example:
.nf
curl --styled-output -I https://example.com
.fi
See also \fI-I, --head\fP and \fI-v, --verbose\fP. Added in 7.61.0.
.IP "\-\-suppress-connect-headers"
When \-\-proxytunnel is used and a CONNECT request is made do not output proxy
CONNECT response headers. This option is meant to be used with \-\-dump-header or
\-\-include which are used to show protocol headers in the output. It has no
effect on debug options such as \-\-verbose or \fI\-\-trace\fP, or any statistics.
Providing --suppress-connect-headers multiple times has no extra effect.
Disable it again with --no-suppress-connect-headers.
Example:
.nf
curl --suppress-connect-headers --include -x proxy https://example.com
.fi
See also \fI-D, --dump-header\fP, \fI-i, --include\fP and \fI-p, --proxytunnel\fP. Added in 7.54.0.
.IP "\-\-tcp-fastopen"
Enable use of TCP Fast Open (RFC7413).
Providing --tcp-fastopen multiple times has no extra effect.
Disable it again with --no-tcp-fastopen.
Example:
.nf
curl --tcp-fastopen https://example.com
.fi
See also \fI--false-start\fP. Added in 7.49.0.
.IP "\-\-tcp-nodelay"
Turn on the TCP_NODELAY option. See the \fIcurl_easy_setopt(3)\fP man page for
details about this option.
Since 7.50.2, curl sets this option by default and you need to explicitly
switch it off if you do not want it on.
Providing --tcp-nodelay multiple times has no extra effect.
Disable it again with --no-tcp-nodelay.
Example:
.nf
curl --tcp-nodelay https://example.com
.fi
See also \fI-N, --no-buffer\fP.
.IP "\-t, \-\-telnet-option <opt=val>"
Pass options to the telnet protocol. Supported options are:
TTYPE=<term> Sets the terminal type.
XDISPLOC=<X display> Sets the X display location.
NEW_ENV=<var,val> Sets an environment variable.
--telnet-option can be used several times in a command line
Example:
.nf
curl -t TTYPE=vt100 telnet://example.com/
.fi
See also \fI-K, --config\fP.
.IP "\-\-tftp-blksize <value>"
(TFTP) Set TFTP BLKSIZE option (must be >512). This is the block size that curl will
try to use when transferring data to or from a TFTP server. By default 512
bytes will be used.
If --tftp-blksize is provided several times, the last set value will be used.
Example:
.nf
curl --tftp-blksize 1024 tftp://example.com/file
.fi
See also \fI--tftp-no-options\fP.
.IP "\-\-tftp-no-options"
(TFTP) Tells curl not to send TFTP options requests.
This option improves interop with some legacy servers that do not acknowledge
or properly implement TFTP options. When this option is used \-\-tftp-blksize is
ignored.
Providing --tftp-no-options multiple times has no extra effect.
Disable it again with --no-tftp-no-options.
Example:
.nf
curl --tftp-no-options tftp://192.168.0.1/
.fi
See also \fI--tftp-blksize\fP. Added in 7.48.0.
.IP "\-z, \-\-time-cond <time>"
(HTTP FTP) Request a file that has been modified later than the given time and date, or
one that has been modified before that time. The <date expression> can be all
sorts of date strings or if it does not match any internal ones, it is taken as
a filename and tries to get the modification date (mtime) from <file>
instead. See the \fIcurl_getdate(3)\fP man pages for date expression details.
Start the date expression with a dash (-) to make it request for a document
that is older than the given date/time, default is a document that is newer
than the specified date/time.
If --time-cond is provided several times, the last set value will be used.
Examples:
.nf
curl -z "Wed 01 Sep 2021 12:18:00" https://example.com
curl -z "-Wed 01 Sep 2021 12:18:00" https://example.com
curl -z file https://example.com
.fi
See also \fI--etag-compare\fP and \fI-R, --remote-time\fP.
.IP "\-\-tls-max <VERSION>"
(SSL) VERSION defines maximum supported TLS version. The minimum acceptable version
is set by tlsv1.0, tlsv1.1, tlsv1.2 or tlsv1.3.
If the connection is done without TLS, this option has no effect. This
includes QUIC-using (HTTP/3) transfers.
.RS
.IP "default"
Use up to recommended TLS version.
.IP "1.0"
Use up to TLSv1.0.
.IP "1.1"
Use up to TLSv1.1.
.IP "1.2"
Use up to TLSv1.2.
.IP "1.3"
Use up to TLSv1.3.
.RE
If --tls-max is provided several times, the last set value will be used.
Examples:
.nf
curl --tls-max 1.2 https://example.com
curl --tls-max 1.3 --tlsv1.2 https://example.com
.fi
See also \fI--tlsv1.0\fP, \fI--tlsv1.1\fP, \fI--tlsv1.2\fP and \fI--tlsv1.3\fP. \fI--tls-max\fP requires that the underlying libcurl was built to support TLS. Added in 7.54.0.
.IP "\-\-tls13-ciphers <ciphersuite list>"
(TLS) Specifies which cipher suites to use in the connection if it negotiates TLS
1.3. The list of ciphers suites must specify valid ciphers. Read up on TLS 1.3
cipher suite details on this URL:
.nf
https://curl.se/docs/ssl-ciphers.html
.fi
This option is currently used only when curl is built to use OpenSSL 1.1.1 or
later. If you are using a different SSL backend you can try setting TLS 1.3
cipher suites by using the \-\-ciphers option.
If --tls13-ciphers is provided several times, the last set value will be used.
Example:
.nf
curl --tls13-ciphers TLS_AES_128_GCM_SHA256 https://example.com
.fi
See also \fI--ciphers\fP and \fI--curves\fP. Added in 7.61.0.
.IP "\-\-tlsauthtype <type>"
Set TLS authentication type. Currently, the only supported option is "SRP",
for TLS-SRP (RFC 5054). If \-\-tlsuser and \-\-tlspassword are specified but
\-\-tlsauthtype is not, then this option defaults to "SRP". This option works
only if the underlying libcurl is built with TLS-SRP support, which requires
OpenSSL or GnuTLS with TLS-SRP support.
If --tlsauthtype is provided several times, the last set value will be used.
Example:
.nf
curl --tlsauthtype SRP https://example.com
.fi
See also \fI--tlsuser\fP.
.IP "\-\-tlspassword <string>"
Set password for use with the TLS authentication method specified with
\fI\-\-tlsauthtype\fP. Requires that \-\-tlsuser also be set.
This option does not work with TLS 1.3.
If --tlspassword is provided several times, the last set value will be used.
Example:
.nf
curl --tlspassword pwd --tlsuser user https://example.com
.fi
See also \fI--tlsuser\fP.
.IP "\-\-tlsuser <name>"
Set username for use with the TLS authentication method specified with
\fI\-\-tlsauthtype\fP. Requires that \-\-tlspassword also is set.
This option does not work with TLS 1.3.
If --tlsuser is provided several times, the last set value will be used.
Example:
.nf
curl --tlspassword pwd --tlsuser user https://example.com
.fi
See also \fI--tlspassword\fP.
.IP "\-\-tlsv1.0"
(TLS) Forces curl to use TLS version 1.0 or later when connecting to a remote TLS server.
In old versions of curl this option was documented to allow _only_ TLS 1.0.
That behavior was inconsistent depending on the TLS library. Use \-\-tls-max if
you want to set a maximum TLS version.
Providing --tlsv1.0 multiple times has no extra effect.
Example:
.nf
curl --tlsv1.0 https://example.com
.fi
See also \fI--tlsv1.3\fP. Added in 7.34.0.
.IP "\-\-tlsv1.1"
(TLS) Forces curl to use TLS version 1.1 or later when connecting to a remote TLS server.
In old versions of curl this option was documented to allow _only_ TLS 1.1.
That behavior was inconsistent depending on the TLS library. Use \-\-tls-max if
you want to set a maximum TLS version.
Providing --tlsv1.1 multiple times has no extra effect.
Example:
.nf
curl --tlsv1.1 https://example.com
.fi
See also \fI--tlsv1.3\fP and \fI--tls-max\fP. Added in 7.34.0.
.IP "\-\-tlsv1.2"
(TLS) Forces curl to use TLS version 1.2 or later when connecting to a remote TLS server.
In old versions of curl this option was documented to allow _only_ TLS 1.2.
That behavior was inconsistent depending on the TLS library. Use \-\-tls-max if
you want to set a maximum TLS version.
Providing --tlsv1.2 multiple times has no extra effect.
Example:
.nf
curl --tlsv1.2 https://example.com
.fi
See also \fI--tlsv1.3\fP and \fI--tls-max\fP. Added in 7.34.0.
.IP "\-\-tlsv1.3"
(TLS) Forces curl to use TLS version 1.3 or later when connecting to a remote TLS
server.
If the connection is done without TLS, this option has no effect. This
includes QUIC-using (HTTP/3) transfers.
Note that TLS 1.3 is not supported by all TLS backends.
Providing --tlsv1.3 multiple times has no extra effect.
Example:
.nf
curl --tlsv1.3 https://example.com
.fi
See also \fI--tlsv1.2\fP and \fI--tls-max\fP. Added in 7.52.0.
.IP "\-1, \-\-tlsv1"
(SSL) Tells curl to use at least TLS version 1.x when negotiating with a remote TLS
server. That means TLS version 1.0 or higher
Providing --tlsv1 multiple times has no extra effect.
Example:
.nf
curl --tlsv1 https://example.com
.fi
See also \fI--http1.1\fP and \fI--http2\fP. \fI-1, --tlsv1\fP requires that the underlying libcurl was built to support TLS. This option is mutually exclusive to \fI--tlsv1.1\fP and \fI--tlsv1.2\fP and \fI--tlsv1.3\fP.
.IP "\-\-tr-encoding"
(HTTP) Request a compressed Transfer-Encoding response using one of the algorithms
curl supports, and uncompress the data while receiving it.
Providing --tr-encoding multiple times has no extra effect.
Disable it again with --no-tr-encoding.
Example:
.nf
curl --tr-encoding https://example.com
.fi
See also \fI--compressed\fP.
.IP "\-\-trace-ascii <file>"
Enables a full trace dump of all incoming and outgoing data, including
descriptive information, to the given output file. Use "-" as filename to have
the output sent to stdout.
This is similar to \fI\-\-trace\fP, but leaves out the hex part and only shows the
ASCII part of the dump. It makes smaller output that might be easier to read
for untrained humans.
This option is global and does not need to be specified for each use of
\fI\-:, \-\-next\fP.
If --trace-ascii is provided several times, the last set value will be used.
Example:
.nf
curl --trace-ascii log.txt https://example.com
.fi
See also \fI-v, --verbose\fP and \fI--trace\fP. This option is mutually exclusive to \fI--trace\fP and \fI-v, --verbose\fP.
.IP "\-\-trace-time"
Prepends a time stamp to each trace or verbose line that curl displays.
This option is global and does not need to be specified for each use of
\fI\-:, \-\-next\fP.
Providing --trace-time multiple times has no extra effect.
Disable it again with --no-trace-time.
Example:
.nf
curl --trace-time --trace-ascii output https://example.com
.fi
See also \fI--trace\fP and \fI-v, --verbose\fP.
.IP "\-\-trace <file>"
Enables a full trace dump of all incoming and outgoing data, including
descriptive information, to the given output file. Use "-" as filename to have
the output sent to stdout. Use "%" as filename to have the output sent to
stderr.
This option is global and does not need to be specified for each use of
\fI\-:, \-\-next\fP.
If --trace is provided several times, the last set value will be used.
Example:
.nf
curl --trace log.txt https://example.com
.fi
See also \fI--trace-ascii\fP and \fI--trace-time\fP. This option is mutually exclusive to \fI-v, --verbose\fP and \fI--trace-ascii\fP.
.IP "\-\-unix-socket <path>"
(HTTP) Connect through this Unix domain socket, instead of using the network.
If --unix-socket is provided several times, the last set value will be used.
Example:
.nf
curl --unix-socket socket-path https://example.com
.fi
See also \fI--abstract-unix-socket\fP. Added in 7.40.0.
.IP "\-T, \-\-upload-file <file>"
This transfers the specified local file to the remote URL. If there is no file
part in the specified URL, curl will append the local file name. NOTE that you
must use a trailing / on the last directory to really prove to Curl that there
is no file name or curl will think that your last directory name is the remote
file name to use. That will most likely cause the upload operation to fail. If
this is used on an HTTP(S) server, the PUT command will be used.
Use the file name "-" (a single dash) to use stdin instead of a given file.
Alternately, the file name "." (a single period) may be specified instead of
\(dq-" to use stdin in non-blocking mode to allow reading server output while
stdin is being uploaded.
You can specify one \-\-upload-file for each URL on the command line. Each
\fI\-T, \-\-upload-file\fP + URL pair specifies what to upload and to where. curl also
supports "globbing" of the \-\-upload-file argument, meaning that you can upload
multiple files to a single URL by using the same URL globbing style supported
in the URL.
When uploading to an SMTP server: the uploaded data is assumed to be RFC 5322
formatted. It has to feature the necessary set of headers and mail body
formatted correctly by the user as curl will not transcode nor encode it
further in any way.
--upload-file can be used several times in a command line
Examples:
.nf
curl -T file https://example.com
curl -T "img[1-1000].png" ftp://ftp.example.com/
curl --upload-file "{file1,file2}" https://example.com
.fi
See also \fI-G, --get\fP and \fI-I, --head\fP.
.IP "\-\-url <url>"
Specify a URL to fetch. This option is mostly handy when you want to specify
URL(s) in a config file.
If the given URL is missing a scheme name (such as "http://" or "ftp://" etc)
then curl will make a guess based on the host. If the outermost sub-domain
name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that protocol will be
used, otherwise HTTP will be used. Since 7.45.0 guessing can be disabled by
setting a default protocol, see \-\-proto-default for details.
To control where this URL is written, use the \-\-output or the \-\-remote-name
options.
\fBWARNING\fP: On Windows, particular file:// accesses can be converted to
network accesses by the operating system. Beware!
--url can be used several times in a command line
Example:
.nf
curl --url https://example.com
.fi
See also \fI-:, --next\fP and \fI-K, --config\fP.
.IP "\-B, \-\-use-ascii"
(FTP LDAP) Enable ASCII transfer. For FTP, this can also be enforced by using a URL that
ends with ";type=A". This option causes data sent to stdout to be in text mode
for win32 systems.
Providing --use-ascii multiple times has no extra effect.
Disable it again with --no-use-ascii.
Example:
.nf
curl -B ftp://example.com/README
.fi
See also \fI--crlf\fP and \fI--data-ascii\fP.
.IP "\-A, \-\-user-agent <name>"
(HTTP) Specify the User-Agent string to send to the HTTP server. To encode blanks in
the string, surround the string with single quote marks. This header can also
be set with the \-\-header or the \-\-proxy-header options.
If you give an empty argument to \fI\-A, \-\-user-agent\fP (""), it will remove the header
completely from the request. If you prefer a blank header, you can set it to a
single space (" ").
If --user-agent is provided several times, the last set value will be used.
Example:
.nf
curl -A "Agent 007" https://example.com
.fi
See also \fI-H, --header\fP and \fI--proxy-header\fP.
.IP "\-u, \-\-user <user:password>"
Specify the user name and password to use for server authentication. Overrides
\-\-netrc and \fI\-\-netrc-optional\fP.
If you simply specify the user name, curl will prompt for a password.
The user name and passwords are split up on the first colon, which makes it
impossible to use a colon in the user name with this option. The password can,
still.
On systems where it works, curl will hide the given option argument from
process listings. This is not enough to protect credentials from possibly
getting seen by other users on the same system as they will still be visible
for a moment before cleared. Such sensitive data should be retrieved from a
file instead or similar and never used in clear text in a command line.
When using Kerberos V5 with a Windows based server you should include the
Windows domain name in the user name, in order for the server to successfully
obtain a Kerberos Ticket. If you do not, then the initial authentication
handshake may fail.
When using NTLM, the user name can be specified simply as the user name,
without the domain, if there is a single domain and forest in your setup
for example.
To specify the domain name use either Down-Level Logon Name or UPN (User
Principal Name) formats. For example, EXAMPLE\\user and user@example.com
respectively.
If you use a Windows SSPI-enabled curl binary and perform Kerberos V5,
Negotiate, NTLM or Digest authentication then you can tell curl to select
the user name and password from your environment by specifying a single colon
with this option: "-u :".
If --user is provided several times, the last set value will be used.
Example:
.nf
curl -u user:secret https://example.com
.fi
See also \fI-n, --netrc\fP and \fI-K, --config\fP.
.IP "\-v, \-\-verbose"
Makes curl verbose during the operation. Useful for debugging and seeing
what's going on "under the hood". A line starting with '>' means "header data"
sent by curl, '<' means "header data" received by curl that is hidden in
normal cases, and a line starting with '*' means additional info provided by
curl.
If you only want HTTP headers in the output, \-\-include might be the option
you are looking for.
If you think this option still does not give you enough details, consider using
\-\-trace or \-\-trace-ascii instead.
This option is global and does not need to be specified for each use of
\fI\-:, \-\-next\fP.
Use \-\-silent to make curl really quiet.
Providing --verbose multiple times has no extra effect.
Disable it again with --no-verbose.
Example:
.nf
curl --verbose https://example.com
.fi
See also \fI-i, --include\fP. This option is mutually exclusive to \fI--trace\fP and \fI--trace-ascii\fP.
.IP "\-V, \-\-version"
Displays information about curl and the libcurl version it uses.
The first line includes the full version of curl, libcurl and other 3rd party
libraries linked with the executable.
The second line (starts with "Protocols:") shows all protocols that libcurl
reports to support.
The third line (starts with "Features:") shows specific features libcurl
reports to offer. Available features include:
.RS
.IP "alt-svc"
Support for the Alt-Svc: header is provided.
.IP "AsynchDNS"
This curl uses asynchronous name resolves. Asynchronous name resolves can be
done using either the c-ares or the threaded resolver backends.
.IP "brotli"
Support for automatic brotli compression over HTTP(S).
.IP "CharConv"
curl was built with support for character set conversions (like EBCDIC)
.IP "Debug"
This curl uses a libcurl built with Debug. This enables more error-tracking
and memory debugging etc. For curl-developers only!
.IP "gsasl"
The built-in SASL authentication includes extensions to support SCRAM because
libcurl was built with libgsasl.
.IP "GSS-API"
GSS-API is supported.
.IP "HSTS"
HSTS support is present.
.IP "HTTP2"
HTTP/2 support has been built-in.
.IP "HTTP3"
HTTP/3 support has been built-in.
.IP "HTTPS-proxy"
This curl is built to support HTTPS proxy.
.IP "IDN"
This curl supports IDN \- international domain names.
.IP "IPv6"
You can use IPv6 with this.
.IP "Kerberos"
Kerberos V5 authentication is supported.
.IP "Largefile"
This curl supports transfers of large files, files larger than 2GB.
.IP "libz"
Automatic decompression (via gzip, deflate) of compressed files over HTTP is
supported.
.IP "MultiSSL"
This curl supports multiple TLS backends.
.IP "NTLM"
NTLM authentication is supported.
.IP "NTLM_WB"
NTLM delegation to winbind helper is supported.
.IP "PSL"
PSL is short for Public Suffix List and means that this curl has been built
with knowledge about "public suffixes".
.IP "SPNEGO"
SPNEGO authentication is supported.
.IP "SSL"
SSL versions of various protocols are supported, such as HTTPS, FTPS, POP3S
and so on.
.IP "SSPI"
SSPI is supported.
.IP "TLS-SRP"
SRP (Secure Remote Password) authentication is supported for TLS.
.IP "TrackMemory"
Debug memory tracking is supported.
.IP "Unicode"
Unicode support on Windows.
.IP "UnixSockets"
Unix sockets support is provided.
.IP "zstd"
Automatic decompression (via zstd) of compressed files over HTTP is supported.
.RE
Providing --version multiple times has no extra effect.
Disable it again with --no-version.
Example:
.nf
curl --version
.fi
See also \fI-h, --help\fP and \fI-M, --manual\fP.
.IP "\-w, \-\-write-out <format>"
Make curl display information on stdout after a completed transfer. The format
is a string that may contain plain text mixed with any number of
variables. The format can be specified as a literal "string", or you can have
curl read the format from a file with "@filename" and to tell curl to read the
format from stdin you write "@-".
The variables present in the output format will be substituted by the value or
text that curl thinks fit, as described below. All variables are specified as
%{variable_name} and to output a normal % you just write them as %%. You can
output a newline by using \\n, a carriage return with \\r and a tab space with
\\t.
The output will be written to standard output, but this can be switched to
standard error by using %{stderr}.
Output HTTP headers from the most recent request by using \fB%header{name}\fP
where \fBname\fP is the case insensitive name of the header (without the
trailing colon). The header contents are exactly as sent over the network,
with leading and trailing whitespace trimmed. Added in curl 7.84.0.
.B NOTE:
The %-symbol is a special symbol in the win32-environment, where all
occurrences of % must be doubled when using this option.
The variables available are:
.RS
.TP 15
.B content_type
The Content-Type of the requested document, if there was any.
.TP
.B errormsg
The error message. (Added in 7.75.0)
.TP
.B exitcode
The numerical exitcode of the transfer. (Added in 7.75.0)
.TP
.B filename_effective
The ultimate filename that curl writes out to. This is only meaningful if curl
is told to write to a file with the \-\-remote-name or \-\-output
option. It's most useful in combination with the \-\-remote-header-name
option.
.TP
.B ftp_entry_path
The initial path curl ended up in when logging on to the remote FTP
server.
.TP
.B header_json
A JSON object with all HTTP response headers from the recent transfer. Values
are provided as arrays, since in the case of multiple headers there can be
multiple values.
The header names provided in lowercase, listed in order of appearance over the
wire. Except for duplicated headers. They are grouped on the first occurrence
of that header, each value is presented in the JSON array.
.TP
.B http_code
The numerical response code that was found in the last retrieved HTTP(S) or
FTP(s) transfer.
.TP
.B http_connect
The numerical code that was found in the last response (from a proxy) to a
curl CONNECT request.
.TP
.B http_version
The http version that was effectively used. (Added in 7.50.0)
.TP
.B json
A JSON object with all available keys.
.TP
.B local_ip
The IP address of the local end of the most recently done connection \- can be
either IPv4 or IPv6.
.TP
.B local_port
The local port number of the most recently done connection.
.TP
.B method
The http method used in the most recent HTTP request. (Added in 7.72.0)
.TP
.B num_connects
Number of new connects made in the recent transfer.
.TP
.B num_headers
The number of response headers in the most recent request (restarted at each
redirect). Note that the status line IS NOT a header. (Added in 7.73.0)
.TP
.B num_redirects
Number of redirects that were followed in the request.
.TP
.B onerror
The rest of the output is only shown if the transfer returned a non-zero error
(Added in 7.75.0)
.TP
.B proxy_ssl_verify_result
The result of the HTTPS proxy's SSL peer certificate verification that was
requested. 0 means the verification was successful. (Added in 7.52.0)
.TP
.B redirect_url
When an HTTP request was made without \-\-location to follow redirects (or when
\-\-max-redirs is met), this variable will show the actual URL a redirect
\fIwould\fP have gone to.
.TP
.B referer
The Referer: header, if there was any. (Added in 7.76.0)
.TP
.B remote_ip
The remote IP address of the most recently done connection \- can be either
IPv4 or IPv6.
.TP
.B remote_port
The remote port number of the most recently done connection.
.TP
.B response_code
The numerical response code that was found in the last transfer (formerly
known as "http_code").
.TP
.B scheme
The URL scheme (sometimes called protocol) that was effectively used. (Added in 7.52.0)
.TP
.B size_download
The total amount of bytes that were downloaded. This is the size of the
body/data that was transferred, excluding headers.
.TP
.B size_header
The total amount of bytes of the downloaded headers.
.TP
.B size_request
The total amount of bytes that were sent in the HTTP request.
.TP
.B size_upload
The total amount of bytes that were uploaded. This is the size of the
body/data that was transferred, excluding headers.
.TP
.B speed_download
The average download speed that curl measured for the complete download. Bytes
per second.
.TP
.B speed_upload
The average upload speed that curl measured for the complete upload. Bytes per
second.
.TP
.B ssl_verify_result
The result of the SSL peer certificate verification that was requested. 0
means the verification was successful.
.TP
.B stderr
From this point on, the \-\-write-out output will be written to standard
error. (Added in 7.63.0)
.TP
.B stdout
From this point on, the \-\-write-out output will be written to standard output.
This is the default, but can be used to switch back after switching to stderr.
(Added in 7.63.0)
.TP
.B time_appconnect
The time, in seconds, it took from the start until the SSL/SSH/etc
connect/handshake to the remote host was completed.
.TP
.B time_connect
The time, in seconds, it took from the start until the TCP connect to the
remote host (or proxy) was completed.
.TP
.B time_namelookup
The time, in seconds, it took from the start until the name resolving was
completed.
.TP
.B time_pretransfer
The time, in seconds, it took from the start until the file transfer was just
about to begin. This includes all pre-transfer commands and negotiations that
are specific to the particular protocol(s) involved.
.TP
.B time_redirect
The time, in seconds, it took for all redirection steps including name lookup,
connect, pretransfer and transfer before the final transaction was
started. time_redirect shows the complete execution time for multiple
redirections.
.TP
.B time_starttransfer
The time, in seconds, it took from the start until the first byte was just
about to be transferred. This includes time_pretransfer and also the time the
server needed to calculate the result.
.TP
.B time_total
The total time, in seconds, that the full operation lasted.
.TP
.B url
The URL that was fetched. (Added in 7.75.0)
.TP
.B urlnum
The URL index number of this transfer, 0-indexed. De-globbed URLs share the
same index number as the origin globbed URL. (Added in 7.75.0)
.TP
.B url_effective
The URL that was fetched last. This is most meaningful if you have told curl
to follow location: headers.
.RE
.IP
If --write-out is provided several times, the last set value will be used.
Example:
.nf
curl -w '%{http_code}\\n' https://example.com
.fi
See also \fI-v, --verbose\fP and \fI-I, --head\fP.
.IP "\-\-xattr"
When saving output to a file, this option tells curl to store certain file
metadata in extended file attributes. Currently, the URL is stored in the
xdg.origin.url attribute and, for HTTP, the content type is stored in
the mime_type attribute. If the file system does not support extended
attributes, a warning is issued.
Providing --xattr multiple times has no extra effect.
Disable it again with --no-xattr.
Example:
.nf
curl --xattr -o storage https://example.com
.fi
See also \fI-R, --remote-time\fP, \fI-w, --write-out\fP and \fI-v, --verbose\fP.
.SH FILES
.I ~/.curlrc
.RS
Default config file, see \-\-config for details.
.SH ENVIRONMENT
The environment variables can be specified in lower case or upper case. The
lower case version has precedence. http_proxy is an exception as it is only
available in lower case.
Using an environment variable to set the proxy has the same effect as using
the \-\-proxy option.
.IP "http_proxy [protocol://]<host>[:port]"
Sets the proxy server to use for HTTP.
.IP "HTTPS_PROXY [protocol://]<host>[:port]"
Sets the proxy server to use for HTTPS.
.IP "[url-protocol]_PROXY [protocol://]<host>[:port]"
Sets the proxy server to use for [url-protocol], where the protocol is a
protocol that curl supports and as specified in a URL. FTP, FTPS, POP3, IMAP,
SMTP, LDAP, etc.
.IP "ALL_PROXY [protocol://]<host>[:port]"
Sets the proxy server to use if no protocol-specific proxy is set.
.IP "NO_PROXY <comma-separated list of hosts/domains>"
list of host names that should not go through any proxy. If set to an asterisk
\(aq*' only, it matches all hosts. Each name in this list is matched as either
a domain name which contains the hostname, or the hostname itself.
This environment variable disables use of the proxy even when specified with
the \-\-proxy option. That is
.B NO_PROXY=direct.example.com curl \-x http://proxy.example.com
.B http://direct.example.com
accesses the target URL directly, and
.B NO_PROXY=direct.example.com curl \-x http://proxy.example.com
.B http://somewhere.example.com
accesses the target URL through the proxy.
The list of host names can also be include numerical IP addresses, and IPv6
versions should then be given without enclosing brackets.
IPv6 numerical addresses are compared as strings, so they will only match if
the representations are the same: "::1" is the same as "::0:1" but they do not
match.
.IP "APPDATA <dir>"
On Windows, this variable is used when trying to find the home directory. If
the primary home variable are all unset.
.IP "COLUMNS <terminal width>"
If set, the specified number of characters will be used as the terminal width
when the alternative progress-bar is shown. If not set, curl will try to
figure it out using other ways.
.IP "CURL_CA_BUNDLE <file>"
If set, will be used as the \fI\-\-cacert\fP value.
.IP "CURL_HOME <dir>"
If set, is the first variable curl checks when trying to find its home
directory. If not set, it continues to check \fBXDG_CONFIG_HOME\fP.
.IP "CURL_SSL_BACKEND <TLS backend>"
If curl was built with support for "MultiSSL", meaning that it has built-in
support for more than one TLS backend, this environment variable can be set to
the case insensitive name of the particular backend to use when curl is
invoked. Setting a name that is not a built-in alternative will make curl
stay with the default.
SSL backend names (case-insensitive): bearssl, gnutls, gskit, mbedtls,
nss, openssl, rustls, schannel, secure-transport, wolfssl
.IP "HOME <dir>"
If set, this is used to find the home directory when that is needed. Like when
looking for the default .curlrc. \fBCURL_HOME\fP and \fBXDG_CONFIG_HOME\fP
have preference.
.IP "QLOGDIR <directory name>"
If curl was built with HTTP/3 support, setting this environment variable to a
local directory will make curl produce qlogs in that directory, using file
names named after the destination connection id (in hex). Do note that these
files can become rather large. Works with both QUIC backends.
.IP SHELL
Used on VMS when trying to detect if using a DCL or a "unix" shell.
.IP "SSL_CERT_DIR <dir>"
If set, will be used as the \fI\-\-capath\fP value.
.IP "SSL_CERT_FILE <path>"
If set, will be used as the \fI\-\-cacert\fP value.
.IP "SSLKEYLOGFILE <file name>"
If you set this environment variable to a file name, curl will store TLS
secrets from its connections in that file when invoked to enable you to
analyze the TLS traffic in real time using network analyzing tools such as
Wireshark. This works with the following TLS backends: OpenSSL, libressl,
BoringSSL, GnuTLS, NSS and wolfSSL.
.IP "USERPROFILE <dir>"
On Windows, this variable is used when trying to find the home directory. If
the other, primary, variable are all unset. If set, curl will use the path
\(dq$USERPROFILE\\Application Data".
.IP "XDG_CONFIG_HOME <dir>"
If \fBCURL_HOME\fP is not set, this variable is checked when looking for a
default .curlrc file.
.SH "PROXY PROTOCOL PREFIXES"
The proxy string may be specified with a protocol:// prefix to specify
alternative proxy protocols.
If no protocol is specified in the proxy string or if the string does not match
a supported one, the proxy will be treated as an HTTP proxy.
The supported proxy protocol prefixes are as follows:
.IP "http://"
Makes it use it as an HTTP proxy. The default if no scheme prefix is used.
.IP "https://"
Makes it treated as an \fBHTTPS\fP proxy.
.IP "socks4://"
Makes it the equivalent of \-\-socks4
.IP "socks4a://"
Makes it the equivalent of \-\-socks4a
.IP "socks5://"
Makes it the equivalent of \-\-socks5
.IP "socks5h://"
Makes it the equivalent of \-\-socks5-hostname
.SH EXIT CODES
There are a bunch of different error codes and their corresponding error
messages that may appear under error conditions. At the time of this writing,
the exit codes are:
.IP 0
Success. The operation completed successfully according to the instructions.
.IP 1
Unsupported protocol. This build of curl has no support for this protocol.
.IP 2
Failed to initialize.
.IP 3
URL malformed. The syntax was not correct.
.IP 4
A feature or option that was needed to perform the desired request was not
enabled or was explicitly disabled at build-time. To make curl able to do
this, you probably need another build of libcurl.
.IP 5
Could not resolve proxy. The given proxy host could not be resolved.
.IP 6
Could not resolve host. The given remote host could not be resolved.
.IP 7
Failed to connect to host.
.IP 8
Weird server reply. The server sent data curl could not parse.
.IP 9
FTP access denied. The server denied login or denied access to the particular
resource or directory you wanted to reach. Most often you tried to change to a
directory that does not exist on the server.
.IP 10
FTP accept failed. While waiting for the server to connect back when an active
FTP session is used, an error code was sent over the control connection or
similar.
.IP 11
FTP weird PASS reply. Curl could not parse the reply sent to the PASS request.
.IP 12
During an active FTP session while waiting for the server to connect back to
curl, the timeout expired.
.IP 13
FTP weird PASV reply, Curl could not parse the reply sent to the PASV request.
.IP 14
FTP weird 227 format. Curl could not parse the 227-line the server sent.
.IP 15
FTP cannot use host. Could not resolve the host IP we got in the 227-line.
.IP 16
HTTP/2 error. A problem was detected in the HTTP2 framing layer. This is
somewhat generic and can be one out of several problems, see the error message
for details.
.IP 17
FTP could not set binary. Could not change transfer method to binary.
.IP 18
Partial file. Only a part of the file was transferred.
.IP 19
FTP could not download/access the given file, the RETR (or similar) command
failed.
.IP 21
FTP quote error. A quote command returned error from the server.
.IP 22
HTTP page not retrieved. The requested URL was not found or returned another
error with the HTTP error code being 400 or above. This return code only
appears if \-\-fail is used.
.IP 23
Write error. Curl could not write data to a local filesystem or similar.
.IP 25
FTP could not STOR file. The server denied the STOR operation, used for FTP
uploading.
.IP 26
Read error. Various reading problems.
.IP 27
Out of memory. A memory allocation request failed.
.IP 28
Operation timeout. The specified time-out period was reached according to the
conditions.
.IP 30
FTP PORT failed. The PORT command failed. Not all FTP servers support the PORT
command, try doing a transfer using PASV instead!
.IP 31
FTP could not use REST. The REST command failed. This command is used for
resumed FTP transfers.
.IP 33
HTTP range error. The range "command" did not work.
.IP 34
HTTP post error. Internal post-request generation error.
.IP 35
SSL connect error. The SSL handshaking failed.
.IP 36
Bad download resume. Could not continue an earlier aborted download.
.IP 37
FILE could not read file. Failed to open the file. Permissions?
.IP 38
LDAP cannot bind. LDAP bind operation failed.
.IP 39
LDAP search failed.
.IP 41
Function not found. A required LDAP function was not found.
.IP 42
Aborted by callback. An application told curl to abort the operation.
.IP 43
Internal error. A function was called with a bad parameter.
.IP 45
Interface error. A specified outgoing interface could not be used.
.IP 47
Too many redirects. When following redirects, curl hit the maximum amount.
.IP 48
Unknown option specified to libcurl. This indicates that you passed a weird
option to curl that was passed on to libcurl and rejected. Read up in the
manual!
.IP 49
Malformed telnet option.
.IP 52
The server did not reply anything, which here is considered an error.
.IP 53
SSL crypto engine not found.
.IP 54
Cannot set SSL crypto engine as default.
.IP 55
Failed sending network data.
.IP 56
Failure in receiving network data.
.IP 58
Problem with the local certificate.
.IP 59
Could not use specified SSL cipher.
.IP 60
Peer certificate cannot be authenticated with known CA certificates.
.IP 61
Unrecognized transfer encoding.
.IP 63
Maximum file size exceeded.
.IP 64
Requested FTP SSL level failed.
.IP 65
Sending the data requires a rewind that failed.
.IP 66
Failed to initialise SSL Engine.
.IP 67
The user name, password, or similar was not accepted and curl failed to log in.
.IP 68
File not found on TFTP server.
.IP 69
Permission problem on TFTP server.
.IP 70
Out of disk space on TFTP server.
.IP 71
Illegal TFTP operation.
.IP 72
Unknown TFTP transfer ID.
.IP 73
File already exists (TFTP).
.IP 74
No such user (TFTP).
.IP 77
Problem reading the SSL CA cert (path? access rights?).
.IP 78
The resource referenced in the URL does not exist.
.IP 79
An unspecified error occurred during the SSH session.
.IP 80
Failed to shut down the SSL connection.
.IP 82
Could not load CRL file, missing or wrong format.
.IP 83
Issuer check failed.
.IP 84
The FTP PRET command failed.
.IP 85
Mismatch of RTSP CSeq numbers.
.IP 86
Mismatch of RTSP Session Identifiers.
.IP 87
Unable to parse FTP file list.
.IP 88
FTP chunk callback reported error.
.IP 89
No connection available, the session will be queued.
.IP 90
SSL public key does not matched pinned public key.
.IP 91
Invalid SSL certificate status.
.IP 92
Stream error in HTTP/2 framing layer.
.IP 93
An API function was called from inside a callback.
.IP 94
An authentication function returned an error.
.IP 95
A problem was detected in the HTTP/3 layer. This is somewhat generic and can
be one out of several problems, see the error message for details.
.IP 96
QUIC connection error. This error may be caused by an SSL library error. QUIC
is the protocol used for HTTP/3 transfers.
.IP XX
More error codes will appear here in future releases. The existing ones
are meant to never change.
.SH BUGS
If you experience any problems with curl, submit an issue in the project's bug
tracker on GitHub: https://github.com/curl/curl/issues
.SH AUTHORS / CONTRIBUTORS
Daniel Stenberg is the main author, but the whole list of contributors is
found in the separate THANKS file.
.SH WWW
https://curl.se
.SH "SEE ALSO"
.BR ftp (1),
.BR wget (1)
share/aclocal/libcurl.m4 0000644 00000025703 14751150700 0011151 0 ustar 00 #***************************************************************************
# _ _ ____ _
# Project ___| | | | _ \| |
# / __| | | | |_) | |
# | (__| |_| | _ <| |___
# \___|\___/|_| \_\_____|
#
# Copyright (C) 2006 - 2022, David Shaw <dshaw@jabberwocky.com>
#
# This software is licensed as described in the file COPYING, which
# you should have received as part of this distribution. The terms
# are also available at https://curl.se/docs/copyright.html.
#
# You may opt to use, copy, modify, merge, publish, distribute and/or sell
# copies of the Software, and permit persons to whom the Software is
# furnished to do so, under the terms of the COPYING file.
#
# This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
# KIND, either express or implied.
#
# SPDX-License-Identifier: curl
#
###########################################################################
# LIBCURL_CHECK_CONFIG ([DEFAULT-ACTION], [MINIMUM-VERSION],
# [ACTION-IF-YES], [ACTION-IF-NO])
# ----------------------------------------------------------
# David Shaw <dshaw@jabberwocky.com> May-09-2006
#
# Checks for libcurl. DEFAULT-ACTION is the string yes or no to
# specify whether to default to --with-libcurl or --without-libcurl.
# If not supplied, DEFAULT-ACTION is yes. MINIMUM-VERSION is the
# minimum version of libcurl to accept. Pass the version as a regular
# version number like 7.10.1. If not supplied, any version is
# accepted. ACTION-IF-YES is a list of shell commands to run if
# libcurl was successfully found and passed the various tests.
# ACTION-IF-NO is a list of shell commands that are run otherwise.
# Note that using --without-libcurl does run ACTION-IF-NO.
#
# This macro #defines HAVE_LIBCURL if a working libcurl setup is
# found, and sets @LIBCURL@ and @LIBCURL_CPPFLAGS@ to the necessary
# values. Other useful defines are LIBCURL_FEATURE_xxx where xxx are
# the various features supported by libcurl, and LIBCURL_PROTOCOL_yyy
# where yyy are the various protocols supported by libcurl. Both xxx
# and yyy are capitalized. See the list of AH_TEMPLATEs at the top of
# the macro for the complete list of possible defines. Shell
# variables $libcurl_feature_xxx and $libcurl_protocol_yyy are also
# defined to 'yes' for those features and protocols that were found.
# Note that xxx and yyy keep the same capitalization as in the
# curl-config list (e.g. it's "HTTP" and not "http").
#
# Users may override the detected values by doing something like:
# LIBCURL="-lcurl" LIBCURL_CPPFLAGS="-I/usr/myinclude" ./configure
#
# For the sake of sanity, this macro assumes that any libcurl that is
# found is after version 7.7.2, the first version that included the
# curl-config script. Note that it is very important for people
# packaging binary versions of libcurl to include this script!
# Without curl-config, we can only guess what protocols are available,
# or use curl_version_info to figure it out at runtime.
AC_DEFUN([LIBCURL_CHECK_CONFIG],
[
AH_TEMPLATE([LIBCURL_FEATURE_SSL],[Defined if libcurl supports SSL])
AH_TEMPLATE([LIBCURL_FEATURE_KRB4],[Defined if libcurl supports KRB4])
AH_TEMPLATE([LIBCURL_FEATURE_IPV6],[Defined if libcurl supports IPv6])
AH_TEMPLATE([LIBCURL_FEATURE_LIBZ],[Defined if libcurl supports libz])
AH_TEMPLATE([LIBCURL_FEATURE_ASYNCHDNS],[Defined if libcurl supports AsynchDNS])
AH_TEMPLATE([LIBCURL_FEATURE_IDN],[Defined if libcurl supports IDN])
AH_TEMPLATE([LIBCURL_FEATURE_SSPI],[Defined if libcurl supports SSPI])
AH_TEMPLATE([LIBCURL_FEATURE_NTLM],[Defined if libcurl supports NTLM])
AH_TEMPLATE([LIBCURL_PROTOCOL_HTTP],[Defined if libcurl supports HTTP])
AH_TEMPLATE([LIBCURL_PROTOCOL_HTTPS],[Defined if libcurl supports HTTPS])
AH_TEMPLATE([LIBCURL_PROTOCOL_FTP],[Defined if libcurl supports FTP])
AH_TEMPLATE([LIBCURL_PROTOCOL_FTPS],[Defined if libcurl supports FTPS])
AH_TEMPLATE([LIBCURL_PROTOCOL_FILE],[Defined if libcurl supports FILE])
AH_TEMPLATE([LIBCURL_PROTOCOL_TELNET],[Defined if libcurl supports TELNET])
AH_TEMPLATE([LIBCURL_PROTOCOL_LDAP],[Defined if libcurl supports LDAP])
AH_TEMPLATE([LIBCURL_PROTOCOL_DICT],[Defined if libcurl supports DICT])
AH_TEMPLATE([LIBCURL_PROTOCOL_TFTP],[Defined if libcurl supports TFTP])
AH_TEMPLATE([LIBCURL_PROTOCOL_RTSP],[Defined if libcurl supports RTSP])
AH_TEMPLATE([LIBCURL_PROTOCOL_POP3],[Defined if libcurl supports POP3])
AH_TEMPLATE([LIBCURL_PROTOCOL_IMAP],[Defined if libcurl supports IMAP])
AH_TEMPLATE([LIBCURL_PROTOCOL_SMTP],[Defined if libcurl supports SMTP])
AC_ARG_WITH(libcurl,
AS_HELP_STRING([--with-libcurl=PREFIX],[look for the curl library in PREFIX/lib and headers in PREFIX/include]),
[_libcurl_with=$withval],[_libcurl_with=ifelse([$1],,[yes],[$1])])
if test "$_libcurl_with" != "no" ; then
AC_PROG_AWK
_libcurl_version_parse="eval $AWK '{split(\$NF,A,\".\"); X=256*256*A[[1]]+256*A[[2]]+A[[3]]; print X;}'"
_libcurl_try_link=yes
if test -d "$_libcurl_with" ; then
LIBCURL_CPPFLAGS="-I$withval/include"
_libcurl_ldflags="-L$withval/lib"
AC_PATH_PROG([_libcurl_config],[curl-config],[],
["$withval/bin"])
else
AC_PATH_PROG([_libcurl_config],[curl-config],[],[$PATH])
fi
if test x$_libcurl_config != "x" ; then
AC_CACHE_CHECK([for the version of libcurl],
[libcurl_cv_lib_curl_version],
[libcurl_cv_lib_curl_version=`$_libcurl_config --version | $AWK '{print $[]2}'`])
_libcurl_version=`echo $libcurl_cv_lib_curl_version | $_libcurl_version_parse`
_libcurl_wanted=`echo ifelse([$2],,[0],[$2]) | $_libcurl_version_parse`
if test $_libcurl_wanted -gt 0 ; then
AC_CACHE_CHECK([for libcurl >= version $2],
[libcurl_cv_lib_version_ok],
[
if test $_libcurl_version -ge $_libcurl_wanted ; then
libcurl_cv_lib_version_ok=yes
else
libcurl_cv_lib_version_ok=no
fi
])
fi
if test $_libcurl_wanted -eq 0 || test x$libcurl_cv_lib_version_ok = xyes ; then
if test x"$LIBCURL_CPPFLAGS" = "x" ; then
LIBCURL_CPPFLAGS=`$_libcurl_config --cflags`
fi
if test x"$LIBCURL" = "x" ; then
LIBCURL=`$_libcurl_config --libs`
# This is so silly, but Apple actually has a bug in their
# curl-config script. Fixed in Tiger, but there are still
# lots of Panther installs around.
case "${host}" in
powerpc-apple-darwin7*)
LIBCURL=`echo $LIBCURL | sed -e 's|-arch i386||g'`
;;
esac
fi
# All curl-config scripts support --feature
_libcurl_features=`$_libcurl_config --feature`
# Is it modern enough to have --protocols? (7.12.4)
if test $_libcurl_version -ge 461828 ; then
_libcurl_protocols=`$_libcurl_config --protocols`
fi
else
_libcurl_try_link=no
fi
unset _libcurl_wanted
fi
if test $_libcurl_try_link = yes ; then
# we didn't find curl-config, so let's see if the user-supplied
# link line (or failing that, "-lcurl") is enough.
LIBCURL=${LIBCURL-"$_libcurl_ldflags -lcurl"}
AC_CACHE_CHECK([whether libcurl is usable],
[libcurl_cv_lib_curl_usable],
[
_libcurl_save_cppflags=$CPPFLAGS
CPPFLAGS="$LIBCURL_CPPFLAGS $CPPFLAGS"
_libcurl_save_libs=$LIBS
LIBS="$LIBCURL $LIBS"
AC_LINK_IFELSE([AC_LANG_PROGRAM([[#include <curl/curl.h>]],[[
/* Try and use a few common options to force a failure if we are
missing symbols or can't link. */
int x;
curl_easy_setopt(NULL,CURLOPT_URL,NULL);
x=CURL_ERROR_SIZE;
x=CURLOPT_WRITEFUNCTION;
x=CURLOPT_WRITEDATA;
x=CURLOPT_ERRORBUFFER;
x=CURLOPT_STDERR;
x=CURLOPT_VERBOSE;
if (x) {;}
]])],libcurl_cv_lib_curl_usable=yes,libcurl_cv_lib_curl_usable=no)
CPPFLAGS=$_libcurl_save_cppflags
LIBS=$_libcurl_save_libs
unset _libcurl_save_cppflags
unset _libcurl_save_libs
])
if test $libcurl_cv_lib_curl_usable = yes ; then
# Does curl_free() exist in this version of libcurl?
# If not, fake it with free()
_libcurl_save_cppflags=$CPPFLAGS
CPPFLAGS="$CPPFLAGS $LIBCURL_CPPFLAGS"
_libcurl_save_libs=$LIBS
LIBS="$LIBS $LIBCURL"
AC_CHECK_FUNC(curl_free,,
AC_DEFINE(curl_free,free,
[Define curl_free() as free() if our version of curl lacks curl_free.]))
CPPFLAGS=$_libcurl_save_cppflags
LIBS=$_libcurl_save_libs
unset _libcurl_save_cppflags
unset _libcurl_save_libs
AC_DEFINE(HAVE_LIBCURL,1,
[Define to 1 if you have a functional curl library.])
AC_SUBST(LIBCURL_CPPFLAGS)
AC_SUBST(LIBCURL)
for _libcurl_feature in $_libcurl_features ; do
AC_DEFINE_UNQUOTED(AS_TR_CPP(libcurl_feature_$_libcurl_feature),[1])
eval AS_TR_SH(libcurl_feature_$_libcurl_feature)=yes
done
if test "x$_libcurl_protocols" = "x" ; then
# We don't have --protocols, so just assume that all
# protocols are available
_libcurl_protocols="HTTP FTP FILE TELNET LDAP DICT TFTP"
if test x$libcurl_feature_SSL = xyes ; then
_libcurl_protocols="$_libcurl_protocols HTTPS"
# FTPS wasn't standards-compliant until version
# 7.11.0 (0x070b00 == 461568)
if test $_libcurl_version -ge 461568; then
_libcurl_protocols="$_libcurl_protocols FTPS"
fi
fi
# RTSP, IMAP, POP3 and SMTP were added in
# 7.20.0 (0x071400 == 463872)
if test $_libcurl_version -ge 463872; then
_libcurl_protocols="$_libcurl_protocols RTSP IMAP POP3 SMTP"
fi
fi
for _libcurl_protocol in $_libcurl_protocols ; do
AC_DEFINE_UNQUOTED(AS_TR_CPP(libcurl_protocol_$_libcurl_protocol),[1])
eval AS_TR_SH(libcurl_protocol_$_libcurl_protocol)=yes
done
else
unset LIBCURL
unset LIBCURL_CPPFLAGS
fi
fi
unset _libcurl_try_link
unset _libcurl_version_parse
unset _libcurl_config
unset _libcurl_feature
unset _libcurl_features
unset _libcurl_protocol
unset _libcurl_protocols
unset _libcurl_version
unset _libcurl_ldflags
fi
if test x$_libcurl_with = xno || test x$libcurl_cv_lib_curl_usable != xyes ; then
# This is the IF-NO path
ifelse([$4],,:,[$4])
else
# This is the IF-YES path
ifelse([$3],,:,[$3])
fi
unset _libcurl_with
])dnl
bin/curl-config 0000755 00000013071 14751150700 0007454 0 ustar 00 #! /bin/sh
#***************************************************************************
# _ _ ____ _
# Project ___| | | | _ \| |
# / __| | | | |_) | |
# | (__| |_| | _ <| |___
# \___|\___/|_| \_\_____|
#
# Copyright (C) 2001 - 2022, 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
# are also available at https://curl.se/docs/copyright.html.
#
# You may opt to use, copy, modify, merge, publish, distribute and/or sell
# copies of the Software, and permit persons to whom the Software is
# furnished to do so, under the terms of the COPYING file.
#
# This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
# KIND, either express or implied.
#
# SPDX-License-Identifier: curl
#
###########################################################################
prefix="/usr/local/curl-openssl-1.0.0"
exec_prefix=${prefix}
includedir=${prefix}/include
cppflag_curl_staticlib=
usage()
{
cat <<EOF
Usage: curl-config [OPTION]
Available values for OPTION include:
--built-shared says 'yes' if libcurl was built shared
--ca ca bundle install path
--cc compiler
--cflags pre-processor and compiler flags
--checkfor [version] check for (lib)curl of the specified version
--configure the arguments given to configure when building curl
--features newline separated list of enabled features
--help display this help and exit
--libs library linking information
--prefix curl install prefix
--protocols newline separated list of enabled protocols
--ssl-backends output the SSL backends libcurl was built to support
--static-libs static libcurl library linking information
--version output version information
--vernum output the version information as a number (hexadecimal)
EOF
exit $1
}
if test $# -eq 0; then
usage 1
fi
while test $# -gt 0; do
case "$1" in
# this deals with options in the style
# --option=value and extracts the value part
# [not currently used]
-*=*) value=`echo "$1" | sed 's/[-_a-zA-Z0-9]*=//'` ;;
*) value= ;;
esac
case "$1" in
--built-shared)
echo yes
;;
--ca)
echo "/etc/pki/tls/certs/ca-bundle.crt"
;;
--cc)
echo "gcc"
;;
--prefix)
echo "$prefix"
;;
--feature|--features)
for feature in AsynchDNS HSTS HTTPS-proxy IPv6 Largefile NTLM NTLM_WB SSL UnixSockets alt-svc libz threadsafe zstd ""; do
test -n "$feature" && echo "$feature"
done
;;
--protocols)
for protocol in DICT FILE FTP FTPS GOPHER GOPHERS HTTP HTTPS IMAP IMAPS MQTT POP3 POP3S RTSP SMB SMBS SMTP SMTPS TELNET TFTP; do
echo "$protocol"
done
;;
--version)
echo libcurl 7.86.0
exit 0
;;
--checkfor)
checkfor=$2
cmajor=`echo $checkfor | cut -d. -f1`
cminor=`echo $checkfor | cut -d. -f2`
# when extracting the patch part we strip off everything after a
# dash as that's used for things like version 1.2.3-CVS
cpatch=`echo $checkfor | cut -d. -f3 | cut -d- -f1`
vmajor=`echo 7.86.0 | cut -d. -f1`
vminor=`echo 7.86.0 | cut -d. -f2`
# when extracting the patch part we strip off everything after a
# dash as that's used for things like version 1.2.3-CVS
vpatch=`echo 7.86.0 | cut -d. -f3 | cut -d- -f1`
if test "$vmajor" -gt "$cmajor"; then
exit 0;
fi
if test "$vmajor" -eq "$cmajor"; then
if test "$vminor" -gt "$cminor"; then
exit 0
fi
if test "$vminor" -eq "$cminor"; then
if test "$cpatch" -le "$vpatch"; then
exit 0
fi
fi
fi
echo "requested version $checkfor is newer than existing 7.86.0"
exit 1
;;
--vernum)
echo 075600
exit 0
;;
--help)
usage 0
;;
--cflags)
if test "X$cppflag_curl_staticlib" = "X-DCURL_STATICLIB"; then
CPPFLAG_CURL_STATICLIB="-DCURL_STATICLIB "
else
CPPFLAG_CURL_STATICLIB=""
fi
if test "X${prefix}/include" = "X/usr/include"; then
echo "$CPPFLAG_CURL_STATICLIB"
else
echo "${CPPFLAG_CURL_STATICLIB}-I${prefix}/include"
fi
;;
--libs)
if test "X${exec_prefix}/lib" != "X/usr/lib" -a "X${exec_prefix}/lib" != "X/usr/lib64"; then
CURLLIBDIR="-L${exec_prefix}/lib "
else
CURLLIBDIR=""
fi
if test "Xyes" = "Xno"; then
echo ${CURLLIBDIR}-lcurl -lssl -lcrypto -lssl -lcrypto -ldl -lzstd -lz -pthread
else
echo ${CURLLIBDIR}-lcurl
fi
;;
--ssl-backends)
echo "OpenSSL"
;;
--static-libs)
if test "Xyes" != "Xno" ; then
echo "${exec_prefix}/lib/libcurl.a" -L/usr/local/openssl-1.0.0/lib -lssl -lcrypto -lssl -lcrypto -ldl -lzstd -lz -pthread
else
echo "curl was built with static libraries disabled" >&2
exit 1
fi
;;
--configure)
echo " '--prefix=/usr/local/curl-openssl-1.0.0' '--with-openssl=/usr/local/openssl-1.0.0' '--disable-ldap' '--disable-ldaps'"
;;
*)
echo "unknown option: $1"
usage 1
;;
esac
shift
done
exit 0
bin/curl 0000755 00001010210 14751150700 0006202 0 ustar 00 ELF >