145 lines
5.5 KiB
Groff
145 lines
5.5 KiB
Groff
|
|
.\" **************************************************************************
|
|
.\" * _ _ ____ _
|
|
.\" * Project ___| | | | _ \| |
|
|
.\" * / __| | | | |_) | |
|
|
.\" * | (__| |_| | _ <| |___
|
|
.\" * \___|\___/|_| \_\_____|
|
|
.\" *
|
|
.\" * Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
|
|
.\" *
|
|
.\" * This software is licensed as described in the file COPYING, which
|
|
.\" * you should have received as part of this distribution. The terms
|
|
.\" * are also available at https://curl.se/docs/copyright.html.
|
|
.\" *
|
|
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
|
|
.\" * copies of the Software, and permit persons to whom the Software is
|
|
.\" * furnished to do so, under the terms of the COPYING file.
|
|
.\" *
|
|
.\" * 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 "17 Jun 2014" libcurl libcurl
|
|
.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 RFC 3986.
|
|
|
|
libcurl does not validate the syntax or use the URL until the transfer is
|
|
started. Even if you set a crazy value here, \fIcurl_easy_setopt(3)\fP might
|
|
still return \fICURLE_OK\fP.
|
|
|
|
If the given URL is missing a scheme name (such as "http://" or "ftp://" etc)
|
|
then libcurl guesses based on the host. If the outermost subdomain name
|
|
matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that protocol gets used,
|
|
otherwise HTTP is 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 as specified by the URL scheme or deduced by
|
|
libcurl from the host name, not be supported by libcurl then
|
|
\fICURLE_UNSUPPORTED_PROTOCOL\fP is 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_STR(3)\fP can be used to limit what protocols libcurl may
|
|
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 is ignored if \fICURLOPT_CURLU(3)\fP is set.
|
|
|
|
Either \fICURLOPT_URL(3)\fP or \fICURLOPT_CURLU(3)\fP must be set before a
|
|
transfer is started.
|
|
|
|
The application does not have to keep the string around after setting this
|
|
option.
|
|
|
|
The parser used for handling the URL set with \fICURLOPT_URL(3)\fP is the same
|
|
that \fIcurl_url_set(3)\fP uses.
|
|
.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 brings 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
|
|
int main(void)
|
|
{
|
|
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 does not parse the given string so given a
|
|
bad URL, it is not detected until \fIcurl_easy_perform(3)\fP or similar is
|
|
called.
|
|
.SH "SEE ALSO"
|
|
.BR curl_easy_perform (3),
|
|
.BR curl_url_get (3),
|
|
.BR curl_url_set (3),
|
|
.BR CURLINFO_REDIRECT_URL (3),
|
|
.BR CURLOPT_CURLU (3),
|
|
.BR CURLOPT_FORBID_REUSE (3),
|
|
.BR CURLOPT_FRESH_CONNECT (3),
|
|
.BR CURLOPT_PATH_AS_IS (3),
|
|
.BR CURLOPT_PROTOCOLS (3)
|