CURLOPT_SHARE docs incorrectly say cookie sharing enables the cookie engine

[cyanide-burnout]

Description

The CURLOPT_SHARE documentation currently says:

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 that was using cookies (or change to another object that does not share cookies), the easy handle gets its cookie engine disabled.

This contradicts the current CURLSHOPT_SHARE documentation, which says:

Cookie data is shared across the easy handles using this shared object. Note that this does not activate an easy handle's cookie handling. You can do that separately by using CURLOPT_COOKIEFILE for example.

It also contradicts the "Everything curl" share documentation, which says that each easy handle still needs to start its cookie engine, and the example on the CURLOPT_SHARE page itself, which sets CURLOPT_COOKIEFILE to an empty string on both easy handles.

Actual behavior

The implementation and observed behavior agree with CURLSHOPT_SHARE: attaching a share configured with CURL_LOCK_DATA_COOKIE supplies the shared cookie store but does not enable cookie handling for the easy handle. Without an explicit cookie-enabling option such as CURLOPT_COOKIEFILE set to an empty string, received Set-Cookie headers are not stored and cookies are not sent.

Historical context

This appears to be intentional behavior since 7.67.0. Issue #4429 addressed accidental cookie-engine activation, and the subsequent curl-library discussion explicitly states that each easy handle must enable its cookie engine separately:

https://curl.se/mail/lib-2020-03/0019.html

That discussion led to #5048, which clarified the CURLSHOPT_SHARE documentation. The corresponding statement in CURLOPT_SHARE appears to have remained unchanged.

Suggested change

Please remove or update the cookie-engine enable/disable statement in the CURLOPT_SHARE documentation so that it agrees with CURLSHOPT_SHARE, current behavior, and the example on the page.

Relevant pages:

• https://curl.se/libcurl/c/CURLOPT_SHARE.html
• https://curl.se/libcurl/c/CURLSHOPT_SHARE.html
• https://everything.curl.dev/share/what.html

[jay]

Thanks, I missed that in #5048. I'm proposing in #22790 to remove that incorrect explanation instead of changing it, because the explanations for all the CURL_LOCK_xxx are already documented in CURLSHOPT_SHARE.