curl_easy_setopt man page: Clarification about passed in string storage

[yaobinwen]

Hi,

I see many other issues use a template that has "I did this" and "I expect the following" to report bugs. This issue is not about a bug but I'm hoping for some clarification about the document of curl_easy_setopt. So I'm not following that convention. The link to the code is here.

My Confusion

The doc says:

Strings passed to libcurl as 'char *' arguments, are copied by the library; thus the string storage associated to the pointer argument may be overwritten after curl_easy_setopt returns.

I was confused by the words "... may be overwritten ..." when I initially read it because the sentence doesn't explicitly mention the actor of "overwrite". As a result, being a non-English speaker myself, my first impression was "the string storage could be overwritten (by curl_easy_setopt) after curl_easy_setopt returns", which confused me a little bit because the previous sentence just said "copied by the library".

After reading the entire page, I think the words mean:

• 1). libcurl creates a copy of the strings.
• 2). When curl_easy_setopt returns, the caller doesn't have to keep the string storage available and can either discard the string storage or overwrite it with other content.

Am I understanding the document correctly?

My Suggestion

If my understanding above is correct, can we refine the document as follows?

Firstly, avoid using "... may be overwritten ..." but clearly state what the programmer can do with the string storage. Something like below:

Strings passed to libcurl as 'char *' arguments, are copied by the library; thus the user can either discard the string storage or reuse it for other content after curl_easy_setopt returns.

Or, if passive voice is preferred, the doc could be refined as follows:

Strings passed to libcurl as 'char *' arguments, are copied by the library; thus the string storage associated to the pointer argument may be either discarded or reused for other content after curl_easy_setopt returns.

Secondly, put the note "Before version 7.17.0, strings were not copied." right after the sentence above in order to create a closer link. So my final suggestion is:

(In active voice)

Strings passed to libcurl as 'char *' arguments, are copied by the library; thus the user can either discard the string storage or reuse it for other things after curl_easy_setopt returns. In contrast, before version 7.17.0, strings were not copied so the user was forced keep them available until libcurl no longer needed them. The only exception to this rule is ... (the rest of the paragraph).

(In passive voice)

Strings passed to libcurl as 'char *' arguments, are copied by the library; thus the string storage associated to the pointer argument may be either discarded or reused for other content after curl_easy_setopt returns. In contrast, before version 7.17.0, strings were not copied so the user was forced keep them available until libcurl no longer needed them. The only exception to this rule is ... (the rest of the paragraph).

[bagder]

put the note "Before version 7.17.0, strings were not copied." right after the sentence

I don't think this piece is necessary. Primarily because 7.17.0 is such an old version that this basically doesn't affect any existing user.