emo/procps
1
0
Fork 0
Code Issues Pull Requests Packages Releases Activity
52bd019d8c
procps/doc/procps_pids.3

219 lines
7.8 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>
docs: replace 'procps_pids' stuff with revised version The original approach contained a fatal flaw. In order to use those man pages, users would have been required to already know how to use the library. Or alternately one could randomly search each of them while trying to ascertain which function call satisfies their need and what exactly was the proper compliment/order required. So, this revised approach tries to simplify things and document only what is not apparent in the header file. Along the way, the following assumptions were germane. 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 file serves as an essential reference in successful exploitation of this new library interface. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) 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. 5) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. The following references represent a history for those man documents this new version is intended to replace. Reference(s): . 04/18/16, create libproc.3 + procps_pids_new.3 commit 4217eddf474debe55a7651757ccce1e86aeb04a5 . 04/19/16, create procps_pids_read_open.3 commit d48c54f6793d5faf44e420df43a75e04372d5945 . 01/05/17, create many procps_pids_... docs commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-21 10:30:00 +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_PIDS 3 "July 2022" "libproc-2"
docs: replace 'procps_pids' stuff with revised version The original approach contained a fatal flaw. In order to use those man pages, users would have been required to already know how to use the library. Or alternately one could randomly search each of them while trying to ascertain which function call satisfies their need and what exactly was the proper compliment/order required. So, this revised approach tries to simplify things and document only what is not apparent in the header file. Along the way, the following assumptions were germane. 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 file serves as an essential reference in successful exploitation of this new library interface. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) 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. 5) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. The following references represent a history for those man documents this new version is intended to replace. Reference(s): . 04/18/16, create libproc.3 + procps_pids_new.3 commit 4217eddf474debe55a7651757ccce1e86aeb04a5 . 04/19/16, create procps_pids_read_open.3 commit d48c54f6793d5faf44e420df43a75e04372d5945 . 01/05/17, create many procps_pids_... docs commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-21 10:30:00 +05:30
.\" Please adjust this date whenever revising the manpage.
.\"
.nh
.SH NAME
docs: just a few changes to that new pids man document A patch to address the following man doc deficiencies: . shorten NAME so there's no wrap in an 80x24 terminal . typo wherein the 'item' parm should have been 'info' . expand RETURN text for a potential NULL upon success [ maybe, this might be my last tweak to this man doc ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-25 10:30:00 +05:30
procps_pids \- API to access process information in the /proc filesystem
docs: replace 'procps_pids' stuff with revised version The original approach contained a fatal flaw. In order to use those man pages, users would have been required to already know how to use the library. Or alternately one could randomly search each of them while trying to ascertain which function call satisfies their need and what exactly was the proper compliment/order required. So, this revised approach tries to simplify things and document only what is not apparent in the header file. Along the way, the following assumptions were germane. 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 file serves as an essential reference in successful exploitation of this new library interface. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) 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. 5) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. The following references represent a history for those man documents this new version is intended to replace. Reference(s): . 04/18/16, create libproc.3 + procps_pids_new.3 commit 4217eddf474debe55a7651757ccce1e86aeb04a5 . 04/19/16, create procps_pids_read_open.3 commit d48c54f6793d5faf44e420df43a75e04372d5945 . 01/05/17, create many procps_pids_... docs commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-21 10:30:00 +05:30
.SH SYNOPSIS
.nf
#include <procps/pids.h>
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_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 );
docs: replace 'procps_pids' stuff with revised version The original approach contained a fatal flaw. In order to use those man pages, users would have been required to already know how to use the library. Or alternately one could randomly search each of them while trying to ascertain which function call satisfies their need and what exactly was the proper compliment/order required. So, this revised approach tries to simplify things and document only what is not apparent in the header file. Along the way, the following assumptions were germane. 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 file serves as an essential reference in successful exploitation of this new library interface. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) 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. 5) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. The following references represent a history for those man documents this new version is intended to replace. Reference(s): . 04/18/16, create libproc.3 + procps_pids_new.3 commit 4217eddf474debe55a7651757ccce1e86aeb04a5 . 04/19/16, create procps_pids_read_open.3 commit d48c54f6793d5faf44e420df43a75e04372d5945 . 01/05/17, create many procps_pids_... docs commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-21 10:30:00 +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 pids_stack *" procps_pids_get " ("
.RI " struct pids_info *" info ,
.RI " enum pids_fetch_type " which );
docs: replace 'procps_pids' stuff with revised version The original approach contained a fatal flaw. In order to use those man pages, users would have been required to already know how to use the library. Or alternately one could randomly search each of them while trying to ascertain which function call satisfies their need and what exactly was the proper compliment/order required. So, this revised approach tries to simplify things and document only what is not apparent in the header file. Along the way, the following assumptions were germane. 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 file serves as an essential reference in successful exploitation of this new library interface. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) 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. 5) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. The following references represent a history for those man documents this new version is intended to replace. Reference(s): . 04/18/16, create libproc.3 + procps_pids_new.3 commit 4217eddf474debe55a7651757ccce1e86aeb04a5 . 04/19/16, create procps_pids_read_open.3 commit d48c54f6793d5faf44e420df43a75e04372d5945 . 01/05/17, create many procps_pids_... docs commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-21 10:30:00 +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 pids_fetch *" procps_pids_reap " ("
.RI " struct pids_info *" info ,
.RI " enum pids_fetch_type " which );
docs: replace 'procps_pids' stuff with revised version The original approach contained a fatal flaw. In order to use those man pages, users would have been required to already know how to use the library. Or alternately one could randomly search each of them while trying to ascertain which function call satisfies their need and what exactly was the proper compliment/order required. So, this revised approach tries to simplify things and document only what is not apparent in the header file. Along the way, the following assumptions were germane. 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 file serves as an essential reference in successful exploitation of this new library interface. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) 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. 5) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. The following references represent a history for those man documents this new version is intended to replace. Reference(s): . 04/18/16, create libproc.3 + procps_pids_new.3 commit 4217eddf474debe55a7651757ccce1e86aeb04a5 . 04/19/16, create procps_pids_read_open.3 commit d48c54f6793d5faf44e420df43a75e04372d5945 . 01/05/17, create many procps_pids_... docs commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-21 10:30:00 +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 pids_fetch *" procps_pids_select " ("
.RI " struct pids_info *" info ,
.RI " unsigned *" these ,
.RI " int " numthese ,
.RI " enum pids_select_type " which );
docs: replace 'procps_pids' stuff with revised version The original approach contained a fatal flaw. In order to use those man pages, users would have been required to already know how to use the library. Or alternately one could randomly search each of them while trying to ascertain which function call satisfies their need and what exactly was the proper compliment/order required. So, this revised approach tries to simplify things and document only what is not apparent in the header file. Along the way, the following assumptions were germane. 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 file serves as an essential reference in successful exploitation of this new library interface. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) 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. 5) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. The following references represent a history for those man documents this new version is intended to replace. Reference(s): . 04/18/16, create libproc.3 + procps_pids_new.3 commit 4217eddf474debe55a7651757ccce1e86aeb04a5 . 04/19/16, create procps_pids_read_open.3 commit d48c54f6793d5faf44e420df43a75e04372d5945 . 01/05/17, create many procps_pids_... docs commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-21 10:30:00 +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 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 );
docs: replace 'procps_pids' stuff with revised version The original approach contained a fatal flaw. In order to use those man pages, users would have been required to already know how to use the library. Or alternately one could randomly search each of them while trying to ascertain which function call satisfies their need and what exactly was the proper compliment/order required. So, this revised approach tries to simplify things and document only what is not apparent in the header file. Along the way, the following assumptions were germane. 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 file serves as an essential reference in successful exploitation of this new library interface. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) 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. 5) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. The following references represent a history for those man documents this new version is intended to replace. Reference(s): . 04/18/16, create libproc.3 + procps_pids_new.3 commit 4217eddf474debe55a7651757ccce1e86aeb04a5 . 04/19/16, create procps_pids_read_open.3 commit d48c54f6793d5faf44e420df43a75e04372d5945 . 01/05/17, create many procps_pids_... docs commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-21 10:30:00 +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 "int " procps_pids_reset " ("
.RI " struct pids_info *" info ,
.RI " enum pids_item *" newitems ,
.RI " int " newnumitems );
docs: replace 'procps_pids' stuff with revised version The original approach contained a fatal flaw. In order to use those man pages, users would have been required to already know how to use the library. Or alternately one could randomly search each of them while trying to ascertain which function call satisfies their need and what exactly was the proper compliment/order required. So, this revised approach tries to simplify things and document only what is not apparent in the header file. Along the way, the following assumptions were germane. 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 file serves as an essential reference in successful exploitation of this new library interface. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) 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. 5) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. The following references represent a history for those man documents this new version is intended to replace. Reference(s): . 04/18/16, create libproc.3 + procps_pids_new.3 commit 4217eddf474debe55a7651757ccce1e86aeb04a5 . 04/19/16, create procps_pids_read_open.3 commit d48c54f6793d5faf44e420df43a75e04372d5945 . 01/05/17, create many procps_pids_... docs commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-21 10:30:00 +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 pids_stack *" fatal_proc_unmounted " ("
.RI " struct pids_info *" info ,
.RI " int " return_self );
docs: replace 'procps_pids' stuff with revised version The original approach contained a fatal flaw. In order to use those man pages, users would have been required to already know how to use the library. Or alternately one could randomly search each of them while trying to ascertain which function call satisfies their need and what exactly was the proper compliment/order required. So, this revised approach tries to simplify things and document only what is not apparent in the header file. Along the way, the following assumptions were germane. 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 file serves as an essential reference in successful exploitation of this new library interface. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) 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. 5) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. The following references represent a history for those man documents this new version is intended to replace. Reference(s): . 04/18/16, create libproc.3 + procps_pids_new.3 commit 4217eddf474debe55a7651757ccce1e86aeb04a5 . 04/19/16, create procps_pids_read_open.3 commit d48c54f6793d5faf44e420df43a75e04372d5945 . 01/05/17, create many procps_pids_... docs commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-21 10:30:00 +05:30
.fi
docs: tweak two man pages due to renaming of libproc-2 Reference(s): commit 9aa09d8862c00a8dc85910d0365332c8c99b59ce Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-02-20 22:41:11 +05:30
Link with \fI\-lproc-2\fP.
docs: replace 'procps_pids' stuff with revised version The original approach contained a fatal flaw. In order to use those man pages, users would have been required to already know how to use the library. Or alternately one could randomly search each of them while trying to ascertain which function call satisfies their need and what exactly was the proper compliment/order required. So, this revised approach tries to simplify things and document only what is not apparent in the header file. Along the way, the following assumptions were germane. 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 file serves as an essential reference in successful exploitation of this new library interface. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) 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. 5) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. The following references represent a history for those man documents this new version is intended to replace. Reference(s): . 04/18/16, create libproc.3 + procps_pids_new.3 commit 4217eddf474debe55a7651757ccce1e86aeb04a5 . 04/19/16, create procps_pids_read_open.3 commit d48c54f6793d5faf44e420df43a75e04372d5945 . 01/05/17, create many procps_pids_... docs commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-21 10:30:00 +05:30
.SH DESCRIPTION
.SS Overview
Central to this interface 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 this interface there are two unique enumerators.
docs: replace 'procps_pids' stuff with revised version The original approach contained a fatal flaw. In order to use those man pages, users would have been required to already know how to use the library. Or alternately one could randomly search each of them while trying to ascertain which function call satisfies their need and what exactly was the proper compliment/order required. So, this revised approach tries to simplify things and document only what is not apparent in the header file. Along the way, the following assumptions were germane. 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 file serves as an essential reference in successful exploitation of this new library interface. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) 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. 5) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. The following references represent a history for those man documents this new version is intended to replace. Reference(s): . 04/18/16, create libproc.3 + procps_pids_new.3 commit 4217eddf474debe55a7651757ccce1e86aeb04a5 . 04/19/16, create procps_pids_read_open.3 commit d48c54f6793d5faf44e420df43a75e04372d5945 . 01/05/17, create many procps_pids_... docs commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-21 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 pids.h 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
this interface.
.nf
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
.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()
docs: replace 'procps_pids' stuff with revised version The original approach contained a fatal flaw. In order to use those man pages, users would have been required to already know how to use the library. Or alternately one could randomly search each of them while trying to ascertain which function call satisfies their need and what exactly was the proper compliment/order required. So, this revised approach tries to simplify things and document only what is not apparent in the header file. Along the way, the following assumptions were germane. 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 file serves as an essential reference in successful exploitation of this new library interface. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) 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. 5) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. The following references represent a history for those man documents this new version is intended to replace. Reference(s): . 04/18/16, create libproc.3 + procps_pids_new.3 commit 4217eddf474debe55a7651757ccce1e86aeb04a5 . 04/19/16, create procps_pids_read_open.3 commit d48c54f6793d5faf44e420df43a75e04372d5945 . 01/05/17, create many procps_pids_... docs commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-21 10:30:00 +05:30
.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 an iterator for successive PIDs/TIDs,
returning those `items' previously identified via \fBnew\fR
or \fBreset\fR.
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 `stacks' each containing multiple `result'
structures.
Optionally, a user may choose to \fBsort\fR such 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: replace 'procps_pids' stuff with revised version The original approach contained a fatal flaw. In order to use those man pages, users would have been required to already know how to use the library. Or alternately one could randomly search each of them while trying to ascertain which function call satisfies their need and what exactly was the proper compliment/order required. So, this revised approach tries to simplify things and document only what is not apparent in the header file. Along the way, the following assumptions were germane. 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 file serves as an essential reference in successful exploitation of this new library interface. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) 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. 5) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. The following references represent a history for those man documents this new version is intended to replace. Reference(s): . 04/18/16, create libproc.3 + procps_pids_new.3 commit 4217eddf474debe55a7651757ccce1e86aeb04a5 . 04/19/16, create procps_pids_read_open.3 commit d48c54f6793d5faf44e420df43a75e04372d5945 . 01/05/17, create many procps_pids_... docs commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-21 10:30:00 +05:30
.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.
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.
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 and \fBreap\fR functions use the \fIwhich\fR parameter
to specify whether just tasks or both tasks and threads are to be fetched.
docs: replace 'procps_pids' stuff with revised version The original approach contained a fatal flaw. In order to use those man pages, users would have been required to already know how to use the library. Or alternately one could randomly search each of them while trying to ascertain which function call satisfies their need and what exactly was the proper compliment/order required. So, this revised approach tries to simplify things and document only what is not apparent in the header file. Along the way, the following assumptions were germane. 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 file serves as an essential reference in successful exploitation of this new library interface. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) 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. 5) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. The following references represent a history for those man documents this new version is intended to replace. Reference(s): . 04/18/16, create libproc.3 + procps_pids_new.3 commit 4217eddf474debe55a7651757ccce1e86aeb04a5 . 04/19/16, create procps_pids_read_open.3 commit d48c54f6793d5faf44e420df43a75e04372d5945 . 01/05/17, create many procps_pids_... docs commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-21 10:30:00 +05:30
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.
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
This function then operates as a subset of \fBreap\fR.
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 `pids_fetch'
structure.
docs: replace 'procps_pids' stuff with revised version The original approach contained a fatal flaw. In order to use those man pages, users would have been required to already know how to use the library. Or alternately one could randomly search each of them while trying to ascertain which function call satisfies their need and what exactly was the proper compliment/order required. So, this revised approach tries to simplify things and document only what is not apparent in the header file. Along the way, the following assumptions were germane. 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 file serves as an essential reference in successful exploitation of this new library interface. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) 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. 5) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. The following references represent a history for those man documents this new version is intended to replace. Reference(s): . 04/18/16, create libproc.3 + procps_pids_new.3 commit 4217eddf474debe55a7651757ccce1e86aeb04a5 . 04/19/16, create procps_pids_read_open.3 commit d48c54f6793d5faf44e420df43a75e04372d5945 . 01/05/17, create many procps_pids_... docs commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-21 10:30:00 +05:30
Lastly, a \fBfatal_proc_unmounted\fR function may be called before
any other function to ensure that the /proc/ directory is mounted.
docs: just a few changes to that new pids man document A patch to address the following man doc deficiencies: . shorten NAME so there's no wrap in an 80x24 terminal . typo wherein the 'item' parm should have been 'info' . expand RETURN text for a potential NULL upon success [ maybe, this might be my last tweak to this man doc ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-25 10:30:00 +05:30
As such, the \fIinfo\fR parameter would be NULL and the
docs: replace 'procps_pids' stuff with revised version The original approach contained a fatal flaw. In order to use those man pages, users would have been required to already know how to use the library. Or alternately one could randomly search each of them while trying to ascertain which function call satisfies their need and what exactly was the proper compliment/order required. So, this revised approach tries to simplify things and document only what is not apparent in the header file. Along the way, the following assumptions were germane. 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 file serves as an essential reference in successful exploitation of this new library interface. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) 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. 5) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. The following references represent a history for those man documents this new version is intended to replace. Reference(s): . 04/18/16, create libproc.3 + procps_pids_new.3 commit 4217eddf474debe55a7651757ccce1e86aeb04a5 . 04/19/16, create procps_pids_read_open.3 commit d48c54f6793d5faf44e420df43a75e04372d5945 . 01/05/17, create many procps_pids_... docs commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-21 10:30:00 +05:30
\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
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
it to identify the \fIitems\fR and obtain the required \fIinfo\fR pointer.
docs: replace 'procps_pids' stuff with revised version The original approach contained a fatal flaw. In order to use those man pages, users would have been required to already know how to use the library. Or alternately one could randomly search each of them while trying to ascertain which function call satisfies their need and what exactly was the proper compliment/order required. So, this revised approach tries to simplify things and document only what is not apparent in the header file. Along the way, the following assumptions were germane. 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 file serves as an essential reference in successful exploitation of this new library interface. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) 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. 5) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. The following references represent a history for those man documents this new version is intended to replace. Reference(s): . 04/18/16, create libproc.3 + procps_pids_new.3 commit 4217eddf474debe55a7651757ccce1e86aeb04a5 . 04/19/16, create procps_pids_read_open.3 commit d48c54f6793d5faf44e420df43a75e04372d5945 . 01/05/17, create many procps_pids_... docs commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-21 10:30:00 +05:30
.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.
docs: just a few changes to that new pids man document A patch to address the following man doc deficiencies: . shorten NAME so there's no wrap in an 80x24 terminal . typo wherein the 'item' parm should have been 'info' . expand RETURN text for a potential NULL upon success [ maybe, this might be my last tweak to this man doc ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-25 10:30:00 +05:30
However, if one survives the \fBfatal_proc_unmounted\fR call,
NULL is always returned when \fIreturn_self\fR is zero.
docs: replace 'procps_pids' stuff with revised version The original approach contained a fatal flaw. In order to use those man pages, users would have been required to already know how to use the library. Or alternately one could randomly search each of them while trying to ascertain which function call satisfies their need and what exactly was the proper compliment/order required. So, this revised approach tries to simplify things and document only what is not apparent in the header file. Along the way, the following assumptions were germane. 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 file serves as an essential reference in successful exploitation of this new library interface. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) 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. 5) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. The following references represent a history for those man documents this new version is intended to replace. Reference(s): . 04/18/16, create libproc.3 + procps_pids_new.3 commit 4217eddf474debe55a7651757ccce1e86aeb04a5 . 04/19/16, create procps_pids_read_open.3 commit d48c54f6793d5faf44e420df43a75e04372d5945 . 01/05/17, create many procps_pids_... docs commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-21 10:30:00 +05:30
.SH DEBUGGING
doc: added the new valgrind 'warning-suppression' file Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-10-14 10:30:00 +05:30
To aid in program development, there are two procps-ng provisions
that can be exploited.
The first is a supplied file named `libproc.supp' which may be
useful when developing a \fImulti-threaded\fR application.
When used with the valgrind `--suppressions=' option, warnings
associated with the procps library itself are avoided.
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.
The second provision 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: replace 'procps_pids' stuff with revised version The original approach contained a fatal flaw. In order to use those man pages, users would have been required to already know how to use the library. Or alternately one could randomly search each of them while trying to ascertain which function call satisfies their need and what exactly was the proper compliment/order required. So, this revised approach tries to simplify things and document only what is not apparent in the header file. Along the way, the following assumptions were germane. 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 file serves as an essential reference in successful exploitation of this new library interface. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) 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. 5) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. The following references represent a history for those man documents this new version is intended to replace. Reference(s): . 04/18/16, create libproc.3 + procps_pids_new.3 commit 4217eddf474debe55a7651757ccce1e86aeb04a5 . 04/19/16, create procps_pids_read_open.3 commit d48c54f6793d5faf44e420df43a75e04372d5945 . 01/05/17, create many procps_pids_... docs commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-21 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: replace 'procps_pids' stuff with revised version The original approach contained a fatal flaw. In order to use those man pages, users would have been required to already know how to use the library. Or alternately one could randomly search each of them while trying to ascertain which function call satisfies their need and what exactly was the proper compliment/order required. So, this revised approach tries to simplify things and document only what is not apparent in the header file. Along the way, the following assumptions were germane. 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 file serves as an essential reference in successful exploitation of this new library interface. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) 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. 5) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. The following references represent a history for those man documents this new version is intended to replace. Reference(s): . 04/18/16, create libproc.3 + procps_pids_new.3 commit 4217eddf474debe55a7651757ccce1e86aeb04a5 . 04/19/16, create procps_pids_read_open.3 commit d48c54f6793d5faf44e420df43a75e04372d5945 . 01/05/17, create many procps_pids_... docs commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-21 10:30:00 +05:30
.IP 1) 3
Add CFLAGS='-DXTRA_PROCPS_DEBUG' to any other ./configure
doc: added the new valgrind 'warning-suppression' file Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-10-14 10:30:00 +05:30
options your project may employ.
docs: replace 'procps_pids' stuff with revised version The original approach contained a fatal flaw. In order to use those man pages, users would have been required to already know how to use the library. Or alternately one could randomly search each of them while trying to ascertain which function call satisfies their need and what exactly was the proper compliment/order required. So, this revised approach tries to simplify things and document only what is not apparent in the header file. Along the way, the following assumptions were germane. 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 file serves as an essential reference in successful exploitation of this new library interface. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) 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. 5) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. The following references represent a history for those man documents this new version is intended to replace. Reference(s): . 04/18/16, create libproc.3 + procps_pids_new.3 commit 4217eddf474debe55a7651757ccce1e86aeb04a5 . 04/19/16, create procps_pids_read_open.3 commit d48c54f6793d5faf44e420df43a75e04372d5945 . 01/05/17, create many procps_pids_... docs commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-21 10:30:00 +05:30
.IP 2) 3
Add #include <procps/xtra-procps-debug.h> to any program
\fIafter\fR the #include <procps/pids.h>.
.PP
This verification feature incurs substantial overhead.
Therefore, it is important that it \fInot\fR be activated
for a production/release build.
doc: updated 3 man pages for 'LIBPROC_HIDE_KERNEL' var This patch was prompted by Björn Fischer's merge #147 request referenced below. And since the library change may impact all users, multiple man pages were updated. [ and thanks to Björn for initiating this extension ] Reference(s): https://gitlab.com/procps-ng/procps/-/merge_requests/147 Prototyped-by: Björn Fischer <bf@CeBiTec.Uni-Bielefeld.DE> Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-01-04 04:30:00 +05:30
.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
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_pids_get ", " procps_pids_select " or " procps_pids_reap
doc: updated 3 man pages for 'LIBPROC_HIDE_KERNEL' var This patch was prompted by Björn Fischer's merge #147 request referenced below. And since the library change may impact all users, multiple man pages were updated. [ and thanks to Björn for initiating this extension ] Reference(s): https://gitlab.com/procps-ng/procps/-/merge_requests/147 Prototyped-by: Björn Fischer <bf@CeBiTec.Uni-Bielefeld.DE> Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-01-04 04:30:00 +05:30
call.
docs: replace 'procps_pids' stuff with revised version The original approach contained a fatal flaw. In order to use those man pages, users would have been required to already know how to use the library. Or alternately one could randomly search each of them while trying to ascertain which function call satisfies their need and what exactly was the proper compliment/order required. So, this revised approach tries to simplify things and document only what is not apparent in the header file. Along the way, the following assumptions were germane. 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 file serves as an essential reference in successful exploitation of this new library interface. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) 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. 5) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. The following references represent a history for those man documents this new version is intended to replace. Reference(s): . 04/18/16, create libproc.3 + procps_pids_new.3 commit 4217eddf474debe55a7651757ccce1e86aeb04a5 . 04/19/16, create procps_pids_read_open.3 commit d48c54f6793d5faf44e420df43a75e04372d5945 . 01/05/17, create many procps_pids_... docs commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-21 10:30:00 +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 (3),
.BR procps_misc (3),
docs: replace 'procps_pids' stuff with revised version The original approach contained a fatal flaw. In order to use those man pages, users would have been required to already know how to use the library. Or alternately one could randomly search each of them while trying to ascertain which function call satisfies their need and what exactly was the proper compliment/order required. So, this revised approach tries to simplify things and document only what is not apparent in the header file. Along the way, the following assumptions were germane. 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 file serves as an essential reference in successful exploitation of this new library interface. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) 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. 5) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. The following references represent a history for those man documents this new version is intended to replace. Reference(s): . 04/18/16, create libproc.3 + procps_pids_new.3 commit 4217eddf474debe55a7651757ccce1e86aeb04a5 . 04/19/16, create procps_pids_read_open.3 commit d48c54f6793d5faf44e420df43a75e04372d5945 . 01/05/17, create many procps_pids_... docs commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-06-21 10:30:00 +05:30
.BR proc (5).
Reference in New Issue Copy Permalink