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