88 lines
3.1 KiB
Groff
88 lines
3.1 KiB
Groff
|
.\" (C) Copyright 2016 Craig Small <csmall@enc.com.au>
|
||
|
|
.\"
|
||
|
|
.\" %%%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_PIDS_READ_OPEN 3 2016-04-19 "libproc-2"
|
||
|
|
.\" Please adjust this date whenever revising the manpage.
|
||
|
|
.\"
|
||
|
|
.SH NAME
|
||
|
|
procps_pids_read_open, procps_pids_read_next \-
|
||
|
|
Load and iterate the PIDs information structure.
|
||
|
|
.SH SYNOPSIS
|
||
|
|
.B #include <proc/procps.h>
|
||
|
|
.sp
|
||
|
|
.BI "int procps_pids_read_open(struct procps_pidsinfo *" info ", enum pids_reap_type " which ");"
|
||
|
|
.sp
|
||
|
|
.BI "int procps_pids_read_next(struct procps_pidsinfo *" info ");"
|
||
|
|
.sp
|
||
|
|
.BI "int procps_pids_read_shut(struct procps_pidsinfo *" info ");"
|
||
|
|
.sp
|
||
|
|
Link with \fI\-lprocps\fP.
|
||
|
|
|
||
|
|
.SH DESCRIPTION
|
||
|
|
This trio of functions is one method of reading and iterating through the
|
||
|
|
procps PIDS information. The info structure first needs to be initialised by
|
||
|
|
.BR procps_pids_new (3).
|
||
|
|
|
||
|
|
\fBprocps_pids_read_open()\fR is the function that will load the various
|
||
|
|
files in the
|
||
|
|
.BR proc (5)
|
||
|
|
filesystem and fill the \fIinfo\fR structure with the parsed values.
|
||
|
|
The function is able to parse only processes or also include threads, the
|
||
|
|
option \fIwhich\fR can be set to \fBPROCPS_REAP_TASKS_ONLY\fR or
|
||
|
|
\fBPROCPS_REAP_THREADS_TOO\fR to determine what is collected.
|
||
|
|
|
||
|
|
Assuming that \fBprocps_pids_read_open()\fR returns successfully, a program can
|
||
|
|
then iterate through a loop using \fBprocps_pids_read_next()\fR
|
||
|
|
and using the accessor methods described in
|
||
|
|
.BR libproc (3).
|
||
|
|
|
||
|
|
One the loop has been completed or the information is no longer
|
||
|
|
required, the function \fBprocps_pids_read_shut()\fR is used to
|
||
|
|
free the information filled by \fBprocps_pids_read_open\fR.
|
||
|
|
Note, the \fIinfo\fR structure is still allocated and requires
|
||
|
|
.BR procps_pids_unref (3)
|
||
|
|
to free \fIinfo\fR entirely.
|
||
|
|
|
||
|
|
.SH RETURN VALUE
|
||
|
|
\fBprocps_pids_read_open()\fR and \fBprocps_pids_read_shut()\fR returns 0
|
||
|
|
on success and one of the negative values below on failure.
|
||
|
|
.PP
|
||
|
|
\fBprocps_pids_read_next()\fR returns a pointer to struct pids_stack for
|
||
|
|
the next process on success and NULL on failure.
|
||
|
|
.TP
|
||
|
|
.B -EINVAL
|
||
|
|
One of the given parameters is incorrect.
|
||
|
|
.TP
|
||
|
|
.B -ENOMEM
|
||
|
|
Unable to allocate memory for the structure.
|
||
|
|
.B -1
|
||
|
|
Unable to parse the
|
||
|
|
.BR proc (5)
|
||
|
|
filesystem.
|
||
|
|
|
||
|
|
.SH VERSIONS
|
||
|
|
\fBprocps_pids_read_open()\fR, \fBprocps_pids_read_next()\fR and
|
||
|
|
\fBprocps_pids_read_shut()\fR
|
||
|
|
first appeared in libproc-2 version 0.0.
|
||
|
|
|
||
|
|
.SH SEE ALSO
|
||
|
|
.BR libproc (3),
|
||
|
|
.BR procps_pids_new (3),
|
||
|
|
.BR procps_pids_unref (3),
|
||
|
|
.BR proc (5).
|