mirror of
https://github.com/moparisthebest/curl
synced 2024-11-05 09:05:04 -05:00
121 lines
4.6 KiB
Groff
121 lines
4.6 KiB
Groff
|
.\" **************************************************************************
|
||
|
.\" * _ _ ____ _
|
||
|
.\" * Project ___| | | | _ \| |
|
||
|
.\" * / __| | | | |_) | |
|
||
|
.\" * | (__| |_| | _ <| |___
|
||
|
.\" * \___|\___/|_| \_\_____|
|
||
|
.\" *
|
||
|
.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al.
|
||
|
.\" *
|
||
|
.\" * This software is licensed as described in the file COPYING, which
|
||
|
.\" * you should have received as part of this distribution. The terms
|
||
|
.\" * are also available at https://curl.haxx.se/docs/copyright.html.
|
||
|
.\" *
|
||
|
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
|
||
|
.\" * copies of the Software, and permit persons to whom the Software is
|
||
|
.\" * furnished to do so, under the terms of the COPYING file.
|
||
|
.\" *
|
||
|
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
|
||
|
.\" * KIND, either express or implied.
|
||
|
.\" *
|
||
|
.\" **************************************************************************
|
||
|
.TH curl_url_set 3 "6 Aug 2018" "libcurl" "libcurl Manual"
|
||
|
.SH NAME
|
||
|
curl_url_set - set a part from a URL
|
||
|
.SH SYNOPSIS
|
||
|
.B #include <curl/curl.h>
|
||
|
|
||
|
CURLUcode curl_url_set(CURLU *url,
|
||
|
CURLUPart part,
|
||
|
const char *content,
|
||
|
unsigned int flags)
|
||
|
.fi
|
||
|
.SH DESCRIPTION
|
||
|
Given the \fIurl\fP handle of an already parsed URL, this function lets the
|
||
|
user set/update individual pieces of it.
|
||
|
|
||
|
The \fIpart\fP argument should identify the particular URL part (see list
|
||
|
below) to set or change, with \fIcontent\fP pointing to a zero 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.
|
||
|
|
||
|
Setting a part to a NULL pointer will effectively remove that part's contents
|
||
|
from the CURLU handle.
|
||
|
|
||
|
The \fIflags\fP argument is a bitmask with independent features.
|
||
|
.SH PARTS
|
||
|
.IP 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 zero terminated string to the \fIurl\fP parameter. The
|
||
|
string must point to a correctly formatted "RFC 3986+" URL or be a NULL
|
||
|
pointer.
|
||
|
.IP CURLUPART_SCHEME
|
||
|
Scheme cannot be URL decoded on set.
|
||
|
.IP CURLUPART_USER
|
||
|
.IP CURLUPART_PASSWORD
|
||
|
.IP CURLUPART_OPTIONS
|
||
|
.IP CURLUPART_HOST
|
||
|
The host name can use IDNA. The string must then be encoded as your locale
|
||
|
says or UTF-8 (when winidn is used).
|
||
|
.IP CURLUPART_PORT
|
||
|
Port cannot be URL encoded on set.
|
||
|
.IP 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.
|
||
|
.IP 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 in with \fICURLU_APPENDQUERY\fP, the provided part will be appended on
|
||
|
the end of the existing query - and if the previous part didn't end with an
|
||
|
ampersand (&), an ampersand will be inserted before the new appended part.
|
||
|
|
||
|
When \fCURLU_APPENDQUERY\fP is used together with \fICURLU_URLENCODE\fP,
|
||
|
the '=' symbols will not be URL encoded.
|
||
|
|
||
|
The question mark in the URL is not part of the actual query contents.
|
||
|
.IP CURLUPART_FRAGMENT
|
||
|
The hash sign in the URL is not part of the actual fragment contents.
|
||
|
.SH FLAGS
|
||
|
The flags argument is zero, one or more bits set in a bitmask.
|
||
|
.IP CURLU_NON_SUPPORT_SCHEME
|
||
|
If set, allows \fIcurl_url_set(3)\fP to set a non-supported scheme.
|
||
|
.IP CURLU_URLENCODE
|
||
|
When set, \fIcurl_url_set(3)\fP 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.
|
||
|
.SH RETURN VALUE
|
||
|
Returns a CURLUcode error value, which is CURLUE_OK (0) if everything went
|
||
|
fine.
|
||
|
|
||
|
If this function returns an error, no URL part is returned.
|
||
|
.SH EXAMPLE
|
||
|
.nf
|
||
|
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);
|
||
|
.fi
|
||
|
.SH AVAILABILITY
|
||
|
Added in curl 7.63.0
|
||
|
.SH "SEE ALSO"
|
||
|
.BR curl_url_cleanup "(3), " curl_url "(3), " curl_url_get "(3), "
|
||
|
.BR curl_url_dup "(3), "
|