1 files changed, 179 insertions, 0 deletions
diff --git a/doc/procps.3 b/doc/procps.3
new file mode 100644
index 0000000..ecd640d
--- /dev/null
+++ b/doc/procps.3
@@ -0,0 +1,179 @@
+.\" (C) Copyright 2020 Craig Small <csmall@dropbear.xyz>
+.\"
+.\" %%%LICENSE_START(LGPL_2.1+)
+.\" This manual 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; either
+.\" version 2.1 of the License, or (at your option) any later version.
+.\"
+.\" This manual is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+.\" Lesser General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU Lesser General Public
+.\" License along with this library; if not, write to the Free Software
+.\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+.\" %%%LICENSE_END
+.\"
+.TH PROCPS_LINUX_VERSION 3 2020-0519 "libproc-2"
+.\" Please adjust this date whenever revising the manpage.
+.\"
+.SH NAME
+procps \- API to the procps librayr
+.SH SYNOPSIS
+See XXXXX for what file to include
+
+.BI "int PROCITEM_new(struct PROCITEM_info **" info ");"
+
+.BI "int PROCITEM_ref(struct PROCITEM_info *" info ");"
+
+.BI "int PROCITEM_unref(struct PROCITEM_info *" info ");"
+
+.BI "struct diststats_result *procps_diststats_get(struct diststats_info *" info ", const char *" name ", enum diststats_item " item ");"
+
+.BI "struct PROCITEM_result *procps_PROCITEM_get(struct PROCITEM_info *" info ", enum PROCITEM_item " item ");"
+(for all other PROCITEMs except diskstats)
+
+.BI "struct PROCITEM_reap *procps_PROCITEM_reap(struct PROCITEM_info * " info ", enum PROCITEM_item *" items ", int " numitems ");"
+(for PROCITEMs diskstats and slabinfo)
+
+.BI "struct stat_reap *procps_stat_reap(struct stat_info * " info ", enum stat_item *" items ", int " numitems ");"
+
+.BI "struct diststats_stack *procps_diststats_select(struct diststats_info *" info ", const char *" name ", enum diststats_item *" items ", int " numitems ");"
+
+.BI "struct PROCITEM_stack *procps_PROCITEM_select(struct PROCITEM_info *" info ", enum PROCITEM_item *" items ", int " numitems ");"
+(for all other PROCITEMs except diskstats)
+
+.BI "struct PROCITEM_stack **procps_PROCITEM_sort(struct PROCITEM_info *" info ", struct PROCITEM_stack *" stacks "[], int " numstacked ", enum PROCITEM_item " sortitem ", enum PROCITEM_sort_order " order ");"
+
+Link with \fI\-lprocps\fP.
+
+.SH DESCRIPTION
+This manual page describes the common functions for obtaining information
+about the following information types out of the
+.BR proc (5)
+filesystem:
+.TP
+.B diskstats
+I/O statistics of the system disks.
+.TP
+.B meminfo
+Statistics on the usage of the memory system such as what is seen in
+.BR free (1).
+Does not have \fB_reap\fR or \fB_sort\fR functions.
+.TP
+.B slabinfo
+Statistics on the memory caches called slabs.
+.TP
+.B stat
+Generic system statistics such as CPU times and interrupts.
+.TP
+.B vmstat
+Virtual memory statistics.
+Does not have \fB_reap\fR or \fB_sort\fR functions.
+.PP
+.BR procps_pids
+man page describes similar functions for obtaining information about the
+running processes on a system.
+.PP
+For each statistics type, substitute the name for \fBPROCITEM\fR as
+seen in the \fBSYNOPSIS\fR. For example, to obtain a new \fBmeminfo\fR
+structure, you would call
+.BI procps_meminfo_new( &info_ptr );
+where \fIinfo_ptr\fR is a pointer to \fIstruct meminfo_info\fR.
+.SS Procps functions
+.TP
+.B _new()
+The first call to the library should always be the relevant \fB_new\fR() function to obtain a \fIinfo\fR
+structure that can be used for subsequent calls on the library. The function just allocates memory to the
+structure and does not fetch any data.
+.TP
+.B _ref()
+Increments an internal reference count within the given \fIinfo\fR structure.
+.TP
+.B _unref()
+Decrements an internal reference count within the given \fIinfo\fR structure.
+If the count reaches zero then the structure is de-allocated.
+.TP
+.B _get()
+Get one piece of data as described by the enum. For diskstats the device also
+needs to be specified. For subsequent calls to this function, the data is only
+refeshed after one second from the previous call.
+.TP
+.B _reap()
+Get multiple pieces of data as described in the array of enums.
+.TP
+.B select()
+ok reap versus select...
+.TP
+.B sort()
+Sorts the already-fetched data in the given stacks based upon the given
+item and sort order.
+.SS Procps structures
+The procps library uses a variety of structures to hold the extracted,
+filtered or sorted information about the various aspects of the proc
+filesystem.
+.TP
+.B info structure
+The main structure used for the library. All information calls for a particular
+information type will need this structure. For example, all functions for
+vmstat will have a requirement for \fBstruct vmstat_info\fR.
+.TP
+.B item enum
+The item enum is used to select a particular statistic from the information
+type. This determines if you get the value for free memory versus used, or
+system CPU time versus user CPU time.
+.TP
+.B result struct
+Holds a single value for a particular statistic, including the \fBitem enum\fR
+to tell what the value is for. As results can be of various types, the structure
+uses a union.
+.TP
+.B stack structure
+A stack is simply an array of \fBresult struct\fR. This is used to contain
+multiple values in one place.
+.TP
+.B reap struct
+Structure holding multiple \fBstack struct\fRs.
+
+.SH RETURN VALUE
+The \fBprocps_PROCITEM_new\fR() functions return 0 on success and 1 on any failure.
+.PP
+The \fBprocps_PROCITEM_ref\fR() and \fBprocps_PROCITEM_unref\fR() functions
+return the updated reference count on success and \fB-EINVAL\fR if given
+invalid parameters.
+.PP
+The \fBprocps_PROCITEM_result\fR() functions return a pointer to
+.B struct PROCITEM_result
+structure on success and \fBNULL\fR on failure.
+.PP
+The \fBprocps_PROCITEM_reap\fR() functions return a pointer to
+.B struct PROCITEM_reap
+structure on success and \fBNULL\fR on failure.
+.PP
+The \fBprocps_PROCITEM_select\fR() and \fBprocps_PROCITEM_sort\fR
+ functions return a pointer to
+.B struct PROCITEM_stack
+structure on success and \fBNULL\fR on failure.
+.SH FILES
+.TP
+.I /proc/diskstats
+I/O statistics for disks
+.TP
+.I /proc/meminfo
+Memory useage statistics
+.TP
+.I /proc/slabinfo
+Source of the statistics of slabinfo
+.TP
+.I /proc/vmstat
+Source of the statistics for virtual memory.
+.SH VERSIONS
+All of the new API functions
+first appeared in libproc-2 version 0.0.
+
+.SH SEE ALSO
+.BR procps_pids (3),
+.BR proc (5),
+.BR slabinfo (5).