Manual page update for mallinfo2()

["Michael Kerrisk \(man-pages\) via Libc-alpha" <libc-alpha@sourceware.org>]

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


diff --git a/man3/mallinfo.3 b/man3/mallinfo.3
index 0218c2fd3..605e8cd8a 100644
--- a/man3/mallinfo.3
+++ b/man3/mallinfo.3
@@ -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);
 }

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/