| .\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .TH MALLINFO 3 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| mallinfo, mallinfo2 \- obtain memory allocation information |
| .SH SYNOPSIS |
| .nf |
| .B #include <malloc.h> |
| .PP |
| .B struct mallinfo mallinfo(void); |
| .B struct mallinfo2 mallinfo2(void); |
| .fi |
| .SH DESCRIPTION |
| These functions return a copy of a structure containing information about |
| memory allocations performed by |
| .BR malloc (3) |
| and related functions. |
| The structure returned by each function contains the same fields. |
| However, the older function, |
| .BR mallinfo (), |
| is deprecated since the type used for the fields is too small (see BUGS). |
| .PP |
| Note that not all allocations are visible to these functions; |
| see BUGS and consider using |
| .BR malloc_info (3) |
| instead. |
| .PP |
| The |
| .I mallinfo2 |
| structure returned by |
| .BR mallinfo2 () |
| is defined as follows: |
| .PP |
| .in +4n |
| .EX |
| struct mallinfo2 { |
| size_t arena; /* Non\-mmapped space allocated (bytes) */ |
| size_t ordblks; /* Number of free chunks */ |
| size_t smblks; /* Number of free fastbin blocks */ |
| size_t hblks; /* Number of mmapped regions */ |
| size_t hblkhd; /* Space allocated in mmapped regions |
| (bytes) */ |
| size_t usmblks; /* See below */ |
| size_t fsmblks; /* Space in freed fastbin blocks (bytes) */ |
| size_t uordblks; /* Total allocated space (bytes) */ |
| size_t fordblks; /* Total free space (bytes) */ |
| size_t keepcost; /* Top\-most, releasable space (bytes) */ |
| }; |
| .EE |
| .in |
| .PP |
| The |
| .I mallinfo |
| structure returned by the deprecated |
| .BR mallinfo () |
| function is exactly the same, except that the fields are typed as |
| .IR int . |
| .PP |
| The structure fields contain the following information: |
| .TP 10 |
| .I arena |
| The total amount of memory allocated by means other than |
| .BR mmap (2) |
| (i.e., memory allocated on the heap). |
| This figure includes both in-use blocks and blocks on the free list. |
| .TP |
| .I ordblks |
| The number of ordinary (i.e., non-fastbin) free blocks. |
| .TP |
| .I smblks |
| .\" the glibc info page wrongly says this field is unused |
| .\" https://sourceware.org/bugzilla/show_bug.cgi?id=26746 |
| The number of fastbin free blocks (see |
| .BR mallopt (3)). |
| .TP |
| .I hblks |
| The number of blocks currently allocated using |
| .BR mmap (2). |
| (See the discussion of |
| .B M_MMAP_THRESHOLD |
| in |
| .BR mallopt (3).) |
| .TP |
| .I hblkhd |
| The number of bytes in blocks currently allocated using |
| .BR mmap (2). |
| .TP |
| .I usmblks |
| This field is unused, and is always 0. |
| .\" It seems to have been zero since at least as far back as glibc 2.15 |
| Historically, it was the "highwater mark" for allocated space\(emthat is, |
| the maximum amount of space that was ever allocated (in bytes); |
| this field was maintained only in nonthreading environments. |
| .TP |
| .I fsmblks |
| .\" the glibc info page wrongly says this field is unused |
| .\" https://sourceware.org/bugzilla/show_bug.cgi?id=26746 |
| The total number of bytes in fastbin free blocks. |
| .TP |
| .I uordblks |
| The total number of bytes used by in-use allocations. |
| .TP |
| .I fordblks |
| The total number of bytes in free blocks. |
| .TP |
| .I keepcost |
| The total amount of releasable free space at the top |
| of the heap. |
| This is the maximum number of bytes that could ideally |
| (i.e., ignoring page alignment restrictions, and so on) be released by |
| .BR malloc_trim (3). |
| .SH VERSIONS |
| .\" mallinfo(): Available already in glibc 2.0, possibly earlier |
| The |
| .BR mallinfo2 () |
| function was added |
| .\" commit e3960d1c57e57f33e0e846d615788f4ede73b945 |
| in glibc 2.33. |
| .SH ATTRIBUTES |
| For an explanation of the terms used in this section, see |
| .BR attributes (7). |
| .ad l |
| .nh |
| .TS |
| allbox; |
| lb lb lbx |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR mallinfo (), |
| .BR mallinfo2 () |
| T} Thread safety T{ |
| MT-Unsafe init const:mallopt |
| T} |
| .TE |
| .hy |
| .ad |
| .sp 1 |
| .BR mallinfo ()/ |
| .BR mallinfo2 () |
| would access some global internal objects. |
| If modify them with non-atomically, |
| may get inconsistent results. |
| The identifier |
| .I mallopt |
| in |
| .I const:mallopt |
| mean that |
| .BR mallopt () |
| would modify the global internal objects with atomics, that make sure |
| .BR mallinfo ()/ |
| .BR mallinfo2 () |
| is safe enough, others modify with non-atomically maybe not. |
| .SH CONFORMING TO |
| These functions are not specified by POSIX or the C standards. |
| A |
| .BR mallinfo () |
| function exists on many System V derivatives, |
| and was specified in the SVID. |
| .SH BUGS |
| .\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=208 |
| .\" See the 24 Aug 2011 mail by Paul Pluzhnikov: |
| .\" "[patch] Fix mallinfo() to accumulate results for all arenas" |
| .\" on libc-alpha@sourceware.org |
| .B Information is returned for only the main memory allocation area. |
| Allocations in other arenas are excluded. |
| See |
| .BR malloc_stats (3) |
| and |
| .BR malloc_info (3) |
| for alternatives that include information about other arenas. |
| .PP |
| The fields of the |
| .I mallinfo |
| structure that is returned by the older |
| .BR mallinfo () |
| function are typed as |
| .IR int . |
| However, because some internal bookkeeping values may be of type |
| .IR long , |
| the reported values may wrap around zero and thus be inaccurate. |
| .SH EXAMPLES |
| The program below employs |
| .BR mallinfo2 () |
| to retrieve memory allocation statistics before and after |
| allocating and freeing some blocks of memory. |
| The statistics are displayed on standard output. |
| .PP |
| The first two command-line arguments specify the number and size of |
| blocks to be allocated with |
| .BR malloc (3). |
| .PP |
| The remaining three arguments specify which of the allocated blocks |
| should be freed with |
| .BR free (3). |
| These three arguments are optional, and specify (in order): |
| the step size to be used in the loop that frees blocks |
| (the default is 1, meaning free all blocks in the range); |
| the ordinal position of the first block to be freed |
| (default 0, meaning the first allocated block); |
| and a number one greater than the ordinal position |
| of the last block to be freed |
| (default is one greater than the maximum block number). |
| If these three arguments are omitted, |
| then the defaults cause all allocated blocks to be freed. |
| .PP |
| In the following example run of the program, |
| 1000 allocations of 100 bytes are performed, |
| and then every second allocated block is freed: |
| .PP |
| .in +4n |
| .EX |
| $ \fB./a.out 1000 100 2\fP |
| ============== Before allocating blocks ============== |
| Total non\-mmapped bytes (arena): 0 |
| # of free chunks (ordblks): 1 |
| # of free fastbin blocks (smblks): 0 |
| # of mapped regions (hblks): 0 |
| Bytes in mapped regions (hblkhd): 0 |
| Max. total allocated space (usmblks): 0 |
| Free bytes held in fastbins (fsmblks): 0 |
| Total allocated space (uordblks): 0 |
| Total free space (fordblks): 0 |
| Topmost releasable block (keepcost): 0 |
| |
| ============== After allocating blocks ============== |
| Total non\-mmapped bytes (arena): 135168 |
| # of free chunks (ordblks): 1 |
| # of free fastbin blocks (smblks): 0 |
| # of mapped regions (hblks): 0 |
| Bytes in mapped regions (hblkhd): 0 |
| Max. total allocated space (usmblks): 0 |
| Free bytes held in fastbins (fsmblks): 0 |
| Total allocated space (uordblks): 104000 |
| Total free space (fordblks): 31168 |
| Topmost releasable block (keepcost): 31168 |
| |
| ============== After freeing blocks ============== |
| Total non\-mmapped bytes (arena): 135168 |
| # of free chunks (ordblks): 501 |
| # of free fastbin blocks (smblks): 0 |
| # of mapped regions (hblks): 0 |
| Bytes in mapped regions (hblkhd): 0 |
| Max. total allocated space (usmblks): 0 |
| Free bytes held in fastbins (fsmblks): 0 |
| Total allocated space (uordblks): 52000 |
| Total free space (fordblks): 83168 |
| Topmost releasable block (keepcost): 31168 |
| .EE |
| .in |
| .SS Program source |
| \& |
| .EX |
| #include <malloc.h> |
| #include <stdlib.h> |
| #include <string.h> |
| |
| static void |
| display_mallinfo2(void) |
| { |
| struct mallinfo2 mi; |
| |
| mi = mallinfo2(); |
| |
| printf("Total non\-mmapped bytes (arena): %zu\en", mi.arena); |
| printf("# of free chunks (ordblks): %zu\en", mi.ordblks); |
| printf("# of free fastbin blocks (smblks): %zu\en", mi.smblks); |
| printf("# of mapped regions (hblks): %zu\en", mi.hblks); |
| printf("Bytes in mapped regions (hblkhd): %zu\en", mi.hblkhd); |
| printf("Max. total allocated space (usmblks): %zu\en", mi.usmblks); |
| printf("Free bytes held in fastbins (fsmblks): %zu\en", mi.fsmblks); |
| printf("Total allocated space (uordblks): %zu\en", mi.uordblks); |
| printf("Total free space (fordblks): %zu\en", mi.fordblks); |
| printf("Topmost releasable block (keepcost): %zu\en", mi.keepcost); |
| } |
| |
| int |
| main(int argc, char *argv[]) |
| { |
| #define MAX_ALLOCS 2000000 |
| char *alloc[MAX_ALLOCS]; |
| int numBlocks, freeBegin, freeEnd, freeStep; |
| size_t blockSize; |
| |
| if (argc < 3 || strcmp(argv[1], "\-\-help") == 0) { |
| fprintf(stderr, "%s num\-blocks block\-size [free\-step " |
| "[start\-free [end\-free]]]\en", argv[0]); |
| exit(EXIT_FAILURE); |
| } |
| |
| numBlocks = atoi(argv[1]); |
| blockSize = atoi(argv[2]); |
| freeStep = (argc > 3) ? atoi(argv[3]) : 1; |
| freeBegin = (argc > 4) ? atoi(argv[4]) : 0; |
| freeEnd = (argc > 5) ? atoi(argv[5]) : numBlocks; |
| |
| printf("============== Before allocating blocks ==============\en"); |
| display_mallinfo2(); |
| |
| for (int j = 0; j < numBlocks; j++) { |
| if (numBlocks >= MAX_ALLOCS) { |
| fprintf(stderr, "Too many allocations\en"); |
| exit(EXIT_FAILURE); |
| } |
| |
| alloc[j] = malloc(blockSize); |
| if (alloc[j] == NULL) { |
| perror("malloc"); |
| exit(EXIT_FAILURE); |
| } |
| } |
| |
| printf("\en============== After allocating blocks ==============\en"); |
| display_mallinfo2(); |
| |
| for (int j = freeBegin; j < freeEnd; j += freeStep) |
| free(alloc[j]); |
| |
| printf("\en============== After freeing blocks ==============\en"); |
| display_mallinfo2(); |
| |
| exit(EXIT_SUCCESS); |
| } |
| .EE |
| .SH SEE ALSO |
| .ad l |
| .nh |
| .BR mmap (2), |
| .BR malloc (3), |
| .BR malloc_info (3), |
| .BR malloc_stats (3), |
| .BR malloc_trim (3), |
| .BR mallopt (3) |