MPI_Info_get_string "provided buffer" is ambiguous

[jeffhammond]

This should be an erratum.

Problem

In the definition of MPI_Info_get_string,

This function retrieves the value associated with key from info, if any. If such a key exists in info, it sets flag to true and returns the value in value, otherwise it sets flag to false and leaves value unchanged. buflen on input is the size of the provided buffer, for the output of buflen it is the size of the buffer needed to store the value string. If the buflen passed into the function is less than the actual size needed to store the value string (including null terminator in C), the value is truncated. On return, the value of buflen will be set to the required buffer size to hold the value string. If buflen is set to 0, value is not changed. In C, buflen includes the required space for the null terminator. In C, this function returns a null terminated string in all cases where the buflen input value is greater than 0.

the term "the provided buffer" is ambiguous, since this function takes two buffer arguments.

Proposal

Say something that indicates which provided buffer is being discussed.

Changes to the Text

Replace "the provided buffer" with "value" or "the provided output buffer, value," or anything else that makes the text unambiguous.

Impact on Implementations

None

Impact on Users

Makes the standard easier to understand.

References and Pull Requests

[wesbland]

This wasn't read at the December 2022 meeting. The last opportunity for MPI 4.1 is to have it ready at the March 2022 meeting (and it needs to "pass" the reading).

@schulzm / @jeffhammond Are you (or is someone else) planning to push this forward or should we move it out of the plan for MPI 4.1?

[jeffhammond]

i think this is a chapter committee change. it is trivial and changes nothing. it is just an editorial edit to make it easy for readers.

[jeffhammond]

i filed this ticket because i am implementing an MPI F08 module from scratch, and when i went to implement this function, i was confused by this text.

[wesbland]

Fair point. If this is an errata or a chapter committee change, there's more time to get this in. However, the point about needing an owner was really what I was getting at. If someone doesn't say they're going to write the text, it won't get done. 😄

[regrant]

I agree that this is a chapter committee change. If we just do the ", value," addition, it's trivial and we can get it done in chapter committee as long as @schulzm agrees. I'm happy to track this and get the change put in during the chapter cleanup for 4.1

[regrant]

@wesbland @jeffhammond the fix for the chapter committee is now linked as a pull request, so we can make sure this gets included in 4.1.

[schulzm]

Thanks for putting this is in - I only suggested a small tweak, and I agree, this could be a CC change