Document lpsm_alloc_stats()lpsm-0.1.5

2 files changed, 72 insertions, 2 deletions

diff --git a/lpsm_alloc_stats.3.in b/lpsm_alloc_stats.3.in
new file mode 100644
index 0000000..593c7df
--- /dev/null
+++ b/lpsm_alloc_stats.3.in
@@ -0,0 +1,69 @@
+.\" -*- nroff -*- ---------------------------------------------------------
+.\"   
+.\"   Copyright 2001 H. Peter Anvin - All Rights Reserved
+.\"
+.\"   This program is free software; you can redistribute it and/or modify
+.\"   it under the terms of the GNU Lesser General Public License as
+.\"   published by the Free Software Foundation, Inc.,
+.\"   59 Temple Place Ste 330, Bostom MA 02111-1307, USA; version 2.1,
+.\"   incorporated herein by reference.
+.\"
+.\" -----------------------------------------------------------------------
+.\" $Id$
+.TH LPSM_ALLOC_STATS 3  "22 October 2001" "LPSM @@VERSION@@" "Linux Persistent Memory"
+.SH NAME
+lpsm_alloc_stats \- Get persistent memory allocation statistics
+.SH SYNOPSIS
+.nf
+.B #include <lpsm.h>
+.sp
+.BI "struct lpsm_alloc_stats *lpsm_alloc_stats(void);"
+.nl
+.fi
+.SH DESCRIPTION
+.B lpsm_alloc_stats()
+return allocation statistics for persistent memory allocated with
+.B lpsm_malloc()
+and its associated functions.  A persistent memory arena needs to be
+initialized via
+.B lpsm_init()
+before this function can be called.
+.SH "RETURN VALUES"
+.B lpsm_alloc_stats()
+returns a pointer to an array of
+.IR "struct lpsm_alloc_stats" ,
+defined as:
+.RS
+.sp
+.nf
+struct lpsm_alloc_stats {
+	size_t \fIsize\fP;
+	size_t \fIfree\fP;
+	size_t \fIalloc\fP;
+};
+.fi
+.sp
+.RE
+Each entry in this array indicates the size of a particular memory
+block class, in bytes, and the number of blocks of each class
+currently available and currently allocated.  The list is terminated
+by an entry with
+.I size
+set to zero.
+.PP
+This list is allocated (with
+.BR malloc() )
+in conventional (transient) memory; it is the responsibity of the
+application to free this memory.
+.PP
+On failure,
+.B lpsm_alloc_stats()
+returns
+.B NULL
+and
+.I errno
+is set to
+.BR ENOMEM .
+.SH "SEE ALSO"
+.BR lpsm_malloc (3),
+.BR malloc (3).
diff --git a/lpsm_malloc.3.in b/lpsm_malloc.3.in
index c364b42..2112f2f 100644
--- a/lpsm_malloc.3.in
+++ b/lpsm_malloc.3.in
@@ -143,8 +143,9 @@ were unable to allocate the memory requested.
 These functions mimic in as much as possible the ISO C and POSIX
 behaviour of the equivalent transient memory allocation functions.
 .SH "SEE ALSO"
-.BR malloc (3),
-.BR lpsm_init (3).
+.BR lpsm_alloc_stats (3),
+.BR lpsm_init (3),
+.BR malloc (3).
 .SH NOTES
 The allocator used can handle allocations down to single byte size
 with high efficiency.  Large allocations are rounded to the nearest