watchmalloc(3malloc)

1watchmalloc(3MALLOC)  Memory Allocation Library Functions watchmalloc(3MALLOC)
2
3
4

NAME

6       watchmalloc - debugging memory allocator
7

SYNOPSIS

9       #include <stdlib.h>
10
11       void *malloc(size_t size);
12
13
14       void free(void *ptr);
15
16
17       void *realloc(void *ptr, size_t size);
18
19
20       void *memalign(size_t alignment, size_t size);
21
22
23       void *valloc(size_t size);
24
25
26       void *calloc(size_t nelem, size_t elsize);
27
28
29       #include <malloc.h>
30
31       int mallopt(int cmd, int value);
32
33
34       struct mallinfo mallinfo(void);
35
36

DESCRIPTION

38       The  collection  of  malloc()  functions  in  this shared object are an
39       optional replacement for the standard versions of the  same   functions
40       in  the  system  C  library. See malloc(3C). They provide a more strict
41       interface than the standard versions  and  enable  enforcement  of  the
42       interface through the watchpoint facility of /proc. See proc(4).
43
44
45       Any  dynamically  linked application can be run with these functions in
46       place of the standard functions if the following string is  present  in
47       the environment (see ld.so.1(1)):
48
49          LD_PRELOAD=watchmalloc.so.1
50
51
52
53       The  individual  function interfaces are identical to the standard ones
54       as described in malloc(3C). However, laxities provided in the  standard
55       versions are not permitted when the watchpoint facility is enabled (see
56       WATCHPOINTS  below):
57
58           o      Memory may not be freed more than once.
59
60           o      A pointer to freed memory may not be used in a call to real‐
61                  loc().
62
63           o      A  call  to  malloc() immediately following a call to free()
64                  will not return the same space.
65
66           o      Any reference to memory that has been freed yields undefined
67                  results.
68
69
70       To enforce these restrictions partially, without great loss in speed as
71       compared to the watchpoint facility described below, a freed  block  of
72       memory is overwritten with the pattern 0xdeadbeef before returning from
73       free(). The malloc() function returns with the allocated memory  filled
74       with the pattern 0xbaddcafe as a precaution against applications incor‐
75       rectly expecting to  receive  back  unmodified  memory  from  the  last
76       free().  The  calloc()  function  always  returns with the memory zero-
77       filled.
78
79
80       Entry points for mallopt() and mallinfo() are provided  as  empty  rou‐
81       tines,  and are present only because some malloc() implementations pro‐
82       vide them.
83

WATCHPOINTS

85       The watchpoint facility of /proc can be applied by a process to itself.
86       The  functions  in  watchmalloc.so.1  use this feature if the following
87       string is present in the environment:
88
89
90       MALLOC_DEBUG=WATCH
91
92
93       This causes every block of freed memory to  be  covered  with  WA_WRITE
94       watched  areas.  If the application attempts to write any part of freed
95       memory, it will trigger a watchpoint trap, resulting in a SIGTRAP  sig‐
96       nal, which normally produces an  application core dump.
97
98
99       A  header  is  maintained  before  each block of allocated memory. Each
100       header is covered with a watched area, thereby  providing  a  red  zone
101       before  and  after  each  block of allocated memory (the header for the
102       subsequent memory block serves as the trailing red zone for its preced‐
103       ing  memory  block).  Writing  just before or just after a memory block
104       returned by malloc() will trigger a watchpoint trap.
105
106
107       Watchpoints  incur  a  large  performance  penalty.   Requesting   MAL‐
108       LOC_DEBUG=WATCH  can  cause  the  application  to  run  10 to 100 times
109       slower, depending on the use made of allocated memory.
110
111
112       Further options are enabled by specifying a comma-separated  string  of
113       options:
114
115
116       MALLOC_DEBUG=WATCH,RW,STOP
117
118       WATCH    Enables WA_WRITE watched areas as described above.
119
120
121       RW       Enables  both  WA_READ  and WA_WRITE watched areas. An attempt
122                either to read or write freed memory or  the  red  zones  will
123                trigger  a watchpoint trap. This incurs even more overhead and
124                can cause the application to run up to 1000 times slower.
125
126
127       STOP     The process will stop showing a FLTWATCH machine fault  if  it
128                triggers  a  watchpoint  trap, rather than dumping core with a
129                SIGTRAP signal. This allows a debugger to be attached  to  the
130                live  process  at  the point where it underwent the watchpoint
131                trap. Also, the various /proc tools described in  proc(1)  can
132                be used to examine the stopped process.
133
134
135
136       One  of  WATCH or RW must be specified, else the watchpoint facility is
137       not engaged. RW overrides  WATCH.  Unrecognized  options  are  silently
138       ignored.
139

LIMITATIONS

141       Sizes  of  memory  blocks  allocated  by malloc() are rounded up to the
142       worst-case alignment size, 8 bytes for 32-bit processes  and  16  bytes
143       for  64-bit processes. Accessing the extra space allocated for a memory
144       block is technically a memory violation but is in fact innocuous.  Such
145       accesses are not detected by the watchpoint facility of watchmalloc.
146
147
148       Interposition  of  watchmalloc.so.1  fails  innocuously  if  the target
149       application is statically linked with respect  to  its  malloc()  func‐
150       tions.
151

ATTRIBUTES

153       See attributes(5) for descriptions of the following attributes:
154
155
156
157
158       ┌─────────────────────────────┬─────────────────────────────┐
159       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
160       ├─────────────────────────────┼─────────────────────────────┤
161       │MT-Level                     │MT-Safe                      │
162       └─────────────────────────────┴─────────────────────────────┘
163

NAME

SYNOPSIS

DESCRIPTION

WATCHPOINTS

LIMITATIONS

ATTRIBUTES

SEE ALSO