From: Daniel Stenberg Date: Tue, 16 Sep 2025 14:49:54 +0000 (+0200) Subject: docs/libcurl: use lowercase must X-Git-Tag: rc-8_17_0-1~372 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=3053a3e90f696dc1cfb481c61a2032dcc3b6c15c;p=thirdparty%2Fcurl.git docs/libcurl: use lowercase must To shout less. Use bold in some places. Closes #18570 --- diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_TYPE.md b/docs/libcurl/opts/CURLINFO_CONTENT_TYPE.md index 71e9c5122c..8a9093ced2 100644 --- a/docs/libcurl/opts/CURLINFO_CONTENT_TYPE.md +++ b/docs/libcurl/opts/CURLINFO_CONTENT_TYPE.md @@ -33,8 +33,8 @@ object. This is the value read from the Content-Type: field. If you get NULL, it means that the server did not send a valid Content-Type header or that the protocol used does not support this. -The **ct** pointer is set to NULL or pointing to private memory. You MUST -NOT free it - it gets freed when you call curl_easy_cleanup(3) on the +The **ct** pointer is NULL or points to private memory. You **must not** free +it. It gets freed automatically when you call curl_easy_cleanup(3) on the corresponding curl handle. The modern way to get this header from a response is to instead use the diff --git a/docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.md b/docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.md index 0a748063c6..5299dab8c1 100644 --- a/docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.md +++ b/docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.md @@ -35,9 +35,9 @@ method. In cases when you have asked libcurl to follow redirects, the method may not be the same method the first request would use. -The **methodp** pointer is NULL or points to private memory. You MUST NOT -free - it gets freed when you call curl_easy_cleanup(3) on the -corresponding curl handle. +The **methodp** pointer is NULL or points to private memory. You +**must not** free it. The memory gets freed automatically when you call +curl_easy_cleanup(3) on the corresponding curl handle. # %PROTOCOLS% diff --git a/docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.md b/docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.md index aa50901834..172f6de3d4 100644 --- a/docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.md +++ b/docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.md @@ -32,9 +32,9 @@ Pass in a pointer to a char pointer and get the last used effective URL. In cases when you have asked libcurl to follow redirects, it may not be the same value you set with CURLOPT_URL(3). -The **urlp** pointer is NULL or points to private memory. You MUST NOT free -- it gets freed when you call curl_easy_cleanup(3) on the corresponding curl -handle. +The **urlp** pointer is NULL or points to private memory. You **must not** +free it. It memory gets freed automatically when you call curl_easy_cleanup(3) +on the corresponding curl handle. # %PROTOCOLS% diff --git a/docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.md b/docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.md index 08b5a6d336..db053e311e 100644 --- a/docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.md +++ b/docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.md @@ -32,9 +32,9 @@ path of the entry path. That is the initial path libcurl ended up in when logging on to the remote FTP or SFTP server. This stores a NULL as pointer if something is wrong. -The **path** pointer is NULL or points to private memory. You MUST NOT free -- it gets freed when you call curl_easy_cleanup(3) on the corresponding curl -handle. +The **path** pointer is NULL or points to private memory. You **must not** +free it. The memory gets freed automatically when you call +curl_easy_cleanup(3) on the corresponding curl handle. # %PROTOCOLS% diff --git a/docs/libcurl/opts/CURLINFO_LOCAL_IP.md b/docs/libcurl/opts/CURLINFO_LOCAL_IP.md index a8b89914a0..c626815c90 100644 --- a/docs/libcurl/opts/CURLINFO_LOCAL_IP.md +++ b/docs/libcurl/opts/CURLINFO_LOCAL_IP.md @@ -35,9 +35,9 @@ with this **curl** handle. This string may be IPv6 when that is enabled. Note that you get a pointer to a memory area that is reused at next request so you need to copy the string if you want to keep the information. -The **ip** pointer is NULL or points to private memory. You MUST NOT free - it -gets freed when you call curl_easy_cleanup(3) on the corresponding CURL -handle. +The **ip** pointer is NULL or points to private memory. You **must not** free +it. The memory gets freed automatically when you call curl_easy_cleanup(3) on +the corresponding curl handle. # %PROTOCOLS% diff --git a/docs/libcurl/opts/CURLINFO_PRIMARY_IP.md b/docs/libcurl/opts/CURLINFO_PRIMARY_IP.md index e87be53e3c..1fdb130711 100644 --- a/docs/libcurl/opts/CURLINFO_PRIMARY_IP.md +++ b/docs/libcurl/opts/CURLINFO_PRIMARY_IP.md @@ -35,9 +35,9 @@ string holding the IP address of the most recent connection done with this get a pointer to a memory area that is reused at next request so you need to copy the string if you want to keep the information. -The **ip** pointer is NULL or points to private memory. You MUST NOT free - it -gets freed when you call curl_easy_cleanup(3) on the corresponding curl -handle. +The **ip** pointer is NULL or points to private memory. You **must not** free +it. The memory gets freed automatically when you call curl_easy_cleanup(3) on +the corresponding curl handle. # %PROTOCOLS% diff --git a/docs/libcurl/opts/CURLINFO_REFERER.md b/docs/libcurl/opts/CURLINFO_REFERER.md index bd278dd603..17b9db1a18 100644 --- a/docs/libcurl/opts/CURLINFO_REFERER.md +++ b/docs/libcurl/opts/CURLINFO_REFERER.md @@ -31,9 +31,9 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_REFERER, char **hdrp); Pass in a pointer to a char pointer and get the referrer header used in the most recent request. -The **hdrp** pointer is NULL or points to private memory you MUST NOT free - -it gets freed when you call curl_easy_cleanup(3) on the corresponding curl -handle. +The **hdrp** pointer is NULL or points to private memory. You **must not** +free it. The memory gets freed automatically when you call +curl_easy_cleanup(3) on the corresponding curl handle. # %PROTOCOLS% diff --git a/docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.md b/docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.md index c24f42b24d..121642677b 100644 --- a/docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.md +++ b/docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.md @@ -33,9 +33,9 @@ most recent RTSP Session ID. Applications wishing to resume an RTSP session on another connection should retrieve this info before closing the active connection. -The **id** pointer is NULL or points to private memory. You MUST NOT free - it -gets freed when you call curl_easy_cleanup(3) on the corresponding curl -handle. +The **id** pointer is NULL or points to private memory. You **must not** free +it. The memory gets freed automatically when you call curl_easy_cleanup(3) on +the corresponding curl handle. # %PROTOCOLS% diff --git a/docs/libcurl/opts/CURLINFO_SCHEME.md b/docs/libcurl/opts/CURLINFO_SCHEME.md index 0089531d01..1c61849829 100644 --- a/docs/libcurl/opts/CURLINFO_SCHEME.md +++ b/docs/libcurl/opts/CURLINFO_SCHEME.md @@ -33,9 +33,9 @@ Pass a pointer to a char pointer to receive the pointer to a null-terminated string holding the URL scheme used for the most recent connection done with this CURL **handle**. -The **scheme** pointer is NULL or points to private memory. You MUST NOT -free - it gets freed when you call curl_easy_cleanup(3) on the corresponding -curl handle. +The **scheme** pointer is NULL or points to private memory. You **must not** +free it. The memory gets freed automatically when you call +curl_easy_cleanup(3) on the corresponding curl handle. The returned scheme might be upper or lowercase. Do comparisons case insensitively. diff --git a/docs/libcurl/opts/CURLOPT_HEADERDATA.md b/docs/libcurl/opts/CURLOPT_HEADERDATA.md index bb3f2ed834..f767961cdc 100644 --- a/docs/libcurl/opts/CURLOPT_HEADERDATA.md +++ b/docs/libcurl/opts/CURLOPT_HEADERDATA.md @@ -36,9 +36,9 @@ If CURLOPT_WRITEFUNCTION(3) or CURLOPT_HEADERFUNCTION(3) is used, If neither of those options are set, *pointer* must be a valid FILE * and it is used by a plain fwrite() to write headers to. -If you are using libcurl as a Windows DLL, you **MUST** use a -CURLOPT_WRITEFUNCTION(3) or CURLOPT_HEADERFUNCTION(3) if you set -this option or you might experience crashes. +If you are using libcurl as a Windows DLL, you **must** use a +CURLOPT_WRITEFUNCTION(3) or CURLOPT_HEADERFUNCTION(3) if you set this option +or you might experience crashes. # DEFAULT diff --git a/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.md b/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.md index 29dc8bb4ff..d2dda82dd8 100644 --- a/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.md @@ -50,15 +50,15 @@ rewinding the read data stream is the only action it can request. The rewinding of the read data stream may be necessary when doing an HTTP PUT or POST with a multi-pass authentication method. -The callback MUST return *CURLIOE_UNKNOWNCMD* if the input *cmd* is -not *CURLIOCMD_RESTARTREAD*. +The callback **must** return *CURLIOE_UNKNOWNCMD* if the input *cmd* is not +*CURLIOCMD_RESTARTREAD*. -The *clientp* argument to the callback is set with the -CURLOPT_IOCTLDATA(3) option. +The *clientp* argument to the callback is set with the CURLOPT_IOCTLDATA(3) +option. **This option is deprecated**. Do not use it. Use CURLOPT_SEEKFUNCTION(3) -instead to provide seeking. If CURLOPT_SEEKFUNCTION(3) is set, this -parameter is ignored when seeking. +instead to provide seeking. If CURLOPT_SEEKFUNCTION(3) is set, this parameter +is ignored when seeking. # DEFAULT diff --git a/docs/libcurl/opts/CURLOPT_SHARE.md b/docs/libcurl/opts/CURLOPT_SHARE.md index c4488086a7..9b9a281e00 100644 --- a/docs/libcurl/opts/CURLOPT_SHARE.md +++ b/docs/libcurl/opts/CURLOPT_SHARE.md @@ -26,13 +26,12 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SHARE, CURLSH *share); # DESCRIPTION -Pass a *share* handle as a parameter. The share handle must have been -created by a previous call to curl_share_init(3). Setting this option, -makes this curl handle use the data from the shared handle instead of keeping -the data to itself. This enables several curl handles to share data. If the -curl handles are used simultaneously in multiple threads, you **MUST** use -the locking methods in the share handle. See curl_share_setopt(3) for -details. +Pass a *share* handle as a parameter. The share handle must have been created +by a previous call to curl_share_init(3). Setting this option, makes this curl +handle use the data from the shared handle instead of keeping the data to +itself. This enables several curl handles to share data. If the curl handles +are used simultaneously in multiple threads, you **must** use the locking +methods in the share handle. See curl_share_setopt(3) for details. If you add a share that is set to share cookies, your easy handle uses that cookie cache and get the cookie engine enabled. If you stop sharing an object diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYFUNCTION.md b/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYFUNCTION.md index 89422e4ef6..0f7e9996bd 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_SSH_HOSTKEYFUNCTION.md @@ -44,7 +44,7 @@ says what type it is, from the **CURLKHTYPE_*** series in the **clientp** is a custom pointer set with CURLOPT_SSH_HOSTKEYDATA(3). -The callback MUST return one of the following return codes to tell libcurl how +The callback must return one of the following return codes to tell libcurl how to act: ## CURLKHMATCH_OK diff --git a/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.md b/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.md index 636b7a3609..1e21b614f1 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.md +++ b/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.md @@ -68,7 +68,7 @@ called if CURLOPT_SSH_KNOWNHOSTS(3) is also set. This callback function gets passed the curl handle, the key from the known_hosts file *knownkey*, the key from the remote site *foundkey*, info from libcurl on the matching status and a custom pointer (set with -CURLOPT_SSH_KEYDATA(3)). It MUST return one of the following return codes to +CURLOPT_SSH_KEYDATA(3)). It must return one of the following return codes to tell libcurl how to act: ## CURLKHSTAT_FINE_REPLACE diff --git a/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.md b/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.md index 262c089794..07e7266da5 100644 --- a/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.md +++ b/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.md @@ -35,8 +35,8 @@ HTTP response sent using a compressed Transfer-Encoding that is automatically uncompressed by libcurl on reception. Transfer-Encoding differs slightly from the Content-Encoding you ask for with -CURLOPT_ACCEPT_ENCODING(3) in that a Transfer-Encoding is strictly meant -to be for the transfer and thus MUST be decoded before the data arrives in the +CURLOPT_ACCEPT_ENCODING(3) in that a Transfer-Encoding is strictly meant to be +for the transfer and thus must be decoded before the data arrives in the client. Traditionally, Transfer-Encoding has been much less used and supported by both HTTP clients and HTTP servers. diff --git a/docs/libcurl/opts/CURLOPT_WRITEDATA.md b/docs/libcurl/opts/CURLOPT_WRITEDATA.md index 5983de5d27..f6c6a2eeb9 100644 --- a/docs/libcurl/opts/CURLOPT_WRITEDATA.md +++ b/docs/libcurl/opts/CURLOPT_WRITEDATA.md @@ -36,7 +36,7 @@ to *fwrite(3)* when writing data. The internal CURLOPT_WRITEFUNCTION(3) writes the data to the FILE * given with this option, or to stdout if this option has not been set. -If you are using libcurl as a Windows DLL, you **MUST** use a +If you are using libcurl as a Windows DLL, you must also use CURLOPT_WRITEFUNCTION(3) if you set this option or you might experience crashes.