share/man/man3malloc/watchmalloc.3malloc

   1 '\" te
   2 .\" Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH WATCHMALLOC 3MALLOC "Jan 10, 2007"
   7 .SH NAME
   8 watchmalloc \- debugging memory allocator
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <stdlib.h>
  13
  14 \fBvoid *\fR\fBmalloc\fR(\fBsize_t\fR \fIsize\fR);
  15 .fi
  16
  17 .LP
  18 .nf
  19 \fBvoid\fR \fBfree\fR(\fBvoid *\fR\fIptr\fR);
  20 .fi
  21
  22 .LP
  23 .nf
  24 \fBvoid *\fR\fBrealloc\fR(\fBvoid *\fR\fIptr\fR, \fBsize_t\fR \fIsize\fR);
  25 .fi
  26
  27 .LP
  28 .nf
  29 \fBvoid *\fR\fBmemalign\fR(\fBsize_t\fR \fIalignment\fR, \fBsize_t\fR \fIsize\fR);
  30 .fi
  31
  32 .LP
  33 .nf
  34 \fBvoid *\fR\fBvalloc\fR(\fBsize_t\fR \fIsize\fR);
  35 .fi
  36
  37 .LP
  38 .nf
  39 \fBvoid *\fR\fBcalloc\fR(\fBsize_t\fR \fInelem\fR, \fBsize_t\fR \fIelsize\fR);
  40 .fi
  41
  42 .LP
  43 .nf
  44 #include <malloc.h>
  45
  46 \fBint\fR \fBmallopt\fR(\fBint\fR \fIcmd\fR, \fBint\fR \fIvalue\fR);
  47 .fi
  48
  49 .LP
  50 .nf
  51 \fBstruct mallinfo\fR \fBmallinfo\fR(\fBvoid\fR);
  52 .fi
  53
  54 .SH DESCRIPTION
  55 .sp
  56 .LP
  57 The collection of \fBmalloc()\fR functions in this shared object are an
  58 optional replacement for the standard versions of the same  functions in the
  59 system C library. See \fBmalloc\fR(3C). They provide a more strict interface
  60 than the standard versions and enable enforcement of the interface through the
  61 watchpoint facility of \fB/proc\fR. See \fBproc\fR(4).
  62 .sp
  63 .LP
  64 Any dynamically linked application can be run with these functions in place of
  65 the standard functions if the following string is present in the environment
  66 (see \fBld.so.1\fR(1)):
  67 .sp
  68 .in +2
  69 .nf
  70  LD_PRELOAD=watchmalloc.so.1
  71 .fi
  72 .in -2
  73
  74 .sp
  75 .LP
  76 The individual function interfaces are identical to the standard ones as
  77 described in \fBmalloc\fR(3C). However, laxities provided in the standard
  78 versions are not permitted when the watchpoint facility is enabled (see
  79 \fBWATCHPOINTS\fR  below):
  80 .RS +4
  81 .TP
  82 .ie t \(bu
  83 .el o
  84 Memory may not be freed more than once.
  85 .RE
  86 .RS +4
  87 .TP
  88 .ie t \(bu
  89 .el o
  90 A pointer to freed memory may not be used in a call to \fBrealloc()\fR.
  91 .RE
  92 .RS +4
  93 .TP
  94 .ie t \(bu
  95 .el o
  96 A call to \fBmalloc()\fR immediately following a call to \fBfree()\fR will not
  97 return the same space.
  98 .RE
  99 .RS +4
 100 .TP
 101 .ie t \(bu
 102 .el o
 103 Any reference to memory that has been freed yields undefined results.
 104 .RE
 105 .sp
 106 .LP
 107 To enforce these restrictions partially, without great loss in speed as
 108 compared to the watchpoint facility described below, a freed block of memory is
 109 overwritten with the pattern \fB0xdeadbeef\fR before returning from
 110 \fBfree()\fR. The \fBmalloc()\fR function returns with the allocated memory
 111 filled with the pattern \fB0xbaddcafe\fR as a precaution against applications
 112 incorrectly expecting to receive back unmodified memory from the last
 113 \fBfree()\fR. The \fBcalloc()\fR function always returns with the memory
 114 zero-filled.
 115 .sp
 116 .LP
 117 Entry points for \fBmallopt()\fR and \fBmallinfo()\fR are provided as empty
 118 routines, and are present only because some \fBmalloc()\fR implementations
 119 provide them.
 120 .SH WATCHPOINTS
 121 .sp
 122 .LP
 123 The watchpoint facility of \fB/proc\fR can be applied by a process to itself.
 124 The functions in \fBwatchmalloc.so.1\fR use this feature if the following
 125 string is present in the environment:
 126 .sp
 127 .LP
 128 MALLOC_DEBUG=WATCH
 129 .sp
 130 .LP
 131 This causes every block of freed memory to be covered with \fBWA_WRITE\fR
 132 watched areas. If the application attempts to write any part of freed memory,
 133 it will trigger a watchpoint trap, resulting in a \fBSIGTRAP\fR signal, which
 134 normally produces an  application core dump.
 135 .sp
 136 .LP
 137 A header is maintained before each block of allocated memory. Each header is
 138 covered with a watched area, thereby providing a red zone before and after each
 139 block of allocated memory (the header for the subsequent memory block serves as
 140 the trailing red zone for its preceding memory block). Writing just before or
 141 just after a memory block returned by \fBmalloc()\fR will trigger a watchpoint
 142 trap.
 143 .sp
 144 .LP
 145 Watchpoints incur a large performance penalty. Requesting
 146 \fBMALLOC_DEBUG=WATCH\fR can cause the application to run 10 to 100 times
 147 slower, depending on the use made of allocated memory.
 148 .sp
 149 .LP
 150 Further options are enabled by specifying a comma-separated string of options:
 151 .sp
 152 .LP
 153 MALLOC_DEBUG=WATCH,RW,STOP
 154 .sp
 155 .ne 2
 156 .na
 157 \fB\fBWATCH\fR\fR
 158 .ad
 159 .RS 9n
 160 Enables \fBWA_WRITE\fR watched areas as described above.
 161 .RE
 162
 163 .sp
 164 .ne 2
 165 .na
 166 \fB\fBRW\fR\fR
 167 .ad
 168 .RS 9n
 169 Enables both \fBWA_READ\fR and \fBWA_WRITE\fR watched areas. An attempt either
 170 to read or write freed memory or the red zones will trigger a watchpoint trap.
 171 This incurs even more overhead and can cause the application to run up to 1000
 172 times slower.
 173 .RE
 174
 175 .sp
 176 .ne 2
 177 .na
 178 \fB\fBSTOP\fR\fR
 179 .ad
 180 .RS 9n
 181 The process will stop showing a \fBFLTWATCH\fR machine fault if it triggers a
 182 watchpoint trap, rather than dumping core with a \fBSIGTRAP\fR signal. This
 183 allows a debugger to be attached to the live process at the point where it
 184 underwent the watchpoint trap. Also, the various \fB/proc\fR tools described in
 185 \fBproc\fR(1) can be used to examine the stopped process.
 186 .RE
 187
 188 .sp
 189 .LP
 190 One of \fBWATCH\fR or \fBRW\fR must be specified, else the watchpoint facility
 191 is not engaged. \fBRW\fR overrides \fBWATCH\fR. Unrecognized options are
 192 silently ignored.
 193 .SH LIMITATIONS
 194 .sp
 195 .LP
 196 Sizes of memory blocks allocated by \fBmalloc()\fR are rounded up to the
 197 worst-case alignment size, 8 bytes for 32-bit processes and 16 bytes for 64-bit
 198 processes. Accessing the extra space allocated for a memory block is
 199 technically a memory violation but is in fact innocuous. Such accesses are not
 200 detected by the watchpoint facility of \fBwatchmalloc\fR.
 201 .sp
 202 .LP
 203 Interposition of \fBwatchmalloc.so.1\fR fails innocuously if the target
 204 application is statically linked with respect to its \fBmalloc()\fR functions.
 205 .SH ATTRIBUTES
 206 .sp
 207 .LP
 208 See \fBattributes\fR(5) for descriptions of the following attributes:
 209 .sp
 210
 211 .sp
 212 .TS
 213 box;
 214 c | c
 215 l | l .
 216 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 217 _
 218 MT-Level        MT-Safe
 219 .TE
 220
 221 .SH SEE ALSO
 222 .sp
 223 .LP
 224 \fBproc\fR(1), \fBbsdmalloc\fR(3MALLOC), \fBcalloc\fR(3C), \fBfree\fR(3C),
 225 \fBmalloc\fR(3C), \fBmalloc\fR(3MALLOC), \fBmapmalloc\fR(3MALLOC),
 226 \fBmemalign\fR(3C), \fBrealloc\fR(3C), \fBvalloc\fR(3C),
 227 \fBlibmapmalloc\fR(3LIB), \fBproc\fR(4), \fBattributes\fR(5)