From e3be059d4da38aa36f1aee1d56f8ceb943d92f1c Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 14 Apr 2024 22:34:44 +0200 Subject: Adding upstream version 2:4.0.4. Signed-off-by: Daniel Baumann --- man/procps.3 | 185 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 185 insertions(+) create mode 100644 man/procps.3 (limited to 'man/procps.3') diff --git a/man/procps.3 b/man/procps.3 new file mode 100644 index 0000000..4e07a92 --- /dev/null +++ b/man/procps.3 @@ -0,0 +1,185 @@ +.\" +.\" Copyright (c) 2020-2023 Jim Warner +.\" Copyright (c) 2020-2023 Craig Small +.\" +.\" 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 3 "August 2022" "libproc2" +.\" Please adjust this date whenever revising the manpage. +.\" +.nh +.SH NAME +procps \- API to access system level information in the /proc filesystem + +.SH SYNOPSIS +Five distinct interfaces are represented in this synopsis and named after +the files they access in the /proc pseudo filesystem: +.BR diskstats ", " meminfo ", " slabinfo ", " stat " and " vmstat . + +.nf +.RS +4 +#include + +.RI "int\fB procps_new \fR (struct info **" info ); +.RI "int\fB procps_ref \fR (struct info *" info ); +.RI "int\fB procps_unref\fR (struct info **" info ); + +.RB "struct result *" procps_get " (" +.RI " struct info *" info , +.RI "[ const char *" name ", ] \fBdiskstats\fR api only" +.RI " enum item " item ); + +.RB "struct stack *" procps_select " (" +.RI " struct info *" info , +.RI "[ const char *" name ", ] \fBdiskstats\fR api only" +.RI " enum item *" items , +.RI " int " numitems ); + +.RB "struct reaped *" procps_reap " (" +.RI " struct info *" info , +.RI "[ enum reap_type " what ", ] \fBstat\fR api only" +.RI " enum item *" items , +.RI " int " numitems ); + +.RB "struct stack **" procps_sort " (" +.RI " struct info *" info , +.RI " struct stack *" stacks [], +.RI " int " numstacked , +.RI " enum item " sortitem , +.RI " enum sort_order " order ); + +.fi + +The above functions and structures are generic but the specific +\fBnamed_interface\fR would also be part of any identifiers. +For example, `procps_new' would actually be `procps_\fBmeminfo\fR_new' +and `info' would really be `\fBdiskstats\fR_info', etc. + +The same \fBnamed_interface\fR is used in each header file name with +an appended `.h' suffix. + +Link with \fI\-lproc2\fP. + +.SH DESCRIPTION +.SS Overview +Central to these interfaces is a simple `result' +structure reflecting an `item' plus its value (in a union +with standard C language types as members). +All `result' structures are automatically allocated and +provided by the library. + +By specifying an array of `items', these structures can be +organized as a `stack', potentially yielding many results +with a single function call. +Thus, a `stack' can be viewed as a variable length record +whose content and order is determined solely by the user. + +As part of each interface there are two unique enumerators. +The `noop' and `extra' items exist to hold user values. +They are never set by the library, but the `extra' +result will be zeroed with each library interaction. + +The \fBnamed_interface\fR header file will be an essential +document during user program development. +There you will find available items, their return type +(the `result' 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 +these interfaces. + +.nf +.RB "1. " procps_new() +.RB "2. " procps_get() ", " procps_select() " or " procps_reap() +.RB "3. " procps_unref() +.fi + +The \fBget\fR function is used to retrieve a `result' structure for +a single `item'. +Alternatively, a \fBGET\fR macro is available when only the return +value is of interest. + +The \fBselect\fR function can retrieve multiple `result' structures +in a single `stack'. + +For unpredictable variable outcomes, the \fBdiskstats\fR, \fBslabinfo\fR +and \fBstat\fR interfaces export a \fBreap\fR function. +It is used to retrieve multiple `stacks' each containing multiple +`result' structures. +Optionally, a user may choose to \fBsort\fR those results. + +To exploit any `stack', and access individual `result' 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 `items' array. + +.SS Caveats +The \fBnew\fR, \fBref\fR, \fBunref\fR, \fBget\fR and \fBselect\fR +functions are available in all five interfaces. + +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. + +In the case of the \fBdiskstats\fR interface, a \fIname\fR parameter +on the \fBget\fR and \fBselect\fR functions identifies a disk or +partition name + +For the \fBstat\fR interface, a \fIwhat\fR parameter on the \fBreap\fR +function identifies whether data for just CPUs or both CPUs and NUMA +nodes is to be gathered. + +When using the \fBsort\fR function, the parameters \fIstacks\fR and +\fInumstacked\fR would normally be those returned in the `reaped' +structure. + +.SH RETURN VALUE +.SS Functions Returning an `int' +An error will be indicated by a negative number that +is always the inverse of some well known errno.h value. + +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 `address' +An error will be indicated by a NULL return pointer +with the reason found in the formal errno value. + +Success is indicated by a pointer to the named structure. + +.SH DEBUGGING +To aid in program development, there is a provision that can +help ensure `result' member references agree with library +expectations. +It assumes that a supplied macro in the header file is +used to access the `result' value. + +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 employed. + +.IP 2) 3 +Add #include to any program +\fIafter\fR the named interface includes. + +.PP +This verification feature incurs substantial overhead. +Therefore, it is important that it \fInot\fR be activated +for a production/release build. + +.SH SEE ALSO +.BR procps_misc (3), +.BR procps_pids (3), +.BR proc (5). -- cgit v1.2.3