Debian Codegraph @

upstream/debian-unstable/man3/bzero.3

raw
1 '\" t
2 .\" Copyright 2017, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH bzero 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 bzero, explicit_bzero \- zero a byte string
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <strings.h>
16 .P
17 .BR "void bzero(" "size_t n;"
18 .BI " void " s [ n "], size_t " n );
19 .P
20 .B #include <string.h>
21 .P
22 .BR "void explicit_bzero(" "size_t n;"
23 .BI " void " s [ n "], size_t " n );
24 .fi
25 .SH DESCRIPTION
26 The
27 .BR bzero ()
28 function erases the data in the
29 .I n
30 bytes of the memory starting at the location pointed to by
31 .IR s ,
32 by writing zeros (bytes containing \[aq]\[rs]0\[aq]) to that area.
33 .P
34 The
35 .BR explicit_bzero ()
36 function performs the same task as
37 .BR bzero ().
38 It differs from
39 .BR bzero ()
40 in that it guarantees that compiler optimizations will not remove the
41 erase operation if the compiler deduces that the operation is "unnecessary".
42 .SH RETURN VALUE
43 None.
44 .SH ATTRIBUTES
45 For an explanation of the terms used in this section, see
46 .BR attributes (7).
47 .TS
48 allbox;
49 lbx lb lb
50 l l l.
51 Interface Attribute Value
52 T{
53 .na
54 .nh
55 .BR bzero (),
56 .BR explicit_bzero ()
57 T} Thread safety MT-Safe
58 .TE
59 .SH STANDARDS
60 None.
61 .SH HISTORY
62 .TP
63 .BR explicit_bzero ()
64 glibc 2.25.
65 .IP
66 The
67 .BR explicit_bzero ()
68 function is a nonstandard extension that is also present on some of the BSDs.
69 Some other implementations have a similar function, such as
70 .BR memset_explicit ()
71 or
72 .BR memset_s ().
73 .TP
74 .BR bzero ()
75 4.3BSD.
76 .IP
77 Marked as LEGACY in POSIX.1-2001.
78 Removed in POSIX.1-2008.
79 .SH NOTES
80 The
81 .BR explicit_bzero ()
82 function addresses a problem that security-conscious applications
83 may run into when using
84 .BR bzero ():
85 if the compiler can deduce that the location to be zeroed will
86 never again be touched by a
87 .I correct
88 program, then it may remove the
89 .BR bzero ()
90 call altogether.
91 This is a problem if the intent of the
92 .BR bzero ()
93 call was to erase sensitive data (e.g., passwords)
94 to prevent the possibility that the data was leaked
95 by an incorrect or compromised program.
96 Calls to
97 .BR explicit_bzero ()
98 are never optimized away by the compiler.
99 .P
100 The
101 .BR explicit_bzero ()
102 function does not solve all problems associated with erasing sensitive data:
103 .IP \[bu] 3
104 The
105 .BR explicit_bzero ()
106 function does
107 .I not
108 guarantee that sensitive data is completely erased from memory.
109 (The same is true of
110 .BR bzero ().)
111 For example, there may be copies of the sensitive data in
112 a register and in "scratch" stack areas.
113 The
114 .BR explicit_bzero ()
115 function is not aware of these copies, and can't erase them.
116 .IP \[bu]
117 In some circumstances,
118 .BR explicit_bzero ()
119 can
120 .I decrease
121 security.
122 If the compiler determined that the variable containing the
123 sensitive data could be optimized to be stored in a register
124 (because it is small enough to fit in a register,
125 and no operation other than the
126 .BR explicit_bzero ()
127 call would need to take the address of the variable), then the
128 .BR explicit_bzero ()
129 call will force the data to be copied from the register
130 to a location in RAM that is then immediately erased
131 (while the copy in the register remains unaffected).
132 The problem here is that data in RAM is more likely to be exposed
133 by a bug than data in a register, and thus the
134 .BR explicit_bzero ()
135 call creates a brief time window where the sensitive data is more
136 vulnerable than it would otherwise have been
137 if no attempt had been made to erase the data.
138 .P
139 Note that declaring the sensitive variable with the
140 .B volatile
141 qualifier does
142 .I not
143 eliminate the above problems.
144 Indeed, it will make them worse, since, for example,
145 it may force a variable that would otherwise have been optimized
146 into a register to instead be maintained in (more vulnerable)
147 RAM for its entire lifetime.
148 .P
149 Notwithstanding the above details, for security-conscious applications, using
150 .BR explicit_bzero ()
151 is generally preferable to not using it.
152 The developers of
153 .BR explicit_bzero ()
154 anticipate that future compilers will recognize calls to
155 .BR explicit_bzero ()
156 and take steps to ensure that all copies of the sensitive data are erased,
157 including copies in registers or in "scratch" stack areas.
158 .SH SEE ALSO
159 .BR bstring (3),
160 .BR memset (3),
161 .BR swab (3)