doc: some returned in-memory data may not be altered

Some public prototypes do not declare return values or out parameters as
const where they should be. Avoid changing the public interface, but
document those values as read-only.

Closes #19692

docs/libcurl/curl_easy_escape.md

@@ -30,7 +30,8 @@ char *curl_easy_escape(CURL *curl, const char *string, int length);
 This function converts the given input *string* to a URL encoded string and
 returns that as a new allocated string. All input characters that are not a-z,
 A-Z, 0-9, '-', '.', '_' or '~' are converted to their "URL escaped" version
-(**%NN** where **NN** is a two-digit hexadecimal number).
+(**%NN** where **NN** is a two-digit hexadecimal number). Although not
+constrained by its type, the returned string may not be altered.
 
 If *length* is set to 0 (zero), curl_easy_escape(3) uses strlen() on the input
 *string* to find out the size. This function does not accept input strings

docs/libcurl/curl_easy_unescape.md

@@ -30,7 +30,8 @@ char *curl_easy_unescape(CURL *curl, const char *input,
 This function converts the URL encoded string **input** to a "plain string"
 and returns that in an allocated memory area. All input characters that are URL
 encoded (%XX where XX is a two-digit hexadecimal number) are converted to their
-binary versions.
+binary versions. Although not constrained by its type, the returned data may
+not be altered.
 
 If the **length** argument is set to 0 (zero), curl_easy_unescape(3)
 uses strlen() on **input** to find out the size.

docs/libcurl/curl_escape.md

@@ -31,7 +31,8 @@ Obsolete function. Use curl_easy_escape(3) instead.
 This function converts the given input **string** to a URL encoded string
 and return that as a new allocated string. All input characters that are not
 a-z, A-Z or 0-9 are converted to their "URL escaped" version (**%NN** where
-**NN** is a two-digit hexadecimal number).
+**NN** is a two-digit hexadecimal number). Although not constrained by its
+type, the returned string may not be altered.
 
 If the **length** argument is set to 0, curl_escape(3) uses strlen()
 on **string** to find out the size.

docs/libcurl/curl_getenv.md

@@ -29,7 +29,8 @@ curl_getenv() is a portable wrapper for the getenv() function, meant to
 emulate its behavior and provide an identical interface for all operating
 systems libcurl builds on (including Windows).
 
-You must curl_free(3) the returned string when you are done with it.
+You must curl_free(3) the returned string when you are done with it and,
+although not constrained by its type, it may not be altered.
 
 # %PROTOCOLS%
 

docs/libcurl/curl_mprintf.md

@@ -67,7 +67,7 @@ the value of *ap* is undefined after the call.
 
 The functions **curl_maprintf()** and **curl_mvaprintf()** return the
 output string as pointer to a newly allocated memory area. The returned string
-must be curl_free(3)ed by the receiver.
+may not be overwritten and must be curl_free(3)ed by the receiver.
 
 All of these functions write the output under the control of a format string
 that specifies how subsequent arguments are converted for output.

docs/libcurl/curl_multi_get_handles.md

@@ -41,7 +41,8 @@ are out of sync.
 
 The order of the easy handles within the array is not guaranteed.
 
-The returned array must be freed with a call to curl_free(3) after use.
+The returned array may not be overwritten and must be freed with a call to
+curl_free(3) after use.
 
 # %PROTOCOLS%
 

docs/libcurl/curl_pushheader_byname.md

@@ -33,7 +33,8 @@ elsewhere and it has no function then.
 It returns the value for the given header field name (or NULL) for the
 incoming server push request. This is a shortcut so that the application does
 not have to loop through all headers to find the one it is interested in. The
-data this function points to is freed when this callback returns. If more than
+data this function points to is freed when this callback returns and,
+although not constrained by its type, may not be altered. If more than
 one header field use the same name, this returns only the first one.
 
 # %PROTOCOLS%

docs/libcurl/curl_pushheader_bynum.md

@@ -33,7 +33,8 @@ elsewhere and it has no function then.
 It returns the value for the header field at the given index **num**, for
 the incoming server push request or NULL. The data pointed to is freed by
 libcurl when this callback returns. The returned pointer points to a
-"name:value" string that gets freed when this callback returns.
+"name:value" string that gets freed when this callback returns; although
+not constrained by its type, this string may not be altered.
 
 # %PROTOCOLS%
 

docs/libcurl/curl_slist_append.md

@@ -33,8 +33,8 @@ new list. The specified **string** has been appended when this function
 returns. curl_slist_append(3) copies the string. The **string** argument must
 be a valid string pointer and cannot be NULL.
 
-The list should be freed again (after usage) with
-curl_slist_free_all(3).
+The list should be freed (after usage) with curl_slist_free_all(3).
+Its nodes and pointed content may not be altered outside this function.
 
 # %PROTOCOLS%
 

docs/libcurl/curl_unescape.md

@@ -33,7 +33,8 @@ Deprecated. Use curl_easy_unescape(3) instead.
 This function converts the URL encoded string **input** to a "plain string"
 and return that as a new allocated string. All input characters that are URL
 encoded (%XX where XX is a two-digit hexadecimal number) are converted to
-their plain text versions.
+their plain text versions. Although not constrained by its type, the returned
+data may not be altered.
 
 If the **length** argument is set to 0, curl_unescape(3) calls
 strlen() on **input** to find out the size.

docs/libcurl/curl_url.md

@@ -38,6 +38,9 @@ single URL. When the object is first created, there is of course no components
 stored. They are then set in the object with the curl_url_set(3)
 function.
 
+The object must be destroyed with a call to curl_url_cleanup(3) when no
+longer needed.
+
 # %PROTOCOLS%
 
 # EXAMPLE

docs/libcurl/curl_url_get.md

@@ -43,6 +43,7 @@ allocated string with the contents.
 The *flags* argument is a bitmask with individual features.
 
 The returned content pointer must be freed with curl_free(3) after use.
+Although not constrained by its type, the pointed string may not be altered.
 
 # FLAGS