document MALLOC_OPTIONS=D output; OK otto@

1 files changed, 72 insertions, 2 deletions

diff --git a/src/lib/libc/stdlib/malloc.3 b/src/lib/libc/stdlib/malloc.3
index ee13b01bd4..f66bd1cbb6 100644
--- a/src/lib/libc/stdlib/malloc.3
+++ b/src/lib/libc/stdlib/malloc.3
@@ -30,9 +30,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\"     $OpenBSD: malloc.3,v 1.147 2025/06/04 00:38:01 yasuoka Exp $
+.\"     $OpenBSD: malloc.3,v 1.148 2026/08/22 12:22:16 schwarze Exp $
 .\"
-.Dd $Mdocdate: June 4 2025 $
+.Dd $Mdocdate: August 22 2026 $
 .Dt MALLOC 3
 .Os
 .Sh NAME
@@ -315,6 +315,76 @@ or
 to record deeper call stacks.
 These malloc options imply
 .Cm D .
+.Pp
+The report begins with a header line showing the following integer variables:
+.Pp
+.Bl -tag -width Ds -compact
+.It M
+the number of pools used
+.It I
+internal
+.Fn recallocarray
+and
+.Fn freezero
+used (0 or 1)
+.It F
+whether the
+.Cm F Dq freecheck
+option is used (0 or 1)
+.It U
+whether the
+.Cm U Dq free unmap
+option is used (0 or 1)
+.It J
+the number of
+.Cm J Dq junking
+options used (0, 1, or 2)
+.It R
+whether the
+.Cm R Dq realloc
+option is used (0 or 1)
+.It X
+whether the
+.Cm X Dq xmalloc
+option is used (0 or 1)
+.It C
+whether the
+.Cm C Dq canaries
+option is used (0 or 1)
+.It cache
+the cache size in pages
+.It G
+the size of guard pages in bytes (0 or
+.Dv MALLOC_PAGESIZE )
+.El
+.Pp
+The leak report consists of five columns:
+.Pp
+.Bl -bullet -compact
+.It
+the address from where the allocation function was called
+.It
+the total number of bytes leaked from that location
+.It
+the number of allocations leaked from that location
+.It
+the average size in bytes per leak from that location,
+i.e. the quotient of the two preceding columns
+.It
+an
+.Xr addr2line 1
+invocation using the pathname of the object file calling
+the allocation function and the offset from where it is called
+to find the source file name and line number of the call site
+.El
+.Pp
+With malloc options
+.Cm 2 ,
+.Cm 3 ,
+or
+.Cm 4 ,
+each line of the leak report is followed by 1, 2, or 3 additional lines,
+respectively, giving the addresses, pathnames and offsets of indirect callers.
 .It Cm F
 .Dq Freecheck .
 Enable more extensive double free and write after free detection.