emo/procps
1
0
Fork 0
Code Issues Pull Requests Packages Releases Activity
b72eb5c9ea
procps/man/procps.3

194 lines
6.7 KiB
Groff
Raw Normal View History

misc: fixed several inconsistencies in email addresses [ you wouldn't believe how many back-and-forths were ] [ involved in Craig convincing me there were several ] [ inconsistencies. i am so dense sometimes (often?). ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-01-07 11:30:00 +05:30
.\" (C) Copyright 2020-2022 Jim Warner <james.warner@comcast.net>
doc: First cut at new combined API doc Instead of repeating the same thing for each info type, use one huge man page. Needs more work but lets see how it looks for now.
2020-05-19 18:13:21 +05:30
.\"
.\" %%%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
.\"
doc: make the library API pages a little more readable Use of the the '.B' and '.BI' man documentation macros had rendered the three library API pages less readable than they could be. In addition, sometimes the pointer indicator and an identifier were separated by a space. So, this commit will trade those macros for some '.RI' and '.RB' macros plus treat the pointers consistently. [ plus we no longer italicize sort 'stacks' brackets ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-07-26 10:30:00 +05:30
.TH PROCPS 3 "July 2022" "libproc-2"
doc: First cut at new combined API doc Instead of repeating the same thing for each info type, use one huge man page. Needs more work but lets see how it looks for now.
2020-05-19 18:13:21 +05:30
.\" Please adjust this date whenever revising the manpage.
.\"
docs: update 'first cut' procps.3 with revised version This represents the 'second cut' at providing a shared man page that supports more than one newlib interface. In this approach, the following assumptions were made: 1) It is the kernel folks' job to document /proc files not to mention fields within those files. And since we don't yet know what some of those fields represent, we shouldn't attempt to document any of those we do know. 2) Our header files serve as an essential reference in successful exploitation of the new library interfaces. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) Some inconsistencies among the interfaces have been handled more visually rather than in a narrative form. 5) Armed with our header file users can easily see the self-documenting enumerators & structures. There isn't a need to explain them yet again in this man document. 6) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. Reference(s): . 05/19/20, procps.3 man page introduced commit fc69028d374ae933b55b05b0f1418ac6a3da87e2 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-20 10:30:00 +05:30
.nh
doc: First cut at new combined API doc Instead of repeating the same thing for each info type, use one huge man page. Needs more work but lets see how it looks for now.
2020-05-19 18:13:21 +05:30
.SH NAME
docs: update 'first cut' procps.3 with revised version This represents the 'second cut' at providing a shared man page that supports more than one newlib interface. In this approach, the following assumptions were made: 1) It is the kernel folks' job to document /proc files not to mention fields within those files. And since we don't yet know what some of those fields represent, we shouldn't attempt to document any of those we do know. 2) Our header files serve as an essential reference in successful exploitation of the new library interfaces. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) Some inconsistencies among the interfaces have been handled more visually rather than in a narrative form. 5) Armed with our header file users can easily see the self-documenting enumerators & structures. There isn't a need to explain them yet again in this man document. 6) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. Reference(s): . 05/19/20, procps.3 man page introduced commit fc69028d374ae933b55b05b0f1418ac6a3da87e2 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-20 10:30:00 +05:30
procps \- API to access system level information in the /proc filesystem
doc: First cut at new combined API doc Instead of repeating the same thing for each info type, use one huge man page. Needs more work but lets see how it looks for now.
2020-05-19 18:13:21 +05:30
docs: update 'first cut' procps.3 with revised version This represents the 'second cut' at providing a shared man page that supports more than one newlib interface. In this approach, the following assumptions were made: 1) It is the kernel folks' job to document /proc files not to mention fields within those files. And since we don't yet know what some of those fields represent, we shouldn't attempt to document any of those we do know. 2) Our header files serve as an essential reference in successful exploitation of the new library interfaces. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) Some inconsistencies among the interfaces have been handled more visually rather than in a narrative form. 5) Armed with our header file users can easily see the self-documenting enumerators & structures. There isn't a need to explain them yet again in this man document. 6) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. Reference(s): . 05/19/20, procps.3 man page introduced commit fc69028d374ae933b55b05b0f1418ac6a3da87e2 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-20 10:30:00 +05:30
.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 .
doc: First cut at new combined API doc Instead of repeating the same thing for each info type, use one huge man page. Needs more work but lets see how it looks for now.
2020-05-19 18:13:21 +05:30
docs: update 'first cut' procps.3 with revised version This represents the 'second cut' at providing a shared man page that supports more than one newlib interface. In this approach, the following assumptions were made: 1) It is the kernel folks' job to document /proc files not to mention fields within those files. And since we don't yet know what some of those fields represent, we shouldn't attempt to document any of those we do know. 2) Our header files serve as an essential reference in successful exploitation of the new library interfaces. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) Some inconsistencies among the interfaces have been handled more visually rather than in a narrative form. 5) Armed with our header file users can easily see the self-documenting enumerators & structures. There isn't a need to explain them yet again in this man document. 6) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. Reference(s): . 05/19/20, procps.3 man page introduced commit fc69028d374ae933b55b05b0f1418ac6a3da87e2 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-20 10:30:00 +05:30
.nf
.RS +4
#include <procps/\fBnamed_interface\fR.h>
doc: First cut at new combined API doc Instead of repeating the same thing for each info type, use one huge man page. Needs more work but lets see how it looks for now.
2020-05-19 18:13:21 +05:30
doc: make the library API pages a little more readable Use of the the '.B' and '.BI' man documentation macros had rendered the three library API pages less readable than they could be. In addition, sometimes the pointer indicator and an identifier were separated by a space. So, this commit will trade those macros for some '.RI' and '.RB' macros plus treat the pointers consistently. [ plus we no longer italicize sort 'stacks' brackets ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-07-26 10:30:00 +05:30
.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 );
doc: First cut at new combined API doc Instead of repeating the same thing for each info type, use one huge man page. Needs more work but lets see how it looks for now.
2020-05-19 18:13:21 +05:30
doc: make the library API pages a little more readable Use of the the '.B' and '.BI' man documentation macros had rendered the three library API pages less readable than they could be. In addition, sometimes the pointer indicator and an identifier were separated by a space. So, this commit will trade those macros for some '.RI' and '.RB' macros plus treat the pointers consistently. [ plus we no longer italicize sort 'stacks' brackets ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-07-26 10:30:00 +05:30
.RB "struct result *" procps_get " ("
.RI " struct info *" info ,
docs: update 'first cut' procps.3 with revised version This represents the 'second cut' at providing a shared man page that supports more than one newlib interface. In this approach, the following assumptions were made: 1) It is the kernel folks' job to document /proc files not to mention fields within those files. And since we don't yet know what some of those fields represent, we shouldn't attempt to document any of those we do know. 2) Our header files serve as an essential reference in successful exploitation of the new library interfaces. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) Some inconsistencies among the interfaces have been handled more visually rather than in a narrative form. 5) Armed with our header file users can easily see the self-documenting enumerators & structures. There isn't a need to explain them yet again in this man document. 6) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. Reference(s): . 05/19/20, procps.3 man page introduced commit fc69028d374ae933b55b05b0f1418ac6a3da87e2 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-20 10:30:00 +05:30
.RI "[ const char *" name ", ] \fBdiskstats\fR api only"
doc: make the library API pages a little more readable Use of the the '.B' and '.BI' man documentation macros had rendered the three library API pages less readable than they could be. In addition, sometimes the pointer indicator and an identifier were separated by a space. So, this commit will trade those macros for some '.RI' and '.RB' macros plus treat the pointers consistently. [ plus we no longer italicize sort 'stacks' brackets ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-07-26 10:30:00 +05:30
.RI " enum item " item );
doc: First cut at new combined API doc Instead of repeating the same thing for each info type, use one huge man page. Needs more work but lets see how it looks for now.
2020-05-19 18:13:21 +05:30
doc: make the library API pages a little more readable Use of the the '.B' and '.BI' man documentation macros had rendered the three library API pages less readable than they could be. In addition, sometimes the pointer indicator and an identifier were separated by a space. So, this commit will trade those macros for some '.RI' and '.RB' macros plus treat the pointers consistently. [ plus we no longer italicize sort 'stacks' brackets ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-07-26 10:30:00 +05:30
.RB "struct stack *" procps_select " ("
.RI " struct info *" info ,
docs: update 'first cut' procps.3 with revised version This represents the 'second cut' at providing a shared man page that supports more than one newlib interface. In this approach, the following assumptions were made: 1) It is the kernel folks' job to document /proc files not to mention fields within those files. And since we don't yet know what some of those fields represent, we shouldn't attempt to document any of those we do know. 2) Our header files serve as an essential reference in successful exploitation of the new library interfaces. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) Some inconsistencies among the interfaces have been handled more visually rather than in a narrative form. 5) Armed with our header file users can easily see the self-documenting enumerators & structures. There isn't a need to explain them yet again in this man document. 6) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. Reference(s): . 05/19/20, procps.3 man page introduced commit fc69028d374ae933b55b05b0f1418ac6a3da87e2 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-20 10:30:00 +05:30
.RI "[ const char *" name ", ] \fBdiskstats\fR api only"
doc: make the library API pages a little more readable Use of the the '.B' and '.BI' man documentation macros had rendered the three library API pages less readable than they could be. In addition, sometimes the pointer indicator and an identifier were separated by a space. So, this commit will trade those macros for some '.RI' and '.RB' macros plus treat the pointers consistently. [ plus we no longer italicize sort 'stacks' brackets ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-07-26 10:30:00 +05:30
.RI " enum item *" items ,
.RI " int " numitems );
doc: First cut at new combined API doc Instead of repeating the same thing for each info type, use one huge man page. Needs more work but lets see how it looks for now.
2020-05-19 18:13:21 +05:30
doc: make the library API pages a little more readable Use of the the '.B' and '.BI' man documentation macros had rendered the three library API pages less readable than they could be. In addition, sometimes the pointer indicator and an identifier were separated by a space. So, this commit will trade those macros for some '.RI' and '.RB' macros plus treat the pointers consistently. [ plus we no longer italicize sort 'stacks' brackets ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-07-26 10:30:00 +05:30
.RB "struct reaped *" procps_reap " ("
.RI " struct info *" info ,
docs: update 'first cut' procps.3 with revised version This represents the 'second cut' at providing a shared man page that supports more than one newlib interface. In this approach, the following assumptions were made: 1) It is the kernel folks' job to document /proc files not to mention fields within those files. And since we don't yet know what some of those fields represent, we shouldn't attempt to document any of those we do know. 2) Our header files serve as an essential reference in successful exploitation of the new library interfaces. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) Some inconsistencies among the interfaces have been handled more visually rather than in a narrative form. 5) Armed with our header file users can easily see the self-documenting enumerators & structures. There isn't a need to explain them yet again in this man document. 6) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. Reference(s): . 05/19/20, procps.3 man page introduced commit fc69028d374ae933b55b05b0f1418ac6a3da87e2 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-20 10:30:00 +05:30
.RI "[ enum reap_type " what ", ] \fBstat\fR api only"
doc: make the library API pages a little more readable Use of the the '.B' and '.BI' man documentation macros had rendered the three library API pages less readable than they could be. In addition, sometimes the pointer indicator and an identifier were separated by a space. So, this commit will trade those macros for some '.RI' and '.RB' macros plus treat the pointers consistently. [ plus we no longer italicize sort 'stacks' brackets ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-07-26 10:30:00 +05:30
.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 );
doc: First cut at new combined API doc Instead of repeating the same thing for each info type, use one huge man page. Needs more work but lets see how it looks for now.
2020-05-19 18:13:21 +05:30
docs: update 'first cut' procps.3 with revised version This represents the 'second cut' at providing a shared man page that supports more than one newlib interface. In this approach, the following assumptions were made: 1) It is the kernel folks' job to document /proc files not to mention fields within those files. And since we don't yet know what some of those fields represent, we shouldn't attempt to document any of those we do know. 2) Our header files serve as an essential reference in successful exploitation of the new library interfaces. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) Some inconsistencies among the interfaces have been handled more visually rather than in a narrative form. 5) Armed with our header file users can easily see the self-documenting enumerators & structures. There isn't a need to explain them yet again in this man document. 6) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. Reference(s): . 05/19/20, procps.3 man page introduced commit fc69028d374ae933b55b05b0f1418ac6a3da87e2 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-20 10:30:00 +05:30
.fi
doc: First cut at new combined API doc Instead of repeating the same thing for each info type, use one huge man page. Needs more work but lets see how it looks for now.
2020-05-19 18:13:21 +05:30
docs: update 'first cut' procps.3 with revised version This represents the 'second cut' at providing a shared man page that supports more than one newlib interface. In this approach, the following assumptions were made: 1) It is the kernel folks' job to document /proc files not to mention fields within those files. And since we don't yet know what some of those fields represent, we shouldn't attempt to document any of those we do know. 2) Our header files serve as an essential reference in successful exploitation of the new library interfaces. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) Some inconsistencies among the interfaces have been handled more visually rather than in a narrative form. 5) Armed with our header file users can easily see the self-documenting enumerators & structures. There isn't a need to explain them yet again in this man document. 6) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. Reference(s): . 05/19/20, procps.3 man page introduced commit fc69028d374ae933b55b05b0f1418ac6a3da87e2 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-20 10:30:00 +05:30
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.
doc: First cut at new combined API doc Instead of repeating the same thing for each info type, use one huge man page. Needs more work but lets see how it looks for now.
2020-05-19 18:13:21 +05:30
docs: update 'first cut' procps.3 with revised version This represents the 'second cut' at providing a shared man page that supports more than one newlib interface. In this approach, the following assumptions were made: 1) It is the kernel folks' job to document /proc files not to mention fields within those files. And since we don't yet know what some of those fields represent, we shouldn't attempt to document any of those we do know. 2) Our header files serve as an essential reference in successful exploitation of the new library interfaces. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) Some inconsistencies among the interfaces have been handled more visually rather than in a narrative form. 5) Armed with our header file users can easily see the self-documenting enumerators & structures. There isn't a need to explain them yet again in this man document. 6) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. Reference(s): . 05/19/20, procps.3 man page introduced commit fc69028d374ae933b55b05b0f1418ac6a3da87e2 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-20 10:30:00 +05:30
The same \fBnamed_interface\fR is used in each header file name with
an appended `.h' suffix.
doc: First cut at new combined API doc Instead of repeating the same thing for each info type, use one huge man page. Needs more work but lets see how it looks for now.
2020-05-19 18:13:21 +05:30
library: Rename to libproc-2 What to call the new library? Keep using libprocps wouldn't do, its a very different library from the programs' point of view. It would also mean we could have some clashes around the packages (two package names, same library name). The ancient procps used libproc or libproc-a.b.c where a.b.c was the package version. Kept the revision numbers down (it was always 0.0.0) but the name of the library changed. So if we use libproc-2 is there a clash with an ancient procps? procps v 2.0.0 was around in 1999 so it was 22 years ago, also the name of the library would have been libproc-2.0.0.so not libproc-2.so so we're fine with that. libproc-2 seems to fit, our second major re-work of the procps library. Signed-off-by: Craig Small <csmall@dropbear.xyz>
2021-02-20 17:00:31 +05:30
Link with \fI\-lproc-2\fP.
doc: First cut at new combined API doc Instead of repeating the same thing for each info type, use one huge man page. Needs more work but lets see how it looks for now.
2020-05-19 18:13:21 +05:30
.SH DESCRIPTION
docs: update 'first cut' procps.3 with revised version This represents the 'second cut' at providing a shared man page that supports more than one newlib interface. In this approach, the following assumptions were made: 1) It is the kernel folks' job to document /proc files not to mention fields within those files. And since we don't yet know what some of those fields represent, we shouldn't attempt to document any of those we do know. 2) Our header files serve as an essential reference in successful exploitation of the new library interfaces. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) Some inconsistencies among the interfaces have been handled more visually rather than in a narrative form. 5) Armed with our header file users can easily see the self-documenting enumerators & structures. There isn't a need to explain them yet again in this man document. 6) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. Reference(s): . 05/19/20, procps.3 man page introduced commit fc69028d374ae933b55b05b0f1418ac6a3da87e2 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-20 10:30:00 +05:30
.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.
docs: expand 2 man pages 'Usage' to include VAL macros Maybe, the biggest obstacle to successfully exploiting this new library is after those `stacks' are returned. Unless a user requests all available `items', there is always a need to translate an actual enumerator into a relative position within returned stack(s) of results. So, this patch attempts to bridge that gap by adding a brief explanation to the existing discussion in Usage. [ along the way, 'Usage' & 'Caveats' were refactored ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-02-15 11:30:00 +05:30
As part of each interface there are two unique enumerators.
docs: update 'first cut' procps.3 with revised version This represents the 'second cut' at providing a shared man page that supports more than one newlib interface. In this approach, the following assumptions were made: 1) It is the kernel folks' job to document /proc files not to mention fields within those files. And since we don't yet know what some of those fields represent, we shouldn't attempt to document any of those we do know. 2) Our header files serve as an essential reference in successful exploitation of the new library interfaces. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) Some inconsistencies among the interfaces have been handled more visually rather than in a narrative form. 5) Armed with our header file users can easily see the self-documenting enumerators & structures. There isn't a need to explain them yet again in this man document. 6) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. Reference(s): . 05/19/20, procps.3 man page introduced commit fc69028d374ae933b55b05b0f1418ac6a3da87e2 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-20 10:30:00 +05:30
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
docs: expand 2 man pages 'Usage' to include VAL macros Maybe, the biggest obstacle to successfully exploiting this new library is after those `stacks' are returned. Unless a user requests all available `items', there is always a need to translate an actual enumerator into a relative position within returned stack(s) of results. So, this patch attempts to bridge that gap by adding a brief explanation to the existing discussion in Usage. [ along the way, 'Usage' & 'Caveats' were refactored ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-02-15 11:30:00 +05:30
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.
docs: update 'first cut' procps.3 with revised version This represents the 'second cut' at providing a shared man page that supports more than one newlib interface. In this approach, the following assumptions were made: 1) It is the kernel folks' job to document /proc files not to mention fields within those files. And since we don't yet know what some of those fields represent, we shouldn't attempt to document any of those we do know. 2) Our header files serve as an essential reference in successful exploitation of the new library interfaces. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) Some inconsistencies among the interfaces have been handled more visually rather than in a narrative form. 5) Armed with our header file users can easily see the self-documenting enumerators & structures. There isn't a need to explain them yet again in this man document. 6) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. Reference(s): . 05/19/20, procps.3 man page introduced commit fc69028d374ae933b55b05b0f1418ac6a3da87e2 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-20 10:30:00 +05:30
.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
docs: expand 2 man pages 'Usage' to include VAL macros Maybe, the biggest obstacle to successfully exploiting this new library is after those `stacks' are returned. Unless a user requests all available `items', there is always a need to translate an actual enumerator into a relative position within returned stack(s) of results. So, this patch attempts to bridge that gap by adding a brief explanation to the existing discussion in Usage. [ along the way, 'Usage' & 'Caveats' were refactored ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-02-15 11:30:00 +05:30
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.
docs: fix a couple of spelling errors in new man pages Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-04-03 10:30:00 +05:30
When using the \fBsort\fR function, the parameters \fIstacks\fR and
docs: expand 2 man pages 'Usage' to include VAL macros Maybe, the biggest obstacle to successfully exploiting this new library is after those `stacks' are returned. Unless a user requests all available `items', there is always a need to translate an actual enumerator into a relative position within returned stack(s) of results. So, this patch attempts to bridge that gap by adding a brief explanation to the existing discussion in Usage. [ along the way, 'Usage' & 'Caveats' were refactored ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-02-15 11:30:00 +05:30
\fInumstacked\fR would normally be those returned in the `reaped'
structure.
doc: First cut at new combined API doc Instead of repeating the same thing for each info type, use one huge man page. Needs more work but lets see how it looks for now.
2020-05-19 18:13:21 +05:30
.SH RETURN VALUE
docs: update 'first cut' procps.3 with revised version This represents the 'second cut' at providing a shared man page that supports more than one newlib interface. In this approach, the following assumptions were made: 1) It is the kernel folks' job to document /proc files not to mention fields within those files. And since we don't yet know what some of those fields represent, we shouldn't attempt to document any of those we do know. 2) Our header files serve as an essential reference in successful exploitation of the new library interfaces. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) Some inconsistencies among the interfaces have been handled more visually rather than in a narrative form. 5) Armed with our header file users can easily see the self-documenting enumerators & structures. There isn't a need to explain them yet again in this man document. 6) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. Reference(s): . 05/19/20, procps.3 man page introduced commit fc69028d374ae933b55b05b0f1418ac6a3da87e2 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-20 10:30:00 +05:30
.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.
docs: tweak both of those newly created man docs a tad An important fact was omitted in the DEBUGGING section for the two newest man documents. Users must utilize a macro in the header files before verification happens. So, this commit will sneak in such mention and in that way reduce future liability if the feature won't work. Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-24 03:59:14 +05:30
It assumes that a supplied macro in the header file is
used to access the `result' value.
docs: update 'first cut' procps.3 with revised version This represents the 'second cut' at providing a shared man page that supports more than one newlib interface. In this approach, the following assumptions were made: 1) It is the kernel folks' job to document /proc files not to mention fields within those files. And since we don't yet know what some of those fields represent, we shouldn't attempt to document any of those we do know. 2) Our header files serve as an essential reference in successful exploitation of the new library interfaces. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) Some inconsistencies among the interfaces have been handled more visually rather than in a narrative form. 5) Armed with our header file users can easily see the self-documenting enumerators & structures. There isn't a need to explain them yet again in this man document. 6) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. Reference(s): . 05/19/20, procps.3 man page introduced commit fc69028d374ae933b55b05b0f1418ac6a3da87e2 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-20 10:30:00 +05:30
This feature can be activated through either of the following
docs: fix a couple of spelling errors in new man pages Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-04-03 10:30:00 +05:30
methods and any discrepancies will be written to \fBstderr\fR.
docs: update 'first cut' procps.3 with revised version This represents the 'second cut' at providing a shared man page that supports more than one newlib interface. In this approach, the following assumptions were made: 1) It is the kernel folks' job to document /proc files not to mention fields within those files. And since we don't yet know what some of those fields represent, we shouldn't attempt to document any of those we do know. 2) Our header files serve as an essential reference in successful exploitation of the new library interfaces. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) Some inconsistencies among the interfaces have been handled more visually rather than in a narrative form. 5) Armed with our header file users can easily see the self-documenting enumerators & structures. There isn't a need to explain them yet again in this man document. 6) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. Reference(s): . 05/19/20, procps.3 man page introduced commit fc69028d374ae933b55b05b0f1418ac6a3da87e2 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-20 10:30:00 +05:30
.IP 1) 3
Add CFLAGS='-DXTRA_PROCPS_DEBUG' to any other ./configure
options employed.
.IP 2) 3
Add #include <procps/xtra-procps-debug.h> to any program
\fIafter\fR the named interface includes.
doc: First cut at new combined API doc Instead of repeating the same thing for each info type, use one huge man page. Needs more work but lets see how it looks for now.
2020-05-19 18:13:21 +05:30
.PP
docs: update 'first cut' procps.3 with revised version This represents the 'second cut' at providing a shared man page that supports more than one newlib interface. In this approach, the following assumptions were made: 1) It is the kernel folks' job to document /proc files not to mention fields within those files. And since we don't yet know what some of those fields represent, we shouldn't attempt to document any of those we do know. 2) Our header files serve as an essential reference in successful exploitation of the new library interfaces. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) Some inconsistencies among the interfaces have been handled more visually rather than in a narrative form. 5) Armed with our header file users can easily see the self-documenting enumerators & structures. There isn't a need to explain them yet again in this man document. 6) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. Reference(s): . 05/19/20, procps.3 man page introduced commit fc69028d374ae933b55b05b0f1418ac6a3da87e2 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-20 10:30:00 +05:30
This verification feature incurs substantial overhead.
Therefore, it is important that it \fInot\fR be activated
for a production/release build.
doc: First cut at new combined API doc Instead of repeating the same thing for each info type, use one huge man page. Needs more work but lets see how it looks for now.
2020-05-19 18:13:21 +05:30
.SH SEE ALSO
doc: minor tweaks affecting three newlib man documents . add the proper function names to the procps_pids man page when discussing the 'LIBPROC_HIDE_KERNEL' feature under recently added 'ENVIRONMENT VARIABLE(S)' section . ensure the 'SEE ALSO' references are comma delimited Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-02-24 11:30:00 +05:30
.BR procps_misc (3),
.BR procps_pids (3),
docs: update 'first cut' procps.3 with revised version This represents the 'second cut' at providing a shared man page that supports more than one newlib interface. In this approach, the following assumptions were made: 1) It is the kernel folks' job to document /proc files not to mention fields within those files. And since we don't yet know what some of those fields represent, we shouldn't attempt to document any of those we do know. 2) Our header files serve as an essential reference in successful exploitation of the new library interfaces. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) Some inconsistencies among the interfaces have been handled more visually rather than in a narrative form. 5) Armed with our header file users can easily see the self-documenting enumerators & structures. There isn't a need to explain them yet again in this man document. 6) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. Reference(s): . 05/19/20, procps.3 man page introduced commit fc69028d374ae933b55b05b0f1418ac6a3da87e2 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-20 10:30:00 +05:30
.BR proc (5).
Reference in New Issue Copy Permalink