| blob | 20ac7f8962540d7b23f11b0679fb58f6e7438594 |
1 '\" t
2 .\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com>
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH mallinfo 3 (date) "Linux man-pages (unreleased)"
7 .SH NAME
8 mallinfo, mallinfo2 \- obtain memory allocation information
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ", " \-lc )
12 .SH SYNOPSIS
13 .nf
14 .B #include <malloc.h>
15 .P
16 .B struct mallinfo mallinfo(void);
17 .B struct mallinfo2 mallinfo2(void);
18 .fi
19 .SH DESCRIPTION
20 These functions return a copy of a structure containing information about
21 memory allocations performed by
22 .BR malloc (3)
23 and related functions.
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).
28 .P
29 Note that not all allocations are visible to these functions;
30 see BUGS and consider using
31 .BR malloc_info (3)
32 instead.
33 .P
34 The
35 .I mallinfo2
36 structure returned by
37 .BR mallinfo2 ()
38 is defined as follows:
39 .P
40 .in +4n
41 .EX
42 struct mallinfo2 {
43 size_t arena; /* Non\-mmapped space allocated (bytes) */
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) */
53 size_t keepcost; /* Top\-most, releasable space (bytes) */
54 };
55 .EE
56 .in
57 .P
58 The
59 .I mallinfo
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 .P
65 The structure fields contain the following information:
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
77 .\" the glibc info page wrongly says this field is unused
78 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=26746
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).
85 (See the discussion of
86 .B M_MMAP_THRESHOLD
87 in
88 .BR mallopt (3).)
89 .TP
90 .I hblkhd
91 The number of bytes in blocks currently allocated using
92 .BR mmap (2).
93 .TP
94 .I usmblks
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
97 Historically, it was the "highwater mark" for allocated space\[em]that is,
98 the maximum amount of space that was ever allocated (in bytes);
99 this field was maintained only in nonthreading environments.
100 .TP
101 .I fsmblks
102 .\" the glibc info page wrongly says this field is unused
103 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=26746
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).
118 .SH ATTRIBUTES
119 For an explanation of the terms used in this section, see
120 .BR attributes (7).
121 .TS
122 allbox;
123 lb lb lbx
124 l l l.
125 Interface Attribute Value
126 T{
127 .na
128 .nh
129 .BR mallinfo (),
130 .BR mallinfo2 ()
131 T} Thread safety T{
132 .na
133 .nh
134 MT-Unsafe init const:mallopt
135 T}
136 .TE
137 .P
138 .BR mallinfo ()/
139 .BR mallinfo2 ()
140 would access some global internal objects.
141 If modify them with non-atomically,
142 may get inconsistent results.
143 The identifier
144 .I mallopt
145 in
146 .I const:mallopt
147 mean that
148 .BR mallopt ()
149 would modify the global internal objects with atomics, that make sure
150 .BR mallinfo ()/
151 .BR mallinfo2 ()
152 is safe enough, others modify with non-atomically maybe not.
153 .SH STANDARDS
154 None.
155 .SH HISTORY
156 .TP
157 .BR mallinfo ()
158 glibc 2.0.
159 SVID.
160 .TP
161 .BR mallinfo2 ()
162 .\" commit e3960d1c57e57f33e0e846d615788f4ede73b945
163 glibc 2.33.
164 .SH BUGS
165 .\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=208
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
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.
176 .P
177 The fields of the
178 .I mallinfo
179 structure that is returned by the older
180 .BR mallinfo ()
181 function are typed as
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.
186 .SH EXAMPLES
187 The program below employs
188 .BR mallinfo2 ()
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.
192 .P
193 The first two command-line arguments specify the number and size of
194 blocks to be allocated with
195 .BR malloc (3).
196 .P
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.
210 .P
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 .P
215 .in +4n
216 .EX
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
229 \&
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
241 \&
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
253 .EE
254 .in
255 .SS Program source
256 \&
257 .\" SRC BEGIN (mallinfo.c)
258 .EX
259 #include <malloc.h>
260 #include <stdlib.h>
261 #include <string.h>
262 \&
263 static void
264 display_mallinfo2(void)
265 {
266 struct mallinfo2 mi;
267 \&
268 mi = mallinfo2();
269 \&
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);
280 }
281 \&
282 int
283 main(int argc, char *argv[])
284 {
285 #define MAX_ALLOCS 2000000
286 char *alloc[MAX_ALLOCS];
287 size_t blockSize, numBlocks, freeBegin, freeEnd, freeStep;
288 \&
289 if (argc < 3 || strcmp(argv[1], "\-\-help") == 0) {
290 fprintf(stderr, "%s num\-blocks block\-size [free\-step "
291 "[start\-free [end\-free]]]\en", argv[0]);
292 exit(EXIT_FAILURE);
293 }
294 \&
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;
300 \&
301 printf("============== Before allocating blocks ==============\en");
302 display_mallinfo2();
303 \&
304 for (size_t j = 0; j < numBlocks; j++) {
305 if (numBlocks >= MAX_ALLOCS) {
306 fprintf(stderr, "Too many allocations\en");
307 exit(EXIT_FAILURE);
308 }
309 \&
310 alloc[j] = malloc(blockSize);
311 if (alloc[j] == NULL) {
312 perror("malloc");
313 exit(EXIT_FAILURE);
314 }
315 }
316 \&
317 printf("\en============== After allocating blocks ==============\en");
318 display_mallinfo2();
319 \&
320 for (size_t j = freeBegin; j < freeEnd; j += freeStep)
321 free(alloc[j]);
322 \&
323 printf("\en============== After freeing blocks ==============\en");
324 display_mallinfo2();
325 \&
326 exit(EXIT_SUCCESS);
327 }
328 .EE
329 .\" SRC END
330 .SH SEE ALSO
331 .ad l
332 .nh
333 .BR mmap (2),
334 .BR malloc (3),
335 .BR malloc_info (3),
336 .BR malloc_stats (3),
337 .BR malloc_trim (3),
338 .BR mallopt (3)