Differential D13682 Diff 38076 lib/libc/string/memset.3

Changeset View

Standalone View

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, resulting from storage overlay, will occur if
				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…
				.Fa len
				is greater than the the length of buffer
				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 dest .
				The behaviour is also undefined if the pointer
				.Fa dest
				is NULL.
				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…
				.Pp
				The
				.Fn memset_s
				kibUnsubmitted Done Inline Actions .Dv RSIZE_MAX kib: .Dv RSIZE_MAX
				function behaves the same as
				bjkUnsubmitted Done Inline Actions maybe s/performs/behaves/? bjk: maybe s/performs/behaves/?
				.Fn memset
				except that an error is thrown and constraint handler is called if
				.Fa dest
				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_handler`s 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?
				is a null pointer,
				.Fa destsz
				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…
				or
				.Fa len
				is greater than
				.Dv RSIZE_MAX ,
				or
				.Sp
				.Fa len
				is greater than
				.Fa destsz
				(buffer overflow would occur).
				Like
				.Xr explicit_bzero 3 ,
				kibUnsubmitted Done Inline Actions What is this ? kib: What is this ?
				.Fn memset_s
				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
				is not removed through Dead Store Elimination (DSE), making it useful for
				kibUnsubmitted Done Inline Actions .Xr 3 explicit_bzero , kib: .Xr 3 explicit_bzero ,
				clearing sensitve data.
				bjkUnsubmitted Done Inline Actions I might put a comma after "(DSE)". bjk: I might put a comma after "(DSE)".
				In contrast
				.Fn memset
				function
				may be optimized away if the object modified by the function is not accessed
				again.
				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…
				To clear memory that will not subsequently be accessed it is advised to use
				kibUnsubmitted Done Inline Actions New line for new sentence. kib: New line for new sentence.
				.Fn memset_s
				instead of
				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 .
				For instance, a buffer containing a password should be cleared with
				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_s
				bjkUnsubmitted Done Inline Actions a password. bjk: a password.
				before
				.Xr free 3 .
				.Pp
				.Fa dest
				kibUnsubmitted Done Inline Actions perhaps .Xr 3 free . kib: perhaps .Xr 3 free .
				<
				.Fa len
				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 destsz
				can cause a buffer overrun.
	.Sh RETURN VALUES			.Sh RETURN VALUES
	The			The
				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…
	.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.