Provided by: libcurl4-doc_7.65.3-1ubuntu3_all bug

NAME

       CURLOPT_URL - provide the URL to use in the request

SYNOPSIS

       #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 zero
       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 doesn't validate the syntax or use this variable until  the  transfer  is  issued.
       Even if you set a crazy value here, curl_easy_setopt(3) will still return CURLE_OK.

       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
       CURLOPT_DEFAULT_PROTOCOL(3) 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 CURLE_UNSUPPORTED_PROTOCOL  will  be  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(3)  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 CURLOPT_URL(3) string will be ignored if CURLOPT_CURLU(3) is set.

       CURLOPT_URL(3) or CURLOPT_CURLU(3) must be set before a transfer is started.

       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.example.com/

       http://hostname/

       http://192.168.0.1/

       http://[2001:1890:1112:1::20]/

       It is also possible to specify the user name, password and any supported login options  as
       part  of  the  host,  for the following protocols, when connecting to servers that require
       authentication:

       http://user:password@www.example.com

       ftp://user:password@ftp.example.com

       smb://domain%2fuser:password@server.example.com

       imap://user:password;options@mail.example.com

       pop3://user:password;options@mail.example.com

       smtp://user:password;options@mail.example.com

       At present only IMAP, POP3 and SMTP support login options as part of the host.   For  more
       information  about  the  login  options in URL syntax please see RFC2384, RFC5092 and IETF
       draft draft-earhart-url-smtp-00.txt (Added in 7.31.0).

       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.example.com:8080/ - This will connect to a web server using  port  8080  rather
       than 80.

       smtp://mail.example.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:

       HTTP   The  path  part  of  an  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. The exact  resource  returned
              for each URL is entirely dependent on the server's configuration.

              http://www.example.com - This gets the main page from the web server.

              http://www.example.com/index.html  -  This  returns  the  main  page  by explicitly
              requesting it.

              http://www.example.com/contactus/ - This returns  the  default  document  from  the
              contactus directory.

       FTP    The  path  part  of  an  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://ftp.example.com  -  This  retrieves  the  directory  listing  for  the   root
              directory.

              ftp://ftp.example.com/readme.txt - This downloads the file readme.txt from the root
              directory.

              ftp://ftp.example.com/libcurl/readme.txt  -  This  downloads  readme.txt  from  the
              libcurl directory.

              ftp://user:password@ftp.example.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 prepending an additional
              forward slash to the beginning of the path.

              ftp://user:password@ftp.example.com//readme.txt -  This  retrieves  the  readme.txt
              from the root directory when logging in as a specified user.

       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
              attempt to resolve the local computer's host name. However, this may not return the
              fully qualified domain name that is required by some mail  servers  and  specifying
              this  path  allows  you  to  set  an alternative name, 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.example.com - This connects to the mail server at example.com and sends
              your local computer's host name in the HELO / EHLO command.

              smtp://mail.example.com/client.example.com - This will send  client.example.com  in
              the HELO / EHLO command to the mail server at example.com.

       POP3   The  path part of a POP3 request specifies the message ID to retrieve. If the ID is
              not specified then a list of waiting messages is returned instead.

              pop3://user:password@mail.example.com - This lists the available messages  for  the
              user

              pop3://user:password@mail.example.com/1  - This retrieves the first message for the
              user

       IMAP   The path part of an IMAP request not only specifies the mailbox to list  (Added  in
              7.30.0) or select, but can also be used to check the UIDVALIDITY of the mailbox, to
              specify the UID, SECTION (Added in 7.30.0) and PARTIAL octets (Added in 7.37.0)  of
              the message to fetch and to specify what messages to search for (Added in 7.37.0).

              imap://user:password@mail.example.com - Performs a top level folder list

              imap://user:password@mail.example.com/INBOX  - Performs a folder list on the user's
              inbox

              imap://user:password@mail.example.com/INBOX/;UID=1 - Selects the user's  inbox  and
              fetches message with uid = 1

              imap://user:password@mail.example.com/INBOX/;MAILINDEX=1 - Selects the user's inbox
              and fetches the first message in the mail box

              imap://user:password@mail.example.com/INBOX;UIDVALIDITY=50/;UID=2  -  Selects   the
              user's  inbox, checks the UIDVALIDITY of the mailbox is 50 and fetches message 2 if
              it is

              imap://user:password@mail.example.com/INBOX/;UID=3/;SECTION=TEXT  -   Selects   the
              user's inbox and fetches the text portion of message 3

              imap://user:password@mail.example.com/INBOX/;UID=4/;PARTIAL=0.1024  -  Selects  the
              user's inbox and fetches the first 1024 octets of message 4

              imap://user:password@mail.example.com/INBOX?NEW -  Selects  the  user's  inbox  and
              checks for NEW messages

              imap://user:password@mail.example.com/INBOX?SUBJECT%20shadows  - Selects the user's
              inbox and searches for messages containing "shadows" in the subject line

              For more information about the individual components of  an  IMAP  URL  please  see
              RFC5092.

       SCP    The  path  part  of  a  SCP  request  specifies  the file to retrieve and from what
              directory. The file part may not be omitted. The file is taken as an absolute  path
              from  the  root  directory  on the server. To specify a path relative to the user's
              home directory on the server, prepend ~/ to the path portion.  If the user name  is
              not   embedded   in  the  URL,  it  can  be  set  with  the  CURLOPT_USERPWD(3)  or
              CURLOPT_USERNAME(3) option.

              scp://user@example.com/etc/issue - This specifies the file /etc/issue

              scp://example.com/~/my-file - This specifies the file my-file in  the  user's  home
              directory on the server

       SFTP   The  path  part  of  a  SFTP  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 path ends in a / then a directory listing is
              returned instead of a file.  If the path is omitted  entirely  then  the  directory
              listing  for  the  root / home directory will be returned.  If the user name is not
              embedded  in  the  URL,  it   can   be   set   with   the   CURLOPT_USERPWD(3)   or
              CURLOPT_USERNAME(3) option.

              sftp://user:password@example.com/etc/issue - This specifies the file /etc/issue

              sftp://user@example.com/~/my-file  -  This specifies the file my-file in the user's
              home directory

              sftp://ssh.example.com/~/Documents/ - This requests  a  directory  listing  of  the
              Documents directory under the user's home directory

       SMB    The  path  part of a SMB request specifies the file to retrieve and from what share
              and directory or the share to upload to and as such, may not be  omitted.   If  the
              user  name is not embedded in the URL, it can be set with the CURLOPT_USERPWD(3) or
              CURLOPT_USERNAME(3) option. If the user name is embedded in the URL  then  it  must
              contain the domain name and as such, the backslash must be URL encoded as %2f.

              smb://server.example.com/files/issue  -  This specifies the file "issue" located in
              the root of the "files" share

              smb://server.example.com/files/ -T issue - This specifies the file "issue" will  be
              uploaded to the root of the "files" share.

       LDAP   The  path  part  of  a LDAP request can be used to specify the: Distinguished Name,
              Attributes, Scope, Filter and Extension for a LDAP search. Each field is  separated
              by  a  question  mark  and when that field is not required an empty string with the
              question mark separator should be included.

              ldap://ldap.example.com/o=My%20Organisation - This will perform a LDAP search  with
              the DN as My Organisation.

              ldap://ldap.example.com/o=My%20Organisation?postalAddress  -  This will perform the
              same search but will only return postalAddress attributes.

              ldap://ldap.example.com/?rootDomainNamingContext - This specifies an empty  DN  and
              requests  information  about  the  rootDomainNamingContext  attribute for an Active
              Directory server.

              For more information about the individual components  of  a  LDAP  URL  please  see
              RFC4516.

       RTMP   There's  no  official URL spec for RTMP so libcurl uses the URL syntax supported by
              the underlying librtmp library. It has a syntax where it wants a  traditional  URL,
              followed by a space and a series of space-separated name=value pairs.

              While  space  is  not typically a "legal" letter, libcurl accepts them. When a user
              wants to pass in a '#' (hash) character it will be treated as a  fragment  and  get
              cut  off  by  libcurl  if provided literally. You will instead have to escape it by
              providing it as backslash and its ASCII value in hexadecimal: "\23".

       The application does not have to keep the string around after setting this option.

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).

       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 isn't 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 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 very 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

       CURL *curl = curl_easy_init();
       if(curl) {
         curl_easy_setopt(curl, CURLOPT_URL, "http://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) won't actually parse the given string so given a bad URL, it
       will not be detected until curl_easy_perform(3) or similar is called.

SEE ALSO

       CURLOPT_VERBOSE(3),             CURLOPT_PROTOCOLS(3),             CURLOPT_FORBID_REUSE(3),
       CURLOPT_FRESH_CONNECT(3),         curl_easy_perform(3),          CURLINFO_REDIRECT_URL(3),
       CURLOPT_PATH_AS_IS(3), CURLOPT_CURLU(3),