diff options
Diffstat (limited to 'man3/mallinfo.3')
| -rw-r--r-- | man3/mallinfo.3 | 338 |
1 files changed, 338 insertions, 0 deletions
diff --git a/man3/mallinfo.3 b/man3/mallinfo.3 new file mode 100644 index 0000000..af08137 --- /dev/null +++ b/man3/mallinfo.3 @@ -0,0 +1,338 @@ +'\" t +.\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mallinfo 3 2023-07-20 "Linux man-pages 6.05.01" +.SH NAME +mallinfo, mallinfo2 \- obtain memory allocation information +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.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\[em]that 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 ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mallinfo (), +.BR mallinfo2 () +T} Thread safety T{ +.na +.nh +MT-Unsafe init const:mallopt +T} +.TE +.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 STANDARDS +None. +.SH HISTORY +.TP +.BR mallinfo () +glibc 2.0. +SVID. +.TP +.BR mallinfo2 () +.\" commit e3960d1c57e57f33e0e846d615788f4ede73b945 +glibc 2.33. +.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 +\& +.\" SRC BEGIN (mallinfo.c) +.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]; + size_t blockSize, numBlocks, freeBegin, freeEnd, freeStep; +\& + 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 (size_t 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 (size_t j = freeBegin; j < freeEnd; j += freeStep) + free(alloc[j]); +\& + printf("\en============== After freeing blocks ==============\en"); + display_mallinfo2(); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.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) |