CURLOPT_URL: Expanded URL description

Expanded the section about CURLOPT_URL to include the format of the URL
and detailed information and examples relating to specific protocols.

1 files changed, 107 insertions, 10 deletions

diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3
index 90ebd8fd2..bdc0e9707 100644
--- a/docs/libcurl/curl_easy_setopt.3
+++ b/docs/libcurl/curl_easy_setopt.3
@@ -584,20 +584,117 @@ POST/PUT and a 401 or 407 is received immediately afterwards.
 .SH NETWORK OPTIONS
 .IP CURLOPT_URL
 The actual URL to deal with. The parameter should be a char * to a zero
-terminated string.
+terminated string which must be URL-encoded in the following format:
 
-If the given URL lacks the protocol part ("http://" or "ftp://" etc), it will
-attempt to guess which protocol to use based on the given host name. If the
-given protocol of the set URL is not supported, libcurl will return on error
-(\fICURLE_UNSUPPORTED_PROTOCOL\fP) when you call \fIcurl_easy_perform(3)\fP or
-\fIcurl_multi_perform(3)\fP. Use \fIcurl_version_info(3)\fP for detailed info
-on which protocols are supported.
+scheme://host:port/path
 
-The string given to CURLOPT_URL must be url-encoded and follow RFC 2396
+For a greater explaination of the format please see RFC 2396
 (http://curl.haxx.se/rfc/rfc2396.txt).
 
-Starting with version 7.20.0, the fragment part of the URI will not be send as
-part of the path, which was the case previously.
+If the given URL lacks the scheme, or protocol, part ("http://" or "ftp://"
+etc), libcurl will attempt to resolve which protocol to use based on the
+given host mame. If the protocol is not supported, libcurl will return
+(\fICURLE_UNSUPPORTED_PROTOCOL\fP) when you call \fIcurl_easy_perform(3)\fP
+or \fIcurl_multi_perform(3)\fP. Use \fIcurl_version_info(3)\fP for detailed
+information on which protocols are supported.
+
+The host part of the URL contains the address of the server that you want to
+connect to. This can be the fully qualified domain name of the server, the
+local network name of the machine on your network or the IP address of the
+server or machine represented by either an IPv4 or IPv6 address. For example:
+
+http://www.domain.com/
+
+http://hostname/
+
+http://192.168.0.1/
+
+http://[2001:1890:1112:1::20]/
+
+It is also possible to specify the user name and password as part of the
+host, for some protocols, when connecting to servers that require
+authentication.
+
+HTTP and FTP support this type of authentication as follows:
+
+http://name:password@www.domain.com
+ftp://name:password@ftp.domain.com
+
+The port is optional and when not specified libcurl will use the default port
+based on the determined or specified protocol: 80 for http, 21 for ftp and 25
+for smtp, etc. The following examples show how to specify the port:
+
+http://www.weirdserver.com:8080/ - This will connect to a web server using
+port 8080.
+
+smtp://mail.domain.com:587/ - This will connect to a smtp server on the
+alternative mail port.
+
+The path part of the URL is protocol specific and whilst some examples are
+given below this list is not conclusive:
+
+.B HTTP
+
+The path part of a HTTP request specifies the file to retrieve and from what
+directory. If the directory is not specified then the web server's root
+directory is used. If the file is omitted then the default document will be
+retrieved for either the directory specified or the root directory.
+
+http://www.netscape.com - This gets the main page (index.html in this
+example) from Netscape's web server.
+
+http://www.netscape.com/index.html - This returns the main page from Netscape
+by specifing the page to get.
+
+http://www.netscape.com/contactus/ - This returns the default document from
+the contact us directory.
+
+.B FTP
+
+The path part of a FTP request specifies the file to retrieve and from what
+directory. If the file part is omitted then libcurl downloads the directory
+listing for the directory specified. If the directory is omitted then
+the directory listing for the root / home directory will be returned.
+
+ftp://cool.haxx.se - This retrieves the directory listing for our FTP server.
+
+ftp://cool.haxx.se/readme.txt - This downloads the file readme.txt from the
+root directory.
+
+ftp://cool.haxx.se/libcurl/readme.txt - This downloads readme.txt from the
+libcurl directory.
+
+ftp://user:password@my.site.com/readme.txt - This retrieves the readme.txt
+file from the user's home directory. When a username and password is
+specified, everything that is specified in the path part is relative to the
+user's home directory. To retrieve files from the root directory or a
+directory underneath the root directory then the absolute path must be
+specified by using an additional forward slash to the beginning of the path.
+
+ftp://user:password@my.site.com//readme.txt - This retrieves the readme.txt
+from the root directory when logging in as a specified user. 
+
+.B SMTP
+
+The path part of a SMTP request specifies the host name to present during
+communication with the mail server. If the path is omitted then libcurl will
+perform a call to \fCurl_gethostname\fP to resolve the local computer's
+host name. However, \fCurl_gethostname\fP does not return the fully qualified
+domain name that is required by some mail servers and specifing this path
+allows you to specify an alternative nane such as your machine's fully
+qualified domain name which you might have obtained from an external function
+such as gethostname or getaddrinfo.
+
+smtp://mail.domain.com - This connects to the mail server at domain.com and
+sends your local computer's host name in the HELO / EHLO command.
+
+smtp://mail.domain.com/client.domain.com - This will send client.domain.com
+in the HELO / EHLO command to the mail server at domain.com.
+
+.B NOTES
+
+Starting with version 7.20.0, the fragment part of the URI will not be sent as
+part of the path, which was previously the case.
 
 \fICURLOPT_URL\fP is the only option that \fBmust\fP be set before
 \fIcurl_easy_perform(3)\fP is called.