Page MenuHomeFreeBSD
Differential D13682 Diff 38374 lib/libc/string/memset.3

Changeset View

Standalone View

View Options

lib/libc/string/memset.3

Show All 37 Lines
.Sh NAME .Sh NAME
.Nm memset .Nm memset
.Nd write a byte to byte string .Nd write a byte to byte string
.Sh LIBRARY .Sh LIBRARY
.Lb libc .Lb libc
.Sh SYNOPSIS .Sh SYNOPSIS
.In string.h .In string.h
.Ft void * .Ft void *
.Fn memset "void *b" "int c" "size_t len" .Fn memset "void *dest" "int c" "size_t len"
.Ft errno_t
.Fn memset_s "void *dest" "rsize_t destsz" "int c" "rsize_t len"
.Sh DESCRIPTION .Sh DESCRIPTION
The The
.Fn memset .Fn memset
function function
writes writes
.Fa len .Fa len
bytes of value bytes of value
.Fa c .Fa c
(converted to an (converted to an
.Vt "unsigned char" ) .Vt "unsigned char" )
to the string to the string
.Fa b . .Fa dest .
Undefined behaviour from
kibUnsubmitted
Done
Inline Actions

resulting *from* storage overlay

kib: resulting *from* storage overlay
bjkUnsubmitted
Done
Inline Actions

or even "resulting from storage overflow"?

bjk: or even "resulting from storage overflow"?
cyAuthorUnsubmitted
Done
Inline Actions

yes, from is better.

overlay == overflow ... my exposure to IBM is beginning to show.

cy: yes, from is better. overlay == overflow ... my exposure to IBM is beginning to show.
kibUnsubmitted
Done
Inline Actions

overlay has very different meaning for me, referencing long time obsolete run-time linking technology.

kib: overlay has very different meaning for me, referencing long time obsolete run-time linking…
.Fn memset ,
resulting from storage overflow, will occur if
jillesUnsubmitted
Done
Inline Actions

memset_s() also differs from memset() in that it is not removed as a dead store, making it useful for clearing sensitive data such as a password, like explicit_bzero().

jilles: `memset_s()` also differs from `memset()` in that it is not removed as a dead store, making it…
.Fa len
is greater than the the length of buffer
.Fa dest .
The behaviour is also undefined if the pointer
kibUnsubmitted
Not Done
Inline Actions

is invalid, in particular
.Dv NULL .

kib: is invalid, in particular .Dv NULL .
kibUnsubmitted
Not Done
Inline Actions

This is not handled. Claiming that only NULL is undef is not correct.

kib: This is not handled. Claiming that only NULL is undef is not correct.
kibUnsubmitted
Not Done
Inline Actions

I still do not like that the text mention NULL pointer as undefined behavior, but does not say that invalid pointer is an unhandled undefined behavior as well, even for memset_s().

kib: I still do not like that the text mention NULL pointer as undefined behavior, but does not say…
cyAuthorUnsubmitted
Not Done
Inline Actions

I will reword this for memset().

memset_s() handles a NULL dest (memset_s.c line 48) but it does not handle dest being an invalid pointer. Also documented at http://en.cppreference.com/w/c/string/byte/memset.

I agree that it should be documented that memset_s() will otherwise not handle an invalid pointer.

cy: I will reword this for memset(). memset_s() handles a NULL dest (memset_s.c line 48) but it…
.Fa dest
is NULL.
.Pp
kibUnsubmitted
Done
Inline Actions

.Dv RSIZE_MAX

kib: .Dv RSIZE_MAX
The
bjkUnsubmitted
Done
Inline Actions

maybe s/performs/behaves/?

bjk: maybe s/performs/behaves/?
.Fn memset_s
function behaves the same as
.Fn memset
cemUnsubmitted
Not Done
Inline Actions

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.

cem: This case is a little weird and probably should be fully documented. If the overflow would…
cyAuthorUnsubmitted
Not Done
Inline Actions

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?

cy: Agreed that buffer overrun should probably be documented in memset.3. Trying to keep the…
cemUnsubmitted
Not Done
Inline Actions

Access beyond the end of the b array will result in corruption of neigbouring memory (stack or heap).

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.

Unfortunately set_constraint_handler_s is not documented in our tree -- and yes it should be documented.

Right.

Should this revision and the revision implementing gets_s (D12785) block pending documentation of set_constraint_handler_s?

No, I don't think there's any particular reason to force an ordering. I'd just like it to be documented eventually.

cem: > Access beyond the end of the b array will result in corruption of neigbouring memory (stack…
cemUnsubmitted
Not Done
Inline Actions

FYI http://en.cppreference.com/w/c/string/byte/memset describes it well, I think:

[Memset_s is the] Same as [memset], except that the following errors are detected at runtime and call the currently installed constraint handler function after storing ch in every location of the destination range [dest, dest+destsz) if dest and destsz are themselves valid: ...

cem: FYI http://en.cppreference.com/w/c/string/byte/memset describes it well, I think: > [Memset_s…
cyAuthorUnsubmitted
Not Done
Inline Actions

I think I'll revise memset and add memset_s doc.

cy: I think I'll revise `memset` and add `memset_s` doc.
cyAuthorUnsubmitted
Not Done
Inline Actions

Agreed. It should be documented. I'll put it on my list of things to do.

cy: Agreed. It should be documented. I'll put it on my list of things to do.
bjkUnsubmitted
Done
Inline Actions

Is "thrown" really a conventional word to use in this context? To me it has more connotations of (e.g., C++) exceptions than a C library's internals.

bjk: Is "thrown" really a conventional word to use in this context? To me it has more connotations…
cemUnsubmitted
Done
Inline Actions

*Shrug*. constraint_handlers are really weird C APIs that no one uses, AFAIK.

C11:

Implementations shall verify that the runtime-constraints for a function are not violated by the program. If a runtime-constraint is violated, the implementation shall call the currently registered runtime-constraint handler (see set_constraint_handler_s in <stdlib.h>).

...

The runtime-constraint handler might not return.

...

The abort_handler_s function writes a message on the standard error stream in an implementation-defined format. The message shall include the string pointed to by msg. The abort_handler_s function then calls the abort function. 393)

cem: *Shrug*. `constraint_handler`s are really weird C APIs that no one uses, AFAIK. C11: >…
rpokalaUnsubmitted
Done
Inline Actions

"except that an error is returned, and the constraint handler is called, if"

rpokala: "except that an error is returned, and the constraint handler is called, if"
cyAuthorUnsubmitted
Not Done
Inline Actions

Can you review my new rewording?

cy: Can you review my new rewording?
except that an error is thrown and constraint handler is called if
.Fa dest
bjkUnsubmitted
Done
Inline Actions

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).

bjk: What is the .Sp macro? I don't think you need a macro to put a space after the comma; that…
kibUnsubmitted
Done
Inline Actions

Error handler is called first, and if it returns, the error is returned to the caller. The intent is that the handler does not return but performs the urgent process termination.

kib: Error handler is called first, and if it returns, the error is returned to the caller. The…
cyAuthorUnsubmitted
Not Done
Inline Actions

Rather than make that sentence even longer (and more confusing) I've added this sentence:

The runtime-constraint handler is called first and may not return.
If it does return, an error is returned to the caller.

cy: Rather than make that sentence even longer (and more confusing) I've added this sentence: The…
is a null pointer,
.Fa destsz
or
.Fa len
is greater than
.Dv RSIZE_MAX ,
or
.Sp
.Fa len
is greater than
.Fa destsz
(buffer overflow would occur).
kibUnsubmitted
Done
Inline Actions

What is this ?

kib: What is this ?
Like
bjkUnsubmitted
Done
Inline Actions

The order of arguments to .Xr is the other way -- .Xr explicit_bzero 3

bjk: The order of arguments to .Xr is the other way -- .Xr explicit_bzero 3
.Xr explicit_bzero 3 ,
kibUnsubmitted
Done
Inline Actions

.Xr 3 explicit_bzero ,

kib: .Xr 3 explicit_bzero ,
.Fn memset_s
bjkUnsubmitted
Done
Inline Actions

I might put a comma after "(DSE)".

bjk: I might put a comma after "(DSE)".
is not removed through Dead Store Elimination (DSE), making it useful for
clearing sensitve data.
In contrast
.Fn memset
function
bjkUnsubmitted
Done
Inline Actions

"On the other hand" might be too informal; an alternative would be "In contrast, .Fn memset may be optimized away if [...]"

bjk: "On the other hand" might be too informal; an alternative would be "In contrast, .Fn memset may…
may be optimized away if the object modified by the function is not accessed
kibUnsubmitted
Done
Inline Actions

New line for new sentence.

kib: New line for new sentence.
again.
To clear memory that will not subsequently be accessed it is advised to use
kibUnsubmitted
Done
Inline Actions

I would say that this claim is too wide. If you say ' ... clear memory not referenced after the memset call, e.g. immediately freed' it would be less eye-scratching.

kib: I would say that this claim is too wide. If you say ' ... clear memory not referenced after…
cyAuthorUnsubmitted
Done
Inline Actions

I can soften it a bit. How does this sound?

For this reason it is not advised to use
.Fn memset
to clear subsequently unreferenced memory, such as immediately freed memory (i.e used for passwords).

cy: I can soften it a bit. How does this sound? For this reason it is not advised to use .Fn…
kibUnsubmitted
Done
Inline Actions

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().

kib: I think it is better to give advise what to do instead of what to avoid. For this reason it is…
cyAuthorUnsubmitted
Not Done
Inline Actions

Agreed. Thank you.

cy: Agreed. Thank you.
.Fn memset_s
instead of
bjkUnsubmitted
Done
Inline Actions

"subsequently unreferenced memory" is an unusual phrasing; I might say "to clear memory that will not subsequently be accessed".

bjk: "subsequently unreferenced memory" is an unusual phrasing; I might say "to clear memory that…
.Fn memset .
bjkUnsubmitted
Done
Inline Actions

*a* password.

bjk: *a* password.
For instance, a buffer containing a password should be cleared with
.Fn memset_s
before
.Xr free 3 .
kibUnsubmitted
Done
Inline Actions

perhaps
.Xr 3 free .

kib: perhaps .Xr 3 free .
.Pp
.Fa dest
kibUnsubmitted
Done
Inline Actions

This and the next sentences are out of place, incomplete, and/or duplicates the previous text.

kib: This and the next sentences are out of place, incomplete, and/or duplicates the previous text.
<
bjkUnsubmitted
Done
Inline Actions

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).

bjk: This ("Undefined behavior...value of destsz") is not even a complete sentence. I agree with…
.Fa len
<=
.Fa destsz
can cause a buffer overrun.
kibUnsubmitted
Done
Inline Actions

I do not understand this sentence at all. Why do you compare pointers with length, what should it mean etc.

kib: I do not understand this sentence at all. Why do you compare pointers with length, what should…
cyAuthorUnsubmitted
Not Done
Inline Actions

This would be better said:

A short
.Fa destsz
may result in a buffer overflow.

However I say this in the previous paragraph. I'll simply remove it.

cy: This would be better said: A short .Fa destsz may result in a buffer overflow. However I say…
.Sh RETURN VALUES .Sh RETURN VALUES
The The
.Fn memset .Fn memset
function returns its first argument. function returns its first argument.
The
.Fn memset_s
function returns zero on success, non-zero on error.
.Sh SEE ALSO .Sh SEE ALSO
.Xr bzero 3 , .Xr bzero 3 ,
.Xr explicit_bzero 3 ,
.Xr swab 3 , .Xr swab 3 ,
.Xr wmemset 3 .Xr wmemset 3
.Sh STANDARDS .Sh STANDARDS
The The
.Fn memset .Fn memset
function function
conforms to conforms to
.St -isoC . .St -isoC .
.Fn memset_s
conforms to:
.St -isoC-2011
K.3.7.4.1.