Debian Codegraph @

upstream/debian-unstable/man3/mallinfo.3

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