vmm: Use a task_thread cache
[akaros.git] / user / electric-fence / libefence.3
1 .TH efence 3 27-April-1993
2 .SH NAME
3 efence \- Electric Fence Malloc Debugger
4 .SH SYNOPSIS
5 .nf
6 .ft B
7 #include <stdlib.h>
8 .ft
9 .fi
10 .LP
11 .nf
12 .ft B
13 void * malloc (size_t size);
14 .ft
15 .fi
16 .LP
17 .nf
18 .ft B
19 void free (void *ptr);
20 .ft
21 .fi
22 .LP
23 .nf
24 .ft B
25 void * realloc (void *ptr, size_t size);
26 .ft
27 .fi
28 .LP
29 .nf
30 .ft B
31 void * calloc (size_t nelem, size_t elsize);
32 .ft
33 .fi
34 .LP
35 .nf
36 .ft B
37 void * memalign (size_t alignment, size_t size);
38 .ft
39 .fi
40 .LP
41 .nf
42 .ft B
43 void * valloc (size_t size);
44 .ft
45 .fi
46 .LP
47 .nf
48 .ft B
49 extern int EF_DISABLE_BANNER;
50 .ft
51 .fi
52 .LP
53 .nf
54 .ft B
55 extern int EF_ALIGNMENT;
56 .ft
57 .fi
58 .LP
59 .nf
60 .ft B
61 extern int EF_PROTECT_BELOW;
62 .ft
63 .fi
64 .LP
65 .nf
66 .ft B
67 extern int EF_PROTECT_FREE;
68 .ft
69 .fi
70 .LP
71 .nf
72 .ft B
73 extern int EF_ALLOW_MALLOC_0;
74 .ft
75 .fi
76 .LP
77 .nf
78 .ft B
79 extern int EF_FREE_WIPES;
80 .ft
81 .fi
82 .SH DESCRIPTION
83 .I Electric Fence
84 helps you detect two common programming bugs:
85 software that overruns the boundaries of a malloc() memory
86 allocation, and software that touches a memory allocation that has been
87 released by free(). Unlike other malloc() debuggers, Electric Fence will
88 detect
89 .I read
90 accesses as well as writes, and it will pinpoint the exact instruction that
91 causes an error. It has been in use at Pixar since 1987, and at many other
92 sites for years.
93 .LP
94 Electric Fence uses the virtual memory hardware of your computer to place an
95 inaccessible memory page immediately after (or before, at the user's option)
96 each memory allocation. When software reads or writes this inaccessible page,
97 the
98 hardware issues a segmentation fault, stopping the program at the offending
99 instruction. It is then trivial to find the erroneous statement using your
100 favorite debugger. In a similar manner, memory that has been released by
101 free() is made inaccessible, and any code that touches it will get a
102 segmentation fault.
103 .LP
104 Simply linking your application with libefence.a will allow you to detect
105 most, but not all, malloc buffer overruns and accesses of free memory.
106 If you want to be reasonably sure that you've found
107 .I all
108 bugs of this type, you'll have to read and understand the rest of this
109 man page.
110 .SH USAGE
111 Link your program with the library
112 .B libefence.a .
113 Make sure you are
114 .I not
115 linking with
116 .B -lmalloc,
117 .B -lmallocdebug,
118 or with other malloc-debugger or malloc-enhancer libraries.
119 You can only use one at a time.
120 If your system administrator
121 has installed Electric Fence for public use, you'll be able to use the
122 .B -lefence
123 argument to the linker, otherwise you'll have to put the path-name for
124 .B libefence.a
125 in the linker's command line.
126 Some systems will require special arguments to the linker to assure that
127 you are using the Electric Fence malloc() and not the one from your C library.
128 On AIX systems, you may have to use the flags
129 .br
130 .B -bnso
131 .B -bnodelcsect
132 .B -bI:/lib/syscalls.exp
133 .br
134 On Sun systems running SunOS 4.X, you'll probably have to use
135 .B -Bstatic.
136 .LP
137 Run your program
138 .I using a debugger. 
139 It's easier to work this way than to create a
140 .B core
141 file and post-mortem debug it. Electric Fence can create
142 .I huge
143 core files, and some operating systems will thus take minutes simply to dump
144 core! Some operating systems will not create usable core files from programs
145 that are linked with Electric Fence.
146 If your program has one of the errors detected by Electric Fence, it will
147 get a segmentation fault (SIGSEGV) at the offending instruction. Use the
148 debugger to locate the erroneous statement, and repair it.
149 .SH GLOBAL AND ENVIRONMENT VARIABLES
150 Electric Fence has six configuration switches that can be enabled via
151 the shell environment, or by setting the value of global integer variables
152 using a debugger. These switches change what bugs Electric Fence will detect,
153 so it's important that you know how to use them.
154 .TP
155 EF_DISABLE_BANNER
156 This is an integer which if nonzero specifies that the usual Electric
157 Fence banner and copyright notice should not be printed.  This is
158 provided for certain circumstances where the banner can be annoying
159 (eg, running a regression test suite that also monitors stderr).  Note
160 that you should almost certainly not set this in your program, because
161 then you might leave Electric Fence linked into the production
162 version, which would be very bad.
163 .TP
164 EF_ALIGNMENT
165 This is an integer that specifies the alignment for any memory allocations
166 that will be returned by malloc(), calloc(), and realloc().
167 The value is specified in
168 bytes, thus a value of 4 will cause memory to be aligned to 32-bit boundaries
169 unless your system doesn't have a 8-bit characters. EF_ALIGNMENT is set to
170 sizeof(int) by default, since that is generally the word-size of your CPU.
171 If your program requires that allocations be aligned to 64-bit
172 boundaries and you have a 32-bit
173 .B int
174 you'll have to set this value to 8. This is the case when compiling with the
175 .B -mips2
176 flag on MIPS-based systems such as those from SGI.
177 The memory allocation that is returned by Electric Fence malloc() is aligned
178 using the value in EF_ALIGNMENT, and
179 .I its size the multiple of
180 .I that value
181 that is greater than or equal to the requested size.
182 For this reason, you will sometimes want to set EF_ALIGNMENT to 0 (no
183 alignment), so that
184 you can detect overruns of less than your CPU's word size. Be sure to read
185 the section
186 .I WORD-ALIGNMENT AND OVERRUN DETECTION
187 in this manual page before you try this.
188 To change this value, set EF_ALIGNMENT in the shell environment to an
189 integer value, or assign
190 to the global integer variable EF_ALIGNMENT using a debugger.
191 .TP
192 EF_PROTECT_BELOW
193 Electric Fence usually places an inaccessible page immediately after each
194 memory allocation, so that software that runs past the end of the allocation
195 will be detected. Setting EF_PROTECT_BELOW to 1 causes Electric Fence
196 to place the inaccessible page
197 .I before
198 the allocation in the address space, so that under-runs will be detected
199 instead of over-runs.
200 When EF_PROTECT_BELOW is set, the EF_ALIGNMENT parameter is ignored.
201 All allocations will be aligned to virtual-memory-page boundaries, and
202 their size will be the exact size that was requested.
203 To change this value, set EF_PROTECT_BELOW in the shell environment to an
204 integer value, or assign to the global integer variable EF_PROTECT_BELOW using
205 a debugger.
206 .TP
207 EF_PROTECT_FREE
208 When EF_PROTECT_FREE is not set (i. e. set to 0), Electric Fence returns free
209 memory to a pool and only checks accesses to it until it is reallocated. If
210 you suspect that a program may be touching free memory, set EF_PROTECT_FREE to
211 1. This will cause Electric Fence to never re-allocate memory once it has been
212 freed, so that any access to free memory will be detected. Some programs will
213 use tremendous amounts of memory when this parameter is set. To change this
214 value, set EF_PROTECT_FREE in the shell environment to an integer value, or
215 assign to the global integer variable EF_PROTECT_FREE using a debugger.
216 .TP
217 EF_ALLOW_MALLOC_0
218 By default, Electric Fence traps calls to malloc() with a size of zero, because
219 they are often the result of a software bug. If EF_ALLOW_MALLOC_0 is non-zero,
220 the software will not trap calls to malloc() with a size of zero.
221 To change this value, set EF_ALLOW_MALLOC_0 in the shell environment to an
222 integer value, or assign to the global integer variable EF_ALLOW_MALLOC_0 using
223 a debugger.
224 .TP
225 EF_FREE_WIPES
226 By default, Electric Fence releases memory without changing the content
227 of the released memory block.  IF EF_FREE_WIPES is non-zero, the sofware
228 will fill the memory block with 0xbd values before it is released.
229 This makes it easier to trigger illegal use of released memory, and eaiser
230 to understand why a memory access failed during gdb runs.
231 .SH WORD-ALIGNMENT AND OVERRUN DETECTION
232 There is a conflict between the alignment restrictions that malloc() operates
233 under and the debugging strategy used by Electric Fence. When detecting
234 overruns, Electric Fence malloc() allocates two or more virtual memory
235 pages for each allocation. The last page is made inaccessible in such a way
236 that any read, write, or execute access will cause a segmentation fault.
237 Then, Electric Fence malloc() will return an address such that the first
238 byte after
239 the end of the allocation is on the inaccessible page.
240 Thus, any overrun
241 of the allocation will cause a segmentation fault.
242 .LP
243 It follows that the
244 address returned by malloc() is the address of the inaccessible page minus
245 the size of the memory allocation.
246 Unfortunately, malloc() is required to return
247 .I word-aligned
248 allocations, since many CPUs can only access a word when its address is aligned.
249 The conflict happens when software makes a memory allocation using a size that
250 is not a multiple of the word size, and expects to do word accesses to that
251 allocation. The location of the inaccessible page is fixed by hardware at
252 a word-aligned address. If Electric Fence malloc() is to return an aligned
253 address, it must increase the size of the allocation to a multiple of the
254 word size.
255 In addition, the functions memalign() and valloc() must honor explicit
256 specifications on the alignment of the memory allocation, and this, as well
257 can only be implemented by increasing the size of the allocation.
258 Thus, there will be situations in which the end of a memory allocation
259 contains some padding space, and accesses of that padding space will not
260 be detected, even if they are overruns.
261 .LP
262 Electric Fence provides the variable EF_ALIGNMENT so that the user can
263 control the default alignment used by malloc(), calloc(), and realloc().
264 To debug overruns as small as a single byte, you can set EF_ALIGNMENT to
265 zero. This will result in Electric Fence malloc() returning unaligned
266 addresses for allocations with sizes that are not a multiple of the word
267 size. This is not a problem in most cases, because compilers must pad the
268 size of objects so that alignment restrictions are honored when storing
269 those objects in arrays. The problem surfaces when software allocates
270 odd-sized buffers for objects that must be word-aligned. One case of this
271 is software that allocates a buffer to contain a structure and a
272 string, and the string has an odd size (this example was in a popular TIFF
273 library). If word references are made to un-aligned buffers, you will see
274 a bus error (SIGBUS) instead of a segmentation fault. The only way to fix
275 this is to re-write the offending code to make byte references or not make
276 odd-sized allocations, or to set EF_ALIGNMENT to the word size.
277 .LP
278 Another example of software incompatible with
279 EF_ALIGNMENT < word-size
280 is the strcmp() function and other string functions on SunOS (and probably
281 Solaris), which make word-sized accesses to character strings, and may
282 attempt to access up to three bytes beyond the end of a string. These
283 result in a segmentation fault (SIGSEGV). The only way around this is to
284 use versions of the string functions that perform byte references instead
285 of word references.
286 .SH INSTRUCTIONS FOR DEBUGGING YOUR PROGRAM
287 .TP
288 1.
289 Link with libefence.a as explained above.
290 .TP
291 2.
292 Run your program in a debugger and fix any overruns or accesses to free memory.
293 .TP
294 3.
295 Quit the debugger.
296 .TP
297 4.
298 Set EF_PROTECT_BELOW = 1 in the shell environment.
299 .TP
300 5.
301 Repeat step 2, this time repairing underruns if they occur.
302 .TP
303 6.
304 Quit the debugger.
305 .TP
306 7.
307 Read the restrictions in the section on
308 .I WORD-ALIGNMENT AND OVERRUN DETECTION.
309 See if you can
310 set EF_ALIGNMENT to 0 and repeat step 2. Sometimes this will be too much work,
311 or there will be problems with library routines for which you don't have the
312 source, that will prevent you from doing this.
313 .SH MEMORY USAGE AND EXECUTION SPEED
314 Since Electric Fence uses at least two virtual memory pages for each of its
315 allocations, it's a terrible memory hog. I've sometimes found it necessary to
316 add a swap file using swapon(8) so that the system would have enough virtual
317 memory to debug my program. Also, the way we manipulate memory results in
318 various cache and translation buffer entries being flushed with each call
319 to malloc or free. The end result is that your program will be much slower
320 and use more resources while you are debugging it with Electric Fence.
321 .LP
322 Don't leave libefence.a linked into production software! Use it only
323 for debugging.
324 .SH PORTING
325 Electric Fence is written for ANSI C. You should be able to port it with
326 simple changes to the Makefile and to page.c,
327 which contains the memory management primitives .
328 Many POSIX platforms will require only a re-compile.
329 The operating system facilities required to port Electric Fence are:
330 .IP
331 A way to allocate memory pages
332 .br
333 A way to make selected pages inaccessible.
334 .br
335 A way to make the pages accessible again.
336 .br
337 A way to detect when a program touches an inaccessible page.
338 .br
339 A way to print messages.
340 .LP
341 Please e-mail me a copy of any changes you have to make, so that I can
342 merge them into the distribution.
343 .SH AUTHOR
344 Bruce Perens
345 .SH WARNINGS
346 I have tried to do as good a job as I can on this software, but I doubt
347 that it is even theoretically possible to make it bug-free.
348 This software has no warranty. It will not detect some bugs that you might
349 expect it to detect, and will indicate that some non-bugs are bugs.
350 Bruce Perens and/or Pixar will not be liable to any claims resulting
351 from the use of this software or the ideas within it.
352 The entire responsibility for its use must
353 be assumed by the user. If you use it and it results in loss of life
354 and/or property, tough. If it leads you on a wild goose chase and you waste
355 two weeks debugging something, too bad.
356 If you can't deal with the above, please don't use the software! I've written
357 this in an attempt to help other people, not to get myself sued or prosecuted.
358 .SH LICENSE
359 Copyright 1987-1995 Bruce Perens. All rights reserved.
360 .br
361 This program is free software; you can redistribute it and/or modify
362 it under the terms of the GNU General Public License, Version 2,
363 as published by the Free Software Foundation. A copy of this license is
364 distributed with this software in the file "COPYING".
365
366 This program is distributed in the hope that it will be useful,
367 but WITHOUT ANY WARRANTY; without even the implied warranty of
368 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Read the
369 file "COPYING" for more details.
370 .SH CONTACTING THE AUTHOR
371 .nf
372 Bruce Perens
373 c/o Pixar
374 1001 West Cutting Blvd., Suite 200
375 Richmond, CA 94804
376
377 Telephone: 510-215-3502
378 Fax: 510-236-0388
379 Internet: Bruce@Pixar.com
380 .fi
381 .ft
382 .SH FILES
383 /dev/zero: Source of memory pages (via mmap(2)).
384 .SH SEE ALSO
385 malloc(3), mmap(2), mprotect(2), swapon(8)
386 .SH DIAGNOSTICS
387 Segmentation Fault: Examine the offending statement for violation of the
388 boundaries of a memory allocation.
389 .br
390 Bus Error: See the section on
391 .I WORD-ALIGNMENT AND OVERRUN DETECTION.
392 in this manual page.
393 .SH BUGS
394 My explanation of the alignment issue could be improved.
395 .LP
396 Some Sun systems running SunOS 4.1 are reported to signal an access to a
397 protected page with
398 .B  SIGBUS
399 rather than
400 .B SIGSEGV,
401 I suspect this is an undocumented feature of a particular Sun hardware
402 version, not just the operating system.
403 On these systems, eftest will fail with a bus error until you modify the
404 Makefile to define
405 .B PAGE_PROTECTION_VIOLATED_SIGNAL
406 as
407 .B SIGBUS.
408 .LP
409 There are, without doubt, other bugs and porting issues. Please contact me via
410 e-mail if you have any bug reports, ideas, etc.
411 .SH WHAT'S BETTER
412 PURIFY, from Purify Systems, does a much better job than Electric Fence, and
413 does much more. It's available at this writing on SPARC and HP.
414 I'm not affiliated with Purify, I just think it's a wonderful product
415 and you should check it out.