root/trunk/umem_debug.3

Revision 30, 6.5 kB (checked in by wez, 7 years ago)

add man pages from opensolaris

Line 
1 '\" te
2 .\" CDDL HEADER START
3 .\"
4 .\" The contents of this file are subject to the terms of the
5 .\" Common Development and Distribution License (the "License"). 
6 .\" You may not use this file except in compliance with the License.
7 .\"
8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 .\" or http://www.opensolaris.org/os/licensing.
10 .\" See the License for the specific language governing permissions
11 .\" and limitations under the License.
12 .\"
13 .\" When distributing Covered Code, include this CDDL HEADER in each
14 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 .\" If applicable, add the following below this CDDL HEADER, with the
16 .\" fields enclosed by brackets "[]" replaced with your own identifying
17 .\" information: Portions Copyright [yyyy] [name of copyright owner]
18 .\"
19 .\" CDDL HEADER END
20 .\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved.
21 .TH umem_debug 3MALLOC "26 July 2002" "SunOS 5.11" "Memory Allocation Library Functions"
22 .SH NAME
23 umem_debug \- debugging features of the umem library
24 .SH SYNOPSIS
25 .LP
26 .nf
27 \fBcc\fR [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lumem\fR [ \fIlibrary\fR\&.\|.\|. ]
28 #include <\fBumem.h\fR>
29 .fi
30
31 .SH DESCRIPTION
32
33 .LP
34 The \fBlibumem\fR library provides debugging features that detect memory leaks, buffer overruns, multiple frees, use of uninitialized data, use of freed data, and many other common programming errors. The activation of the run-time debugging features is controlled by environment variables.
35 .sp
36
37 .LP
38 When the library detects an error, it writes a description of the error to an internal buffer that is readable with the \fB::umem_status\fR
39 \fBmdb\fR(1) \fIdcmd\fR and then calls
40 \fBabort\fR(3C).
41 .sp
42
43 .SH ENVIRONMENT VARIABLES
44
45 .sp
46 .ne 2
47 .mk
48 .na
49 \fBUMEM_DEBUG\fR
50 .ad
51 .RS 14n
52 .rt 
53 This variable contains a list of comma-separated options.  Unrecognized options are ignored. Possible options include:
54 .sp
55
56 .sp
57 .ne 2
58 .mk
59 .na
60 \fB\fBaudit\fR[=\fIframes\fR]\fR
61 .ad
62 .RS 18n
63 .rt 
64 This option enables the recording of auditing information, including thread ID, high-resolution time stamp, and stack trace for the last action (allocation or free) on every allocation.  If transaction logging
65 (see UMEM_LOGGING) is enabled, this auditing information is also logged.
66 .sp
67
68 .sp
69 The \fIframes\fR parameter sets the number of stack frames recorded in the auditing structure. The upper bound for frames is implementation-defined. If a larger value is requested, the upper bound is used instead.
70 .sp
71
72 .sp
73 If \fIframes\fR is not specified or is not an integer, the default value of 15 is used.
74 .sp
75
76 .sp
77 This option also enables the \fBguards\fR option.
78 .sp
79
80 .RE
81
82 .sp
83 .ne 2
84 .mk
85 .na
86 \fB\fBcontents\fR[=\fIcount\fR]\fR
87 .ad
88 .RS 18n
89 .rt 
90 If auditing and contents logging (see UMEM_LOGGING) are enabled, the first \fIcount\fR bytes of each buffer are logged when they are freed.  If a buffer is shorter than \fIcount\fR bytes, it is logged in its entirety.
91 .sp
92
93 .sp
94 If \fIcount\fR is not specified or is not an integer, the default value of 256 is used.
95 .sp
96
97 .RE
98
99 .sp
100 .ne 2
101 .mk
102 .na
103 \fB\fBdefault\fR\fR
104 .ad
105 .RS 18n
106 .rt 
107 This option is equivalent to \fBaudit\fR,\fBcontents\fR,\fBguards\fR.
108 .sp
109
110 .RE
111
112 .sp
113 .ne 2
114 .mk
115 .na
116 \fB\fBguards\fR\fR
117 .ad
118 .RS 18n
119 .rt 
120 This option enables filling allocated and freed buffers with special patterns to help detect the use of uninitialized data and previously freed buffers. It also enables an 8-byte redzone after each buffer that contains \fB0xfeedfacefeedfaceULL\fR.
121 .sp
122
123 .sp
124 When an object is freed, it is filled with \fB0xdeadbeef\fR.  When an object is allocated, the \fB0xdeadbeef\fR pattern is verified and replaced with \fB0xbaddcafe\fR.  The redzone is checked every time a buffer is allocated or freed.
125 .sp
126
127 .sp
128 For caches with either constructors or destructors, or both,
129 \fBumem_cache_alloc\fR(3MALLOC) and
130 \fBumem_cache_free\fR(3MALLOC) apply the cache's constructor and destructor, respectively, instead of caching constructed objects. The presence of
131 \fBassert\fR(3C)s
132 in the destructor verifying that the buffer is in the constructed state can be used to detect any objects returned in an improper state.  See
133 \fBumem_cache_create\fR(3MALLOC) for
134 details.
135 .sp
136
137 .RE
138
139 .sp
140 .ne 2
141 .mk
142 .na
143 \fB\fBverbose\fR\fR
144 .ad
145 .RS 18n
146 .rt 
147 The library writes error descriptions to standard error before aborting. These messages are not localized.
148 .sp
149
150 .RE
151
152 .RE
153
154 .sp
155 .ne 2
156 .mk
157 .na
158 \fBUMEM_LOGGING\fR
159 .ad
160 .RS 14n
161 .rt 
162 To be enabled, this variable should be set to a comma-separated list of in-memory logs. The logs available are:
163 .sp
164
165 .sp
166 .ne 2
167 .mk
168 .na
169 \fB\fBtransaction\fR[=\fIsize\fR]\fR
170 .ad
171 .RS 20n
172 .rt 
173 If the \fBaudit\fR debugging option is set (see \fBUMEM_DEBUG\fR), the audit structures from previous transactions are entered into this log.
174 .sp
175
176 .RE
177
178 .sp
179 .ne 2
180 .mk
181 .na
182 \fB\fBcontents\fR[=\fIsize\fR]\fR
183 .ad
184 .RS 20n
185 .rt 
186 If the \fBaudit\fR debugging option is set, the contents of objects are recorded in this log as they are freed.
187 .sp
188
189 .sp
190 If the "contents" debugging option was not set, 256 bytes of each freed buffer are saved.
191 .sp
192
193 .RE
194
195 .sp
196 .ne 2
197 .mk
198 .na
199 \fB\fBfail\fR[=\fIsize\fR]\fR
200 .ad
201 .RS 20n
202 .rt 
203 Records are entered into this log for every failed allocation.
204 .sp
205
206 .RE
207
208 For any of these options, if \fIsize\fR is not specified, the default value of 64k is used.  The \fIsize\fR parameter must be an integer that can be qualified with K, M, G, or T to specify kilobytes, megabytes, gigabytes, or terabytes, respectively.
209 .sp
210
211 .sp
212 Logs that are not listed or that have either a size of 0 or an invalid size are disabled.
213 .sp
214
215 .sp
216 The log is disabled if during initialization the requested amount of storage cannot be allocated.
217 .sp
218
219 .RE
220
221 .SH ATTRIBUTES
222
223 .LP
224 See
225 \fBattributes\fR(5) for descriptions of the following attributes:
226 .sp
227
228 .LP
229
230 .sp
231 .TS
232 tab() box;
233 cw(2.75i) |cw(2.75i)
234 lw(2.75i) |lw(2.75i)
235 .
236 ATTRIBUTE TYPEATTRIBUTE VALUE
237 _
238 Interface StabilityUnstable
239 _
240 MT-LevelMT-Safe
241 .TE
242
243 .SH SEE ALSO
244
245 .LP
246
247 \fBmdb\fR(1),
248 \fBabort\fR(3C),
249 \fBsignal\fR(3C),
250 \fBumem_cache_create\fR(3MALLOC),
251 \fBattributes\fR(5)
252 .sp
253
254 .LP
255
256 .sp
257
258 .SH WARNINGS
259
260 .LP
261 When \fBlibumem\fR aborts the process using
262 \fBabort\fR(3C), any existing signal handler for \fBSIGABRT\fR is called. If the signal handler performs allocations, undefined
263 behavior can result.
264 .sp
265
266 .SH NOTES
267
268 .LP
269 Some of the debugging features work only for allocations smaller than 16 kilobytes in size. Allocations larger than 16 kilobytes could have reduced support.
270 .sp
271
272 .LP
273 Activating any of the library's debugging features could significantly increase the library's memory footprint and decrease its performance.
274 .sp
275
Note: See TracBrowser for help on using the browser.