Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CURLOPT_URL(3)		   curl_easy_setopt options		CURLOPT_URL(3)

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_se-
       topt(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_UN-
       SUPPORTED_PROTOCOL will be  returned  from  either  the	curl_easy_per-
       form(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.

       CURLOPT_URL(3) is the only option that 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 sup-
       ported 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  de-
       fault  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 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 di-
	      rectory specified	or the root directory. The exact resource  re-
	      turned  for  each	URL is entirely	dependent on the server's con-
	      figuration.

	      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	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 re-
	      trieve 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 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-
	      drinfo.

	      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 re-
	      trieve. 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 1

	      imap://user:password@mail.example.com/INBOX;UIDVALID-
	      ITY=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  mes-
	      sage 3

	      imap://user:password@mail.example.com/INBOX/;UID=4/;PAR-
	      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
	      /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	speci-
	      fied.  If	the path ends in a / then a directory listing  is  re-
	      turned  instead of a file.  If the path is omitted entirely then
	      the directory listing for	the root / home	directory will be  re-
	      turned.	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	direc-
	      tory

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

	      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.

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	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-
       LOPT_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	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 ALSO
       CURLOPT_VERBOSE(3), CURLOPT_PROTOCOLS(3), CURLOPT_FORBID_REUSE(3), CUR-
       LOPT_FRESH_CONNECT(3),  curl_easy_perform(3), CURLINFO_REDIRECT_URL(3),
       CURLOPT_PATH_AS_IS(3),

libcurl	7.54.1		       December	21, 2016		CURLOPT_URL(3)

NAME | SYNOPSIS | DESCRIPTION | DEFAULT | SECURITY CONCERNS | PROTOCOLS | EXAMPLE | AVAILABILITY | RETURN VALUE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=CURLOPT_URL&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help