original/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  2012-05-06 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 mallinfo \- obtain memory allocation information
  29 .SH SYNOPSIS
  30 .B #include <malloc.h>
  31
  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 .nf
  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 .fi
  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 CONFORMING TO
 111 This function is not specified by POSIX or the C standards.
 112 A similar function exists on many System V derivatives,
 113 and was specified in the SVID.
 114 .SH BUGS
 115 .\" FIXME http://sourceware.org/bugzilla/show_bug.cgi?id=208
 116 .\" See the 24 Aug 2011 mail by Paul Pluzhnikov:
 117 .\"     "[patch] Fix mallinfo() to accumulate results for all arenas"
 118 .\" on libc-alpha@sourceware.org
 119 .B Information is returned for only the main memory allocation area.
 120 Allocations in other arenas are excluded.
 121 See
 122 .BR malloc_stats (3)
 123 and
 124 .BR malloc_info (3)
 125 for alternatives that include information about other arenas.
 126
 127 The fields of the
 128 .I mallinfo
 129 structure are typed as
 130 .IR int .
 131 However, because some internal bookkeeping values may be of type
 132 .IR long ,
 133 the reported values may wrap around zero and thus be inaccurate.
 134 .SH EXAMPLE
 135 The program below employs
 136 .BR mallinfo ()
 137 to retrieve memory allocation statistics before and after
 138 allocating and freeing some blocks of memory.
 139 The statistics are displayed on standard output.
 140
 141 The first two command-line arguments specify the number and size of
 142 blocks to be allocated with
 143 .BR malloc (3).
 144
 145 The remaining three arguments specify which of the allocated blocks
 146 should be freed with
 147 .BR free (3).
 148 These three arguments are optional, and specify (in order):
 149 the step size to be used in the loop that frees blocks
 150 (the default is 1, meaning free all blocks in the range);
 151 the ordinal position of the first block to be freed
 152 (default 0, meaning the first allocated block);
 153 and a number one greater than the ordinal position
 154 of the last block to be freed
 155 (default is one greater than the maximum block number).
 156 If these three arguments are omitted,
 157 then the defaults cause all allocated blocks to be freed.
 158
 159 In the following example run of the program,
 160 1000 allocations of 100 bytes are performed,
 161 and then every second allocated block is freed:
 162 .PP
 163 .in +4n
 164 .nf
 165 $ \fB./a.out 1000 100 2\fP
 166 ============== Before allocating blocks ==============
 167 Total non\-mmapped bytes (arena):       0
 168 # of free chunks (ordblks):            1
 169 # of free fastbin blocks (smblks):     0
 170 # of mapped regions (hblks):           0
 171 Bytes in mapped regions (hblkhd):      0
 172 Max. total allocated space (usmblks):  0
 173 Free bytes held in fastbins (fsmblks): 0
 174 Total allocated space (uordblks):      0
 175 Total free space (fordblks):           0
 176 Topmost releasable block (keepcost):   0
 177
 178 ============== After allocating blocks ==============
 179 Total non\-mmapped bytes (arena):       135168
 180 # of free chunks (ordblks):            1
 181 # of free fastbin blocks (smblks):     0
 182 # of mapped regions (hblks):           0
 183 Bytes in mapped regions (hblkhd):      0
 184 Max. total allocated space (usmblks):  0
 185 Free bytes held in fastbins (fsmblks): 0
 186 Total allocated space (uordblks):      104000
 187 Total free space (fordblks):           31168
 188 Topmost releasable block (keepcost):   31168
 189
 190 ============== After freeing blocks ==============
 191 Total non\-mmapped bytes (arena):       135168
 192 # of free chunks (ordblks):            501
 193 # of free fastbin blocks (smblks):     0
 194 # of mapped regions (hblks):           0
 195 Bytes in mapped regions (hblkhd):      0
 196 Max. total allocated space (usmblks):  0
 197 Free bytes held in fastbins (fsmblks): 0
 198 Total allocated space (uordblks):      52000
 199 Total free space (fordblks):           83168
 200 Topmost releasable block (keepcost):   31168
 201 .fi
 202 .in
 203 .SS Program source
 204 \&
 205 .nf
 206 #include <malloc.h>
 207 #include "tlpi_hdr.h"
 208
 209 static void
 210 display_mallinfo(void)
 211 {
 212     struct mallinfo mi;
 213
 214     mi = mallinfo();
 215
 216     printf("Total non\-mmapped bytes (arena):       %d\\n", mi.arena);
 217     printf("# of free chunks (ordblks):            %d\\n", mi.ordblks);
 218     printf("# of free fastbin blocks (smblks):     %d\\n", mi.smblks);
 219     printf("# of mapped regions (hblks):           %d\\n", mi.hblks);
 220     printf("Bytes in mapped regions (hblkhd):      %d\\n", mi.hblkhd);
 221     printf("Max. total allocated space (usmblks):  %d\\n", mi.usmblks);
 222     printf("Free bytes held in fastbins (fsmblks): %d\\n", mi.fsmblks);
 223     printf("Total allocated space (uordblks):      %d\\n", mi.uordblks);
 224     printf("Total free space (fordblks):           %d\\n", mi.fordblks);
 225     printf("Topmost releasable block (keepcost):   %d\\n", mi.keepcost);
 226 }
 227
 228 int
 229 main(int argc, char *argv[])
 230 {
 231 #define MAX_ALLOCS 2000000
 232     char *alloc[MAX_ALLOCS];
 233     int numBlocks, j, freeBegin, freeEnd, freeStep;
 234     size_t blockSize;
 235
 236     if (argc < 3 || strcmp(argv[1], "\-\-help") == 0)
 237         usageErr("%s num\-blocks block\-size [free\-step [start\-free "
 238                 "[end\-free]]]\\n", argv[0]);
 239
 240     numBlocks = atoi(argv[1]);
 241     blockSize = atoi(argv[2]);
 242     freeStep = (argc > 3) ? atoi(argv[3]) : 1;
 243     freeBegin = (argc > 4) ? atoi(argv[4]) : 0;
 244     freeEnd = (argc > 5) ? atoi(argv[5]) : numBlocks;
 245
 246     printf("============== Before allocating blocks ==============\\n");
 247     display_mallinfo();
 248
 249     for (j = 0; j < numBlocks; j++) {
 250         if (numBlocks >= MAX_ALLOCS)
 251             fatal("Too many allocations");
 252
 253         alloc[j] = malloc(blockSize);
 254         if (alloc[j] == NULL)
 255             errExit("malloc");
 256     }
 257
 258     printf("\\n============== After allocating blocks ==============\\n");
 259     display_mallinfo();
 260
 261     for (j = freeBegin; j < freeEnd; j += freeStep)
 262         free(alloc[j]);
 263
 264     printf("\\n============== After freeing blocks ==============\\n");
 265     display_mallinfo();
 266
 267     exit(EXIT_SUCCESS);
 268 }
 269 .fi
 270 .SH SEE ALSO
 271 .ad l
 272 .nh
 273 .BR mmap (2),
 274 .BR malloc (3),
 275 .BR malloc_info (3),
 276 .BR malloc_stats (3),
 277 .BR malloc_trim (3),
 278 .BR mallopt (3)
 279 .SH COLOPHON
 280 This page is part of release 3.68 of the Linux
 281 .I man-pages
 282 project.
 283 A description of the project,
 284 information about reporting bugs,
 285 and the latest version of this page,
 286 can be found at
 287 \%http://www.kernel.org/doc/man\-pages/.