]>
Commit | Line | Data |
---|---|---|
a1eaacb1 | 1 | '\" t |
3c81c5a4 | 2 | .\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com> |
62d874a0 | 3 | .\" |
5fbde956 | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
62d874a0 | 5 | .\" |
4c1c5274 | 6 | .TH mallinfo 3 (date) "Linux man-pages (unreleased)" |
62d874a0 | 7 | .SH NAME |
5bf72683 | 8 | mallinfo, mallinfo2 \- obtain memory allocation information |
9b621573 AC |
9 | .SH LIBRARY |
10 | Standard C library | |
8fc3b2cf | 11 | .RI ( libc ", " \-lc ) |
62d874a0 | 12 | .SH SYNOPSIS |
5bf72683 | 13 | .nf |
62d874a0 | 14 | .B #include <malloc.h> |
f90f031e | 15 | .PP |
62d874a0 | 16 | .B struct mallinfo mallinfo(void); |
5bf72683 MK |
17 | .B struct mallinfo2 mallinfo2(void); |
18 | .fi | |
62d874a0 | 19 | .SH DESCRIPTION |
5bf72683 | 20 | These functions return a copy of a structure containing information about |
62d874a0 MK |
21 | memory allocations performed by |
22 | .BR malloc (3) | |
23 | and related functions. | |
5bf72683 MK |
24 | The structure returned by each function contains the same fields. |
25 | However, the older function, | |
26 | .BR mallinfo (), | |
27 | is deprecated since the type used for the fields is too small (see BUGS). | |
2eb8835a | 28 | .PP |
5bf72683 | 29 | Note that not all allocations are visible to these functions; |
2eb8835a EH |
30 | see BUGS and consider using |
31 | .BR malloc_info (3) | |
32 | instead. | |
33 | .PP | |
5bf72683 MK |
34 | The |
35 | .I mallinfo2 | |
36 | structure returned by | |
37 | .BR mallinfo2 () | |
38 | is defined as follows: | |
62d874a0 MK |
39 | .PP |
40 | .in +4n | |
b8302363 | 41 | .EX |
5bf72683 | 42 | struct mallinfo2 { |
d064d41a | 43 | size_t arena; /* Non\-mmapped space allocated (bytes) */ |
5bf72683 MK |
44 | size_t ordblks; /* Number of free chunks */ |
45 | size_t smblks; /* Number of free fastbin blocks */ | |
46 | size_t hblks; /* Number of mmapped regions */ | |
47 | size_t hblkhd; /* Space allocated in mmapped regions | |
48 | (bytes) */ | |
49 | size_t usmblks; /* See below */ | |
50 | size_t fsmblks; /* Space in freed fastbin blocks (bytes) */ | |
51 | size_t uordblks; /* Total allocated space (bytes) */ | |
52 | size_t fordblks; /* Total free space (bytes) */ | |
d064d41a | 53 | size_t keepcost; /* Top\-most, releasable space (bytes) */ |
62d874a0 | 54 | }; |
b8302363 | 55 | .EE |
62d874a0 MK |
56 | .in |
57 | .PP | |
5bf72683 | 58 | The |
62d874a0 | 59 | .I mallinfo |
5bf72683 MK |
60 | structure returned by the deprecated |
61 | .BR mallinfo () | |
62 | function is exactly the same, except that the fields are typed as | |
63 | .IR int . | |
64 | .PP | |
65 | The structure fields contain the following information: | |
62d874a0 MK |
66 | .TP 10 |
67 | .I arena | |
68 | The total amount of memory allocated by means other than | |
69 | .BR mmap (2) | |
70 | (i.e., memory allocated on the heap). | |
71 | This figure includes both in-use blocks and blocks on the free list. | |
72 | .TP | |
73 | .I ordblks | |
74 | The number of ordinary (i.e., non-fastbin) free blocks. | |
75 | .TP | |
76 | .I smblks | |
185f4da5 MK |
77 | .\" the glibc info page wrongly says this field is unused |
78 | .\" https://sourceware.org/bugzilla/show_bug.cgi?id=26746 | |
62d874a0 MK |
79 | The number of fastbin free blocks (see |
80 | .BR mallopt (3)). | |
81 | .TP | |
82 | .I hblks | |
83 | The number of blocks currently allocated using | |
84 | .BR mmap (2). | |
35af1345 MK |
85 | (See the discussion of |
86 | .B M_MMAP_THRESHOLD | |
87 | in | |
88 | .BR mallopt (3).) | |
62d874a0 MK |
89 | .TP |
90 | .I hblkhd | |
91 | The number of bytes in blocks currently allocated using | |
92 | .BR mmap (2). | |
93 | .TP | |
94 | .I usmblks | |
70fd3c08 MK |
95 | This field is unused, and is always 0. |
96 | .\" It seems to have been zero since at least as far back as glibc 2.15 | |
36546c38 | 97 | Historically, it was the "highwater mark" for allocated space\[em]that is, |
70fd3c08 MK |
98 | the maximum amount of space that was ever allocated (in bytes); |
99 | this field was maintained only in nonthreading environments. | |
62d874a0 MK |
100 | .TP |
101 | .I fsmblks | |
185f4da5 MK |
102 | .\" the glibc info page wrongly says this field is unused |
103 | .\" https://sourceware.org/bugzilla/show_bug.cgi?id=26746 | |
62d874a0 MK |
104 | The total number of bytes in fastbin free blocks. |
105 | .TP | |
106 | .I uordblks | |
107 | The total number of bytes used by in-use allocations. | |
108 | .TP | |
109 | .I fordblks | |
110 | The total number of bytes in free blocks. | |
111 | .TP | |
112 | .I keepcost | |
113 | The total amount of releasable free space at the top | |
114 | of the heap. | |
115 | This is the maximum number of bytes that could ideally | |
116 | (i.e., ignoring page alignment restrictions, and so on) be released by | |
117 | .BR malloc_trim (3). | |
c32cf268 ZL |
118 | .SH ATTRIBUTES |
119 | For an explanation of the terms used in this section, see | |
120 | .BR attributes (7). | |
121 | .TS | |
122 | allbox; | |
b32feea5 | 123 | lb lb lbx |
c32cf268 ZL |
124 | l l l. |
125 | Interface Attribute Value | |
126 | T{ | |
9e54434e BR |
127 | .na |
128 | .nh | |
5bf72683 MK |
129 | .BR mallinfo (), |
130 | .BR mallinfo2 () | |
b32feea5 | 131 | T} Thread safety T{ |
9e54434e BR |
132 | .na |
133 | .nh | |
b32feea5 MK |
134 | MT-Unsafe init const:mallopt |
135 | T} | |
c32cf268 | 136 | .TE |
847e0d88 | 137 | .sp 1 |
5bf72683 MK |
138 | .BR mallinfo ()/ |
139 | .BR mallinfo2 () | |
696bd2da MK |
140 | would access some global internal objects. |
141 | If modify them with non-atomically, | |
c32cf268 ZL |
142 | may get inconsistent results. |
143 | The identifier | |
144 | .I mallopt | |
145 | in | |
146 | .I const:mallopt | |
147 | mean that | |
148 | .BR mallopt () | |
3c841730 | 149 | would modify the global internal objects with atomics, that make sure |
5bf72683 MK |
150 | .BR mallinfo ()/ |
151 | .BR mallinfo2 () | |
c32cf268 | 152 | is safe enough, others modify with non-atomically maybe not. |
3113c7f3 | 153 | .SH STANDARDS |
4131356c AC |
154 | None. |
155 | .SH HISTORY | |
156 | .TP | |
5bf72683 | 157 | .BR mallinfo () |
4131356c AC |
158 | glibc 2.0. |
159 | SVID. | |
160 | .TP | |
161 | .BR mallinfo2 () | |
162 | .\" commit e3960d1c57e57f33e0e846d615788f4ede73b945 | |
163 | glibc 2.33. | |
f704bc68 | 164 | .SH BUGS |
bea08fec | 165 | .\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=208 |
f704bc68 MK |
166 | .\" See the 24 Aug 2011 mail by Paul Pluzhnikov: |
167 | .\" "[patch] Fix mallinfo() to accumulate results for all arenas" | |
168 | .\" on libc-alpha@sourceware.org | |
3c81c5a4 MK |
169 | .B Information is returned for only the main memory allocation area. |
170 | Allocations in other arenas are excluded. | |
171 | See | |
172 | .BR malloc_stats (3) | |
173 | and | |
174 | .BR malloc_info (3) | |
175 | for alternatives that include information about other arenas. | |
847e0d88 | 176 | .PP |
62d874a0 MK |
177 | The fields of the |
178 | .I mallinfo | |
5bf72683 MK |
179 | structure that is returned by the older |
180 | .BR mallinfo () | |
181 | function are typed as | |
62d874a0 MK |
182 | .IR int . |
183 | However, because some internal bookkeeping values may be of type | |
184 | .IR long , | |
185 | the reported values may wrap around zero and thus be inaccurate. | |
a14af333 | 186 | .SH EXAMPLES |
62d874a0 | 187 | The program below employs |
e9e53453 | 188 | .BR mallinfo2 () |
62d874a0 MK |
189 | to retrieve memory allocation statistics before and after |
190 | allocating and freeing some blocks of memory. | |
191 | The statistics are displayed on standard output. | |
847e0d88 | 192 | .PP |
62d874a0 MK |
193 | The first two command-line arguments specify the number and size of |
194 | blocks to be allocated with | |
195 | .BR malloc (3). | |
847e0d88 | 196 | .PP |
62d874a0 MK |
197 | The remaining three arguments specify which of the allocated blocks |
198 | should be freed with | |
199 | .BR free (3). | |
200 | These three arguments are optional, and specify (in order): | |
201 | the step size to be used in the loop that frees blocks | |
202 | (the default is 1, meaning free all blocks in the range); | |
203 | the ordinal position of the first block to be freed | |
204 | (default 0, meaning the first allocated block); | |
205 | and a number one greater than the ordinal position | |
206 | of the last block to be freed | |
207 | (default is one greater than the maximum block number). | |
208 | If these three arguments are omitted, | |
209 | then the defaults cause all allocated blocks to be freed. | |
847e0d88 | 210 | .PP |
62d874a0 MK |
211 | In the following example run of the program, |
212 | 1000 allocations of 100 bytes are performed, | |
213 | and then every second allocated block is freed: | |
214 | .PP | |
215 | .in +4n | |
b8302363 | 216 | .EX |
62d874a0 MK |
217 | $ \fB./a.out 1000 100 2\fP |
218 | ============== Before allocating blocks ============== | |
219 | Total non\-mmapped bytes (arena): 0 | |
220 | # of free chunks (ordblks): 1 | |
221 | # of free fastbin blocks (smblks): 0 | |
222 | # of mapped regions (hblks): 0 | |
223 | Bytes in mapped regions (hblkhd): 0 | |
224 | Max. total allocated space (usmblks): 0 | |
225 | Free bytes held in fastbins (fsmblks): 0 | |
226 | Total allocated space (uordblks): 0 | |
227 | Total free space (fordblks): 0 | |
228 | Topmost releasable block (keepcost): 0 | |
fe5dba13 | 229 | \& |
62d874a0 MK |
230 | ============== After allocating blocks ============== |
231 | Total non\-mmapped bytes (arena): 135168 | |
232 | # of free chunks (ordblks): 1 | |
233 | # of free fastbin blocks (smblks): 0 | |
234 | # of mapped regions (hblks): 0 | |
235 | Bytes in mapped regions (hblkhd): 0 | |
236 | Max. total allocated space (usmblks): 0 | |
237 | Free bytes held in fastbins (fsmblks): 0 | |
238 | Total allocated space (uordblks): 104000 | |
239 | Total free space (fordblks): 31168 | |
240 | Topmost releasable block (keepcost): 31168 | |
fe5dba13 | 241 | \& |
62d874a0 MK |
242 | ============== After freeing blocks ============== |
243 | Total non\-mmapped bytes (arena): 135168 | |
244 | # of free chunks (ordblks): 501 | |
245 | # of free fastbin blocks (smblks): 0 | |
246 | # of mapped regions (hblks): 0 | |
247 | Bytes in mapped regions (hblkhd): 0 | |
248 | Max. total allocated space (usmblks): 0 | |
249 | Free bytes held in fastbins (fsmblks): 0 | |
250 | Total allocated space (uordblks): 52000 | |
251 | Total free space (fordblks): 83168 | |
252 | Topmost releasable block (keepcost): 31168 | |
b8302363 | 253 | .EE |
62d874a0 MK |
254 | .in |
255 | .SS Program source | |
256 | \& | |
b0b6ab4e | 257 | .\" SRC BEGIN (mallinfo.c) |
e7d0bb47 | 258 | .EX |
62d874a0 | 259 | #include <malloc.h> |
e40be343 JW |
260 | #include <stdlib.h> |
261 | #include <string.h> | |
fe5dba13 | 262 | \& |
62d874a0 | 263 | static void |
e9e53453 | 264 | display_mallinfo2(void) |
62d874a0 | 265 | { |
e9e53453 | 266 | struct mallinfo2 mi; |
fe5dba13 | 267 | \& |
e9e53453 | 268 | mi = mallinfo2(); |
fe5dba13 | 269 | \& |
e9e53453 MK |
270 | printf("Total non\-mmapped bytes (arena): %zu\en", mi.arena); |
271 | printf("# of free chunks (ordblks): %zu\en", mi.ordblks); | |
272 | printf("# of free fastbin blocks (smblks): %zu\en", mi.smblks); | |
273 | printf("# of mapped regions (hblks): %zu\en", mi.hblks); | |
274 | printf("Bytes in mapped regions (hblkhd): %zu\en", mi.hblkhd); | |
275 | printf("Max. total allocated space (usmblks): %zu\en", mi.usmblks); | |
276 | printf("Free bytes held in fastbins (fsmblks): %zu\en", mi.fsmblks); | |
277 | printf("Total allocated space (uordblks): %zu\en", mi.uordblks); | |
278 | printf("Total free space (fordblks): %zu\en", mi.fordblks); | |
279 | printf("Topmost releasable block (keepcost): %zu\en", mi.keepcost); | |
62d874a0 | 280 | } |
fe5dba13 | 281 | \& |
62d874a0 MK |
282 | int |
283 | main(int argc, char *argv[]) | |
284 | { | |
285 | #define MAX_ALLOCS 2000000 | |
286 | char *alloc[MAX_ALLOCS]; | |
b42296e4 | 287 | size_t blockSize, numBlocks, freeBegin, freeEnd, freeStep; |
fe5dba13 | 288 | \& |
e40be343 JW |
289 | if (argc < 3 || strcmp(argv[1], "\-\-help") == 0) { |
290 | fprintf(stderr, "%s num\-blocks block\-size [free\-step " | |
d1a71985 | 291 | "[start\-free [end\-free]]]\en", argv[0]); |
e40be343 JW |
292 | exit(EXIT_FAILURE); |
293 | } | |
fe5dba13 | 294 | \& |
62d874a0 MK |
295 | numBlocks = atoi(argv[1]); |
296 | blockSize = atoi(argv[2]); | |
297 | freeStep = (argc > 3) ? atoi(argv[3]) : 1; | |
298 | freeBegin = (argc > 4) ? atoi(argv[4]) : 0; | |
299 | freeEnd = (argc > 5) ? atoi(argv[5]) : numBlocks; | |
fe5dba13 | 300 | \& |
d1a71985 | 301 | printf("============== Before allocating blocks ==============\en"); |
e9e53453 | 302 | display_mallinfo2(); |
fe5dba13 | 303 | \& |
b42296e4 | 304 | for (size_t j = 0; j < numBlocks; j++) { |
e40be343 | 305 | if (numBlocks >= MAX_ALLOCS) { |
d1a71985 | 306 | fprintf(stderr, "Too many allocations\en"); |
e40be343 JW |
307 | exit(EXIT_FAILURE); |
308 | } | |
fe5dba13 | 309 | \& |
62d874a0 | 310 | alloc[j] = malloc(blockSize); |
e40be343 JW |
311 | if (alloc[j] == NULL) { |
312 | perror("malloc"); | |
313 | exit(EXIT_FAILURE); | |
314 | } | |
62d874a0 | 315 | } |
fe5dba13 | 316 | \& |
d1a71985 | 317 | printf("\en============== After allocating blocks ==============\en"); |
e9e53453 | 318 | display_mallinfo2(); |
fe5dba13 | 319 | \& |
b42296e4 | 320 | for (size_t j = freeBegin; j < freeEnd; j += freeStep) |
62d874a0 | 321 | free(alloc[j]); |
fe5dba13 | 322 | \& |
d1a71985 | 323 | printf("\en============== After freeing blocks ==============\en"); |
e9e53453 | 324 | display_mallinfo2(); |
fe5dba13 | 325 | \& |
62d874a0 MK |
326 | exit(EXIT_SUCCESS); |
327 | } | |
e7d0bb47 | 328 | .EE |
b0b6ab4e | 329 | .\" SRC END |
62d874a0 MK |
330 | .SH SEE ALSO |
331 | .ad l | |
332 | .nh | |
333 | .BR mmap (2), | |
334 | .BR malloc (3), | |
3c81c5a4 | 335 | .BR malloc_info (3), |
62d874a0 MK |
336 | .BR malloc_stats (3), |
337 | .BR malloc_trim (3), | |
338 | .BR mallopt (3) |