]>
Commit | Line | Data |
---|---|---|
47c31183 MK |
1 | .\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com> |
2 | .\" | |
93015253 | 3 | .\" %%%LICENSE_START(VERBATIM) |
47c31183 MK |
4 | .\" Permission is granted to make and distribute verbatim copies of this |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
12 | .\" | |
13 | .\" Since the Linux kernel and libraries are constantly changing, this | |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
16 | .\" the use of the information contained herein. The author(s) may not | |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
20 | .\" | |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 23 | .\" %%%LICENSE_END |
47c31183 | 24 | .\" |
4b8c67d9 | 25 | .TH MALLOC_INFO 3 2017-09-15 "GNU" "Linux Programmer's Manual" |
47c31183 MK |
26 | .SH NAME |
27 | malloc_info \- export malloc state to a stream | |
28 | .SH SYNOPSIS | |
29 | .nf | |
30 | .B #include <malloc.h> | |
68e4db0a | 31 | .PP |
91f8edd6 | 32 | .BI "int malloc_info(int " options ", FILE *" stream ); |
47c31183 MK |
33 | .fi |
34 | .SH DESCRIPTION | |
35 | The | |
36 | .BR malloc_info () | |
37 | function exports an XML string that describes the current state | |
38 | of the memory-allocation | |
39 | implementation in the caller. | |
40 | The string is printed on the file stream | |
91f8edd6 | 41 | .IR stream . |
47c31183 MK |
42 | The exported string includes information about all arenas (see |
43 | .BR malloc (3)). | |
847e0d88 | 44 | .PP |
47c31183 MK |
45 | As currently implemented, |
46 | .I options | |
47 | must be zero. | |
48 | .SH RETURN VALUE | |
49 | On success, | |
50 | .BR malloc_info () | |
51 | returns 0; | |
921dd685 MK |
52 | on error, it returns \-1, with |
53 | .I errno | |
54 | set to indicate the cause. | |
47c31183 MK |
55 | .SH ERRORS |
56 | .TP | |
57 | .B EINVAL | |
58 | .I options | |
59 | was nonzero. | |
60 | .SH VERSIONS | |
42a6569e | 61 | .BR malloc_info () |
47c31183 | 62 | was added to glibc in version 2.10. |
1cd7128b ZL |
63 | .SH ATTRIBUTES |
64 | For an explanation of the terms used in this section, see | |
65 | .BR attributes (7). | |
66 | .TS | |
67 | allbox; | |
68 | lb lb lb | |
69 | l l l. | |
70 | Interface Attribute Value | |
71 | T{ | |
72 | .BR malloc_info () | |
73 | T} Thread safety MT-Safe | |
74 | .TE | |
847e0d88 | 75 | .sp 1 |
47c31183 MK |
76 | .SH CONFORMING TO |
77 | This function is a GNU extension. | |
78 | .SH NOTES | |
79 | The memory-allocation information is provided as an XML string | |
80 | (rather than a C structure) | |
81 | because the information may change over time | |
82 | (according to changes in the underlying implementation). | |
83 | The output XML string includes a version field. | |
847e0d88 | 84 | .PP |
a5cbea5f MK |
85 | The |
86 | .BR open_memstream (3) | |
87 | function can be used to send the output of | |
88 | .BR malloc_info () | |
89 | directly into a buffer in memory, rather than to a file. | |
847e0d88 | 90 | .PP |
47c31183 MK |
91 | The |
92 | .BR malloc_info () | |
93 | function is designed to address deficiencies in | |
94 | .BR malloc_stats (3) | |
95 | and | |
96 | .BR mallinfo (3). | |
97 | .SH EXAMPLE | |
98 | The program below takes up to four command-line arguments, | |
99 | of which the first three are mandatory. | |
100 | The first argument specifies the number of threads that | |
101 | the program should create. | |
102 | All of the threads, including the main thread, | |
103 | allocate the number of blocks of memory specified by the second argument. | |
104 | The third argument controls the size of the blocks to be allocated. | |
105 | The main thread creates blocks of this size, | |
106 | the second thread created by the program allocates blocks of twice this size, | |
107 | the third thread allocates blocks of three times this size, and so on. | |
847e0d88 | 108 | .PP |
47c31183 MK |
109 | The program calls |
110 | .BR malloc_info () | |
111 | twice to display the memory-allocation state. | |
112 | The first call takes place before any threads | |
113 | are created or memory allocated. | |
114 | The second call is performed after all threads have allocated memory. | |
847e0d88 | 115 | .PP |
47c31183 MK |
116 | In the following example, |
117 | the command-line arguments specify the creation of one additional thread, | |
118 | and both the main thread and the additional thread | |
119 | allocate 10000 blocks of memory. | |
120 | After the blocks of memory have been allocated, | |
121 | .BR malloc_info () | |
122 | shows the state of two allocation arenas. | |
207050fa | 123 | .PP |
47c31183 | 124 | .in +4 |
207050fa | 125 | .EX |
47c31183 MK |
126 | .RB "$ " "getconf GNU_LIBC_VERSION" |
127 | glibc 2.13 | |
128 | .RB "$ " "./a.out 1 10000 100" | |
129 | ============ Before allocating blocks ============ | |
130 | <malloc version="1"> | |
131 | <heap nr="0"> | |
132 | <sizes> | |
133 | </sizes> | |
134 | <total type="fast" count="0" size="0"/> | |
135 | <total type="rest" count="0" size="0"/> | |
136 | <system type="current" size="135168"/> | |
137 | <system type="max" size="135168"/> | |
138 | <aspace type="total" size="135168"/> | |
139 | <aspace type="mprotect" size="135168"/> | |
140 | </heap> | |
141 | <total type="fast" count="0" size="0"/> | |
142 | <total type="rest" count="0" size="0"/> | |
143 | <system type="current" size="135168"/> | |
144 | <system type="max" size="135168"/> | |
145 | <aspace type="total" size="135168"/> | |
146 | <aspace type="mprotect" size="135168"/> | |
147 | </malloc> | |
148 | ||
149 | ============ After allocating blocks ============ | |
150 | <malloc version="1"> | |
151 | <heap nr="0"> | |
152 | <sizes> | |
153 | </sizes> | |
154 | <total type="fast" count="0" size="0"/> | |
155 | <total type="rest" count="0" size="0"/> | |
156 | <system type="current" size="1081344"/> | |
157 | <system type="max" size="1081344"/> | |
158 | <aspace type="total" size="1081344"/> | |
159 | <aspace type="mprotect" size="1081344"/> | |
160 | </heap> | |
161 | <heap nr="1"> | |
162 | <sizes> | |
163 | </sizes> | |
164 | <total type="fast" count="0" size="0"/> | |
165 | <total type="rest" count="0" size="0"/> | |
166 | <system type="current" size="1032192"/> | |
167 | <system type="max" size="1032192"/> | |
168 | <aspace type="total" size="1032192"/> | |
169 | <aspace type="mprotect" size="1032192"/> | |
170 | </heap> | |
171 | <total type="fast" count="0" size="0"/> | |
172 | <total type="rest" count="0" size="0"/> | |
173 | <system type="current" size="2113536"/> | |
174 | <system type="max" size="2113536"/> | |
175 | <aspace type="total" size="2113536"/> | |
176 | <aspace type="mprotect" size="2113536"/> | |
177 | </malloc> | |
b8302363 | 178 | .EE |
47c31183 MK |
179 | .in |
180 | .SS Program source | |
e7d0bb47 | 181 | .EX |
47c31183 MK |
182 | #include <unistd.h> |
183 | #include <stdlib.h> | |
184 | #include <pthread.h> | |
185 | #include <malloc.h> | |
186 | #include <errno.h> | |
187 | ||
188 | static size_t blockSize; | |
189 | static int numThreads, numBlocks; | |
190 | ||
191 | #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\ | |
192 | } while (0) | |
193 | ||
194 | static void * | |
195 | thread_func(void *arg) | |
196 | { | |
197 | int j; | |
198 | int tn = (int) arg; | |
199 | ||
200 | /* The multiplier \(aq(2 + tn)\(aq ensures that each thread (including | |
201 | the main thread) allocates a different amount of memory */ | |
202 | ||
203 | for (j = 0; j < numBlocks; j++) | |
204 | if (malloc(blockSize * (2 + tn)) == NULL) | |
205 | errExit("malloc\-thread"); | |
206 | ||
207 | sleep(100); /* Sleep until main thread terminates */ | |
208 | return NULL; | |
209 | } | |
210 | ||
211 | int | |
212 | main(int argc, char *argv[]) | |
213 | { | |
214 | int j, tn, sleepTime; | |
215 | pthread_t *thr; | |
216 | ||
217 | if (argc < 4) { | |
218 | fprintf(stderr, | |
219 | "%s num\-threads num\-blocks block\-size [sleep\-time]\\n", | |
220 | argv[0]); | |
221 | exit(EXIT_FAILURE); | |
222 | } | |
223 | ||
224 | numThreads = atoi(argv[1]); | |
225 | numBlocks = atoi(argv[2]); | |
226 | blockSize = atoi(argv[3]); | |
227 | sleepTime = (argc > 4) ? atoi(argv[4]) : 0; | |
228 | ||
229 | thr = calloc(numThreads, sizeof(pthread_t)); | |
230 | if (thr == NULL) | |
231 | errExit("calloc"); | |
232 | ||
233 | printf("============ Before allocating blocks ============\\n"); | |
234 | malloc_info(0, stdout); | |
235 | ||
236 | /* Create threads that allocate different amounts of memory */ | |
237 | ||
238 | for (tn = 0; tn < numThreads; tn++) { | |
239 | errno = pthread_create(&thr[tn], NULL, thread_func, | |
240 | (void *) tn); | |
241 | if (errno != 0) | |
242 | errExit("pthread_create"); | |
243 | ||
244 | /* If we add a sleep interval after the start\-up of each | |
245 | thread, the threads likely won\(aqt contend for malloc | |
246 | mutexes, and therefore additional arenas won\(aqt be | |
247 | allocated (see malloc(3)). */ | |
248 | ||
249 | if (sleepTime > 0) | |
250 | sleep(sleepTime); | |
251 | } | |
252 | ||
253 | /* The main thread also allocates some memory */ | |
0ab8aeec | 254 | |
47c31183 MK |
255 | for (j = 0; j < numBlocks; j++) |
256 | if (malloc(blockSize) == NULL) | |
257 | errExit("malloc"); | |
258 | ||
259 | sleep(2); /* Give all threads a chance to | |
260 | complete allocations */ | |
261 | ||
262 | printf("\\n============ After allocating blocks ============\\n"); | |
263 | malloc_info(0, stdout); | |
264 | ||
265 | exit(EXIT_SUCCESS); | |
266 | } | |
e7d0bb47 | 267 | .EE |
47c31183 | 268 | .SH SEE ALSO |
47c31183 MK |
269 | .BR mallinfo (3), |
270 | .BR malloc (3), | |
271 | .BR malloc_stats (3), | |
a5cbea5f MK |
272 | .BR mallopt (3), |
273 | .BR open_memstream (3) |