man3/mallinfo.3

   1 '\" t
   2 .\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .TH MALLINFO 3  2017-09-15 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 mallinfo \- obtain memory allocation information
  29 .SH SYNOPSIS
  30 .B #include <malloc.h>
  31 .PP
  32 .B struct mallinfo mallinfo(void);
  33 .SH DESCRIPTION
  34 The
  35 .BR mallinfo ()
  36 function returns a copy of a structure containing information about
  37 memory allocations performed by
  38 .BR malloc (3)
  39 and related functions.
  40 This structure is defined as follows:
  41 .PP
  42 .in +4n
  43 .EX
  44 struct mallinfo {
  45     int arena;     /* Non-mmapped space allocated (bytes) */
  46     int ordblks;   /* Number of free chunks */
  47     int smblks;    /* Number of free fastbin blocks */
  48     int hblks;     /* Number of mmapped regions */
  49     int hblkhd;    /* Space allocated in mmapped regions (bytes) */
  50     int usmblks;   /* Maximum total allocated space (bytes) */
  51     int fsmblks;   /* Space in freed fastbin blocks (bytes) */
  52     int uordblks;  /* Total allocated space (bytes) */
  53     int fordblks;  /* Total free space (bytes) */
  54     int keepcost;  /* Top-most, releasable space (bytes) */
  55 };
  56 .EE
  57 .in
  58 .PP
  59 The fields of the
  60 .I mallinfo
  61 structure contain the following information:
  62 .TP 10
  63 .I arena
  64 The total amount of memory allocated by means other than
  65 .BR mmap (2)
  66 (i.e., memory allocated on the heap).
  67 This figure includes both in-use blocks and blocks on the free list.
  68 .TP
  69 .I ordblks
  70 The number of ordinary (i.e., non-fastbin) free blocks.
  71 .TP
  72 .I smblks
  73 The number of fastbin free blocks (see
  74 .BR mallopt (3)).
  75 .TP
  76 .I hblks
  77 The number of blocks currently allocated using
  78 .BR mmap (2).
  79 (See the discussion of
  80 .B M_MMAP_THRESHOLD
  81 in
  82 .BR mallopt (3).)
  83 .TP
  84 .I hblkhd
  85 The number of bytes in blocks currently allocated using
  86 .BR mmap (2).
  87 .TP
  88 .I usmblks
  89 The "highwater mark" for allocated space\(emthat is,
  90 the maximum amount of space that was ever allocated.
  91 This field is maintained only in nonthreading environments.
  92 .TP
  93 .I fsmblks
  94 The total number of bytes in fastbin free blocks.
  95 .TP
  96 .I uordblks
  97 The total number of bytes used by in-use allocations.
  98 .TP
  99 .I fordblks
 100 The total number of bytes in free blocks.
 101 .TP
 102 .I keepcost
 103 The total amount of releasable free space at the top
 104 of the heap.
 105 This is the maximum number of bytes that could ideally
 106 (i.e., ignoring page alignment restrictions, and so on) be released by
 107 .BR malloc_trim (3).
 108 .\" .SH VERSIONS
 109 .\" Available already in glibc 2.0, possibly earlier
 110 .SH ATTRIBUTES
 111 For an explanation of the terms used in this section, see
 112 .BR attributes (7).
 113 .TS
 114 allbox;
 115 lb lb lbw28
 116 l l l.
 117 Interface       Attribute       Value
 118 T{
 119 .BR mallinfo ()
 120 T}      Thread safety   MT-Unsafe init const:mallopt
 121 .TE
 122 .sp 1
 123 .BR mallinfo ()
 124 would access some global internal objects.
 125 If modify them with non-atomically,
 126 may get inconsistent results.
 127 The identifier
 128 .I mallopt
 129 in
 130 .I const:mallopt
 131 mean that
 132 .BR mallopt ()
 133 would modify the global internal objects with atomics, that make sure
 134 .BR mallinfo ()
 135 is safe enough, others modify with non-atomically maybe not.
 136 .SH CONFORMING TO
 137 This function is not specified by POSIX or the C standards.
 138 A similar function exists on many System V derivatives,
 139 and was specified in the SVID.
 140 .SH BUGS
 141 .\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=208
 142 .\" See the 24 Aug 2011 mail by Paul Pluzhnikov:
 143 .\"     "[patch] Fix mallinfo() to accumulate results for all arenas"
 144 .\" on libc-alpha@sourceware.org
 145 .B Information is returned for only the main memory allocation area.
 146 Allocations in other arenas are excluded.
 147 See
 148 .BR malloc_stats (3)
 149 and
 150 .BR malloc_info (3)
 151 for alternatives that include information about other arenas.
 152 .PP
 153 The fields of the
 154 .I mallinfo
 155 structure are typed as
 156 .IR int .
 157 However, because some internal bookkeeping values may be of type
 158 .IR long ,
 159 the reported values may wrap around zero and thus be inaccurate.
 160 .SH EXAMPLE
 161 The program below employs
 162 .BR mallinfo ()
 163 to retrieve memory allocation statistics before and after
 164 allocating and freeing some blocks of memory.
 165 The statistics are displayed on standard output.
 166 .PP
 167 The first two command-line arguments specify the number and size of
 168 blocks to be allocated with
 169 .BR malloc (3).
 170 .PP
 171 The remaining three arguments specify which of the allocated blocks
 172 should be freed with
 173 .BR free (3).
 174 These three arguments are optional, and specify (in order):
 175 the step size to be used in the loop that frees blocks
 176 (the default is 1, meaning free all blocks in the range);
 177 the ordinal position of the first block to be freed
 178 (default 0, meaning the first allocated block);
 179 and a number one greater than the ordinal position
 180 of the last block to be freed
 181 (default is one greater than the maximum block number).
 182 If these three arguments are omitted,
 183 then the defaults cause all allocated blocks to be freed.
 184 .PP
 185 In the following example run of the program,
 186 1000 allocations of 100 bytes are performed,
 187 and then every second allocated block is freed:
 188 .PP
 189 .in +4n
 190 .EX
 191 $ \fB./a.out 1000 100 2\fP
 192 ============== Before allocating blocks ==============
 193 Total non\-mmapped bytes (arena):       0
 194 # of free chunks (ordblks):            1
 195 # of free fastbin blocks (smblks):     0
 196 # of mapped regions (hblks):           0
 197 Bytes in mapped regions (hblkhd):      0
 198 Max. total allocated space (usmblks):  0
 199 Free bytes held in fastbins (fsmblks): 0
 200 Total allocated space (uordblks):      0
 201 Total free space (fordblks):           0
 202 Topmost releasable block (keepcost):   0
 203
 204 ============== After allocating blocks ==============
 205 Total non\-mmapped bytes (arena):       135168
 206 # of free chunks (ordblks):            1
 207 # of free fastbin blocks (smblks):     0
 208 # of mapped regions (hblks):           0
 209 Bytes in mapped regions (hblkhd):      0
 210 Max. total allocated space (usmblks):  0
 211 Free bytes held in fastbins (fsmblks): 0
 212 Total allocated space (uordblks):      104000
 213 Total free space (fordblks):           31168
 214 Topmost releasable block (keepcost):   31168
 215
 216 ============== After freeing blocks ==============
 217 Total non\-mmapped bytes (arena):       135168
 218 # of free chunks (ordblks):            501
 219 # of free fastbin blocks (smblks):     0
 220 # of mapped regions (hblks):           0
 221 Bytes in mapped regions (hblkhd):      0
 222 Max. total allocated space (usmblks):  0
 223 Free bytes held in fastbins (fsmblks): 0
 224 Total allocated space (uordblks):      52000
 225 Total free space (fordblks):           83168
 226 Topmost releasable block (keepcost):   31168
 227 .EE
 228 .in
 229 .SS Program source
 230 \&
 231 .EX
 232 #include <malloc.h>
 233 #include <stdlib.h>
 234 #include <string.h>
 235
 236 static void
 237 display_mallinfo(void)
 238 {
 239     struct mallinfo mi;
 240
 241     mi = mallinfo();
 242
 243     printf("Total non\-mmapped bytes (arena):       %d\\n", mi.arena);
 244     printf("# of free chunks (ordblks):            %d\\n", mi.ordblks);
 245     printf("# of free fastbin blocks (smblks):     %d\\n", mi.smblks);
 246     printf("# of mapped regions (hblks):           %d\\n", mi.hblks);
 247     printf("Bytes in mapped regions (hblkhd):      %d\\n", mi.hblkhd);
 248     printf("Max. total allocated space (usmblks):  %d\\n", mi.usmblks);
 249     printf("Free bytes held in fastbins (fsmblks): %d\\n", mi.fsmblks);
 250     printf("Total allocated space (uordblks):      %d\\n", mi.uordblks);
 251     printf("Total free space (fordblks):           %d\\n", mi.fordblks);
 252     printf("Topmost releasable block (keepcost):   %d\\n", mi.keepcost);
 253 }
 254
 255 int
 256 main(int argc, char *argv[])
 257 {
 258 #define MAX_ALLOCS 2000000
 259     char *alloc[MAX_ALLOCS];
 260     int numBlocks, j, freeBegin, freeEnd, freeStep;
 261     size_t blockSize;
 262
 263     if (argc < 3 || strcmp(argv[1], "\-\-help") == 0) {
 264         fprintf(stderr, "%s num\-blocks block\-size [free\-step "
 265                 "[start\-free [end\-free]]]\\n", argv[0]);
 266         exit(EXIT_FAILURE);
 267     }
 268
 269     numBlocks = atoi(argv[1]);
 270     blockSize = atoi(argv[2]);
 271     freeStep = (argc > 3) ? atoi(argv[3]) : 1;
 272     freeBegin = (argc > 4) ? atoi(argv[4]) : 0;
 273     freeEnd = (argc > 5) ? atoi(argv[5]) : numBlocks;
 274
 275     printf("============== Before allocating blocks ==============\\n");
 276     display_mallinfo();
 277
 278     for (j = 0; j < numBlocks; j++) {
 279         if (numBlocks >= MAX_ALLOCS) {
 280             fprintf(stderr, "Too many allocations\\n");
 281             exit(EXIT_FAILURE);
 282         }
 283
 284         alloc[j] = malloc(blockSize);
 285         if (alloc[j] == NULL) {
 286             perror("malloc");
 287             exit(EXIT_FAILURE);
 288         }
 289     }
 290
 291     printf("\\n============== After allocating blocks ==============\\n");
 292     display_mallinfo();
 293
 294     for (j = freeBegin; j < freeEnd; j += freeStep)
 295         free(alloc[j]);
 296
 297     printf("\\n============== After freeing blocks ==============\\n");
 298     display_mallinfo();
 299
 300     exit(EXIT_SUCCESS);
 301 }
 302 .EE
 303 .SH SEE ALSO
 304 .ad l
 305 .nh
 306 .BR mmap (2),
 307 .BR malloc (3),
 308 .BR malloc_info (3),
 309 .BR malloc_stats (3),
 310 .BR malloc_trim (3),
 311 .BR mallopt (3)