Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/thirdparty/curl/docs/libcurl/libcurl-url.3 @ 2:b50eed0cc0ef upstream

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. The directory name has changed: no version number in the expanded directory now.
author Franz Glasner <fzglas.hg@dom66.de>
date Mon, 15 Sep 2025 11:43:07 +0200
parents
children
comparison
equal deleted inserted replaced
1:1d09e1dec1d9 2:b50eed0cc0ef
1 .\" **************************************************************************
2 .\" * _ _ ____ _
3 .\" * Project ___| | | | _ \| |
4 .\" * / __| | | | |_) | |
5 .\" * | (__| |_| | _ <| |___
6 .\" * \___|\___/|_| \_\_____|
7 .\" *
8 .\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al.
9 .\" *
10 .\" * This software is licensed as described in the file COPYING, which
11 .\" * you should have received as part of this distribution. The terms
12 .\" * are also available at https://curl.haxx.se/docs/copyright.html.
13 .\" *
14 .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
15 .\" * copies of the Software, and permit persons to whom the Software is
16 .\" * furnished to do so, under the terms of the COPYING file.
17 .\" *
18 .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
19 .\" * KIND, either express or implied.
20 .\" *
21 .\" **************************************************************************
22 .TH libcurl 3 "10 Sep 2018" "libcurl" "libcurl url interface"
23 .SH NAME
24 libcurl-url \- URL interface overview
25 .SH DESCRIPTION
26 The URL interface provides a set of functions for parsing and generating URLs.
27 .SH INCLUDE
28 You still only include <curl/curl.h> in your code. Note that the URL API was
29 introduced in 7.62.0.
30 .SH CREATE
31 Create a handle that holds URL info and resources with \fIcurl_url(3)\fP:
32
33 CURLU *h = curl_url();
34 .SH CLEANUP
35 When done with it, clean it up with \fIcurl_url_cleanup(3)\fP:
36
37 curl_url_cleanup(h);
38 .SH DUPLICATE
39 When you need a copy of a handle, just duplicate it with \fIcurl_url_dup(3)\fP:
40
41 CURLU *nh = curl_url_dup(h);
42 .SH PARSING
43 By "setting" a URL to the handle with \fIcurl_url_set(3)\fP, the URL is parsed
44 and stored in the handle. If the URL is not syntactically correct it will
45 return an error instead.
46
47 .nf
48 rc = curl_url_set(h, CURLUPART_URL,
49 "https://example.com:449/foo/bar?name=moo", 0);
50 .fi
51
52 The zero in the fourth argument is a bitmask for changing specific features.
53
54 If successful, this stores the URL in its individual parts within the handle.
55 .SH REDIRECT
56 When a handle already contains info about a URL, setting a relative URL will
57 make it "redirect" to adapt to it.
58
59 rc = curl_url_set(h, CURLUPART_URL, "../test?another", 0);
60 .SH "GET URL"
61 The `CURLU` handle represents a URL and you can easily extract that with
62 \fIcurl_url_get(3)\fP:
63
64 char *url;
65 rc = curl_url_get(h, CURLUPART_URL, &url, 0);
66 curl_free(url);
67
68 The zero in the fourth argument is a bitmask for changing specific features.
69 .SH "GET PARTS"
70 When a URL has been parsed or parts have been set, you can extract those
71 pieces from the handle at any time.
72
73 .nf
74 rc = curl_url_get(h, CURLUPART_HOST, &host, 0);
75 rc = curl_url_get(h, CURLUPART_SCHEME, &scheme, 0);
76 rc = curl_url_get(h, CURLUPART_USER, &user, 0);
77 rc = curl_url_get(h, CURLUPART_PASSWORD, &password, 0);
78 rc = curl_url_get(h, CURLUPART_PORT, &port, 0);
79 rc = curl_url_get(h, CURLUPART_PATH, &path, 0);
80 rc = curl_url_get(h, CURLUPART_QUERY, &query, 0);
81 rc = curl_url_get(h, CURLUPART_FRAGMENT, &fragment, 0);
82 .fi
83
84 Extracted parts are not URL decoded unless the user also asks for it with the
85 CURLU_URLDECODE flag set in the fourth bitmask argument.
86
87 Remember to free the returned string with \fIcurl_free(3)\fP when you're done
88 with it!
89 .SH "SET PARTS"
90 A user set individual URL parts, either after having parsed a full URL or
91 instead of parsing such.
92
93 .nf
94 rc = curl_url_set(urlp, CURLUPART_HOST, "www.example.com", 0);
95 rc = curl_url_set(urlp, CURLUPART_SCHEME, "https", 0);
96 rc = curl_url_set(urlp, CURLUPART_USER, "john", 0);
97 rc = curl_url_set(urlp, CURLUPART_PASSWORD, "doe", 0);
98 rc = curl_url_set(urlp, CURLUPART_PORT, "443", 0);
99 rc = curl_url_set(urlp, CURLUPART_PATH, "/index.html", 0);
100 rc = curl_url_set(urlp, CURLUPART_QUERY, "name=john", 0);
101 rc = curl_url_set(urlp, CURLUPART_FRAGMENT, "anchor", 0);
102 .fi
103
104 Set parts are not URL encoded unless the user asks for it with the
105 `CURLU_URLENCODE` flag.
106 .SH "APPENDQUERY"
107 An application can append a string to the right end of the query part with the
108 `CURLU_APPENDQUERY` flag to \fIcurl_url_set(3)\fP.
109
110 Imagine a handle that holds the URL `https://example.com/?shoes=2`. An
111 application can then add the string `hat=1` to the query part like this:
112
113 .nf
114 rc = curl_url_set(urlp, CURLUPART_QUERY, "hat=1", CURLU_APPENDQUERY);
115 .fi
116
117 It will even notice the lack of an ampersand (`&`) separator so it will inject
118 one too, and the handle's full URL will then equal
119 `https://example.com/?shoes=2&hat=1`.
120
121 The appended string can of course also get URL encoded on add, and if asked to
122 URL encode, the encoding process will skip the '=' character. For example,
123 append `candy=N&N` to what we already have, and URL encode it to deal with the
124 ampersand in the data:
125
126 .nf
127 rc = curl_url_set(urlp, CURLUPART_QUERY, "candy=N&N",
128 CURLU_APPENDQUERY | CURLU_URLENCODE);
129 .fi
130
131 Now the URL looks like
132 .nf
133 https://example.com/?shoes=2&hat=1&candy=N%26N`
134 .fi
135 .SH "SEE ALSO"
136 .BR curl_url "(3), " curl_url_cleanup "(3), " curl_url_get "(3), "
137 .BR curl_url_dup "(3), " curl_url_set "(3), " CURLOPT_URL "(3), "