urlapi: add curl_url_strerror()

Add curl_url_strerror() to convert CURLUcode into readable string and
facilitate easier troubleshooting in programs using URL API.
Extend CURLUcode with CURLU_LAST for iteration in unit tests.
Update man pages with a mention of new function.
Update example code and tests with new functionality where it fits.

Closes #7605

13 files changed, 70 insertions, 21 deletions

diff --git a/docs/examples/urlapi.c b/docs/examples/urlapi.c
index 229954d05..0c67480a1 100644
--- a/docs/examples/urlapi.c
+++ b/docs/examples/urlapi.c
@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2021, 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
@@ -26,8 +26,8 @@
 #include <stdio.h>
 #include <curl/curl.h>
 
-#if !CURL_AT_LEAST_VERSION(7, 62, 0)
-#error "this example requires curl 7.62.0 or later"
+#if !CURL_AT_LEAST_VERSION(7, 80, 0)
+#error "this example requires curl 7.80.0 or later"
 #endif
 
 int main(void)
@@ -47,7 +47,7 @@ int main(void)
                     "http://example.com/path/index.html", 0);
 
   if(uc) {
-    fprintf(stderr, "curl_url_set() failed: %in", uc);
+    fprintf(stderr, "curl_url_set() failed: %s", curl_url_strerror(uc));
     goto cleanup;
   }
 
diff --git a/docs/libcurl/Makefile.inc b/docs/libcurl/Makefile.inc
index 30eb779e2..706d8b6ba 100644
--- a/docs/libcurl/Makefile.inc
+++ b/docs/libcurl/Makefile.inc
@@ -5,7 +5,7 @@
 #                            | (__| |_| |  _ <| |___
 #                             \___|\___/|_| \_\_____|
 #
-# Copyright (C) 2008 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+# Copyright (C) 2008 - 2021, 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
@@ -95,6 +95,7 @@ man_MANS = \
  curl_url_dup.3 \
  curl_url_get.3 \
  curl_url_set.3 \
+ curl_url_strerror.3 \
  curl_version.3 \
  curl_version_info.3 \
  libcurl-easy.3 \
diff --git a/docs/libcurl/curl_easy_strerror.3 b/docs/libcurl/curl_easy_strerror.3
index accc3b8af..168cd131f 100644
--- a/docs/libcurl/curl_easy_strerror.3
+++ b/docs/libcurl/curl_easy_strerror.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, 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
@@ -37,4 +37,5 @@ This function was added in libcurl 7.12.0
 .SH RETURN VALUE
 A pointer to a null-terminated string.
 .SH "SEE ALSO"
-.BR libcurl-errors "(3), " curl_multi_strerror "(3), " curl_share_strerror "(3)"
+.BR libcurl-errors "(3), " curl_multi_strerror "(3), "
+.BR curl_share_strerror "(3), " curl_url_strerror "(3)"
diff --git a/docs/libcurl/curl_multi_strerror.3 b/docs/libcurl/curl_multi_strerror.3
index ecd928521..c432bc566 100644
--- a/docs/libcurl/curl_multi_strerror.3
+++ b/docs/libcurl/curl_multi_strerror.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, 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
@@ -34,4 +34,5 @@ This function was added in libcurl 7.12.0
 .SH RETURN VALUE
 A pointer to a null-terminated string.
 .SH "SEE ALSO"
-.BR libcurl-errors "(3), " curl_easy_strerror "(3), " curl_share_strerror "(3)"
+.BR libcurl-errors "(3), " curl_easy_strerror "(3), "
+.BR curl_share_strerror "(3), " curl_url_strerror "(3)"
diff --git a/docs/libcurl/curl_share_strerror.3 b/docs/libcurl/curl_share_strerror.3
index 562f74ee4..443df1640 100644
--- a/docs/libcurl/curl_share_strerror.3
+++ b/docs/libcurl/curl_share_strerror.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2021, 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
@@ -34,4 +34,5 @@ This function was added in libcurl 7.12.0
 .SH RETURN VALUE
 A pointer to a null-terminated string.
 .SH "SEE ALSO"
-.BR libcurl-errors "(3), " curl_multi_strerror "(3), " curl_easy_strerror "(3)"
+.BR libcurl-errors "(3), " curl_multi_strerror "(3), "
+.BR curl_easy_strerror "(3), " curl_url_strerror "(3)"
diff --git a/docs/libcurl/curl_url.3 b/docs/libcurl/curl_url.3
index 593a32df7..edec76d2a 100644
--- a/docs/libcurl/curl_url.3
+++ b/docs/libcurl/curl_url.3
@@ -50,4 +50,4 @@ Returns a \fBCURLU *\fP if successful, or NULL if out of memory.
 Added in curl 7.62.0
 .SH "SEE ALSO"
 .BR curl_url_cleanup "(3), " curl_url_get "(3), " curl_url_set "(3), "
-.BR curl_url_dup "(3), " CURLOPT_CURLU "(3), "
+.BR curl_url_dup "(3), " curl_url_strerror "(3), " CURLOPT_CURLU "(3)"
diff --git a/docs/libcurl/curl_url_get.3 b/docs/libcurl/curl_url_get.3
index a61157275..7fbdff0ed 100644
--- a/docs/libcurl/curl_url_get.3
+++ b/docs/libcurl/curl_url_get.3
@@ -99,7 +99,8 @@ 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.
+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 EXAMPLE
@@ -121,4 +122,4 @@ If this function returns an error, no URL part is returned.
 Added in curl 7.62.0. CURLUPART_ZONEID was added in 7.65.0.
 .SH "SEE ALSO"
 .BR curl_url_cleanup "(3), " curl_url "(3), " curl_url_set "(3), "
-.BR curl_url_dup "(3), " CURLOPT_CURLU "(3), "
+.BR curl_url_dup "(3), " curl_url_strerror "(3), " CURLOPT_CURLU "(3)"
diff --git a/docs/libcurl/curl_url_set.3 b/docs/libcurl/curl_url_set.3
index 5c795bde0..02f74ce02 100644
--- a/docs/libcurl/curl_url_set.3
+++ b/docs/libcurl/curl_url_set.3
@@ -136,7 +136,8 @@ space before stored. This affects how the URL will be constructed when
 individual parts.
 .SH RETURN VALUE
 Returns a CURLUcode error value, which is CURLUE_OK (0) if everything went
-fine.
+fine.  See the \fIlibcurl-errors(3)\fP man page for the full list with
+descriptions.
 
 A URL string passed on to \fIcurl_url_set(3)\fP for the \fBCURLUPART_URL\fP
 part, must be shorter than 8000000 bytes otherwise it returns
@@ -159,4 +160,4 @@ If this function returns an error, no URL part is set.
 Added in curl 7.62.0. CURLUPART_ZONEID was added in 7.65.0.
 .SH "SEE ALSO"
 .BR curl_url_cleanup "(3), " curl_url "(3), " curl_url_get "(3), "
-.BR curl_url_dup "(3), " CURLOPT_CURLU "(3), "
+.BR curl_url_dup "(3), " curl_url_strerror "(3), " CURLOPT_CURLU "(3)"
diff --git a/docs/libcurl/curl_url_strerror.3 b/docs/libcurl/curl_url_strerror.3
new file mode 100644
index 000000000..6b1d7b106
--- /dev/null
+++ b/docs/libcurl/curl_url_strerror.3
@@ -0,0 +1,39 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2021, 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.
+.\" *
+.\" **************************************************************************
+.TH curl_url_strerror 3 "21 Aug 2021" "libcurl 7.80.0" "libcurl Manual"
+.SH NAME
+curl_url_strerror - return string describing error code
+.SH SYNOPSIS
+.nf
+.B #include <curl/curl.h>
+.BI "const char *curl_url_strerror(CURLUcode " errornum ");"
+.SH DESCRIPTION
+The curl_url_strerror() function returns a string describing the CURLUcode
+error code passed in the argument \fIerrornum\fP.
+.SH AVAILABILITY
+This function was added in libcurl 7.80.0
+.SH RETURN VALUE
+A pointer to a null-terminated string.
+.SH "SEE ALSO"
+.BR libcurl-errors "(3), " curl_url_get "(3), " curl_url_set "(3), "
+.BR curl_easy_strerror "(3), " curl_multi_strerror "(3), "
+.BR curl_share_strerror "(3)"
diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3
index 707503f4e..400975761 100644
--- a/docs/libcurl/libcurl-errors.3
+++ b/docs/libcurl/libcurl-errors.3
@@ -325,6 +325,8 @@ Not enough memory was available.
 The requested sharing could not be done because the library you use don't have
 that particular feature enabled. (Added in 7.23.0)
 .SH "CURLUcode"
+The URL interface will return a CURLUcode to indicate when an error has
+occurred.  Also consider \fIcurl_url_strerror(3)\fP.
 .IP "CURLUE_BAD_HANDLE (1)"
 An invalid CURLU pointer was passed as argument.
 .IP "CURLUE_BAD_PARTPOINTER (2)"
@@ -361,5 +363,6 @@ There is no query part in the URL.
 There is no fragment part in the URL.
 .SH "SEE ALSO"
 .BR curl_easy_strerror "(3), " curl_multi_strerror "(3), "
-.BR curl_share_strerror "(3), " CURLOPT_ERRORBUFFER "(3), "
-.BR CURLOPT_VERBOSE "(3), " CURLOPT_DEBUGFUNCTION "(3) "
+.BR curl_share_strerror "(3), " curl_url_strerror "(3), "
+.BR CURLOPT_ERRORBUFFER "(3), " CURLOPT_VERBOSE "(3), "
+.BR CURLOPT_DEBUGFUNCTION "(3)"
\ No newline at end of file
diff --git a/docs/libcurl/libcurl-url.3 b/docs/libcurl/libcurl-url.3
index f08ebd826..fe525737f 100644
--- a/docs/libcurl/libcurl-url.3
+++ b/docs/libcurl/libcurl-url.3
@@ -135,4 +135,5 @@ Now the URL looks like
 The URL API was introduced in libcurl 7.62.0.
 .SH "SEE ALSO"
 .BR curl_url "(3), " curl_url_cleanup "(3), " curl_url_get "(3), "
-.BR curl_url_dup "(3), " curl_url_set "(3), " CURLOPT_URL "(3), "
+.BR curl_url_dup "(3), " curl_url_set "(3), " curl_url_strerror "(3), "
+.BR CURLOPT_URL "(3)"
diff --git a/docs/libcurl/opts/CURLOPT_CURLU.3 b/docs/libcurl/opts/CURLOPT_CURLU.3
index 39a732cad..5f6d4af76 100644
--- a/docs/libcurl/opts/CURLOPT_CURLU.3
+++ b/docs/libcurl/opts/CURLOPT_CURLU.3
@@ -67,4 +67,4 @@ Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
 .SH "SEE ALSO"
 .BR CURLOPT_URL "(3), "
 .BR curl_url "(3), " curl_url_get "(3), " curl_url_set "(3), "
-.BR curl_url_dup "(3), " curl_url_cleanup "(3), "
+.BR curl_url_dup "(3), " curl_url_cleanup "(3), " curl_url_strerror "(3)"
diff --git a/docs/libcurl/opts/CURLOPT_ERRORBUFFER.3 b/docs/libcurl/opts/CURLOPT_ERRORBUFFER.3
index dc5109b8e..55fe53d67 100644
--- a/docs/libcurl/opts/CURLOPT_ERRORBUFFER.3
+++ b/docs/libcurl/opts/CURLOPT_ERRORBUFFER.3
@@ -89,4 +89,4 @@ Returns CURLE_OK
 .SH "SEE ALSO"
 .BR CURLOPT_DEBUGFUNCTION "(3), " CURLOPT_VERBOSE "(3), "
 .BR curl_easy_strerror "(3), " curl_multi_strerror "(3), "
-.BR curl_share_strerror "(3) "
+.BR curl_share_strerror "(3), " curl_url_strerror "(3)"