docs/libcurl: return value overhall

Unified, extended, clarified the return values for numerous functions

Closes #15899

docs/libcurl/curl_easy_getinfo.md

@@ -437,5 +437,9 @@ int main(void)
 
 # RETURN VALUE
 
-If the operation was successful, CURLE_OK is returned. Otherwise an
+This function returns a CURLcode indicating success or error.
-appropriate error code is returned.
+
+CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3). If CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3)
+there can be an error message stored in the error buffer when non-zero is
+returned.

docs/libcurl/curl_easy_header.md

@@ -160,4 +160,6 @@ int main(void)
 
 # RETURN VALUE
 
-This function returns a CURLHcode indicating success or error.
+This function returns a CURLHcode indicating success or error. CURLHE_OK (0)
+means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3).

docs/libcurl/curl_easy_pause.md

@@ -138,6 +138,9 @@ might end up having to cache 64 MB of data.
 
 # RETURN VALUE
 
-CURLE_OK (zero) means that the option was set properly, and a non-zero return
+This function returns a CURLcode indicating success or error.
-code means something wrong occurred after the new state was set. See the
+
-libcurl-errors(3) man page for the full list with descriptions.
+CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3). If CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3)
+there can be an error message stored in the error buffer when non-zero is
+returned.

docs/libcurl/curl_easy_perform.md

@@ -80,7 +80,9 @@ int main(void)
 
 # RETURN VALUE
 
-CURLE_OK (0) means everything was OK, non-zero means an error occurred as
+This function returns a CURLcode indicating success or error.
-*\<curl/curl.h\>* defines - see libcurl-errors(3). If CURLOPT_ERRORBUFFER(3)
+
-was set with curl_easy_setopt(3) there is an error message stored in the error
+CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
-buffer when non-zero is returned.
+libcurl-errors(3). If CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3)
+there can be an error message stored in the error buffer when non-zero is
+returned.

docs/libcurl/curl_easy_recv.md

@@ -102,5 +102,5 @@ system facilities to wait until data can be read, and retry.
 
 Reading exactly 0 bytes indicates a closed connection.
 
-If there is no socket available to use from the previous transfer, this function
+If there is no socket available to use from the previous transfer, this
-returns **CURLE_UNSUPPORTED_PROTOCOL**.
+function returns **CURLE_UNSUPPORTED_PROTOCOL**.

docs/libcurl/curl_easy_send.md

@@ -94,5 +94,5 @@ On failure, returns the appropriate error code.
 This function may return **CURLE_AGAIN**. In this case, use your operating
 system facilities to wait until the socket is writable, and retry.
 
-If there is no socket available to use from the previous transfer, this function
+If there is no socket available to use from the previous transfer, this
-returns **CURLE_UNSUPPORTED_PROTOCOL**.
+function returns **CURLE_UNSUPPORTED_PROTOCOL**.

docs/libcurl/curl_easy_setopt.md

@@ -1348,9 +1348,12 @@ int main(void)
 
 # RETURN VALUE
 
-*CURLE_OK* (zero) means that the option was set properly, non-zero means an
+This function returns a CURLcode indicating success or error.
-error occurred as *\<curl/curl.h\>* defines. See the libcurl-errors(3) man
+
-page for the full list with descriptions.
+CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3). If CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3)
+there can be an error message stored in the error buffer when non-zero is
+returned.
 
 Strings passed on to libcurl must be shorter than 8000000 bytes, otherwise
 curl_easy_setopt(3) returns **CURLE_BAD_FUNCTION_ARGUMENT** (added in 7.65.0).

docs/libcurl/curl_easy_upkeep.md

@@ -79,6 +79,9 @@ int main(void)
 
 # RETURN VALUE
 
-On success, returns **CURLE_OK**.
+This function returns a CURLcode indicating success or error.
 
-On failure, returns the appropriate error code.
+CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3). If CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3)
+there can be an error message stored in the error buffer when non-zero is
+returned.

docs/libcurl/curl_global_init_mem.md

@@ -94,5 +94,9 @@ int main(void)
 
 # RETURN VALUE
 
-CURLE_OK (0) means everything was OK, non-zero means an error occurred as
+This function returns a CURLcode indicating success or error.
-*\<curl/curl.h\>* defines - see libcurl-errors(3).
+
+CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3). If CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3)
+there can be an error message stored in the error buffer when non-zero is
+returned.

docs/libcurl/curl_mime_data.md

@@ -78,4 +78,9 @@ int main(void)
 
 # RETURN VALUE
 
-CURLE_OK or a CURL error code upon failure.
+This function returns a CURLcode indicating success or error.
+
+CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3). If CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3)
+there can be an error message stored in the error buffer when non-zero is
+returned.

docs/libcurl/curl_mime_data_cb.md

@@ -170,4 +170,9 @@ int main(void)
 
 # RETURN VALUE
 
-CURLE_OK or a CURL error code upon failure.
+This function returns a CURLcode indicating success or error.
+
+CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3). If CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3)
+there can be an error message stored in the error buffer when non-zero is
+returned.

docs/libcurl/curl_mime_encoder.md

@@ -102,4 +102,9 @@ int main(void)
 
 # RETURN VALUE
 
-CURLE_OK or a CURL error code upon failure.
+This function returns a CURLcode indicating success or error.
+
+CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3). If CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3)
+there can be an error message stored in the error buffer when non-zero is
+returned.

docs/libcurl/curl_mime_filedata.md

@@ -87,7 +87,13 @@ int main(void)
 
 # RETURN VALUE
 
-CURLE_OK or a CURL error code upon failure. CURLE_READ_ERROR is only an
+This function returns a CURLcode indicating success or error.
-indication that the file is not yet readable: it can be safely ignored at
+
-this time, but the file must be made readable before the pertaining
+CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
-easy handle is performed.
+libcurl-errors(3). If CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3)
+there can be an error message stored in the error buffer when non-zero is
+returned.
+
+CURLE_READ_ERROR is only an indication that the file is not yet readable: it
+can be safely ignored at this time, but the file must be made readable before
+the pertaining easy handle is performed.

docs/libcurl/curl_mime_filename.md

@@ -81,4 +81,9 @@ int main(void)
 
 # RETURN VALUE
 
-CURLE_OK or a CURL error code upon failure.
+This function returns a CURLcode indicating success or error.
+
+CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3). If CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3)
+there can be an error message stored in the error buffer when non-zero is
+returned.

docs/libcurl/curl_mime_headers.md

@@ -80,4 +80,9 @@ int main(void)
 
 # RETURN VALUE
 
-CURLE_OK or a CURL error code upon failure.
+This function returns a CURLcode indicating success or error.
+
+CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3). If CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3)
+there can be an error message stored in the error buffer when non-zero is
+returned.

docs/libcurl/curl_mime_name.md

@@ -69,4 +69,9 @@ int main(void)
 
 # RETURN VALUE
 
-CURLE_OK or a CURL error code upon failure.
+This function returns a CURLcode indicating success or error.
+
+CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3). If CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3)
+there can be an error message stored in the error buffer when non-zero is
+returned.

docs/libcurl/curl_mime_subparts.md

@@ -85,4 +85,9 @@ int main(void)
 
 # RETURN VALUE
 
-CURLE_OK or a CURL error code upon failure.
+This function returns a CURLcode indicating success or error.
+
+CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3). If CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3)
+there can be an error message stored in the error buffer when non-zero is
+returned.

docs/libcurl/curl_mime_type.md

@@ -88,4 +88,9 @@ int main(void)
 
 # RETURN VALUE
 
-CURLE_OK or a CURL error code upon failure.
+This function returns a CURLcode indicating success or error.
+
+CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3). If CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3)
+there can be an error message stored in the error buffer when non-zero is
+returned.

docs/libcurl/curl_multi_add_handle.md

@@ -88,4 +88,7 @@ int main(void)
 
 # RETURN VALUE
 
-CURLMcode type, general libcurl multi interface error code.
+This function returns a CURLMcode indicating success or error.
+
+CURLM_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3).

docs/libcurl/curl_multi_assign.md

@@ -81,4 +81,7 @@ do not have to find the struct associated with this socket by ourselves.
 
 # RETURN VALUE
 
-The standard CURLMcode for multi interface error codes.
+This function returns a CURLMcode indicating success or error.
+
+CURLM_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3).

docs/libcurl/curl_multi_cleanup.md

@@ -70,5 +70,7 @@ int main(void)
 
 # RETURN VALUE
 
-CURLMcode type, general libcurl multi interface error code. On success,
+This function returns a CURLMcode indicating success or error.
-CURLM_OK is returned.
+
+CURLM_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3).

docs/libcurl/curl_multi_fdset.md

@@ -119,5 +119,7 @@ int main(void)
 
 # RETURN VALUE
 
-**CURLMcode** type, general libcurl multi interface error code. See
+This function returns a CURLMcode indicating success or error.
-libcurl-errors(3)
+
+CURLM_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3).

docs/libcurl/curl_multi_info_read.md

@@ -100,6 +100,6 @@ int main(void)
 
 # RETURN VALUE
 
-A pointer to a filled-in struct, or NULL if it failed or ran out of
+A pointer to a filled-in struct, or NULL if it failed or ran out of structs.
-structs. It also writes the number of messages left in the queue (after this
+It also writes the number of messages left in the queue (after this read) in
-read) in the integer the second argument points to.
+the integer the second argument points to.

docs/libcurl/curl_multi_perform.md

@@ -95,12 +95,15 @@ int main(void)
 
 # RETURN VALUE
 
-CURLMcode type, general libcurl multi interface error code.
+This function returns a CURLMcode indicating success or error.
+
+CURLM_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3).
 
 This function returns errors regarding the whole multi stack. Problems on
 individual transfers may have occurred even when this function returns
-*CURLM_OK*. Use curl_multi_info_read(3) to figure out how individual
+*CURLM_OK*. Use curl_multi_info_read(3) to figure out how individual transfers
-transfers did.
+did.
 
 # TYPICAL USAGE
 

docs/libcurl/curl_multi_poll.md

@@ -141,5 +141,7 @@ int main(void)
 
 # RETURN VALUE
 
-CURLMcode type, general libcurl multi interface error code. See
+This function returns a CURLMcode indicating success or error.
-libcurl-errors(3)
+
+CURLM_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3).

docs/libcurl/curl_multi_remove_handle.md

@@ -73,4 +73,7 @@ int main(void)
 
 # RETURN VALUE
 
-CURLMcode type, general libcurl multi interface error code.
+This function returns a CURLMcode indicating success or error.
+
+CURLM_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3).

docs/libcurl/curl_multi_setopt.md

@@ -124,6 +124,10 @@ int main(void)
 
 # RETURN VALUE
 
-The standard CURLMcode for multi interface error codes. Note that it returns a
+This function returns a CURLMcode indicating success or error.
-CURLM_UNKNOWN_OPTION if you try setting an option that this version of libcurl
+
-does not know of.
+CURLM_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3).
+
+Note that it returns a CURLM_UNKNOWN_OPTION if you try setting an option that
+this version of libcurl does not know of.

docs/libcurl/curl_multi_socket.md

@@ -79,7 +79,10 @@ curl_multi_socket(3) is deprecated, use curl_multi_socket_action(3) instead.
 
 # RETURN VALUE
 
-CURLMcode type, general libcurl multi interface error code.
+This function returns a CURLMcode indicating success or error.
+
+CURLM_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3).
 
 The return code is for the whole multi stack. Problems still might have
 occurred on individual transfers even when one of these functions return OK.

docs/libcurl/curl_multi_socket_action.md

@@ -119,5 +119,7 @@ int main(void)
 
 # RETURN VALUE
 
-CURLMcode type, general libcurl multi interface error code. See
+This function returns a CURLMcode indicating success or error.
-libcurl-errors(3)
+
+CURLM_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3).

docs/libcurl/curl_multi_socket_all.md

@@ -59,7 +59,10 @@ int main(void)
 
 # RETURN VALUE
 
-CURLMcode type, general libcurl multi interface error code.
+This function returns a CURLMcode indicating success or error.
+
+CURLM_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3).
 
 The return code is for the whole multi stack. Problems still might have
 occurred on individual transfers even when one of these functions return OK.

docs/libcurl/curl_multi_timeout.md

@@ -89,4 +89,7 @@ loop - until all transfers are complete.
 
 # RETURN VALUE
 
-The standard CURLMcode for multi interface error codes.
+This function returns a CURLMcode indicating success or error.
+
+CURLM_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3).

docs/libcurl/curl_multi_wait.md

@@ -120,5 +120,7 @@ int main(void)
 
 # RETURN VALUE
 
-CURLMcode type, general libcurl multi interface error code. See
+This function returns a CURLMcode indicating success or error.
-libcurl-errors(3)
+
+CURLM_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3).

docs/libcurl/curl_multi_waitfds.md

@@ -109,5 +109,7 @@ int main(void)
 
 # RETURN VALUE
 
-**CURLMcode** type, general libcurl multi interface error code. See
+This function returns a CURLMcode indicating success or error.
-libcurl-errors(3)
+
+CURLM_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3).

docs/libcurl/curl_multi_wakeup.md

@@ -91,4 +91,7 @@ int main(void)
 
 # RETURN VALUE
 
-CURLMcode type, general libcurl multi interface error code.
+This function returns a CURLMcode indicating success or error.
+
+CURLM_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3).

docs/libcurl/curl_url_dup.md

@@ -56,4 +56,4 @@ int main(void)
 
 # RETURN VALUE
 
-Returns a new handle or NULL if out of memory.
+Returns a pointer to a new `CURLU` handle or NULL if out of memory.

docs/libcurl/curl_url_get.md

@@ -243,7 +243,6 @@ int main(void)
 # RETURN VALUE
 
 Returns a CURLUcode error value, which is CURLUE_OK (0) if everything went
-fine. See the libcurl-errors(3) man page for the full list with
+fine. See the libcurl-errors(3) man page for the full list with descriptions.
-descriptions.
 
 If this function returns an error, no URL part is returned.

docs/libcurl/curl_ws_recv.md

@@ -67,9 +67,14 @@ int main(void)
 
 # RETURN VALUE
 
-Returns **CURLE_OK** if everything is okay, and a non-zero number for
+This function returns a CURLcode indicating success or error.
-errors. Returns **CURLE_GOT_NOTHING** if the associated connection is
+
-closed.
+CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3). If CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3)
+there can be an error message stored in the error buffer when non-zero is
+returned.
+
+Returns **CURLE_GOT_NOTHING** if the associated connection is closed.
 
 Instead of blocking, the function returns **CURLE_AGAIN**. The correct
 behavior is then to wait for the socket to signal readability before calling

docs/libcurl/curl_ws_send.md

@@ -120,6 +120,9 @@ int main(void)
 
 # RETURN VALUE
 
-*CURLE_OK* (zero) means that the data was sent properly, non-zero means an
+This function returns a CURLcode indicating success or error.
-error occurred as *\<curl/curl.h\>* defines. See the libcurl-errors(3) man
+
-page for the full list with descriptions.
+CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
+libcurl-errors(3). If CURLOPT_ERRORBUFFER(3) was set with curl_easy_setopt(3)
+there can be an error message stored in the error buffer when non-zero is
+returned.