_readme
1# (c) Copyright 1990 Conor P. Cahill. (uunet!virtech!cpcahil)
2# You may copy, distribute, and use this software as long as this
3# copyright statement is not removed.
4
5This package is a collection of routines which are a drop-in replacement
6for the malloc(3), memory(3), string(3), and bstring(3) library functions.
7
8The purpose of these programs is to aid the development and/or debugging
9of programs using these functions by providing a high level of consistancy
10checking whenever a malloc pointer is used. Due to this increased
11level of consistancy checking, these functions have a considerably larger
12overhead than the standard functions, but the extra checking should be
13well worth it in a development environment.
14
15To use these functions all you need to do is compile the library and
16include it on your loader command line. You do not need to recompile
17your code, only a relink is necessary.
18
19Features of this library:
20
21 1. The malloced area returned from each call to malloc is filled with
22 non-null bytes. This should catch any use of uninitialized malloc
23 area. The fill pattern for malloced area is 0x01.
24
25 2. When free is called numerous validity checks are made on the
26 pointer it is passed. In addition, the data in the malloc block
27 beyound the size requested on the initial malloc is checked to
28 verify that it is still filled with the original fill characters.
29
30 This is useful for catching things like:
31
32 ptr = malloc(5);
33 ptr[5] = '\0';
34
35 /*
36 * You should not that this will be caught when it is
37 * freed not when it is done
38 */
39
40 And finally, the freed block is filled with a different fill pattern
41 so that you can easily determine if you are still using free'd space.
42 The fill pattern for free'd areas is 0x02.
43
44 This is useful for catching things like:
45
46 ptr = malloc(20);
47
48 bptr = ptr+10;
49
50 /* do something usefule with bptr */
51
52 free(ptr);
53
54 /*
55 * now try to do something useful with bptr, it should
56 * be trashed enough that it would cause real problems
57 * and when you went to debug the problem it would be
58 * filled with 0x02's and you would then know to look
59 * for something free'ing what bptr points to.
60 */
61
62
63 3. Whenever a bstring(3)/string(3)/memory(3) function is called, it's
64 parameters are checked as follows:
65
66 If they point somewhere in the malloc arena
67 If the operation goes beyond requested malloc space
68 call malloc_warning()
69
70 This is useful for catching things like:
71
72 ptr = malloc(5);
73 strcpy(ptr,"abcde");
74
75
76 4. Malloc_warning() and malloc_fatal() are used when an error condition
77 is detected. If the error is severe, malloc_fatal is called.
78 Malloc_warning is used otherwise. The decision about what is fatal
79 and what is a warning was made somewhat arbitrarily.
80
81 Warning messages include:
82
83 Calling free with a bad pointer
84 Calling a bstring/string/memory (3) function which will go beyond
85 the end of a malloc block (Note that the library function is
86 not modified to refuse the operation. If malloc warnings are
87 in the default IGNORE case, the operation will continue and
88 at some point cause a real problem).
89
90 Fatal errors are:
91
92 Detectable corruption to the malloc chain.
93
94
95 5. The operations to perform when an error is detected are specified at
96 run time by the use of environment variables.
97
98 MALLOC_WARN - specifies the warning error message handling
99 MALLOC_FATAL - specifies the fatal error handling
100
101
102 When one of these error conditions occur you will get an error
103 message and the handler will execute based upon what setting
104 is in the environment variables. Currently understood settings
105 are as follows:
106
107 0 - continue operations
108 1 - drop core and exit
109 2 - just exit
110 3 - drop core, but continue executing. Core files will
111 be placed into core.[PID].[counter] i.e: core.00123.001
112 128 - dump malloc chain and continue
113 129 - dump malloc chain, dump core, and exit
114 130 - dump malloc chain, exit
115 131 - dump malloc chain, dump core, continue processing
116
117
118 There is an additional environment variable MALLOC_ERRFILE which
119 is used to indicate the name of the file for error message output.
120
121 For example, to set up the session to generate a core file for
122 every malloc warning, to drop core and exit on a malloc fatal, and
123 to log all messages to the file "malloc_log" do the following:
124
125 MALLOC_WARN=131
126 MALLOC_FATAL=1
127 MALLOC_ERRFILE=malloc_log
128
129 export MALLOC_WARN MALLOC_FATAL MALLOC_ERRFILE
130
131 6. The function malloc_dump() is available to dump the malloc chain whenever
132 you might want. It's only argument is a file descriptor to use to write
133 the data. Review the code if you need to know what data is printed.
134