diff options
Diffstat (limited to 'docs/libcurl/curl_url_get.3')
| -rw-r--r-- | docs/libcurl/curl_url_get.3 | 111 |
1 files changed, 111 insertions, 0 deletions
diff --git a/docs/libcurl/curl_url_get.3 b/docs/libcurl/curl_url_get.3 new file mode 100644 index 00000000..233e7395 --- /dev/null +++ b/docs/libcurl/curl_url_get.3 @@ -0,0 +1,111 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_get 3 "October 08, 2018" "libcurl 7.62.0" "libcurl Manual" + +.SH NAME +curl_url_get - extract a part from a URL +.SH SYNOPSIS +.B #include <curl/curl.h> + +.nf +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. +.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 +.IP CURLUPART_PORT +Port cannot be URL decoded on get. +.IP CURLUPART_PATH +.IP CURLUPART_QUERY +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 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; + 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 curl 7.62.0 +.SH "SEE ALSO" +.BR curl_url_cleanup "(3), " curl_url "(3), " curl_url_set "(3), " +.BR curl_url_dup "(3), " |