manpagez: man pages & more
man curl_url_set(3)
Home | html | info | man
curl_url_set(3)                     libcurl                    curl_url_set(3)


       curl_url_set - set a URL part


       #include <curl/curl.h>

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


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

       The application does not have to keep content around after a successful

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

       By default, this API only accepts URLs using schemes for protocols that
       are supported built-in. To make libcurl parse URLs generically even for
       schemes it does not know about, the CURLU_NON_SUPPORT_SCHEME flags bit
       must be set. Otherwise, this function returns CURLUE_UNSUPPORTED_SCHEME
       on URL schemes it does not recognize.

       This function call has no particular maximum length for any provided
       input string. In the real world, excessively long field in URLs will
       cause problems even if this API accepts them.

       When setting or updating contents of individual URL parts, this API
       might accept data that would not be otherwise possible to set in the
       string when it gets populated as a result of a full URL parse. Beware.
       If done so, extracting a full URL later on from such components might
       render an invalid URL.

       The flags argument is a bitmask with independent features.


              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 null-terminated string to the url parameter.
              The string must point to a correctly formatted "RFC 3986+" URL
              or be a NULL pointer.

              Unless CURLU_NO_AUTHORITY is set, a blank host name is not
              allowed in the URL.

              Scheme cannot be URL decoded on set. libcurl only accepts
              setting schemes up to 40 bytes long.



              The options field is an optional field that might follow the
              password in the userinfo part. It is only recognized/used when
              parsing URLs for the following schemes: pop3, smtp and imap.
              This function however allows users to independently set this
              field at will.

              The host name. If it is IDNA the string must then be encoded as
              your locale says or UTF-8 (when WinIDN is used). If it is a
              bracketed IPv6 numeric address it may contain a zone id (or you
              can use CURLUPART_ZONEID).

              Unless CURLU_NO_AUTHORITY is set, a blank host name is not
              allowed to set.

              If the host name is a numeric IPv6 address, this field can also
              be set.

              Port cannot be URL encoded on set. The given port number is
              provided as a string and the decimal number must be between 1
              and 65535. Anything else will return an error.

              If a path is set in the URL without a leading slash, a slash
              will be prepended automatically.

              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 is appended on the end of the existing query.

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

              The hash sign in the URL is not part of the actual fragment


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

              Can be used when setting the CURLUPART_QUERY component. The
              provided new part will then instead be appended at the end of
              the existing query - and if the previous part did not end with
              an ampersand (&), an ampersand gets inserted before the new
              appended part.

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

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

              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

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

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

              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

              If set, skips authority checks. The RFC allows individual
              schemes to omit the host part (normally the only mandatory part
              of the authority), but libcurl cannot know whether this is
              permitted for custom schemes. Specifying the flag permits empty
              authority sections, similar to how file scheme is handled.

              When set for CURLUPART_URL, this makes libcurl skip the
              normalization of the path. That is the procedure where curl
              otherwise removes sequences of dot-slash and dot-dot etc. The
              same option used for transfers is called CURLOPT_PATH_AS_IS(3).

              If set, the URL parser allows space (ASCII 32) where possible.
              The URL syntax does normally not allow spaces anywhere, but they
              should be encoded as %20 or '+'. When spaces are allowed, they
              are still not allowed in the scheme.  When space is used and
              allowed in a URL, it will be stored as-is unless CURLU_URLENCODE
              is also set, which then makes libcurl URL-encode the space
              before stored. This affects how the URL will be constructed when
              curl_url_get(3) is subsequently used to extract the full URL or
              individual parts. (Added in 7.78.0)

              If set, the URL parser will not accept embedded credentials for
              the CURLUPART_URL, and will instead return
              CURLUE_USER_NOT_ALLOWED for such URLs.


         CURLUcode rc;
         CURLU *url = curl_url();
         rc = curl_url_set(url, CURLUPART_URL, "", 0);
         if(!rc) {
           char *scheme;
           /* change it to an FTP URL */
           rc = curl_url_set(url, CURLUPART_SCHEME, "ftp", 0);


       Added in 7.62.0. CURLUPART_ZONEID was added in 7.65.0.


       Returns a CURLUcode error value, which is CURLUE_OK (0) if everything
       went fine. See the libcurl-errors(3) man page for the full list with

       The input string passed to curl_url_set(3) must be shorter than eight
       million bytes. Otherwise this function returns CURLUE_MALFORMED_INPUT.

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


       curl_url_cleanup(3), curl_url(3), curl_url_get(3),  curl_url_dup(3),
       curl_url_strerror(3), CURLOPT_CURLU(3)

libcurl 8.2.1                    June 8, 2023                  curl_url_set(3)

curl 8.2.1 - Generated Wed Aug 16 18:27:55 CDT 2023
© 2000-2023
Individual documents may contain additional copyright information.