Hello all,
For the mallinfo2() function that is added in glibc2.33, I
plan to apply te patch below for the mallinfo(3) manual page.
Comments, review, acks are welcome.
Thanks,
Michael
PS While documenting mallinfo2() I alwo noticed some
related bugs in the glibc manual
https://sourceware.org/bugzilla/show_bug.cgi?id=26746
@@ -24,47 +24,61 @@
.\"
.TH MALLINFO 3 2020-06-09 "Linux" "Linux Programmer's Manual"
.SH NAME
-mallinfo \- obtain memory allocation information
+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
-The
-.BR mallinfo ()
-function returns a copy of a structure containing information about
+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
-.BR mallinfo ();
+Note that not all allocations are visible to these functions;
see BUGS and consider using
.BR malloc_info (3)
instead.
.PP
-The returned structure is defined as follows:
+The
+.I mallinfo2
+structure returned by
+.BR mallinfo2 ()
+is defined as follows:
.PP
.in +4n
.EX
-struct mallinfo {
- int arena; /* Non-mmapped space allocated (bytes) */
- int ordblks; /* Number of free chunks */
- int smblks; /* Number of free fastbin blocks */
- int hblks; /* Number of mmapped regions */
- int hblkhd; /* Space allocated in mmapped regions (bytes) */
- int usmblks; /* See below */
- int fsmblks; /* Space in freed fastbin blocks (bytes) */
- int uordblks; /* Total allocated space (bytes) */
- int fordblks; /* Total free space (bytes) */
- int keepcost; /* Top-most, releasable space (bytes) */
+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 fields of the
+The
.I mallinfo
-structure contain the following information:
+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
@@ -117,8 +131,13 @@ 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
-.\" Available already in glibc 2.0, possibly earlier
+.SH VERSIONS
+.\" imallinfo(): 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).
@@ -128,11 +147,13 @@ lb lb lbw28
l l l.
Interface Attribute Value
T{
-.BR mallinfo ()
+.BR mallinfo (),
+.BR mallinfo2 ()
T} Thread safety MT-Unsafe init const:mallopt
.TE
.sp 1
-.BR mallinfo ()
+.BR mallinfo ()/
+.BR mallinfo2 ()
would access some global internal objects.
If modify them with non-atomically,
may get inconsistent results.
@@ -143,11 +164,14 @@ in
mean that
.BR mallopt ()
would modify the global internal objects with atomics, that make sure
-.BR mallinfo ()
+.BR mallinfo ()/
+.BR mallinfo2 ()
is safe enough, others modify with non-atomically maybe not.
.SH CONFORMING TO
-This function is not specified by POSIX or the C standards.
-A similar function exists on many System V derivatives,
+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
@@ -164,14 +188,16 @@ for alternatives that include information about other arenas.
.PP
The fields of the
.I mallinfo
-structure are typed as
+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 mallinfo ()
+.BR mallinfo2 ()
to retrieve memory allocation statistics before and after
allocating and freeing some blocks of memory.
The statistics are displayed on standard output.
@@ -246,22 +272,22 @@ Topmost releasable block (keepcost): 31168
#include <string.h>
static void
-display_mallinfo(void)
+display_mallinfo2(void)
{
- struct mallinfo mi;
+ struct mallinfo2 mi;
- mi = mallinfo();
+ mi = mallinfo2();
- printf("Total non\-mmapped bytes (arena): %d\en", mi.arena);
- printf("# of free chunks (ordblks): %d\en", mi.ordblks);
- printf("# of free fastbin blocks (smblks): %d\en", mi.smblks);
- printf("# of mapped regions (hblks): %d\en", mi.hblks);
- printf("Bytes in mapped regions (hblkhd): %d\en", mi.hblkhd);
- printf("Max. total allocated space (usmblks): %d\en", mi.usmblks);
- printf("Free bytes held in fastbins (fsmblks): %d\en", mi.fsmblks);
- printf("Total allocated space (uordblks): %d\en", mi.uordblks);
- printf("Total free space (fordblks): %d\en", mi.fordblks);
- printf("Topmost releasable block (keepcost): %d\en", mi.keepcost);
+ 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
@@ -285,7 +311,7 @@ main(int argc, char *argv[])
freeEnd = (argc > 5) ? atoi(argv[5]) : numBlocks;
printf("============== Before allocating blocks ==============\en");
- display_mallinfo();
+ display_mallinfo2();
for (int j = 0; j < numBlocks; j++) {
if (numBlocks >= MAX_ALLOCS) {
@@ -301,13 +327,13 @@ main(int argc, char *argv[])
}
printf("\en============== After allocating blocks ==============\en");
- display_mallinfo();
+ display_mallinfo2();
for (int j = freeBegin; j < freeEnd; j += freeStep)
free(alloc[j]);
printf("\en============== After freeing blocks ==============\en");
- display_mallinfo();
+ display_mallinfo2();
exit(EXIT_SUCCESS);
}