diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/libcurl/Makefile.inc | 103 | ||||
| -rw-r--r-- | docs/libcurl/curl_url.3 | 61 | ||||
| -rw-r--r-- | docs/libcurl/curl_url_cleanup.3 | 44 | ||||
| -rw-r--r-- | docs/libcurl/curl_url_dup.3 | 52 | ||||
| -rw-r--r-- | docs/libcurl/curl_url_get.3 | 110 | ||||
| -rw-r--r-- | docs/libcurl/curl_url_set.3 | 120 | ||||
| -rw-r--r-- | docs/libcurl/symbols-in-versions | 30 |
7 files changed, 497 insertions, 23 deletions
diff --git a/docs/libcurl/Makefile.inc b/docs/libcurl/Makefile.inc index f41bbe098..ba4724b4d 100644 --- a/docs/libcurl/Makefile.inc +++ b/docs/libcurl/Makefile.inc @@ -1,25 +1,82 @@ # Shared between Makefile.am and CMakeLists.txt -man_MANS = curl_easy_cleanup.3 curl_easy_getinfo.3 curl_easy_init.3 \ - curl_easy_perform.3 curl_easy_setopt.3 curl_easy_duphandle.3 \ - curl_formadd.3 curl_formfree.3 curl_getdate.3 curl_getenv.3 \ - curl_slist_append.3 curl_slist_free_all.3 curl_version.3 \ - curl_version_info.3 curl_escape.3 curl_unescape.3 curl_free.3 \ - curl_strequal.3 curl_strnequal.3 curl_mprintf.3 curl_global_init.3 \ - curl_global_cleanup.3 curl_multi_add_handle.3 curl_multi_cleanup.3 \ - curl_multi_fdset.3 curl_multi_info_read.3 curl_multi_init.3 \ - curl_multi_perform.3 curl_multi_remove_handle.3 curl_share_cleanup.3 \ - curl_share_init.3 curl_share_setopt.3 libcurl.3 libcurl-easy.3 \ - libcurl-multi.3 libcurl-share.3 libcurl-errors.3 curl_easy_strerror.3 \ - curl_multi_strerror.3 curl_share_strerror.3 curl_global_init_mem.3 \ - libcurl-tutorial.3 curl_easy_reset.3 curl_easy_escape.3 \ - curl_easy_unescape.3 curl_multi_setopt.3 curl_multi_socket.3 \ - curl_multi_timeout.3 curl_formget.3 curl_multi_assign.3 \ - curl_easy_pause.3 curl_easy_recv.3 curl_easy_send.3 \ - curl_multi_socket_action.3 curl_multi_wait.3 libcurl-symbols.3 \ - libcurl-thread.3 curl_multi_socket_all.3 curl_global_sslset.3 \ - curl_mime_init.3 curl_mime_free.3 curl_mime_addpart.3 curl_mime_name.3 \ - curl_mime_data.3 curl_mime_data_cb.3 curl_mime_filedata.3 \ - curl_mime_filename.3 curl_mime_subparts.3 \ - curl_mime_type.3 curl_mime_headers.3 curl_mime_encoder.3 libcurl-env.3 \ - libcurl-security.3 curl_easy_upkeep.3 +man_MANS = \ + curl_easy_cleanup.3 \ + curl_easy_duphandle.3 \ + curl_easy_escape.3 \ + curl_easy_getinfo.3 \ + curl_easy_init.3 \ + curl_easy_pause.3 \ + curl_easy_perform.3 \ + curl_easy_recv.3 \ + curl_easy_reset.3 \ + curl_easy_send.3 \ + curl_easy_setopt.3 \ + curl_easy_strerror.3 \ + curl_easy_unescape.3 \ + curl_easy_upkeep.3 \ + curl_escape.3 \ + curl_formadd.3 \ + curl_formfree.3 \ + curl_formget.3 \ + curl_free.3 \ + curl_getdate.3 \ + curl_getenv.3 \ + curl_global_cleanup.3 \ + curl_global_init.3 \ + curl_global_init_mem.3 \ + curl_global_sslset.3 \ + curl_mime_addpart.3 \ + curl_mime_data.3 \ + curl_mime_data_cb.3 \ + curl_mime_encoder.3 \ + curl_mime_filedata.3 \ + curl_mime_filename.3 \ + curl_mime_free.3 \ + curl_mime_headers.3 \ + curl_mime_init.3 \ + curl_mime_name.3 \ + curl_mime_subparts.3 \ + curl_mime_type.3 \ + curl_mprintf.3 \ + curl_multi_add_handle.3 \ + curl_multi_assign.3 \ + curl_multi_cleanup.3 \ + curl_multi_fdset.3 \ + curl_multi_info_read.3 \ + curl_multi_init.3 \ + curl_multi_perform.3 \ + curl_multi_remove_handle.3 \ + curl_multi_setopt.3 \ + curl_multi_socket.3 \ + curl_multi_socket_action.3 \ + curl_multi_socket_all.3 \ + curl_multi_strerror.3 \ + curl_multi_timeout.3 \ + curl_multi_wait.3 \ + curl_share_cleanup.3 \ + curl_share_init.3 \ + curl_share_setopt.3 \ + curl_share_strerror.3 \ + curl_slist_append.3 \ + curl_slist_free_all.3 \ + curl_strequal.3 \ + curl_strnequal.3 \ + curl_unescape.3 \ + curl_url.3 \ + curl_url_cleanup.3 \ + curl_url_dup.3 \ + curl_url_get.3 \ + curl_url_set.3 \ + curl_version.3 \ + curl_version_info.3 \ + libcurl-easy.3 \ + libcurl-env.3 \ + libcurl-errors.3 \ + libcurl-multi.3 \ + libcurl-security.3 \ + libcurl-share.3 \ + libcurl-symbols.3 \ + libcurl-thread.3 \ + libcurl-tutorial.3 \ + libcurl.3 diff --git a/docs/libcurl/curl_url.3 b/docs/libcurl/curl_url.3 new file mode 100644 index 000000000..0a5626477 --- /dev/null +++ b/docs/libcurl/curl_url.3 @@ -0,0 +1,61 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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 3 "6 Aug 2018" "libcurl" "libcurl Manual" +.SH NAME +curl_url - returns a new CURLU handle +.SH SYNOPSIS +.B #include <curl/curl.h> + +CURLU *curl_url(); +.SH EXPERIMENTAL +The URL API is considered \fBEXPERIMENTAL\fP until further notice. Please test +it, report bugs and help us perfect it. Once proven to be reliable, the +experimental label will be removed. + +While this API is marked experimental, we reserve the right to modify the API +slightly if we deem it necessary and it makes it notably better or easier to +use. +.SH DESCRIPTION +This function will allocates and returns a pointer to a fresh CURLU handle, to +be used for further use of the URL API. +.SH RETURN VALUE +Returns a \fBCURLU *\fP if successful, or NULL if out of memory. +.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.63.0 +.SH "SEE ALSO" +.BR curl_url_cleanup "(3), " curl_url_get "(3), " curl_url_set "(3), " +.BR curl_url_dup "(3), " diff --git a/docs/libcurl/curl_url_cleanup.3 b/docs/libcurl/curl_url_cleanup.3 new file mode 100644 index 000000000..a8158b7b8 --- /dev/null +++ b/docs/libcurl/curl_url_cleanup.3 @@ -0,0 +1,44 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_cleanup 3 "6 Aug 2018" "libcurl" "libcurl Manual" +.SH NAME +curl_url_cleanup - free a CURLU handle +.SH SYNOPSIS +.B #include <curl/curl.h> + +void curl_url_cleanup(CURLU *handle); +.fi +.SH DESCRIPTION +Frees all the resources associated with the given CURLU handle! +.SH RETURN VALUE +none +.SH EXAMPLE +.nf + CURLU *url = curl_url(); + curl_url_set(url, CURLUPART_URL, "https://example.com", 0); + curl_url_cleanup(url); +.fi +.SH AVAILABILITY +Added in curl 7.63.0 +.SH "SEE ALSO" +.BR curl_url_dup "(3), " curl_url "(3), " curl_url_set "(3), " +.BR curl_url_get "(3), " diff --git a/docs/libcurl/curl_url_dup.3 b/docs/libcurl/curl_url_dup.3 new file mode 100644 index 000000000..4815dbd2b --- /dev/null +++ b/docs/libcurl/curl_url_dup.3 @@ -0,0 +1,52 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_dup 3 "6 Aug 2018" "libcurl" "libcurl Manual" +.SH NAME +curl_url_dup - duplicate a CURLU handle +.SH SYNOPSIS +.B #include <curl/curl.h> + +CURLU *curl_url_dup(CURLU *inhandle); +.fi +.SH DESCRIPTION +Duplicates a given CURLU \fIinhandle\fP and all its contents and returns a +pointer to a new CURLU handle. The new handle also needs to be freed with +\fIcurl_url_cleanup(3)\fP. +.SH RETURN VALUE +Returns a new handle or NULL if out of memory. +.SH EXAMPLE +.nf + CURLUcode rc; + CURLU *url = curl_url(); + CURLU *url2; + rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0); + if(!rc) { + url2 = curl_url_dup(url); /* clone it! */ + curl_url_cleanup(url2); + } + 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_set "(3), " +.BR curl_url_get "(3), " diff --git a/docs/libcurl/curl_url_get.3 b/docs/libcurl/curl_url_get.3 new file mode 100644 index 000000000..824d4964f --- /dev/null +++ b/docs/libcurl/curl_url_get.3 @@ -0,0 +1,110 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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 "6 Aug 2018" "libcurl" "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 convertion 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.63.0 +.SH "SEE ALSO" +.BR curl_url_cleanup "(3), " curl_url "(3), " curl_url_set "(3), " +.BR curl_url_dup "(3), " diff --git a/docs/libcurl/curl_url_set.3 b/docs/libcurl/curl_url_set.3 new file mode 100644 index 000000000..75fc0d963 --- /dev/null +++ b/docs/libcurl/curl_url_set.3 @@ -0,0 +1,120 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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), " diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 2803a40d5..950eb5bc6 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -721,6 +721,36 @@ CURLSSLSET_NO_BACKENDS 7.56.0 CURLSSLSET_OK 7.56.0 CURLSSLSET_TOO_LATE 7.56.0 CURLSSLSET_UNKNOWN_BACKEND 7.56.0 +CURLUPART_FRAGMENT 7.62.0 +CURLUPART_HOST 7.62.0 +CURLUPART_OPTIONS 7.62.0 +CURLUPART_PASSWORD 7.62.0 +CURLUPART_PATH 7.62.0 +CURLUPART_PORT 7.62.0 +CURLUPART_QUERY 7.62.0 +CURLUPART_SCHEME 7.62.0 +CURLUPART_URL 7.62.0 +CURLUPART_USER 7.62.0 +CURLUE_BAD_HANDLE 7.62.0 +CURLUE_BAD_PARTPOINTER 7.62.0 +CURLUE_BAD_PORT_NUMBER 7.62.0 +CURLUE_MALFORMED_INPUT 7.62.0 +CURLUE_NO_FRAGMENT 7.62.0 +CURLUE_NO_HOST 7.62.0 +CURLUE_NO_OPTIONS 7.62.0 +CURLUE_NO_PASSWORD 7.62.0 +CURLUE_NO_PATH 7.62.0 +CURLUE_NO_PORT 7.62.0 +CURLUE_NO_QUERY 7.62.0 +CURLUE_NO_SCHEME 7.62.0 +CURLUE_NO_USER 7.62.0 +CURLUE_OK 7.62.0 +CURLUE_OUT_OF_MEMORY 7.62.0 +CURLUE_RELATIVE 7.62.0 +CURLUE_UNKNOWN_PART 7.62.0 +CURLUE_UNSUPPORTED_SCHEME 7.62.0 +CURLUE_URLDECODE 7.62.0 +CURLUE_USER_NOT_ALLOWED 7.62.0 CURLUSESSL_ALL 7.17.0 CURLUSESSL_CONTROL 7.17.0 CURLUSESSL_NONE 7.17.0 |