[Global]: loading init

deps/curl/docs/libcurl/opts/CURLOPT_URL.md

@@ -0,0 +1,145 @@
+---
+c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
+SPDX-License-Identifier: curl
+Title: CURLOPT_URL
+Section: 3
+Source: libcurl
+See-also:
+  - CURLINFO_REDIRECT_URL (3)
+  - CURLOPT_CURLU (3)
+  - CURLOPT_FORBID_REUSE (3)
+  - CURLOPT_FRESH_CONNECT (3)
+  - CURLOPT_PATH_AS_IS (3)
+  - CURLOPT_PROTOCOLS (3)
+  - curl_easy_perform (3)
+  - curl_url_get (3)
+  - curl_url_set (3)
+---
+
+# NAME
+
+CURLOPT_URL - URL for this transfer
+
+# SYNOPSIS
+
+~~~c
+#include <curl/curl.h>
+
+CURLcode curl_easy_setopt(CURL *handle, CURLOPT_URL, char *URL);
+~~~
+
+# DESCRIPTION
+
+Pass in a pointer to the *URL* 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, curl_easy_setopt(3) might
+still return *CURLE_OK*.
+
+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 CURLOPT_DEFAULT_PROTOCOL(3) for details.
+
+Should the protocol, either as specified by the URL scheme or deduced by
+libcurl from the hostname, not be supported by libcurl then
+*CURLE_UNSUPPORTED_PROTOCOL* is returned from either the curl_easy_perform(3)
+or curl_multi_perform(3) functions when you call them. Use
+curl_version_info(3) for detailed information of which protocols are supported
+by the build of libcurl you are using.
+
+CURLOPT_PROTOCOLS_STR(3) 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 CURLOPT_URL(3) string is ignored if CURLOPT_CURLU(3) is set.
+
+Either CURLOPT_URL(3) or CURLOPT_CURLU(3) 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 CURLOPT_URL(3) is the same
+that curl_url_set(3) uses.
+
+# ENCODING
+
+The string pointed to in the CURLOPT_URL(3) 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.
+
+# DEFAULT
+
+There is no default URL. If this option is not set, no transfer can be
+performed.
+
+# 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 CURLOPT_PROTOCOLS(3).
+
+User provided URLs can also be made to point to sites that redirect further on
+(possibly to other protocols too). Consider your
+CURLOPT_FOLLOWLOCATION(3) and CURLOPT_REDIR_PROTOCOLS(3) settings.
+
+# PROTOCOLS
+
+All
+
+# EXAMPLE
+
+~~~c
+int main(void)
+{
+  CURL *curl = curl_easy_init();
+  if(curl) {
+    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
+
+    curl_easy_perform(curl);
+  }
+}
+~~~
+
+# AVAILABILITY
+
+POP3 and SMTP were added in 7.31.0
+
+# RETURN VALUE
+
+Returns CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insufficient
+heap space.
+
+Note that curl_easy_setopt(3) does not parse the given string so given a
+bad URL, it is not detected until curl_easy_perform(3) or similar is
+called.