Differential D13682 Diff 39376 head/lib/libc/string/memset.3

Changeset View

Standalone View

head/lib/libc/string/memset.3

	Show All 26 Lines
	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT			.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY			.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF			.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	.\" SUCH DAMAGE.			.\" SUCH DAMAGE.
	.\"			.\"
	.\" @(#)memset.3 8.1 (Berkeley) 6/4/93			.\" @(#)memset.3 8.1 (Berkeley) 6/4/93
	.\" $FreeBSD$			.\" $FreeBSD$
	.\"			.\"
	.Dd June 4, 1993			.Dd February 15, 2018
	.Dt MEMSET 3			.Dt MEMSET 3
	.Os			.Os
	.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
				.Fn memset ,
				resulting from storage overflow, will occur if
				.Fa len
				is greater than the the length of buffer
				.Fa dest .
				The behaviour is also undefined if
				.Fa dest
				is an invalid pointer.
				.Pp
				The
				.Fn memset_s
				function behaves the same as
				.Fn memset
				except that an error is returned and the currently registered
				runtime-constraint handler is called if
				.Fa dest
				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).
				The runtime-constraint handler is called first and may not return.
				If it does return, an error is returned to the caller.
				Like
				.Xr explicit_bzero 3 ,
				.Fn memset_s
				is not removed through Dead Store Elimination (DSE), making it useful for
				clearing sensitve data.
				In contrast
				.Fn memset
				function
				may be optimized away if the object modified by the function is not accessed
				again.
				To clear memory that will not subsequently be accessed it is advised to use
				.Fn memset_s
				instead of
				.Fn memset .
				For instance, a buffer containing a password should be cleared with
				.Fn memset_s
				before
				.Xr free 3 .
	.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.