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

diff --git a/docs/libcurl/curl_easy_escape.md b/docs/libcurl/curl_easy_escape.md
index b10500ac261950628092a7f75c57461cb919f685..1480a75c591acdc491a3ddacb58018071e7b49b3 100644 (file)
--- a/docs/libcurl/curl_easy_escape.md
+++ b/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

diff --git a/docs/libcurl/curl_easy_unescape.md b/docs/libcurl/curl_easy_unescape.md
index 2e78ad5d9f074af6d71fa882043310c56ce2e7c2..49e4c6bf269ac22579f08ff1164aebb3f09b9dd5 100644 (file)
--- a/docs/libcurl/curl_easy_unescape.md
+++ b/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.

diff --git a/docs/libcurl/curl_escape.md b/docs/libcurl/curl_escape.md
index c24d1890d493161b0088992002983538f9865b5c..967d375a97587fe87d7d8a9943827b342ff327e1 100644 (file)
--- a/docs/libcurl/curl_escape.md
+++ b/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.

diff --git a/docs/libcurl/curl_getenv.md b/docs/libcurl/curl_getenv.md
index 2cfb58148ce73df18e96d2085df2c66eb9cca960..047c913f2530ef1d9401f21004121c1c007ae5af 100644 (file)
--- a/docs/libcurl/curl_getenv.md
+++ b/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%
 

diff --git a/docs/libcurl/curl_mprintf.md b/docs/libcurl/curl_mprintf.md
index 4f5c090579ba397087fe2bc1c6e59a264a93ea9f..a592cfb3e6615ffeeba8671e4f59cb6690fce394 100644 (file)
--- a/docs/libcurl/curl_mprintf.md
+++ b/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.

diff --git a/docs/libcurl/curl_multi_get_handles.md b/docs/libcurl/curl_multi_get_handles.md
index f94436a889ba914ade35a6dd8ef5141a18aa0e19..56da272b8abf8defe3451b82ac83a6d2271eaa4e 100644 (file)
--- a/docs/libcurl/curl_multi_get_handles.md
+++ b/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%
 

diff --git a/docs/libcurl/curl_pushheader_byname.md b/docs/libcurl/curl_pushheader_byname.md
index d066ea7b85b5e6ef461cbcac7d2c4b4ff6263865..e2968fcd4621771b74a058c6db51c14fc651371f 100644 (file)
--- a/docs/libcurl/curl_pushheader_byname.md
+++ b/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%

diff --git a/docs/libcurl/curl_pushheader_bynum.md b/docs/libcurl/curl_pushheader_bynum.md
index 12555c57f0c158f474786b30221235eb80ef0ffe..2431ff446bb1fe10ead2055e5f881211fd82a1c3 100644 (file)
--- a/docs/libcurl/curl_pushheader_bynum.md
+++ b/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%
 

diff --git a/docs/libcurl/curl_slist_append.md b/docs/libcurl/curl_slist_append.md
index b2766f728db090e2961bdfc9ed9f7d74e756eabf..3ebc19e354189bbfcc9fa7d6dd84892c848cc78f 100644 (file)
--- a/docs/libcurl/curl_slist_append.md
+++ b/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%
 

diff --git a/docs/libcurl/curl_unescape.md b/docs/libcurl/curl_unescape.md
index 2600f1436110df277f465f0481cca820bb8999b7..453fd53145b9c48bd43f4ff0d23b1a537e6b78ca 100644 (file)
--- a/docs/libcurl/curl_unescape.md
+++ b/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.

diff --git a/docs/libcurl/curl_url.md b/docs/libcurl/curl_url.md
index 5872134e139a56ccca725fd88022d069d0997032..8053e630b8af6973768404899e2b79c2fcb5b8c1 100644 (file)
--- a/docs/libcurl/curl_url.md
+++ b/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

diff --git a/docs/libcurl/curl_url_get.md b/docs/libcurl/curl_url_get.md
index a9bb0bdc23fb956cdd07f97404961009263fce37..bed1c02f17471d2f097bbe909a30a4c563787758 100644 (file)
--- a/docs/libcurl/curl_url_get.md
+++ b/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