Artifactspublic-v0

curl

master
ply4 git calls48 ms291 KiB3 cachedprotocol v2
288 lines9.4 KiBRaw

NAME

curl_url_set - set a URL part

SYNOPSIS

c
#include <curl/curl.h>

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

DESCRIPTION

The url handle to work on, passed in as the first argument, must be a handle previously created by curl_url(3) or curl_url_dup(3).

This function sets or updates individual URL components, or parts, held by the URL object the handle identifies.

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 would use in a URL: URL encoded.

When setting a part in the URL object that was previously already set, it replaces the data that was previously stored for that part with the new content.

The caller does not have to keep content around after a successful call as this function copies the content.

Setting a part to a NULL pointer removes that part's contents from the CURLU handle.

This function has an 8 MB maximum length limit for all provided input strings. In the real world, excessively long fields in URLs cause problems even if this function accepts them.

When setting or updating contents of individual URL parts, curl_url_set(3) 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.

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 is replaced with the components 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. The URL parser only understands and parses the subset of URLS that are "hierarchical" and therefore contain a :// separator - not the ones that are normally specified with only a colon separator.

By default this API only parses 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 for URL schemes it does not recognize.

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

When a full URL is set (parsed), the hostname component is stored URL decoded.

It is considered fine to set a blank URL ("") as a redirect, but not as a normal URL. Therefore, setting a "" URL works fine if the handle already holds a URL, otherwise it triggers an error.

CURLUPART_SCHEME

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

CURLUPART_USER

If only the user part is set and not the password, the URL is represented with a blank password.

CURLUPART_PASSWORD

If only the password part is set and not the user, the URL is represented with a blank user.

CURLUPART_OPTIONS

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.

CURLUPART_HOST

The hostname. If it is International Domain Name (IDN) 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).

Note that if you set an IPv6 address, it gets ruined and causes an error if you also set the CURLU_URLENCODE flag.

Unless CURLU_NO_AUTHORITY is set, a blank hostname is not allowed to set.

A numeric IPv4 address (in dotted decimal or a legacy form such as a single decimal, octal or hexadecimal number) is normalized to dotted decimal, the same way it is when libcurl parses a full URL.

CURLUPART_ZONEID

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

CURLUPART_PORT

The port number cannot be URL encoded on set. The given port number is provided as a string and the decimal number in it must be between 0 and 65535. Anything else returns an error.

CURLUPART_PATH

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

CURLUPART_QUERY

The query part gets 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 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_APPENDQUERY

Can be used when setting the CURLUPART_QUERY component. The provided new part is then 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 is not URL encoded.

CURLU_NON_SUPPORT_SCHEME

If set, allows curl_url_set(3) to set a non-supported scheme. It then of course cannot know if the provided scheme is a valid one or not.

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 following characters are left as-is if present:

! $ & ' ( ) { } [ ] * + , ; = : @

The query part gets space-to-plus converted before the URL conversion is applied.

This URL encoding is charset unaware and converts the input in a byte-by-byte manner.

CURLU_DEFAULT_SCHEME

If set, allows 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, allows the URL to be set without a scheme and it instead "guesses" which scheme that was intended based on the hostname. If the outermost subdomain name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that scheme is used, otherwise it picks HTTP. Conflicts with the CURLU_DEFAULT_SCHEME option which takes precedence if both are set.

If guessing is not allowed and there is no default scheme set, trying to parse a URL without a scheme returns error.

If the scheme ends up set as a result of guessing, i.e. it is not actually present in the parsed URL, it can later be figured out by using the CURLU_NO_GUESS_SCHEME flag when subsequently getting the URL or the scheme with curl_url_get(3).

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.

This option also makes libcurl accept and parse URLs with known schemes even when they have no hostnames. URLs such as https:// and ftp:// otherwise cause parse errors by default.

CURLU_PATH_AS_IS

When set for CURLUPART_URL, this skips the normalization of the path. That is the procedure where libcurl 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, 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 is stored as-is unless CURLU_URLENCODE is also set, which then makes libcurl URL encode the space before stored. This affects how the URL is constructed when curl_url_get(3) is subsequently used to extract the full URL or individual parts. (Added in 7.78.0)

CURLU_DISALLOW_USER

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

%PROTOCOLS%

EXAMPLE

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

%AVAILABILITY%

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.

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.

1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: curl_url_set
5Section: 3
6Source: libcurl
7See-also:
8 - CURLOPT_CURLU (3)
9 - curl_url (3)
10 - curl_url_cleanup (3)
11 - curl_url_dup (3)
12 - curl_url_get (3)
13 - curl_url_strerror (3)
14Protocol:
15 - All
16Added-in: 7.62.0
17---
19# NAME
21curl_url_set - set a URL part
23# SYNOPSIS
25~~~c
26#include <curl/curl.h>
28CURLUcode curl_url_set(CURLU *url,
29 CURLUPart part,
30 const char *content,
31 unsigned int flags);
32~~~
34# DESCRIPTION
36The *url* handle to work on, passed in as the first argument, must be a
37handle previously created by curl_url(3) or curl_url_dup(3).
39This function sets or updates individual URL components, or parts, held by the
40URL object the handle identifies.
42The *part* argument should identify the particular URL part (see list below)
43to set or change, with *content* pointing to a null-terminated string with the
44new contents for that URL part. The contents should be in the form and
45encoding they would use in a URL: URL encoded.
47When setting a part in the URL object that was previously already set, it
48replaces the data that was previously stored for that part with the new
49*content*.
51The caller does not have to keep *content* around after a successful call
52as this function copies the content.
54Setting a part to a NULL pointer removes that part's contents from the *CURLU*
55handle.
57This function has an 8 MB maximum length limit for all provided input strings.
58In the real world, excessively long fields in URLs cause problems even if this
59function accepts them.
61When setting or updating contents of individual URL parts, curl_url_set(3)
62might accept data that would not be otherwise possible to set in the string
63when it gets populated as a result of a full URL parse. Beware. If done so,
64extracting a full URL later on from such components might render an invalid
65URL.
67The *flags* argument is a bitmask with independent features.
69# PARTS
71## CURLUPART_URL
73Allows the full URL of the handle to be replaced. If the handle already is
74populated with a URL, the new URL can be relative to the previous.
76When successfully setting a new URL, relative or absolute, the handle contents
77is replaced with the components of the newly set URL.
79Pass a pointer to a null-terminated string to the *url* parameter. The string
80must point to a correctly formatted "RFC 3986+" URL or be a NULL pointer. The
81URL parser only understands and parses the subset of URLS that are
82"hierarchical" and therefore contain a `://` separator - not the ones that are
83normally specified with only a colon separator.
85By default this API only parses URLs using schemes for protocols that are
86supported built-in. To make libcurl parse URLs generically even for schemes it
87does not know about, the **CURLU_NON_SUPPORT_SCHEME** flags bit must be set.
88Otherwise, this function returns *CURLUE_UNSUPPORTED_SCHEME* for URL schemes
89it does not recognize.
91Unless *CURLU_NO_AUTHORITY* is set, a blank hostname is not allowed in
92the URL.
94When a full URL is set (parsed), the hostname component is stored URL decoded.
96It is considered fine to set a blank URL ("") as a redirect, but not as a
97normal URL. Therefore, setting a "" URL works fine if the handle already holds
98a URL, otherwise it triggers an error.
100## CURLUPART_SCHEME
102Scheme cannot be URL decoded on set. libcurl only accepts setting schemes up
103to 40 bytes long.
105## CURLUPART_USER
107If only the user part is set and not the password, the URL is represented with
108a blank password.
110## CURLUPART_PASSWORD
112If only the password part is set and not the user, the URL is represented with
113a blank user.
115## CURLUPART_OPTIONS
117The options field is an optional field that might follow the password in the
118userinfo part. It is only recognized/used when parsing URLs for the following
119schemes: pop3, smtp and imap. This function however allows users to
120independently set this field.
122## CURLUPART_HOST
124The hostname. If it is International Domain Name (IDN) the string must then be
125encoded as your locale says or UTF-8 (when WinIDN is used). If it is a
126bracketed IPv6 numeric address it may contain a zone id (or you can use
127*CURLUPART_ZONEID*).
129Note that if you set an IPv6 address, it gets ruined and causes an error if
130you also set the CURLU_URLENCODE flag.
132Unless *CURLU_NO_AUTHORITY* is set, a blank hostname is not allowed to set.
134A numeric IPv4 address (in dotted decimal or a legacy form such as a single
135decimal, octal or hexadecimal number) is normalized to dotted decimal, the
136same way it is when libcurl parses a full URL.
138## CURLUPART_ZONEID
140If the hostname is a numeric IPv6 address, this field can also be set.
142## CURLUPART_PORT
144The port number cannot be URL encoded on set. The given port number is
145provided as a string and the decimal number in it must be between 0 and
14665535. Anything else returns an error.
148## CURLUPART_PATH
150If a path is set in the URL without a leading slash, a slash is prepended
151automatically.
153## CURLUPART_QUERY
155The query part gets spaces converted to pluses when asked to URL encode on set
156with the *CURLU_URLENCODE* bit.
158If used together with the *CURLU_APPENDQUERY* bit, the provided part is
159appended on the end of the existing query.
161The question mark in the URL is not part of the actual query contents.
163## CURLUPART_FRAGMENT
165The hash sign in the URL is not part of the actual fragment contents.
167# FLAGS
169The flags argument is zero, one or more bits set in a bitmask.
171## CURLU_APPENDQUERY
173Can be used when setting the *CURLUPART_QUERY* component. The provided new
174part is then appended at the end of the existing query - and if the previous
175part did not end with an ampersand (&), an ampersand gets inserted before the
176new appended part.
178When *CURLU_APPENDQUERY* is used together with *CURLU_URLENCODE*, the
179first '=' symbol is not URL encoded.
181## CURLU_NON_SUPPORT_SCHEME
183If set, allows curl_url_set(3) to set a non-supported scheme. It then of
184course cannot know if the provided scheme is a valid one or not.
186## CURLU_URLENCODE
188When set, curl_url_set(3) URL encodes the part on entry, except for
189**scheme**, **port** and **URL**.
191When setting the path component with URL encoding enabled, the following
192characters are left as-is if present:
194 ! $ & ' ( ) { } [ ] * + , ; = : @
196The query part gets space-to-plus converted before the URL conversion is
197applied.
199This URL encoding is charset unaware and converts the input in a byte-by-byte
200manner.
202## CURLU_DEFAULT_SCHEME
204If set, allows the URL to be set without a scheme and then sets that to the
205default scheme: HTTPS. Overrides the *CURLU_GUESS_SCHEME* option if both are
206set.
208## CURLU_GUESS_SCHEME
210If set, allows the URL to be set without a scheme and it instead "guesses"
211which scheme that was intended based on the hostname. If the outermost
212subdomain name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that scheme is
213used, otherwise it picks HTTP. Conflicts with the *CURLU_DEFAULT_SCHEME*
214option which takes precedence if both are set.
216If guessing is not allowed and there is no default scheme set, trying to parse
217a URL without a scheme returns error.
219If the scheme ends up set as a result of guessing, i.e. it is not actually
220present in the parsed URL, it can later be figured out by using the
221**CURLU_NO_GUESS_SCHEME** flag when subsequently getting the URL or the scheme
222with curl_url_get(3).
224## CURLU_NO_AUTHORITY
226If set, skips authority checks. The RFC allows individual schemes to omit the
227host part (normally the only mandatory part of the authority), but libcurl
228cannot know whether this is permitted for custom schemes. Specifying the flag
229permits empty authority sections, similar to how file scheme is handled.
231This option also makes libcurl accept and parse URLs with known schemes even
232when they have no hostnames. URLs such as `https://` and `ftp://` otherwise
233cause parse errors by default.
235## CURLU_PATH_AS_IS
237When set for **CURLUPART_URL**, this skips the normalization of the
238path. That is the procedure where libcurl otherwise removes sequences of
239dot-slash and dot-dot etc. The same option used for transfers is called
240CURLOPT_PATH_AS_IS(3).
242## CURLU_ALLOW_SPACE
244If set, the URL parser allows space (ASCII 32) where possible. The URL syntax
245does normally not allow spaces anywhere, but they should be encoded as %20
246or '+'. When spaces are allowed, they are still not allowed in the scheme.
247When space is used and allowed in a URL, it is stored as-is unless
248*CURLU_URLENCODE* is also set, which then makes libcurl URL encode the
249space before stored. This affects how the URL is constructed when
250curl_url_get(3) is subsequently used to extract the full URL or
251individual parts. (Added in 7.78.0)
253## CURLU_DISALLOW_USER
255If set, the URL parser does not accept embedded credentials for the
256**CURLUPART_URL**, and instead returns **CURLUE_USER_NOT_ALLOWED** for
257such URLs.
259# %PROTOCOLS%
261# EXAMPLE
263~~~c
264int main(void)
266 CURLUcode rc;
267 CURLU *url = curl_url();
268 rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
269 if(!rc) {
270 /* change it to an FTP URL */
271 rc = curl_url_set(url, CURLUPART_SCHEME, "ftp", 0);
272 }
273 curl_url_cleanup(url);
275~~~
277# %AVAILABILITY%
279# RETURN VALUE
281Returns a *CURLUcode* error value, which is CURLUE_OK (0) if everything
282went fine. See the libcurl-errors(3) man page for the full list with
283descriptions.
285The input string passed to curl_url_set(3) must be shorter than eight
286million bytes. Otherwise this function returns **CURLUE_MALFORMED_INPUT**.
288If this function returns an error, no URL part is set.
Diagnostics4 git calls · 48 ms
CallStatusSizeTime048 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200149 B · hit2 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
git.response.bytes=149
git.response.cache=HIT
git.response.duration_ms=2
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=149
git.pkt.payload.max=78
git.ls_refs.count=2
git.ls_refs.head=refs/heads/master
fetchblob:none · deepen 10200287 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=43
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=31c911efe5652725e930f4d2e60c9060e5f6646d
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=10
git.pkt.data=8
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=293470
git.pkt.payload.max=65516
git.sideband.band1.bytes=293354
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=87
git.pack.bytes=293354
git.pack.ofs_delta=0
git.pack.ref_delta=1
git.pack.chain.max=1
git.pack.trailer=6a646bcda6740bab42e321b51998b52ea15146c0
git.pack.full=86
Open pack map
fetch2004.1 KiB · hit43 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=4230
git.response.cache=HIT
git.response.duration_ms=43
git.fetch.wants=b2f818cf063ee035122649c133cdd0c2b830bb2b
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=4230
git.pkt.payload.max=4209
git.sideband.band1.bytes=4208
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/curl.git
Ref
refs/heads/master
Commit
31c911efe5652725e930f4d2e60c9060e5f6646d
cf-ray
a5e32fd6ca958821
Request
084a2eba…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format