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

FreeBSD Manual Pages

  
 
  

home | help
libcurl(3)		     libcurl url interface		    libcurl(3)

NAME
       libcurl-url - URL interface overview

DESCRIPTION
       The URL interface provides functions for	parsing	and generating URLs.

INCLUDE
       You still only include <curl/curl.h> in your code.

CREATE
       Create a	handle that holds URL info and resources with curl_url(3):

	 CURLU *h = curl_url();

CLEANUP
       When done with it, clean	it up with curl_url_cleanup(3):

	 curl_url_cleanup(h);

DUPLICATE
       When   you   need   a   copy  of	 a  handle,  just  duplicate  it  with
       curl_url_dup(3):

	 CURLU *nh = curl_url_dup(h);

PARSING
       By "setting" a URL to the  handle  with	curl_url_set(3),  the  URL  is
       parsed  and  stored in the handle. If the URL is	not syntactically cor-
       rect it will return an error instead.

	 rc = curl_url_set(h, CURLUPART_URL,
			   "https://example.com:449/foo/bar?name=moo", 0);

       The zero	in the fourth argument is a bitmask for	changing specific fea-
       tures.

       If  successful,	this stores the	URL in its individual parts within the
       handle.

REDIRECT
       When a handle already contains info about a URL,	setting	a relative URL
       will make it "redirect" to adapt	to it.

	 rc = curl_url_set(h, CURLUPART_URL, "../test?another",	0);

GET URL
       The  `CURLU`  handle  represents	 a URL and you can easily extract that
       with curl_url_get(3):

	 char *url;
	 rc = curl_url_get(h, CURLUPART_URL, &url, 0);
	 curl_free(url);

       The zero	in the fourth argument is a bitmask for	changing specific fea-
       tures.

GET PARTS
       When  a	URL  has  been	parsed or parts	have been set, you can extract
       those pieces from the handle at any time.

	 rc = curl_url_get(h, CURLUPART_HOST, &host, 0);
	 rc = curl_url_get(h, CURLUPART_SCHEME,	&scheme, 0);
	 rc = curl_url_get(h, CURLUPART_USER, &user, 0);
	 rc = curl_url_get(h, CURLUPART_PASSWORD, &password, 0);
	 rc = curl_url_get(h, CURLUPART_PORT, &port, 0);
	 rc = curl_url_get(h, CURLUPART_PATH, &path, 0);
	 rc = curl_url_get(h, CURLUPART_QUERY, &query, 0);
	 rc = curl_url_get(h, CURLUPART_FRAGMENT, &fragment, 0);

       Extracted parts are not URL decoded unless the user also	 asks  for  it
       with the	CURLU_URLDECODE	flag set in the	fourth bitmask argument.

       Remember	to free	the returned string with curl_free(3) when you're done
       with it!

SET PARTS
       A user set individual URL parts,	either after having parsed a full  URL
       or instead of parsing such.

	 rc = curl_url_set(urlp, CURLUPART_HOST, "www.example.com", 0);
	 rc = curl_url_set(urlp, CURLUPART_SCHEME, "https", 0);
	 rc = curl_url_set(urlp, CURLUPART_USER, "john", 0);
	 rc = curl_url_set(urlp, CURLUPART_PASSWORD, "doe", 0);
	 rc = curl_url_set(urlp, CURLUPART_PORT, "443",	0);
	 rc = curl_url_set(urlp, CURLUPART_PATH, "/index.html",	0);
	 rc = curl_url_set(urlp, CURLUPART_QUERY, "name=john", 0);
	 rc = curl_url_set(urlp, CURLUPART_FRAGMENT, "anchor", 0);

       Set  parts  are	not  URL  encoded unless the user asks for it with the
       `CURLU_URLENCODE` flag.

APPENDQUERY
       An application can append a string to the right end of the  query  part
       with the	`CURLU_APPENDQUERY` flag to curl_url_set(3).

       Imagine	a handle that holds the	URL `https://example.com/?shoes=2`. An
       application can then add	the string `hat=1`  to	the  query  part  like
       this:

	 rc = curl_url_set(urlp, CURLUPART_QUERY, "hat=1", CURLU_APPENDQUERY);

       It will even notice the lack of an ampersand (`&`) separator so it will
       inject one too, and the handle's	full URL will then equal  `https://ex-
       ample.com/?shoes=2&hat=1`.

       The  appended  string can of course also	get URL	encoded	on add,	and if
       asked to	URL encode, the	encoding process will skip the '='  character.
       For example, append `candy=N&N` to what we already have,	and URL	encode
       it to deal with the ampersand in	the data:

	 rc = curl_url_set(urlp, CURLUPART_QUERY, "candy=N&N",
			   CURLU_APPENDQUERY | CURLU_URLENCODE);

       Now the URL looks like
	 https://example.com/?shoes=2&hat=1&candy=N%26N`

AVALABILITY
       The URL API was introduced in libcurl 7.62.0.

SEE ALSO
       curl_url(3),  curl_url_cleanup(3),  curl_url_get(3),   curl_url_dup(3),
       curl_url_set(3),	CURLOPT_URL(3),

libcurl	7.79.1			 May 05, 2021			    libcurl(3)

NAME | DESCRIPTION | INCLUDE | CREATE | CLEANUP | DUPLICATE | PARSING | REDIRECT | GET URL | GET PARTS | SET PARTS | APPENDQUERY | AVALABILITY | SEE ALSO

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

home | help