Go to main content

man pages section 3: Library Interfaces and Headers

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

libcurl-url (3)

Name

libcurl-url - URL interface overview

Synopsis

Please see following description for synopsis

Description

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


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+------------------+
       |ATTRIBUTE TYPE | ATTRIBUTE VALUE  |
       +---------------+------------------+
       |Availability   | web/curl         |
       +---------------+------------------+
       |Stability      | Uncommitted      |
       +---------------+------------------+

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



NOTES
       Source  code  for open source software components in Oracle Solaris can
       be found at https://www.oracle.com/downloads/opensource/solaris-source-
       code-downloads.html.

       This     software     was    built    from    source    available    at
       https://github.com/oracle/solaris-userland.   The  original   community
       source       was       downloaded      from       https://curl.se/down-
       load/curl-7.83.1.tar.bz2.

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



libcurl 7.83.1                  March 29, 2022                      libcurl(3)