This diff adds memset_s(3) doc, which was discovered missing while working on another revision. It's been in two of my trees for a while and should be committed before inadvertently committed with something else.
This case is a little weird and probably should be fully documented.
If the overflow would occur, the memset() is still applied to the region of length destsz. Afterwards, the constraint handler / error is thrown.
set_constraint_handler_s is probably worth documenting and Xring here.
Agreed that buffer overrun should probably be documented in memset.3. Trying to keep the description as brief as possible, does this look good?
Access beyond the end of the b array will result in corruption of neigbouring memory (stack or heap).
Unfortunately set_constraint_handler_s is not documented in our tree -- and yes it should be documented. Should this revision and the revision implementing gets_s (D12785) block pending documentation of set_constraint_handler_s?
No, that's inaccurate.
Something like: If .Fn memset_s is called with len greater than destsz, the memset is first applied as if the len parameter was destsz. Then the error condition is thrown and the constraint handler invoked.
No, I don't think there's any particular reason to force an ordering. I'd just like it to be documented eventually.
FYI http://en.cppreference.com/w/c/string/byte/memset describes it well, I think:
All requested changes have been incorporated.
Unfortunately I might not be able to separate out memset_s changes from general memset doc changes prior to commit.
Let me know what you think.
I can soften it a bit. How does this sound?
For this reason it is not advised to use
I think it is better to give advise what to do instead of what to avoid.
For this reason it is advised to use memset_s(), instead of memset(), to clear subsequently unreferenced memory. For instance, a buffer containing the password should be cleared with memset_s() before free().
*Shrug*. constraint_handlers are really weird C APIs that no one uses, AFAIK.
or even "resulting from storage overflow"?
What is the .Sp macro? I don't think you need a macro to put a space after the comma; that should be the default behavior (multiple instances).
The order of arguments to .Xr is the other way -- .Xr explicit_bzero 3
I might put a comma after "(DSE)".
"On the other hand" might be too informal; an alternative would be "In contrast, .Fn memset may be optimized away if [...]"
"subsequently unreferenced memory" is an unusual phrasing; I might say "to clear memory that will not subsequently be accessed".
This ("Undefined behavior...value of destsz") is not even a complete sentence. I agree with kib; just remove it and the next sentence (which is at best confusing).