libc/string: Add explicit_bzero() from OpenBSD.
[dragonfly.git] / lib / libc / string / bzero.3
CommitLineData
984263bc
MD
1.\" Copyright (c) 1990, 1991, 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" This code is derived from software contributed to Berkeley by
5.\" Chris Torek.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\" notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\" notice, this list of conditions and the following disclaimer in the
14.\" documentation and/or other materials provided with the distribution.
dc71b7ab 15.\" 3. Neither the name of the University nor the names of its contributors
984263bc
MD
16.\" may be used to endorse or promote products derived from this software
17.\" without specific prior written permission.
18.\"
19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29.\" SUCH DAMAGE.
30.\"
31.\" @(#)bzero.3 8.1 (Berkeley) 6/4/93
0d5acd74 32.\" $FreeBSD: head/lib/libc/string/bzero.3 251069 2013-05-28 20:57:40Z emaste $
984263bc 33.\"
c1f23d16 34.Dd April 11, 2019
984263bc
MD
35.Dt BZERO 3
36.Os
37.Sh NAME
c1f23d16 38.Nm bzero ,
39.Nm explicit_bzero
984263bc
MD
40.Nd write zeroes to a byte string
41.Sh LIBRARY
42.Lb libc
43.Sh SYNOPSIS
716024cd 44.In strings.h
984263bc
MD
45.Ft void
46.Fn bzero "void *b" "size_t len"
c1f23d16 47.Ft void
48.Fn explicit_bzero "void *b" "size_t len"
984263bc
MD
49.Sh DESCRIPTION
50The
51.Fn bzero
c1f23d16 52function writes
984263bc
MD
53.Fa len
54zero bytes to the string
55.Fa b .
56If
57.Fa len
58is zero,
59.Fn bzero
60does nothing.
c1f23d16 61.Pp
62The
63.Fn explicit_bzero
64variant behaves the same, but will not be removed by a compiler's dead store
65optimization pass, making it useful for clearing sensitive memory such as a
66password.
984263bc
MD
67.Sh SEE ALSO
68.Xr memset 3 ,
69.Xr swab 3
c1f23d16 70.Sh STANDARDS
71The
72.Fn bzero
73function conforms to the X/Open System Interfaces option of the
74.St -p1003.1-2004
75specification.
76It was removed from the standard in
77.St -p1003.1-2008 ,
78which recommends using
79.Xr memset 3
80instead.
984263bc 81.Sh HISTORY
c1f23d16 82The
984263bc 83.Fn bzero
c1f23d16 84function appeared in
984263bc 85.Bx 4.3 .
716024cd
PA
86Its prototype existed previously in
87.In string.h
88before it was moved to
89.In strings.h
90for
91.St -p1003.1-2001
92compliance.
c1f23d16 93.Pp
94The
95.Fn explicit_bzero
96function first appeared in
97.Ox 5.5
98and
99.Dx 5.6 .