jammy (3) curl_url_set.3.gz

Provided by: libcurl4-doc_7.81.0-1ubuntu1.20_all bug

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

       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 null-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. libcurl only accepts setting schemes up to 40 bytes long.

       CURLUPART_USER

       CURLUPART_PASSWORD

       CURLUPART_OPTIONS

       CURLUPART_HOST
              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).

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

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

       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 did not 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 contents.

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

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

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

       CURLU_PATH_AS_IS
              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).

       CURLU_ALLOW_SPACE
              If set, a 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.

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 7.62.0. CURLUPART_ZONEID was added in 7.65.0.

RETURN VALUE

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

       A URL string passed on to curl_url_set(3) for the CURLUPART_URL part, must be shorter than 8000000  bytes
       otherwise it returns CURLUE_MALFORMED_INPUT (added in 7.65.0).

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

SEE ALSO

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