Go to main content

man pages section 3: Library Interfaces and Headers

Exit Print View

Updated: Thursday, June 13, 2019



CURLOPT_URL - provide the URL to use in the request


#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_URL, char *URL);


CURLOPT_URL(3)             curl_easy_setopt options             CURLOPT_URL(3)

       CURLOPT_URL - provide the URL to use in the request

       #include <curl/curl.h>

       CURLcode curl_easy_setopt(CURL *handle, CURLOPT_URL, char *URL);

       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:


       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 CUR-
       LOPT_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 proto-
       cols 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

       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:




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







       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 con-

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

              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 speci-
              fied. 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 user-
              name 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

              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 com-
              puter's host name. However, this may not return the fully quali-
              fied domain name that is required by some mail servers and spec-
              ifying 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 getad-

              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 mes-
              sages 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, SEC-
              TION (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

              ITY=50/;UID=2 - Selects the user's inbox, checks the UIDVALIDITY
              of the mailbox is 50 and fetches message 2 if it is

              - Selects the user's inbox and fetches the text portion of  mes-
              sage 3

              TIAL=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_USER-
              PWD(3) or CURLOPT_USERNAME(3) option.

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

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

              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  direc-

       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  CUR-
              LOPT_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: Dis-
              tinguished 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

              ldap://ldap.example.com/?rootDomainNamingContext -  This  speci-
              fies  an empty DN and requests information about the rootDomain-
              NamingContext 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 pro-
              vided 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.

       The  string  pointed  to  in  the  CURLOPT_URL(3) argument is generally
       expected to be a sequence  of  characters  using  an  ASCII  compatible

       If  libcurl  is built with IDN support, the server name part of the URL
       can use an "international name" by using the current encoding  (accord-
       ing 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.

       There is no default URL. If this option isn't set, no transfer  can  be

       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

       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  local-
       host 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  CUR-


       CURL *curl = curl_easy_init();
       if(curl) {
         curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");


       POP3 and SMTP were added in 7.31.0

       Returns  CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insuf-
       ficient 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 attributes(7) for descriptions of the following attributes:

       |Availability   | web/curl         |
       |Stability      | Uncommitted      |
       LOPT_FRESH_CONNECT(3),  curl_easy_perform(3), CURLINFO_REDIRECT_URL(3),

       This    software    was    built    from    source     available     at
       https://github.com/oracle/solaris-userland.    The  original  community
       source   was    downloaded    from     https://github.com/curl/curl/ar-

       Further information about this software can be found on the open source
       community website at http://curl.haxx.se/.

libcurl 7.37.0                    17 Jun 2014                   CURLOPT_URL(3)