1MALLINFO(3)                Linux Programmer's Manual               MALLINFO(3)
2
3
4

NAME

6       mallinfo, mallinfo2 - obtain memory allocation information
7

SYNOPSIS

9       #include <malloc.h>
10
11       struct mallinfo mallinfo(void);
12       struct mallinfo2 mallinfo2(void);
13

DESCRIPTION

15       These  functions  return  a  copy of a structure containing information
16       about memory allocations performed by malloc(3) and related  functions.
17       The structure returned by each function contains the same fields.  How‐
18       ever, the older function, mallinfo(), is deprecated since the type used
19       for the fields is too small (see BUGS).
20
21       Note  that not all allocations are visible to these functions; see BUGS
22       and consider using malloc_info(3) instead.
23
24       The mallinfo2 structure returned by mallinfo2() is defined as follows:
25
26           struct mallinfo2 {
27               size_t arena;     /* Non-mmapped space allocated (bytes) */
28               size_t ordblks;   /* Number of free chunks */
29               size_t smblks;    /* Number of free fastbin blocks */
30               size_t hblks;     /* Number of mmapped regions */
31               size_t hblkhd;    /* Space allocated in mmapped regions
32                                    (bytes) */
33               size_t usmblks;   /* See below */
34               size_t fsmblks;   /* Space in freed fastbin blocks (bytes) */
35               size_t uordblks;  /* Total allocated space (bytes) */
36               size_t fordblks;  /* Total free space (bytes) */
37               size_t keepcost;  /* Top-most, releasable space (bytes) */
38           };
39
40       The mallinfo structure returned by the deprecated  mallinfo()  function
41       is exactly the same, except that the fields are typed as int.
42
43       The structure fields contain the following information:
44
45       arena     The  total  amount  of  memory  allocated by means other than
46                 mmap(2) (i.e., memory allocated on the  heap).   This  figure
47                 includes both in-use blocks and blocks on the free list.
48
49       ordblks   The number of ordinary (i.e., non-fastbin) free blocks.
50
51       smblks    The number of fastbin free blocks (see mallopt(3)).
52
53       hblks     The number of blocks currently allocated using mmap(2).  (See
54                 the discussion of M_MMAP_THRESHOLD in mallopt(3).)
55
56       hblkhd    The number of  bytes  in  blocks  currently  allocated  using
57                 mmap(2).
58
59       usmblks   This  field is unused, and is always 0.  Historically, it was
60                 the "highwater mark" for allocated space—that is, the maximum
61                 amount  of  space  that  was  ever allocated (in bytes); this
62                 field was maintained only in nonthreading environments.
63
64       fsmblks   The total number of bytes in fastbin free blocks.
65
66       uordblks  The total number of bytes used by in-use allocations.
67
68       fordblks  The total number of bytes in free blocks.
69
70       keepcost  The total amount of releasable free space at the top  of  the
71                 heap.  This is the maximum number of bytes that could ideally
72                 (i.e., ignoring page alignment restrictions, and  so  on)  be
73                 released by malloc_trim(3).
74

VERSIONS

76       The mallinfo2() function was added in glibc 2.33.
77

ATTRIBUTES

79       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
80       tributes(7).
81
82       ┌────────────┬───────────────┬─────────────────────────────────────────┐
83Interface   Attribute     Value                                   
84       ├────────────┼───────────────┼─────────────────────────────────────────┤
85mallinfo(), │ Thread safety │ MT-Unsafe init const:mallopt            │
86mallinfo2() │               │                                         │
87       └────────────┴───────────────┴─────────────────────────────────────────┘
88       mallinfo()/  mallinfo2() would access some global internal objects.  If
89       modify them with non-atomically, may  get  inconsistent  results.   The
90       identifier  mallopt  in  const:mallopt mean that mallopt() would modify
91       the global internal objects with atomics, that  make  sure  mallinfo()/
92       mallinfo2()  is  safe  enough,  others modify with non-atomically maybe
93       not.
94

CONFORMING TO

96       These functions are not specified by  POSIX  or  the  C  standards.   A
97       mallinfo() function exists on many System V derivatives, and was speci‐
98       fied in the SVID.
99

BUGS

101       Information is returned for only the main memory allocation area.   Al‐
102       locations  in  other arenas are excluded.  See malloc_stats(3) and mal‐
103       loc_info(3) for alternatives that include information about other  are‐
104       nas.
105
106       The  fields  of  the  mallinfo  structure that is returned by the older
107       mallinfo() function are typed as int.  However, because  some  internal
108       bookkeeping  values  may  be of type long, the reported values may wrap
109       around zero and thus be inaccurate.
110

EXAMPLES

112       The program below employs mallinfo2()  to  retrieve  memory  allocation
113       statistics before and after allocating and freeing some blocks of memo‐
114       ry.  The statistics are displayed on standard output.
115
116       The first two command-line arguments specify the  number  and  size  of
117       blocks to be allocated with malloc(3).
118
119       The  remaining  three  arguments  specify which of the allocated blocks
120       should be freed with free(3).  These three arguments are optional,  and
121       specify  (in  order):  the  step size to be used in the loop that frees
122       blocks (the default is 1, meaning free all blocks in  the  range);  the
123       ordinal position of the first block to be freed (default 0, meaning the
124       first allocated block); and a number one greater than the ordinal posi‐
125       tion  of  the  last  block to be freed (default is one greater than the
126       maximum block number).  If these three arguments are omitted, then  the
127       defaults cause all allocated blocks to be freed.
128
129       In  the  following  example run of the program, 1000 allocations of 100
130       bytes are performed, and then every second allocated block is freed:
131
132           $ ./a.out 1000 100 2
133           ============== Before allocating blocks ==============
134           Total non-mmapped bytes (arena):       0
135           # of free chunks (ordblks):            1
136           # of free fastbin blocks (smblks):     0
137           # of mapped regions (hblks):           0
138           Bytes in mapped regions (hblkhd):      0
139           Max. total allocated space (usmblks):  0
140           Free bytes held in fastbins (fsmblks): 0
141           Total allocated space (uordblks):      0
142           Total free space (fordblks):           0
143           Topmost releasable block (keepcost):   0
144
145           ============== After allocating blocks ==============
146           Total non-mmapped bytes (arena):       135168
147           # of free chunks (ordblks):            1
148           # of free fastbin blocks (smblks):     0
149           # of mapped regions (hblks):           0
150           Bytes in mapped regions (hblkhd):      0
151           Max. total allocated space (usmblks):  0
152           Free bytes held in fastbins (fsmblks): 0
153           Total allocated space (uordblks):      104000
154           Total free space (fordblks):           31168
155           Topmost releasable block (keepcost):   31168
156
157           ============== After freeing blocks ==============
158           Total non-mmapped bytes (arena):       135168
159           # of free chunks (ordblks):            501
160           # of free fastbin blocks (smblks):     0
161           # of mapped regions (hblks):           0
162           Bytes in mapped regions (hblkhd):      0
163           Max. total allocated space (usmblks):  0
164           Free bytes held in fastbins (fsmblks): 0
165           Total allocated space (uordblks):      52000
166           Total free space (fordblks):           83168
167           Topmost releasable block (keepcost):   31168
168
169   Program source
170
171       #include <malloc.h>
172       #include <stdlib.h>
173       #include <string.h>
174
175       static void
176       display_mallinfo2(void)
177       {
178           struct mallinfo2 mi;
179
180           mi = mallinfo2();
181
182           printf("Total non-mmapped bytes (arena):       %zu\n", mi.arena);
183           printf("# of free chunks (ordblks):            %zu\n", mi.ordblks);
184           printf("# of free fastbin blocks (smblks):     %zu\n", mi.smblks);
185           printf("# of mapped regions (hblks):           %zu\n", mi.hblks);
186           printf("Bytes in mapped regions (hblkhd):      %zu\n", mi.hblkhd);
187           printf("Max. total allocated space (usmblks):  %zu\n", mi.usmblks);
188           printf("Free bytes held in fastbins (fsmblks): %zu\n", mi.fsmblks);
189           printf("Total allocated space (uordblks):      %zu\n", mi.uordblks);
190           printf("Total free space (fordblks):           %zu\n", mi.fordblks);
191           printf("Topmost releasable block (keepcost):   %zu\n", mi.keepcost);
192       }
193
194       int
195       main(int argc, char *argv[])
196       {
197       #define MAX_ALLOCS 2000000
198           char *alloc[MAX_ALLOCS];
199           int numBlocks, freeBegin, freeEnd, freeStep;
200           size_t blockSize;
201
202           if (argc < 3 || strcmp(argv[1], "--help") == 0) {
203               fprintf(stderr, "%s num-blocks block-size [free-step "
204                       "[start-free [end-free]]]\n", argv[0]);
205               exit(EXIT_FAILURE);
206           }
207
208           numBlocks = atoi(argv[1]);
209           blockSize = atoi(argv[2]);
210           freeStep = (argc > 3) ? atoi(argv[3]) : 1;
211           freeBegin = (argc > 4) ? atoi(argv[4]) : 0;
212           freeEnd = (argc > 5) ? atoi(argv[5]) : numBlocks;
213
214           printf("============== Before allocating blocks ==============\n");
215           display_mallinfo2();
216
217           for (int j = 0; j < numBlocks; j++) {
218               if (numBlocks >= MAX_ALLOCS) {
219                   fprintf(stderr, "Too many allocations\n");
220                   exit(EXIT_FAILURE);
221               }
222
223               alloc[j] = malloc(blockSize);
224               if (alloc[j] == NULL) {
225                   perror("malloc");
226                   exit(EXIT_FAILURE);
227               }
228           }
229
230           printf("\n============== After allocating blocks ==============\n");
231           display_mallinfo2();
232
233           for (int j = freeBegin; j < freeEnd; j += freeStep)
234               free(alloc[j]);
235
236           printf("\n============== After freeing blocks ==============\n");
237           display_mallinfo2();
238
239           exit(EXIT_SUCCESS);
240       }
241

SEE ALSO

243       mmap(2), malloc(3), malloc_info(3), malloc_stats(3), malloc_trim(3),
244       mallopt(3)
245

COLOPHON

247       This page is part of release 5.12 of the Linux man-pages project.  A
248       description of the project, information about reporting bugs, and the
249       latest version of this page, can be found at
250       https://www.kernel.org/doc/man-pages/.
251
252
253
254Linux                             2021-03-22                       MALLINFO(3)
Impressum