mirror of
https://gitlab.com/procps-ng/procps.git
synced 2024-11-27 03:54:06 +08:00
39aab8c464
* Stop quoting macro arguments that don't contain spaces.
* Stop defining content for the center header.
* Migrate procio(3) and top(1) to use ISO 8601 date format, like most of
the other man pages in this project.
* Add the day of the month to procps(3)'s and top(1)'s revision dates.
* Replace procio(3)'s inside footer, "Linux Manpage", with "procps-ng".
* Migrate procps(3), procps_misc(3), procps_pids(3) to use "procps-ng"
instead of "libproc2" as their inside footers, like all the other man
pages in this project.
groff_man_style(7):
Macro reference preliminaries
...
If a macro accepts multiple arguments, those containing space
characters must be double‐quoted to be interpreted correctly.
...
Document structure macros
...
.TH identifier section [footer‐middle [footer‐inside [header‐middle]]]
...
identifier and section are positioned at the left and right
in the header; the latter is set after the former, in
parentheses and without space. footer‐middle is centered in
the footer. By default, footer‐inside is positioned at the
bottom left. Use of the double‐sided layout option -rD1
places footer‐inside at the bottom left on recto
(odd‐numbered) pages, and the bottom right on verso
(even‐numbered) pages. By default, the outside footer is
the page number. Use of the continuous‐rendering option
-rcR=1 replaces it with identifier and section, as in the
header. header‐middle is centered in the header. If
section is an integer between 1 and 9 (inclusive), there is
no need to specify header‐middle; an.tmac supplies text for
it.
...
By convention, footer‐middle is the date of the most recent
modification to the man page source document, and footer‐
inside is the name and version or release of the project
providing it.
201 lines
7.7 KiB
Groff
201 lines
7.7 KiB
Groff
.\"
|
|
.\" Copyright (c) 2020-2024 Jim Warner <james.warner@comcast.net>
|
|
.\" Copyright (c) 2020-2024 Craig Small <csmall@dropbear.xyz>
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\"
|
|
.TH PROCPS_PIDS 3 2004-09-03 procps-ng
|
|
.\" Please adjust this date whenever revising the manpage.
|
|
.\"
|
|
.nh
|
|
.SH NAME
|
|
procps_pids \- API to access process information in the /proc filesystem
|
|
.SH SYNOPSIS
|
|
.nf
|
|
#include <libproc2/pids.h>
|
|
.P
|
|
.RI "int\fB procps_pids_new \fR (struct pids_info **" info ", enum pids_item *" items ", int " numitems );
|
|
.RI "int\fB procps_pids_ref \fR (struct pids_info *" info );
|
|
.RI "int\fB procps_pids_unref\fR (struct pids_info **" info );
|
|
.P
|
|
.RB "struct pids_stack *" procps_pids_get " ("
|
|
.RI " struct pids_info *" info ,
|
|
.RI " enum pids_fetch_type " which );
|
|
.P
|
|
.RB "struct pids_fetch *" procps_pids_reap " ("
|
|
.RI " struct pids_info *" info ,
|
|
.RI " enum pids_fetch_type " which );
|
|
.P
|
|
.RB "struct pids_fetch *" procps_pids_select " ("
|
|
.RI " struct pids_info *" info ,
|
|
.RI " unsigned *" these ,
|
|
.RI " int " numthese ,
|
|
.RI " enum pids_select_type " which );
|
|
.P
|
|
.RB "struct pids_stack **" procps_pids_sort " ("
|
|
.RI " struct pids_info *" info ,
|
|
.RI " struct pids_stack *" stacks [],
|
|
.RI " int " numstacked ,
|
|
.RI " enum pids_item " sortitem ,
|
|
.RI " enum pids_sort_order " order );
|
|
.P
|
|
.RB "int " procps_pids_reset " ("
|
|
.RI " struct pids_info *" info ,
|
|
.RI " enum pids_item *" newitems ,
|
|
.RI " int " newnumitems );
|
|
.P
|
|
.RB "struct pids_stack *" fatal_proc_unmounted " ("
|
|
.RI " struct pids_info *" info ,
|
|
.RI " int " return_self );
|
|
.P
|
|
.fi
|
|
.P
|
|
Link with \fI\-lproc2\fP.
|
|
.SH DESCRIPTION
|
|
.SS Overview
|
|
Central to this interface is a simple \[oq]result\[cq]
|
|
structure reflecting an \[oq]item\[cq] plus its value (in a union
|
|
with standard C language types as members).
|
|
All \[oq]result\[cq] structures are automatically allocated and
|
|
provided by the library.
|
|
.P
|
|
By specifying an array of \[oq]items\[cq], these structures can be
|
|
organized as a \[oq]stack\[cq], potentially yielding many results
|
|
with a single function call.
|
|
Thus, a \[oq]stack\[cq] can be viewed as a variable length record
|
|
whose content and order is determined solely by the user.
|
|
.P
|
|
As part of this interface there are two unique enumerators.
|
|
The \[oq]noop\[cq] and \[oq]extra\[cq] items exist to hold user values.
|
|
They are never set by the library, but the \[oq]extra\[cq]
|
|
result will be zeroed with each library interaction.
|
|
.P
|
|
The pids.h file will be an essential document during
|
|
user program development.
|
|
There you will find available items, their return type
|
|
(the \[oq]result\[cq] struct member name)
|
|
and the source for such values.
|
|
Additional enumerators and structures are also documented there.
|
|
.SS Usage
|
|
The following would be a typical sequence of calls to
|
|
this interface.
|
|
.P
|
|
.nf
|
|
.RB "1. " fatal_proc_unmounted()
|
|
.RB "2. " procps_pids_new()
|
|
.RB "3. " procps_pids_get() ", " procps_pids_reap() " or " procps_pids_select()
|
|
.RB "4. " procps_pids_unref()
|
|
.fi
|
|
.P
|
|
The \fBget\fR function is an iterator for successive PIDs/TIDs,
|
|
returning those \[oq]items\[cq] previously identified via \fBnew\fR
|
|
or \fBreset\fR.
|
|
.P
|
|
Two functions support unpredictable variable outcomes.
|
|
The \fBreap\fR function gathers data for all processes while
|
|
the \fBselect\fR function deals with specific PIDs or UIDs.
|
|
Both can return multiple \[oq]stacks\[cq] each containing multiple
|
|
\[oq]result\[cq] structures.
|
|
Optionally, a user may choose to \fBsort\fR such results
|
|
.P
|
|
To exploit any \[oq]stack\[cq],
|
|
and access individual \[oq]result\[cq] structures,
|
|
a \fIrelative_enum\fR is required as shown in the \fBVAL\fR macro
|
|
defined in the header file.
|
|
Such values could be hard coded as: 0 through numitems-1.
|
|
However, this need is typically satisfied by creating your own
|
|
enumerators corresponding to the order of the \[oq]items\[cq] array.
|
|
.SS Caveats
|
|
The <pids> API differs from others in that those items
|
|
of interest must be provided at \fBnew\fR or \fBreset\fR time,
|
|
the latter being unique to this API.
|
|
If either the \fIitems\fR or \fInumitems\fR parameter is zero at
|
|
\fBnew\fR time, then \fBreset\fR becomes mandatory before
|
|
issuing any other call.
|
|
Otherwise, procps_pids_reset() should only be called when the order or
|
|
number of items in your stacks is changed.
|
|
.P
|
|
For the \fBnew\fR and \fBunref\fR functions, the address of an \fIinfo\fR
|
|
struct pointer must be supplied.
|
|
With \fBnew\fR it must have been initialized to NULL.
|
|
With \fBunref\fR it will be reset to NULL if the reference count reaches zero.
|
|
.P
|
|
The \fBget\fR and \fBreap\fR functions use the \fIwhich\fR parameter
|
|
to specify whether just tasks or both tasks and threads are to be fetched.
|
|
.P
|
|
The \fBselect\fR function requires an array of PIDs or UIDs as
|
|
\fIthese\fR along with \fInumthese\fR to identify which processes
|
|
are to be fetched.
|
|
This function then operates as a subset of \fBreap\fR.
|
|
.P
|
|
When using the \fBsort\fR function, the parameters \fIstacks\fR and
|
|
\fInumstacked\fR would normally be those returned in the
|
|
\[oq]pids_fetch\[cq] structure.
|
|
.P
|
|
Lastly, a \fBfatal_proc_unmounted\fR function may be called before
|
|
any other function to ensure that the /proc/ directory is mounted.
|
|
As such, the \fIinfo\fR parameter would be NULL and the
|
|
\fIreturn_self\fR parameter zero.
|
|
If, however, some items are desired for the issuing program (a
|
|
\fIreturn_self\fR other than zero) then the \fBnew\fR call must precede
|
|
it to identify the \fIitems\fR and obtain the required \fIinfo\fR pointer.
|
|
.SH RETURN VALUE
|
|
.SS Functions Returning an \[oq]int\[cq]
|
|
An error will be indicated by a negative number that
|
|
is always the inverse of some well known errno.h value.
|
|
.P
|
|
Success is indicated by a zero return value.
|
|
However, the \fBref\fR and \fBunref\fR functions return
|
|
the current \fIinfo\fR structure reference count.
|
|
.SS Functions Returning an \[oq]address\[cq]
|
|
An error will be indicated by a NULL return pointer
|
|
with the reason found in the formal errno value.
|
|
.P
|
|
Success is indicated by a pointer to the named structure.
|
|
However, if one survives the \fBfatal_proc_unmounted\fR call,
|
|
NULL is always returned when \fIreturn_self\fR is zero.
|
|
.SH DEBUGGING
|
|
To aid in program development, there are two procps-ng provisions
|
|
that can be exploited.
|
|
.P
|
|
The first is a supplied file named \[oq]libproc.supp\[cq] which may be
|
|
useful when developing a \fImulti-threaded\fR application.
|
|
When used with the valgrind \[oq]--suppressions=\[cq] option, warnings
|
|
associated with the procps library itself are avoided.
|
|
.P
|
|
Such warnings arise because the library handles heap based
|
|
allocations in a thread-safe manner.
|
|
A \fIsingle-threaded\fR application will not receive those warnings.
|
|
.P
|
|
The second provision can help ensure \[oq]result\[cq] member references
|
|
agree with library expectations.
|
|
It assumes that a supplied macro in the header file is
|
|
used to access the \[oq]result\[cq] value.
|
|
.P
|
|
This feature can be activated through either of the following
|
|
methods and any discrepancies will be written to \fBstderr\fR.
|
|
.IP 1) 3
|
|
Add CFLAGS='-DXTRA_PROCPS_DEBUG' to any other ./configure
|
|
options your project may employ.
|
|
.IP 2) 3
|
|
Add #include <libproc2/xtra-procps-debug.h> to any program
|
|
\fIafter\fR the #include <libproc2/pids.h>.
|
|
.PP
|
|
This verification feature incurs substantial overhead.
|
|
Therefore, it is important that it \fInot\fR be activated
|
|
for a production/release build.
|
|
.SH ENVIRONMENT VARIABLE(S)
|
|
The value set for the following is unimportant, just its presence.
|
|
.IP LIBPROC_HIDE_KERNEL
|
|
This will hide kernel threads which would otherwise be returned with a
|
|
.BR procps_pids_get ", " procps_pids_select " or " procps_pids_reap
|
|
call.
|
|
.SH SEE ALSO
|
|
.BR procps (3),
|
|
.BR procps_misc (3),
|
|
.BR proc (5).
|