| .\" ************************************************************************** |
| .\" * _ _ ____ _ |
| .\" * 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 "November 08, 2021" "libcurl 7.80.0" "curl_easy_setopt options" |
| |
| .SH NAME |
| CURLOPT_URL \- URL for this transfer |
| .SH SYNOPSIS |
| #include <curl/curl.h> |
| |
| CURLcode curl_easy_setopt(CURL *handle, CURLOPT_URL, char *URL); |
| .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), " |
