180 lines
6.3 KiB
Groff
180 lines
6.3 KiB
Groff
|
.\" (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).
|