Go to main content

man pages section 3: Library Interfaces and Headers

Exit Print View

Updated: Thursday, June 13, 2019
 
 

curl_url_set (3)

Name

curl_url_set - set a URL part

Synopsis

#include <curl/curl.h>

CURLUcode curl_url_set(CURLU *url,
CURLUPart part,
const char *content,
unsigned int flags)

Description

curl_url_set(3)                 libcurl Manual                 curl_url_set(3)



NAME
       curl_url_set - set a URL part

SYNOPSIS
       #include <curl/curl.h>

       CURLUcode curl_url_set(CURLU *url,
                              CURLUPart part,
                              const char *content,
                              unsigned int flags)

DESCRIPTION
       Given  the  url handle of an already parsed URL, this function lets the
       user set/update individual pieces of it.

       The part argument should identify the particular  URL  part  (see  list
       below)  to  set  or  change, with content pointing to a zero terminated
       string with the new contents for that URL part. The contents should  be
       in the form and encoding they'd use in a URL: URL encoded.

       Setting  a  part  to a NULL pointer will effectively remove that part's
       contents from the CURLU handle.

       The flags argument is a bitmask with independent features.

PARTS
       CURLUPART_URL
              Allows the full URL of the handle to be replaced. If the  handle
              already  is populated with a URL, the new URL can be relative to
              the previous.

              When successfully setting a new URL, relative or  absolute,  the
              handle  contents  will  be  replaced with the information of the
              newly set URL.

              Pass a pointer to a zero terminated string to the url parameter.
              The  string  must point to a correctly formatted "RFC 3986+" URL
              or be a NULL pointer.

       CURLUPART_SCHEME
              Scheme cannot be URL decoded on set.

       CURLUPART_USER

       CURLUPART_PASSWORD

       CURLUPART_OPTIONS

       CURLUPART_HOST
              The host name can use IDNA. The string must then be  encoded  as
              your locale says or UTF-8 (when winidn is used).

       CURLUPART_PORT
              Port cannot be URL encoded on set.

       CURLUPART_PATH
              If  a  path  is  set in the URL without a leading slash, a slash
              will be inserted automatically when this URL is  read  from  the
              handle.

       CURLUPART_QUERY
              The  query  part  will  also get spaces converted to pluses when
              asked to URL encode on set with the CURLU_URLENCODE bit.

              If used together with the CURLU_APPENDQUERY  bit,  the  provided
              part  will be appended on the end of the existing query - and if
              the previous part didn't end with an ampersand (&), an ampersand
              will be inserted before the new appended part.

              When  CURLU_APPENDQUERY  is  used together with CURLU_URLENCODE,
              the first '=' symbol will not be URL encoded.

              The question mark in the URL is not part  of  the  actual  query
              contents.

       CURLUPART_FRAGMENT
              The hash sign in the URL is not part of the actual fragment con-
              tents.

FLAGS
       The flags argument is zero, one or more bits set in a bitmask.

       CURLU_NON_SUPPORT_SCHEME
              If set, allows curl_url_set(3) to set a non-supported scheme.

       CURLU_URLENCODE
              When set, curl_url_set(3) URL encodes the part on entry,  except
              for scheme, port and URL.

              When  setting  the path component with URL encoding enabled, the
              slash character will be skipped.

              The query part gets space-to-plus conversion before the URL con-
              version.

              This  URL encoding is charset unaware and will convert the input
              on a byte-by-byte manner.

       CURLU_DEFAULT_SCHEME
              If set, will make libcurl allow the URL  to  be  set  without  a
              scheme  and  then  sets that to the default scheme: HTTPS. Over-
              rides the CURLU_GUESS_SCHEME option if both are set.

       CURLU_GUESS_SCHEME
              If set, will make libcurl allow the URL  to  be  set  without  a
              scheme  and  it instead "guesses" which scheme that was intended
              based on the  host  name.   If  the  outermost  sub-domain  name
              matches  DICT,  FTP,  IMAP,  LDAP, POP3 or SMTP then that scheme
              will be used,  otherwise  it  picks  HTTP.  Conflicts  with  the
              CURLU_DEFAULT_SCHEME  option  which takes precedence if both are
              set.

RETURN VALUE
       Returns a CURLUcode error value, which is CURLUE_OK (0)  if  everything
       went fine.

       If this function returns an error, no URL part is returned.

EXAMPLE
         CURLUcode rc;
         CURLU *url = curl_url();
         rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
         if(!rc) {
           char *scheme;
           /* change it to an FTP URL */
           rc = curl_url_set(url, CURLUPART_SCHEME, "ftp", 0);
         }
         curl_url_cleanup(url);

AVAILABILITY
       Added in curl 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_cleanup(3), curl_url(3), curl_url_get(3), curl_url_dup(3),



NOTES
       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-
       chive/curl-7_64_0.zip

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



libcurl                           6 Aug 2018                   curl_url_set(3)