132 строки
5.5 KiB
Groff
132 строки
5.5 KiB
Groff
.\" **************************************************************************
|
|
.\" * _ _ ____ _
|
|
.\" * Project ___| | | | _ \| |
|
|
.\" * / __| | | | |_) | |
|
|
.\" * | (__| |_| | _ <| |___
|
|
.\" * \___|\___/|_| \_\_____|
|
|
.\" *
|
|
.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
|
|
.\" *
|
|
.\" * This software is licensed as described in the file COPYING, which
|
|
.\" * you should have received as part of this distribution. The terms
|
|
.\" * are also available at https://curl.se/docs/copyright.html.
|
|
.\" *
|
|
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
|
|
.\" * copies of the Software, and permit persons to whom the Software is
|
|
.\" * furnished to do so, under the terms of the COPYING file.
|
|
.\" *
|
|
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
|
|
.\" * KIND, either express or implied.
|
|
.\" *
|
|
.\" **************************************************************************
|
|
.\"
|
|
.TH CURLOPT_URL 3 "17 Jun 2014" "libcurl 7.37.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), "
|