dmake/dbug/malloc/malloc.3

   1 .TH MALLOC 3 "" "" "1.0"
   2 .ds ]T
   3 .\"/*
   4 .\" * (c) Copyright 1990 Conor P. Cahill (uunet!virtech!cpcahil).
   5 .\" * You may copy, distribute, and use this software as long as this
   6 .\" * copyright statement is not removed.
   7 .\" */
   8 .\" $Id: malloc.3,v 1.1.1.1 2000-09-22 15:33:26 hr Exp $
   9 .SH NAME
  10 malloc \t- debugging malloc library
  11 .SH SYNOPSIS
  12 .ft B
  13 .nf
  14 #include <malloc.h>
  15
  16 char    * calloc(nelem,elsize);
  17 void      free(ptr);
  18 char    * malloc(size);
  19 int       malloc_chain_check(flag);
  20 void      malloc_dump(fd);
  21 int       mallopt(cmd,val)
  22 char    * realloc(ptr,size);
  23
  24 int                       cmd,fd,flag;
  25 unsigned                  elsize,nelem,size;
  26 char                    * ptr;
  27 union malloptarg          val;
  28
  29 .fi
  30 .ft R
  31 .SH DESCRIPTION
  32 This malloc library is a replacement for the standard library to be used
  33 during software development/debugging.  See the standard malloc(3) pages
  34 for more information on the use of the following functions:
  35 .nf
  36 .in +.5i
  37 calloc(), free(), malloc(), realloc()
  38 .in -.5i
  39 .fi
  40 .sp
  41 This library differs from the standard malloc library in the
  42 following ways:
  43 .P
  44 1. Each malloc segment contains a magic number so that free can
  45 verify that the pointer passed points to a valid malloc segment.
  46 .P
  47 2. Each malloc segment is filled with a non-zero pattern so that code that
  48 depends upon malloc segments being null will fail.
  49 .P
  50 3. The size of each segment will be at least 1 byte larger than requested
  51 and the extra bytes will be filled with a non-zero pattern.  When free is
  52 called, it will verify that you did not go beyond the number of bytes
  53 you asked for.
  54 .P
  55 4. When a segment is freed, it will be filled with a different non-zero pattern
  56 to ensure that the program doesn't depend upon the use of already freed data.
  57 .P
  58 5. Whenever any of the string or memory functions (str*, b*, mem*) are
  59 called with a pointer that is within the malloc arena,  the operation is
  60 checked to verify that it does not overrun the malloced segment.  A failure
  61 of this check is considered a "warning level error" (described later) and
  62 is handled accordingly.
  63 .P
  64 7. Run time checking can include verification of the malloc chain at each
  65 and every call to one of the malloc functions or manually by calling the
  66 malloc_chain_check function.
  67 .P
  68 6. When a problem is found, the action taken is specified at runtime by
  69 environment variables or at compile time by the use of the mallopt()
  70 function.
  71 .P
  72 There are two arbitrary levels of errors, warning and fatal, that this
  73 library will detect.  They are broken down as follows:
  74 .P
  75 .nf
  76 .in +.25i
  77 Warning messages include:
  78 .sp
  79 .in +.5i
  80 .ti -.25i
  81 Calling free with a bad pointer
  82 .br
  83 .ti -.25i
  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.
  87 .sp
  88 .in -.5i
  89 Fatal errors are:
  90 .in +.5i
  91 .ti -.25i
  92 Detectable corruption to the malloc chain.
  93 .in -.5i
  94 .in -.25i
  95 .P
  96 The error handling for each level (warning or fatal) are specified using
  97 environment variables or mallopt().  The coding for the error handling is
  98 as follows:
  99 .sp
 100 .nf
 101 .in +.5i
 102 .ti -.25i
 103   0 - continue operations
 104 .ti -.25i
 105   1 - drop core and exit
 106 .ti -.25i
 107   2 - just exit
 108 .ti -.25i
 109   3 - drop core, but continue executing.  Core files will
 110 be placed into core.[PID].[counter] i.e: core.00123.001
 111 .ti -.25i
 112 128 - dump malloc chain and continue
 113 .ti -.25i
 114 129 - dump malloc chain, dump core, and exit
 115 .ti -.25i
 116 130 - dump malloc chain, exit
 117 .ti -.25i
 118 131 - dump malloc chain, dump core, continue processing
 119 .in -.5i
 120 .P
 121 In addition error messages can be placed into an error file.
 122 .P
 123 \fBmalloc_opt\fP() is used to set the malloc debugging options. The
 124 following options can be set:
 125 .br
 126 .sp
 127 .in +.5i
 128 MALLOC_WARN - set the error handling for warning level errors.  \fBval.i\fP is
 129 an integer that can contain any one of the following values:
 130 .sp
 131 .in +.5i
 132 M_HANDLE_IGNORE - ignore error
 133 .br
 134 M_HANDLE_ABORT - drop core and exit
 135 .br
 136 M_HANDLE_EXIT - just exit (no core drop)
 137 .br
 138 M_HANDLE_CORE - drop core, but keep on going
 139 .br
 140 .in -.5i
 141 .sp
 142 In addition, M_HANDLE_DUMP may be or'd in to cause a dump of the current
 143 malloc chain.
 144 .br
 145 .sp
 146 MALLOC_FATAL - set the error handling for fatal level errors.  \fBval.i\fP is
 147 equivalent to \fBval.i\fP for MALLOC_WARN.
 148 .br
 149 .sp
 150 MALLOC_ERRFILE - set the destination for malloc error messages.  \fBval.str\fP
 151 is a pointer to a character string containing the name of the file to be used
 152 for error messages.
 153 .br
 154 .sp
 155 MALLOC_CKCHAIN - set the malloc chain checking flag.  If \fBval.i\fP is
 156 non-zero, chain checking at every call to malloc is turned on.
 157 .br
 158 .sp
 159 For example, to set up the session to generate a core file for
 160 every malloc warning, to drop core and exit on a malloc fatal, and
 161 to log all messages to the file "malloc_log" do the following:
 162 .sp
 163 .nf
 164 .in +.5i
 165 #include <malloc.h>
 166 malloc_opt(MALLOC_WARN,131);
 167 malloc_opt(MALLOC_FATAL,1);
 168 malloc_opt(MALLOC_ERRFILE,"malloc_log");
 169 .in -.5i
 170 .fi
 171 .in -.5i
 172 .sp
 173 \fBmalloc_opt\fP() can be used to set/alter the debugging options at any
 174 time.
 175 .P
 176 \fBmalloc_dump\fP() will dump a table of the malloc arena showing all
 177 allocated/freed segments and the first few bytes of data in each segment.
 178 \fBfd\fP is the file descriptor to write the data to.
 179 .P
 180 \fBmalloc_chain_check\fP() will check the status of the malloc arena.
 181 If \fBflag\fP is non-zero, an error found in the chain will cause a
 182 fatal error.  \fBmalloc_chain_check\fP() returns zero when there are no
 183 problems found in the malloc chain, non-zero otherwise.
 184 .SH "ENVIRONMENT VARIABLES"
 185 Environment variables can be used to control error handling, error logging
 186 and malloc chain checking at run time.  The following environment variables
 187 are used:
 188 .P
 189 MALLOC_WARN - specifies the error handling for warning errors
 190 .br
 191 MALLOC_FATAL - specifies the error handling for fatal errors
 192 .br
 193 MALLOC_ERRFILE - specifies the error log file for error messages.
 194 .br
 195 MALLOC_CKCHAIN - if 1, turns on malloc chain checking at every call to any
 196 of the malloc functions.
 197 .P
 198 For example, to set up the session to generate a core file for
 199 every malloc warning, to drop core and exit on a malloc fatal, and
 200 to log all messages to the file "malloc_log" do the following:
 201 .sp
 202 .nf
 203 .in +.5i
 204 MALLOC_WARN=131
 205 MALLOC_FATAL=1
 206 MALLOC_ERRFILE=malloc_log
 207
 208 export MALLOC_WARN MALLOC_FATAL MALLOC_ERRFILE
 209 .in -.5i
 210 .fi
 211 .SH WARNINGS
 212 This malloc library and it's associated string and memory functions are
 213 much less efficient than the standard functions due in part to the extra
 214 error checking.  You do not want to use this library when generating a
 215 production (i.e. releasable) version of your software.  It should only
 216 be used during development and testing.
 217 .SH SEE ALSO
 218 stat(2)
 219 .SH AUTHOR
 220 Conor P. Cahill
 221 Virtual Technologies Incorporated
 222 .sp
 223 uunet!virtech!cpcahil