From: Patrick Monnerat Date: Mon, 24 Nov 2025 18:50:26 +0000 (+0100) Subject: doc: some returned in-memory data may not be altered X-Git-Tag: rc-8_18_0-1~155 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=92e6782d1f0dbf0f011fe01ecc4c17b4109561b2;p=thirdparty%2Fcurl.git 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 b10500ac26..1480a75c59 100644 --- 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 2e78ad5d9f..49e4c6bf26 100644 --- 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 c24d1890d4..967d375a97 100644 --- 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 2cfb58148c..047c913f25 100644 --- 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 4f5c090579..a592cfb3e6 100644 --- 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 f94436a889..56da272b8a 100644 --- 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 d066ea7b85..e2968fcd46 100644 --- 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 12555c57f0..2431ff446b 100644 --- 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 b2766f728d..3ebc19e354 100644 --- 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 2600f14361..453fd53145 100644 --- 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 5872134e13..8053e630b8 100644 --- 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 a9bb0bdc23..bed1c02f17 100644 --- 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