mirror of
https://github.com/curl/curl.git
synced 2024-12-09 06:30:06 +08:00
ad9bc5976d
Add licensing and copyright information for all files in this repository. This either happens in the file itself as a comment header or in the file `.reuse/dep5`. This commit also adds a Github workflow to check pull requests and adapts copyright.pl to the changes. Closes #8869
136 lines
5.2 KiB
Groff
136 lines
5.2 KiB
Groff
.\" **************************************************************************
|
||
.\" * _ _ ____ _
|
||
.\" * Project ___| | | | _ \| |
|
||
.\" * / __| | | | |_) | |
|
||
.\" * | (__| |_| | _ <| |___
|
||
.\" * \___|\___/|_| \_\_____|
|
||
.\" *
|
||
.\" * Copyright (C) 1998 - 2022, 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.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.
|
||
.\" *
|
||
.\" * SPDX-License-Identifier: curl
|
||
.\" *
|
||
.\" **************************************************************************
|
||
.TH curl_url_get 3 "6 Aug 2018" "libcurl" "libcurl Manual"
|
||
.SH NAME
|
||
curl_url_get - extract a part from a URL
|
||
.SH SYNOPSIS
|
||
.nf
|
||
#include <curl/curl.h>
|
||
|
||
CURLUcode curl_url_get(CURLU *url,
|
||
CURLUPart what,
|
||
char **part,
|
||
unsigned int flags)
|
||
.fi
|
||
.SH DESCRIPTION
|
||
Given the \fIurl\fP handle of an already parsed URL, this function lets the
|
||
user extract individual pieces from it.
|
||
|
||
The \fIwhat\fP argument should be the particular part to extract (see list
|
||
below) and \fIpart\fP points to a 'char *' to get updated to point to a newly
|
||
allocated string with the contents.
|
||
|
||
The \fIflags\fP argument is a bitmask with individual features.
|
||
|
||
The returned part pointer must be freed with \fIcurl_free(3)\fP after use.
|
||
.SH FLAGS
|
||
The flags argument is zero, one or more bits set in a bitmask.
|
||
.IP CURLU_DEFAULT_PORT
|
||
If the handle has no port stored, this option will make \fIcurl_url_get(3)\fP
|
||
return the default port for the used scheme.
|
||
.IP CURLU_DEFAULT_SCHEME
|
||
If the handle has no scheme stored, this option will make
|
||
\fIcurl_url_get(3)\fP return the default scheme instead of error.
|
||
.IP CURLU_NO_DEFAULT_PORT
|
||
Instructs \fIcurl_url_get(3)\fP to not return a port number if it matches the
|
||
default port for the scheme.
|
||
.IP CURLU_URLDECODE
|
||
Asks \fIcurl_url_get(3)\fP to URL decode the contents before returning it. It
|
||
will not attempt to decode the scheme, the port number or the full URL.
|
||
´
|
||
The query component will also get plus-to-space conversion as a bonus when
|
||
this bit is set.
|
||
|
||
Note that this URL decoding is charset unaware and you will get a zero
|
||
terminated string back with data that could be intended for a particular
|
||
encoding.
|
||
|
||
If there's any byte values lower than 32 in the decoded string, the get
|
||
operation will return an error instead.
|
||
.IP CURLU_URLENCODE
|
||
If set, will make \fIcurl_url_get(3)\fP URL encode the host name part when a
|
||
full URL is retrieved. If not set (default), libcurl returns the URL with the
|
||
host name "raw" to support IDN names to appear as-is. IDN host names are
|
||
typically using non-ASCII bytes that otherwise will be percent-encoded.
|
||
|
||
Note that even when not asking for URL encoding, the '%' (byte 37) will be URL
|
||
encoded to make sure the host name remains valid.
|
||
.SH PARTS
|
||
.IP CURLUPART_URL
|
||
When asked to return the full URL, \fIcurl_url_get(3)\fP will return a
|
||
normalized and possibly cleaned up version of what was previously parsed.
|
||
.IP CURLUPART_SCHEME
|
||
Scheme cannot be URL decoded on get.
|
||
.IP CURLUPART_USER
|
||
.IP CURLUPART_PASSWORD
|
||
.IP CURLUPART_OPTIONS
|
||
.IP CURLUPART_HOST
|
||
The host name. If it is an IPv6 numeric address, the zoneid will not be part
|
||
of it but is provided separately in \fICURLUPART_ZONEID\fP. IPv6 numerical
|
||
addresses are returned within brackets ([]).
|
||
.IP CURLUPART_ZONEID
|
||
If the host name is a numeric IPv6 address, this field might also be set.
|
||
.IP CURLUPART_PORT
|
||
Port cannot be URL decoded on get.
|
||
.IP CURLUPART_PATH
|
||
\fIpart\fP will be '/' even if no path is supplied in the URL.
|
||
.IP CURLUPART_QUERY
|
||
The initial question mark that denotes the beginning of the query part is
|
||
a delimiter only.
|
||
It is not part of the query contents.
|
||
|
||
|
||
A not-present query will lead \fIpart\fP to be set to NULL.
|
||
A zero-length query will lead \fIpart\fP to be set to a zero-length string.
|
||
|
||
The query part will also get pluses converted to space when asked to URL
|
||
decode on get with the CURLU_URLDECODE bit.
|
||
.IP CURLUPART_FRAGMENT
|
||
.SH EXAMPLE
|
||
.nf
|
||
CURLUcode rc;
|
||
CURLU *url = curl_url();
|
||
rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0);
|
||
if(!rc) {
|
||
char *scheme;
|
||
rc = curl_url_get(url, CURLUPART_SCHEME, &scheme, 0);
|
||
if(!rc) {
|
||
printf("the scheme is %s\\n", scheme);
|
||
curl_free(scheme);
|
||
}
|
||
curl_url_cleanup(url);
|
||
}
|
||
.fi
|
||
.SH AVAILABILITY
|
||
Added in 7.62.0. CURLUPART_ZONEID was added in 7.65.0.
|
||
.SH RETURN VALUE
|
||
Returns a CURLUcode error value, which is CURLUE_OK (0) if everything went
|
||
fine. See the \fIlibcurl-errors(3)\fP man page for the full list with
|
||
descriptions.
|
||
|
||
If this function returns an error, no URL part is returned.
|
||
.SH "SEE ALSO"
|
||
.BR curl_url_cleanup "(3), " curl_url "(3), " curl_url_set "(3), "
|
||
.BR curl_url_dup "(3), " curl_url_strerror "(3), " CURLOPT_CURLU "(3)"
|