1mallinfo(3)                Library Functions Manual                mallinfo(3)
2
3
4

NAME

6       mallinfo, mallinfo2 - obtain memory allocation information
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <malloc.h>
13
14       struct mallinfo mallinfo(void);
15       struct mallinfo2 mallinfo2(void);
16

DESCRIPTION

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

STANDARDS

96       None.
97

HISTORY

99       mallinfo()
100              glibc 2.0.  SVID.
101
102       mallinfo2()
103              glibc 2.33.
104

BUGS

106       Information is returned for  only  the  main  memory  allocation  area.
107       Allocations  in  other  arenas  are  excluded.  See malloc_stats(3) and
108       malloc_info(3) for alternatives that include  information  about  other
109       arenas.
110
111       The  fields  of  the  mallinfo  structure that is returned by the older
112       mallinfo() function are typed as int.  However, because  some  internal
113       bookkeeping  values  may  be of type long, the reported values may wrap
114       around zero and thus be inaccurate.
115

EXAMPLES

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

SEE ALSO

247       mmap(2), malloc(3), malloc_info(3), malloc_stats(3), malloc_trim(3),
248       mallopt(3)
249
250
251
252Linux man-pages 6.05              2023-07-20                       mallinfo(3)
Impressum