Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/thirdparty/curl/docs/libcurl/curl_url_set.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 - 2019, 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 curl_url_set 3 "6 Aug 2018" "libcurl" "libcurl Manual"
23 .SH NAME
24 curl_url_set - set a URL part
25 .SH SYNOPSIS
26 .B #include <curl/curl.h>
27
28 CURLUcode curl_url_set(CURLU *url,
29 CURLUPart part,
30 const char *content,
31 unsigned int flags)
32 .fi
33 .SH DESCRIPTION
34 Given the \fIurl\fP handle of an already parsed URL, this function lets the
35 user set/update individual pieces of it.
36
37 The \fIpart\fP argument should identify the particular URL part (see list
38 below) to set or change, with \fIcontent\fP pointing to a zero terminated
39 string with the new contents for that URL part. The contents should be in the
40 form and encoding they'd use in a URL: URL encoded.
41
42 Setting a part to a NULL pointer will effectively remove that part's contents
43 from the CURLU handle.
44
45 The \fIflags\fP argument is a bitmask with independent features.
46 .SH PARTS
47 .IP CURLUPART_URL
48 Allows the full URL of the handle to be replaced. If the handle already is
49 populated with a URL, the new URL can be relative to the previous.
50
51 When successfully setting a new URL, relative or absolute, the handle contents
52 will be replaced with the information of the newly set URL.
53
54 Pass a pointer to a zero terminated string to the \fIurl\fP parameter. The
55 string must point to a correctly formatted "RFC 3986+" URL or be a NULL
56 pointer.
57 .IP CURLUPART_SCHEME
58 Scheme cannot be URL decoded on set.
59 .IP CURLUPART_USER
60 .IP CURLUPART_PASSWORD
61 .IP CURLUPART_OPTIONS
62 .IP CURLUPART_HOST
63 The host name can use IDNA. The string must then be encoded as your locale
64 says or UTF-8 (when winidn is used).
65 .IP CURLUPART_ZONEID
66 If the host name is a numeric IPv6 address, this field can also be set.
67 .IP CURLUPART_PORT
68 Port cannot be URL encoded on set. The given port number is provided as a
69 string and the decimal number must be between 1 and 65535. Anything else will
70 return an error.
71 .IP CURLUPART_PATH
72 If a path is set in the URL without a leading slash, a slash will be inserted
73 automatically when this URL is read from the handle.
74 .IP CURLUPART_QUERY
75 The query part will also get spaces converted to pluses when asked to URL
76 encode on set with the CURLU_URLENCODE bit.
77
78 If used together with the \fICURLU_APPENDQUERY\fP bit, the provided part will
79 be appended on the end of the existing query - and if the previous part didn't
80 end with an ampersand (&), an ampersand will be inserted before the new
81 appended part.
82
83 When \fICURLU_APPENDQUERY\fP is used together with \fICURLU_URLENCODE\fP, the
84 first '=' symbol will not be URL encoded.
85
86 The question mark in the URL is not part of the actual query contents.
87 .IP CURLUPART_FRAGMENT
88 The hash sign in the URL is not part of the actual fragment contents.
89 .SH FLAGS
90 The flags argument is zero, one or more bits set in a bitmask.
91 .IP CURLU_NON_SUPPORT_SCHEME
92 If set, allows \fIcurl_url_set(3)\fP to set a non-supported scheme.
93 .IP CURLU_URLENCODE
94 When set, \fIcurl_url_set(3)\fP URL encodes the part on entry, except for
95 scheme, port and URL.
96
97 When setting the path component with URL encoding enabled, the slash character
98 will be skipped.
99
100 The query part gets space-to-plus conversion before the URL conversion.
101
102 This URL encoding is charset unaware and will convert the input on a
103 byte-by-byte manner.
104 .IP CURLU_DEFAULT_SCHEME
105 If set, will make libcurl allow the URL to be set without a scheme and then
106 sets that to the default scheme: HTTPS. Overrides the \fICURLU_GUESS_SCHEME\fP
107 option if both are set.
108 .IP CURLU_GUESS_SCHEME
109 If set, will make libcurl allow the URL to be set without a scheme and it
110 instead "guesses" which scheme that was intended based on the host name. If
111 the outermost sub-domain name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then
112 that scheme will be used, otherwise it picks HTTP. Conflicts with the
113 \fICURLU_DEFAULT_SCHEME\fP option which takes precedence if both are set.
114 .SH RETURN VALUE
115 Returns a CURLUcode error value, which is CURLUE_OK (0) if everything went
116 fine.
117
118 If this function returns an error, no URL part is returned.
119 .SH EXAMPLE
120 .nf
121 CURLUcode rc;
122 CURLU *url = curl_url();
123 rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
124 if(!rc) {
125 char *scheme;
126 /* change it to an FTP URL */
127 rc = curl_url_set(url, CURLUPART_SCHEME, "ftp", 0);
128 }
129 curl_url_cleanup(url);
130 .fi
131 .SH AVAILABILITY
132 Added in curl 7.62.0. CURLUPART_ZONEID was added in 7.65.0.
133 .SH "SEE ALSO"
134 .BR curl_url_cleanup "(3), " curl_url "(3), " curl_url_get "(3), "
135 .BR curl_url_dup "(3), "