Artifactspublic-v0

curl

master
ply4 git calls27 ms289 KiB3 cachedprotocol v2
163 lines4.3 KiBRaw

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):

c
  CURLU *h = curl_url();

CLEANUP

When done with it, clean it up with curl_url_cleanup(3)

c
  curl_url_cleanup(h);

DUPLICATE

When you need a copy of a handle, duplicate it with curl_url_dup(3):

c
  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 correct it returns an error instead.

c
  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 features.

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 makes it "redirect" to that.

c
  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):

c
  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 features.

GET PARTS

When a URL has been parsed or parts have been set, you can extract those pieces from the handle at any time.

c
  rc = curl_url_get(h, CURLUPART_FRAGMENT, &fragment, 0);
  rc = curl_url_get(h, CURLUPART_HOST, &host, 0);
  rc = curl_url_get(h, CURLUPART_PASSWORD, &password, 0);
  rc = curl_url_get(h, CURLUPART_PATH, &path, 0);
  rc = curl_url_get(h, CURLUPART_PORT, &port, 0);
  rc = curl_url_get(h, CURLUPART_QUERY, &query, 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_ZONEID, &zoneid, 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 can set individual URL parts, either after having parsed a full URL or instead of parsing one.

c
  rc = curl_url_set(urlp, CURLUPART_FRAGMENT, "anchor", 0);
  rc = curl_url_set(urlp, CURLUPART_HOST, "www.example.com", 0);
  rc = curl_url_set(urlp, CURLUPART_PASSWORD, "doe", 0);
  rc = curl_url_set(urlp, CURLUPART_PATH, "/index.html", 0);
  rc = curl_url_set(urlp, CURLUPART_PORT, "443", 0);
  rc = curl_url_set(urlp, CURLUPART_QUERY, "name=john", 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_ZONEID, "eth0", 0);

Set parts are not URL encoded unless the user asks for it with the CURLU_URLENCODE flag.

CURLU_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:

c
  rc = curl_url_set(urlp, CURLUPART_QUERY, "hat=1", CURLU_APPENDQUERY);

It notices the lack of an ampersand (&) separator and injects one, and the handle's full URL then equals "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 skips 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:

c
  rc = curl_url_set(urlp, CURLUPART_QUERY, "candy=N&N",
                    CURLU_APPENDQUERY | CURLU_URLENCODE);

Now the URL looks like

c
  https://example.com/?shoes=2&hat=1&candy=N%26N

NOTES

A URL with a literal IPv6 address can be parsed even when IPv6 support is not enabled.

1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: libcurl-url
5Section: 3
6Source: libcurl
7See-also:
8 - CURLOPT_URL (3)
9 - curl_url (3)
10 - curl_url_cleanup (3)
11 - curl_url_dup (3)
12 - curl_url_get (3)
13 - curl_url_set (3)
14 - curl_url_strerror (3)
15Protocol:
16 - All
17Added-in: 7.62.0
18---
20# NAME
22libcurl-url - URL interface overview
24# DESCRIPTION
26The URL interface provides functions for parsing and generating URLs.
28# INCLUDE
30You still only include \<curl/curl.h\> in your code.
32# CREATE
34Create a handle that holds URL info and resources with curl_url(3):
35~~~c
36 CURLU *h = curl_url();
37~~~
39# CLEANUP
41When done with it, clean it up with curl_url_cleanup(3)
42~~~c
43 curl_url_cleanup(h);
44~~~
46# DUPLICATE
48When you need a copy of a handle, duplicate it with curl_url_dup(3):
49~~~c
50 CURLU *nh = curl_url_dup(h);
51~~~
53# PARSING
55By setting a URL to the handle with curl_url_set(3), the URL is parsed
56and stored in the handle. If the URL is not syntactically correct it returns
57an error instead.
58~~~c
59 rc = curl_url_set(h, CURLUPART_URL,
60 "https://example.com:449/foo/bar?name=moo", 0);
61~~~
63The zero in the fourth argument is a bitmask for changing specific features.
65If successful, this stores the URL in its individual parts within the handle.
67# REDIRECT
69When a handle already contains info about a URL, setting a relative URL makes
70it "redirect" to that.
71~~~c
72 rc = curl_url_set(h, CURLUPART_URL, "../test?another", 0);
73~~~
75# GET URL
77The **CURLU** handle represents a URL and you can easily extract that with
78curl_url_get(3):
79~~~c
80 char *url;
81 rc = curl_url_get(h, CURLUPART_URL, &url, 0);
82 curl_free(url);
83~~~
84The zero in the fourth argument is a bitmask for changing specific features.
86# GET PARTS
88When a URL has been parsed or parts have been set, you can extract those
89pieces from the handle at any time.
91~~~c
92 rc = curl_url_get(h, CURLUPART_FRAGMENT, &fragment, 0);
93 rc = curl_url_get(h, CURLUPART_HOST, &host, 0);
94 rc = curl_url_get(h, CURLUPART_PASSWORD, &password, 0);
95 rc = curl_url_get(h, CURLUPART_PATH, &path, 0);
96 rc = curl_url_get(h, CURLUPART_PORT, &port, 0);
97 rc = curl_url_get(h, CURLUPART_QUERY, &query, 0);
98 rc = curl_url_get(h, CURLUPART_SCHEME, &scheme, 0);
99 rc = curl_url_get(h, CURLUPART_USER, &user, 0);
100 rc = curl_url_get(h, CURLUPART_ZONEID, &zoneid, 0);
101~~~
103Extracted parts are not URL decoded unless the user also asks for it with the
104*CURLU_URLDECODE* flag set in the fourth bitmask argument.
106Remember to free the returned string with curl_free(3) when you are done
107with it.
109# SET PARTS
111A user can set individual URL parts, either after having parsed a full URL or
112instead of parsing one.
114~~~c
115 rc = curl_url_set(urlp, CURLUPART_FRAGMENT, "anchor", 0);
116 rc = curl_url_set(urlp, CURLUPART_HOST, "www.example.com", 0);
117 rc = curl_url_set(urlp, CURLUPART_PASSWORD, "doe", 0);
118 rc = curl_url_set(urlp, CURLUPART_PATH, "/index.html", 0);
119 rc = curl_url_set(urlp, CURLUPART_PORT, "443", 0);
120 rc = curl_url_set(urlp, CURLUPART_QUERY, "name=john", 0);
121 rc = curl_url_set(urlp, CURLUPART_SCHEME, "https", 0);
122 rc = curl_url_set(urlp, CURLUPART_USER, "john", 0);
123 rc = curl_url_set(urlp, CURLUPART_ZONEID, "eth0", 0);
124~~~
126Set parts are not URL encoded unless the user asks for it with the
127*CURLU_URLENCODE* flag.
129# CURLU_APPENDQUERY
131An application can append a string to the right end of the query part with the
132*CURLU_APPENDQUERY* flag to curl_url_set(3).
134Imagine a handle that holds the URL "https://example.com/?shoes=2". An
135application can then add the string "hat=1" to the query part like this:
137~~~c
138 rc = curl_url_set(urlp, CURLUPART_QUERY, "hat=1", CURLU_APPENDQUERY);
139~~~
141It notices the lack of an ampersand (&) separator and injects one, and the
142handle's full URL then equals "https://example.com/?shoes=2&hat=1".
144The appended string can of course also get URL encoded on add, and if asked to
145URL encode, the encoding process skips the '=' character. For example, append
146"candy=N&N" to what we already have, and URL encode it to deal with the
147ampersand in the data:
149~~~c
150 rc = curl_url_set(urlp, CURLUPART_QUERY, "candy=N&N",
151 CURLU_APPENDQUERY | CURLU_URLENCODE);
152~~~
154Now the URL looks like
156~~~c
157 https://example.com/?shoes=2&hat=1&candy=N%26N
158~~~
160# NOTES
162A URL with a literal IPv6 address can be parsed even when IPv6 support is not
163enabled.
Diagnostics4 git calls · 27 ms
CallStatusSizeTime027 ms
discover200152 B4 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=1
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 · hit3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=149
git.response.cache=HIT
git.response.duration_ms=3
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=21
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
fetch2001.8 KiB · hit21 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=1800
git.response.cache=HIT
git.response.duration_ms=21
git.fetch.wants=bc936fcb4d0a38b967ed4d07aa3343847f82eeac
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=1800
git.pkt.payload.max=1779
git.sideband.band1.bytes=1778
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
a5e3617649a7b86e
Request
5a0dc9c8…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format