emo/procps
1
0
Fork 0
Code Issues Pull Requests Packages Releases Activity
6b71148840
procps/library/include/pids.h

289 lines
14 KiB
C
Raw Normal View History

library: implement task/thread support via the new api This commit is the culmination of efforts to modernize the library api. It should be treated as a first blush attempt, especially since I have absolutely no library design experience. But I did have a very strong desire to lessen the new library's impact on the top program. Under this new api, a 'stack' is the equivalent of the old proc_t. It can be seen as a variable length record whose contents & order is under complete user control. That initial stack/record configuration is established at procps_pids_new() time and will probably serve most program needs. But, a dynamic & demanding program like top will later change a stack via procps_pids_reset(). For programs like top & ps, procps_pids_reap() will be the function that will retrieve all tasks and threads. Any program that needs to filter / select only certain processes or users have available other functions that can be used: procps_pids_stacks_alloc, fill & dealloc. This implementation attempts to maximize that existing proven libprocps code base. As we gain more experience such actual code can be migrated into the pids.c file. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-08-19 10:30:00 +05:30
/*
library: update those source files for copyright dates In addition to copyright date, the initial descriptive line was changed from a generic statement to one which reflects the specific portion of the proc/ filesystem. [ such descriptions alternate between 'declarations' ] [ (h files) & corresponding 'definitions' (c files). ] Also, a few missing copyright attributions were added. Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-02-05 11:30:00 +05:30
* pids.h - process related declarations for libprocps
library: implement task/thread support via the new api This commit is the culmination of efforts to modernize the library api. It should be treated as a first blush attempt, especially since I have absolutely no library design experience. But I did have a very strong desire to lessen the new library's impact on the top program. Under this new api, a 'stack' is the equivalent of the old proc_t. It can be seen as a variable length record whose contents & order is under complete user control. That initial stack/record configuration is established at procps_pids_new() time and will probably serve most program needs. But, a dynamic & demanding program like top will later change a stack via procps_pids_reset(). For programs like top & ps, procps_pids_reap() will be the function that will retrieve all tasks and threads. Any program that needs to filter / select only certain processes or users have available other functions that can be used: procps_pids_stacks_alloc, fill & dealloc. This implementation attempts to maximize that existing proven libprocps code base. As we gain more experience such actual code can be migrated into the pids.c file. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-08-19 10:30:00 +05:30
*
* Copyright (C) 1998-2005 Albert Cahalan
misc: Update Craig's email
2021-01-21 12:07:48 +05:30
* Copyright (C) 2015 Craig Small <csmall@dropbear.xyz>
misc: amend the man page & source file copyright dates This just updates the copyright dates in the documents where I was already represented. Others are unchanged. Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-01-01 11:30:00 +05:30
* Copyright (C) 2015-2022 Jim Warner <james.warner@comcast.net>
library: implement task/thread support via the new api This commit is the culmination of efforts to modernize the library api. It should be treated as a first blush attempt, especially since I have absolutely no library design experience. But I did have a very strong desire to lessen the new library's impact on the top program. Under this new api, a 'stack' is the equivalent of the old proc_t. It can be seen as a variable length record whose contents & order is under complete user control. That initial stack/record configuration is established at procps_pids_new() time and will probably serve most program needs. But, a dynamic & demanding program like top will later change a stack via procps_pids_reset(). For programs like top & ps, procps_pids_reap() will be the function that will retrieve all tasks and threads. Any program that needs to filter / select only certain processes or users have available other functions that can be used: procps_pids_stacks_alloc, fill & dealloc. This implementation attempts to maximize that existing proven libprocps code base. As we gain more experience such actual code can be migrated into the pids.c file. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-08-19 10:30:00 +05:30
*
* This library 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 library 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
*/
library: strictly cosmetic, absolutely no code changes This commit just contains some tweaks to comments plus a few adjustments to whitespace for alignment purposes and a normalization of the header inclusion #define's. [ plus a spelling error in one header file was fixed ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-09-28 20:40:10 +05:30
#ifndef PROCPS_PIDS_H
#define PROCPS_PIDS_H
library: removed all the 'PROCPS_' enumerator prefixes Many of our item enumerator identifiers are very long, especially in that <VMSTAT> module. Additionally, they all contain the exact same universal 'PROCPS_' prefix. The origins for this are likely found in the desire to avoid name clashes with other potential include files. But with procps-ng newlib, we've probably gone way too far. Did 'PROCPS_PIDS_TICS_SYSTEM' actually offer more protection against clash than 'PIDS_TICS_SYSTEM' does? I don't think so. Besides, no matter how big that name becomes, one can never guarantee they'll never be some clash. And, conversely, extremely short names will not always create conflict. Of course, in either case when some clash occurs, one can always #undef that problem. Thus, this commit will eliminate that 'PROCPS_' prefix making all of those enum identifiers a little shorter. And, we'll still be well above some ridiculously short (criminally short) names found in some common headers: - - - - - - - - - - <term.h> - 'tab', 'TTY', etc - - - - - - - - - - - - - - - - <search.h> - 'ENTER', ENTRY', 'FIND', etc ------------------------------------------------------ Finally, with this as a last of the wholesale changes, we will have established the naming conventions below: . only functions will begin with that 'procps_' prefix . exposed structures begin with the module/header name . item enumerators begin like structs, but capitalized . other enumerators work exactly like item enumerators . macros and constants begin just like the enumerators ------------------------------------------------------ Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-21 10:30:00 +05:30
library: replace the troublesome '__BEGIN_DECLS' macro When 'newlib' was introduced, in the commit referenced below, the use of that glibc '__BEGIN_DECLS' macro was standardized. However, as issue #88 revealed, this may result in a fatal build error with other environments. So, this patch just trades that macro for the standard '#ifdef __cplusplus' conventions (thus avoiding use of all those '#include <features.h>' directives as well). Reference(s): . newlib introduced commit a410e236abb47c7c43194e61d0566686f81513af . procps-ng-3.3.13 issue https://gitlab.com/procps-ng/procps/issues/88 . some additional discussion https://www.freelists.org/post/procps/PATCH-Replace-glibcspecific-macros-in-procnumah,1 . musl wiki (see: sys/cdefs.h error messages) https://wiki.musl-libc.org/faq.html Signed-off-by: Jim Warner <james.warner@comcast.net>
2018-04-06 10:30:00 +05:30
#ifdef __cplusplus
extern "C" {
#endif
library: implement task/thread support via the new api This commit is the culmination of efforts to modernize the library api. It should be treated as a first blush attempt, especially since I have absolutely no library design experience. But I did have a very strong desire to lessen the new library's impact on the top program. Under this new api, a 'stack' is the equivalent of the old proc_t. It can be seen as a variable length record whose contents & order is under complete user control. That initial stack/record configuration is established at procps_pids_new() time and will probably serve most program needs. But, a dynamic & demanding program like top will later change a stack via procps_pids_reset(). For programs like top & ps, procps_pids_reap() will be the function that will retrieve all tasks and threads. Any program that needs to filter / select only certain processes or users have available other functions that can be used: procps_pids_stacks_alloc, fill & dealloc. This implementation attempts to maximize that existing proven libprocps code base. As we gain more experience such actual code can be migrated into the pids.c file. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-08-19 10:30:00 +05:30
enum pids_item {
library: removed all the 'PROCPS_' enumerator prefixes Many of our item enumerator identifiers are very long, especially in that <VMSTAT> module. Additionally, they all contain the exact same universal 'PROCPS_' prefix. The origins for this are likely found in the desire to avoid name clashes with other potential include files. But with procps-ng newlib, we've probably gone way too far. Did 'PROCPS_PIDS_TICS_SYSTEM' actually offer more protection against clash than 'PIDS_TICS_SYSTEM' does? I don't think so. Besides, no matter how big that name becomes, one can never guarantee they'll never be some clash. And, conversely, extremely short names will not always create conflict. Of course, in either case when some clash occurs, one can always #undef that problem. Thus, this commit will eliminate that 'PROCPS_' prefix making all of those enum identifiers a little shorter. And, we'll still be well above some ridiculously short (criminally short) names found in some common headers: - - - - - - - - - - <term.h> - 'tab', 'TTY', etc - - - - - - - - - - - - - - - - <search.h> - 'ENTER', ENTRY', 'FIND', etc ------------------------------------------------------ Finally, with this as a last of the wholesale changes, we will have established the naming conventions below: . only functions will begin with that 'procps_' prefix . exposed structures begin with the module/header name . item enumerators begin like structs, but capitalized . other enumerators work exactly like item enumerators . macros and constants begin just like the enumerators ------------------------------------------------------ Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-21 10:30:00 +05:30
PIDS_noop, // ( never altered )
PIDS_extra, // ( reset to zero )
library: add item origin (as comments) to header files A lack of documentation seems to be the major obstacle to releasing this new library. So, in an effort to get the ball rolling again, this patch adds the origins of each item as a comment to six of the new header files. However, before reviewing how such changes may benefit that documentation objective, it seemed appropriate to first reflect on newlib's background & current status. ___________________________________________ BACKGROUND Discussions about and work on a new library began back in July 2012 but quickly died. After a lull of 2 years those discussions were resumed in August 2014 but soon died also (and no code survived the gitorious demise). With those early discussions, the recommended approach was to encapsulate all of the libprocps data offerings in individual functions. When it came to extensibility it was suggested we should rely on symbols versioning. Unfortunately that approach would have made for a huge Application Programming Interface virtually impossible to master or even document. And, runtime call overhead would have been substantial for ps and especially top. So, an alternative design was sought but there were no new suggestions/contributions via freelists or gitlab. Thus, in spite of a lack of library design experience, the procps-ng team (Craig & Jim) set out to develop an alternative API, more concise and with lower overhead. Reference(s): . 07/01/2012, begin library design discussion https://www.freelists.org/post/procps/Old-library-calls . 08/12/2014, revival of library design discussion https://www.freelists.org/post/procps/libprocs-redesign _____________________________________ DESIGN EVOLUTION Our newlib branch first appeared on June 14, 2015. And our current API actually represents the 4th generation during the past 3 years of evolution. First, there was a basic 'new', 'get' and 'unref' approach, using enums to minimize the proliferation of 'get' function calls. Then, in anticipation of other programs like ps, where multiple fields times multiple processes would greatly increase the number of 'get' function calls, a concept of 'chains' was introduced. This became generation #2. Such 'chains' proved unnecessarily complex so 'stacks' replaced them. This was considered the 3rd generation, but too many implementation details were still exposed requiring those users to 'alloc', 'read', 'fill', etc. Finally, a 4th generation emerged representing several refinements to standardize and minimize those exported functions, thus hiding all implementation details from the users. Lastly, handling of 'errno' was normalized. Reference(s): . 06/14/2015, revival of new API discussion https://www.freelists.org/post/procps/The-library-API-again . 06/24/2015, birth of the newlib branch https://www.freelists.org/post/procps/new-library . 06/29/2015, 2nd generation introduced 'chains' https://www.freelists.org/post/procps/new-library,8 . 07/22/2015, 3rd generation introduced 'stacks' https://www.freelists.org/post/procps/newlib-stacks-vs-chains . 06/18/2016, 4th generation refinements begin https://www.freelists.org/post/procps/newlib-generation-35 . 11/10/2017, 4th generation standardized 'errno' https://www.freelists.org/post/procps/some-more-master-newlib-stuff _______________________________________ CURRENT DESIGN Central to this new design is a simple 'result' struct reflecting an item plus its value (thanks to a union). As a user option, these item structures can be grouped into 'stacks', yielding many results with just 1 call. Such a 'stack' can be seen as a variable length record whose content/order is determined solely by the users. Within that 'result' structure, the union has standard C language types so there is never a doubt how a value should be used in a printf statement. Given that linux requires a least a 32-bit platform the only difference in capacity surrounds 'long' integers. And, where such types might be used, the 32-bit maximums are adequate. The items themselves are simply enumerators defined in the respective header files. A user can name any items of interest then the library magically provides result structure(s). The approach was proven to be extensible without breaking the ABI (in commit referenced below). The 6 major APIs each provide for the following calls: . 'new' ---------> always required as the first call . . 'ref' -------------------------> strictly optional . . 'unref' --------> optional, if ill-behaved program . . 'get' --------------------> retrieve a single item . . 'select' ----------------> retrieve multiple items . And the 'get' and 'select' functions provide for delta results representing the difference between successive get/select calls (or a 'new' then 'get/select' call). For the <diskstats>, <pids>, <slabinfo> & <stat> APIs, where results are unpredictable, a 'reap' function can return multiple result structures for multiple stacks. The <pids> API differs from others in that those items of interest must be provided at 'new' or 'reset' time, a function unique to this API. And the <pids> 'select' function requires PIDs or UIDs which are to be fetched which then operates as a subset of 'reap'. Lastly, the 'get' function is an iterator for successive PIDs/TIDs returning items previously identified via 'new/reset'. To provide assistance to users during development, the special header 'proc/xtra-procps-debug.h' is available to check type usage against library expectations. That check is activated by including this header explicitly or via build using: ./configure '-DXTRA_PROCPS_DEBUG'. Reference(s): . 08/05/2016, type validation introduced https://www.freelists.org/post/procps/newlib-types-validation commit e3270d463de7eebd9f5ae20c85495e3cb5b69a9f . 08/11/2016, extensibility while preserving ABI example https://www.freelists.org/post/procps/new-meminfo-fields commit 09e1886c9e731f8b8c89a55d11f72f53f030b2de _________________________ INITIAL DOCUMENTATION EFFORT The initial attempt, referenced below, dealt primarily with the <pids> interface. Separate man pages for each exported function were created. Plus there was another document describing the items, among other miscellany. Adopting such an approach encounters several problems: 1. In order to use these man pages, users are 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. 2. While we can explain what all of those <pids> items represent, that certainly isn't true for all the APIs. See the gaps in kernel documentation for <meminfo> and complete lack of documentation with that <vmstat> API. 3. Our documentation effort should take pains to avoid unnecessary implementation details. Here's an example: . "The pointer to info will have memory" . "allocated and a structure created." Alternatively, the following conveys user requirements while not offering any internal implementation detail: . "You must provide the address of a NULL" . "info structure pointer." Reference(s): . 01/04/2017, initial documentation offering https://www.freelists.org/post/procps/Using-reap-and-get commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 ___________________ RECOMMENDED DOCUMENTATION APPROACH I recommend that the newlib documentation consist of 3 man pages only. The first would cover the 5 major APIs and their common functions. The second would deal with the <pids> API exclusively, explaining how it differs. Any remaining exported libproc functions which are yet to be included could be represented in a 3rd document. For these new documents the following are are assumed: 1. Since we will not be able to document all items, we shouldn't try to document any items. We should instead rely on proc(5) or Documentation/filesystems/proc.txt. 2. Program development often involves referencing some header file(s). So, make that an absolute requirement. 3. With the addition of item origins, represented with this commit, and considering that 'types' were already present, the header file might be all some users need. 4. And who knows, when a user of our libproc complains about gaps in their documentation, it might prompt the kernel folks to correct those long standing omissions. To summarize, I suggest that we replace that libproc.3 document with a more general one explaining the basics of accessing this new library and the common calls for most of the major interfaces. We can then create a new document (libproc-pids.3?), which explains differences in using the <PIDS> application programming interface. A final document (libproc-misc.3?) covers what's left. Signed-off-by: Jim Warner <james.warner@comcast.net>
2018-12-20 11:30:00 +05:30
// returns origin, see proc(5)
// ------- -------------------
library: fix a few source/origin notations, <pids> api After removing brackets from those 'derived' notations I was surprised to discover that several origin/source comments were wrong. So this patch fixes those errors. [ along the way a couple enumerators were renamed to ] [ better (i hope) reflect what they're representing. ] [ that, in turn, also required a little rearranging. ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_ADDR_CODE_END, // ul_int stat: end_code
PIDS_ADDR_CODE_START, // ul_int stat: start_code
PIDS_ADDR_CURR_EIP, // ul_int stat: eip
PIDS_ADDR_CURR_ESP, // ul_int stat: esp
PIDS_ADDR_STACK_START, // ul_int stat: start_stack
library: add provision for displaying autogroup values In the link referenced below there's an explanation of the linux autogroup feature which has been around ever since linux-2.6.38. With that explanation there's also surprising (maybe shocking) revelations about the nice and renice commands if CONFIG_SCHED_AUTOGROUP was set. When autogroups are active, such programs are rendered mostly useless because the nice value will only affect scheduling priority relative to other processes in the same autogroup. In order to accomplish what we thought of as renice, that nice value in /proc/<pid>/autogroup must be changed. Altering any single member of a group will also affect every other member of that autogroup. So, this commit will set the stage for users of newlib to display autogroup identifiers plus their associated nice values (now that their importance is understood). Reference(s): https://github.com/nlburgin/reallynice Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-08-05 10:30:00 +05:30
PIDS_AUTOGRP_ID, // s_int autogroup
PIDS_AUTOGRP_NICE, // s_int autogroup
library: clean 'derived' origins in header, <pids> api None of the other four new api headers use brackets on derived items. With this patch we normalize the fifth. [ it makes for a cleaner, less confusing, appearance ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_CGNAME, // str derived from CGROUP ':name='
library: add item origin (as comments) to header files A lack of documentation seems to be the major obstacle to releasing this new library. So, in an effort to get the ball rolling again, this patch adds the origins of each item as a comment to six of the new header files. However, before reviewing how such changes may benefit that documentation objective, it seemed appropriate to first reflect on newlib's background & current status. ___________________________________________ BACKGROUND Discussions about and work on a new library began back in July 2012 but quickly died. After a lull of 2 years those discussions were resumed in August 2014 but soon died also (and no code survived the gitorious demise). With those early discussions, the recommended approach was to encapsulate all of the libprocps data offerings in individual functions. When it came to extensibility it was suggested we should rely on symbols versioning. Unfortunately that approach would have made for a huge Application Programming Interface virtually impossible to master or even document. And, runtime call overhead would have been substantial for ps and especially top. So, an alternative design was sought but there were no new suggestions/contributions via freelists or gitlab. Thus, in spite of a lack of library design experience, the procps-ng team (Craig & Jim) set out to develop an alternative API, more concise and with lower overhead. Reference(s): . 07/01/2012, begin library design discussion https://www.freelists.org/post/procps/Old-library-calls . 08/12/2014, revival of library design discussion https://www.freelists.org/post/procps/libprocs-redesign _____________________________________ DESIGN EVOLUTION Our newlib branch first appeared on June 14, 2015. And our current API actually represents the 4th generation during the past 3 years of evolution. First, there was a basic 'new', 'get' and 'unref' approach, using enums to minimize the proliferation of 'get' function calls. Then, in anticipation of other programs like ps, where multiple fields times multiple processes would greatly increase the number of 'get' function calls, a concept of 'chains' was introduced. This became generation #2. Such 'chains' proved unnecessarily complex so 'stacks' replaced them. This was considered the 3rd generation, but too many implementation details were still exposed requiring those users to 'alloc', 'read', 'fill', etc. Finally, a 4th generation emerged representing several refinements to standardize and minimize those exported functions, thus hiding all implementation details from the users. Lastly, handling of 'errno' was normalized. Reference(s): . 06/14/2015, revival of new API discussion https://www.freelists.org/post/procps/The-library-API-again . 06/24/2015, birth of the newlib branch https://www.freelists.org/post/procps/new-library . 06/29/2015, 2nd generation introduced 'chains' https://www.freelists.org/post/procps/new-library,8 . 07/22/2015, 3rd generation introduced 'stacks' https://www.freelists.org/post/procps/newlib-stacks-vs-chains . 06/18/2016, 4th generation refinements begin https://www.freelists.org/post/procps/newlib-generation-35 . 11/10/2017, 4th generation standardized 'errno' https://www.freelists.org/post/procps/some-more-master-newlib-stuff _______________________________________ CURRENT DESIGN Central to this new design is a simple 'result' struct reflecting an item plus its value (thanks to a union). As a user option, these item structures can be grouped into 'stacks', yielding many results with just 1 call. Such a 'stack' can be seen as a variable length record whose content/order is determined solely by the users. Within that 'result' structure, the union has standard C language types so there is never a doubt how a value should be used in a printf statement. Given that linux requires a least a 32-bit platform the only difference in capacity surrounds 'long' integers. And, where such types might be used, the 32-bit maximums are adequate. The items themselves are simply enumerators defined in the respective header files. A user can name any items of interest then the library magically provides result structure(s). The approach was proven to be extensible without breaking the ABI (in commit referenced below). The 6 major APIs each provide for the following calls: . 'new' ---------> always required as the first call . . 'ref' -------------------------> strictly optional . . 'unref' --------> optional, if ill-behaved program . . 'get' --------------------> retrieve a single item . . 'select' ----------------> retrieve multiple items . And the 'get' and 'select' functions provide for delta results representing the difference between successive get/select calls (or a 'new' then 'get/select' call). For the <diskstats>, <pids>, <slabinfo> & <stat> APIs, where results are unpredictable, a 'reap' function can return multiple result structures for multiple stacks. The <pids> API differs from others in that those items of interest must be provided at 'new' or 'reset' time, a function unique to this API. And the <pids> 'select' function requires PIDs or UIDs which are to be fetched which then operates as a subset of 'reap'. Lastly, the 'get' function is an iterator for successive PIDs/TIDs returning items previously identified via 'new/reset'. To provide assistance to users during development, the special header 'proc/xtra-procps-debug.h' is available to check type usage against library expectations. That check is activated by including this header explicitly or via build using: ./configure '-DXTRA_PROCPS_DEBUG'. Reference(s): . 08/05/2016, type validation introduced https://www.freelists.org/post/procps/newlib-types-validation commit e3270d463de7eebd9f5ae20c85495e3cb5b69a9f . 08/11/2016, extensibility while preserving ABI example https://www.freelists.org/post/procps/new-meminfo-fields commit 09e1886c9e731f8b8c89a55d11f72f53f030b2de _________________________ INITIAL DOCUMENTATION EFFORT The initial attempt, referenced below, dealt primarily with the <pids> interface. Separate man pages for each exported function were created. Plus there was another document describing the items, among other miscellany. Adopting such an approach encounters several problems: 1. In order to use these man pages, users are 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. 2. While we can explain what all of those <pids> items represent, that certainly isn't true for all the APIs. See the gaps in kernel documentation for <meminfo> and complete lack of documentation with that <vmstat> API. 3. Our documentation effort should take pains to avoid unnecessary implementation details. Here's an example: . "The pointer to info will have memory" . "allocated and a structure created." Alternatively, the following conveys user requirements while not offering any internal implementation detail: . "You must provide the address of a NULL" . "info structure pointer." Reference(s): . 01/04/2017, initial documentation offering https://www.freelists.org/post/procps/Using-reap-and-get commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 ___________________ RECOMMENDED DOCUMENTATION APPROACH I recommend that the newlib documentation consist of 3 man pages only. The first would cover the 5 major APIs and their common functions. The second would deal with the <pids> API exclusively, explaining how it differs. Any remaining exported libproc functions which are yet to be included could be represented in a 3rd document. For these new documents the following are are assumed: 1. Since we will not be able to document all items, we shouldn't try to document any items. We should instead rely on proc(5) or Documentation/filesystems/proc.txt. 2. Program development often involves referencing some header file(s). So, make that an absolute requirement. 3. With the addition of item origins, represented with this commit, and considering that 'types' were already present, the header file might be all some users need. 4. And who knows, when a user of our libproc complains about gaps in their documentation, it might prompt the kernel folks to correct those long standing omissions. To summarize, I suggest that we replace that libproc.3 document with a more general one explaining the basics of accessing this new library and the common calls for most of the major interfaces. We can then create a new document (libproc-pids.3?), which explains differences in using the <PIDS> application programming interface. A final document (libproc-misc.3?) covers what's left. Signed-off-by: Jim Warner <james.warner@comcast.net>
2018-12-20 11:30:00 +05:30
PIDS_CGROUP, // str cgroup
library: refactored some header file items and origins This commit is intended as a refinement of the patches mentioned below, where origins/sources of newlib items were added to the header files for user documentation. However, if those additions are to be truly effective, along with kernel documentation (where available), the following prerequisites must also have been satisfied: . our identifiers closely align with linux field names . our derived items are documented or self-documenting Satisfying those prerequisites prompted this patch and for these changes, kernel sources were emphasized over available documentation (shame on me, it should always have been so). And, while some 'new' fields were found to be conditional, they were included unconditionally. These changes appear more extensive than they actually need be since I have attempted to enforce some spacing conventions. So, I've summarize the significant things in the sections that follow. For a proper perspective, use: 'git diff --ignore-space-change' (good as alias). ___________________________________________ <PIDS> api This api is unique in that there exists many different file/directory origins subordinate to /proc/<pid>. And our item identifiers are sometimes coerced so as to be able to group related or similar enumerators together. So, users needed more help relating our identifiers to an actual documented field. Thus, we will now also add the field names as with 'stat: delayacct_blkio_ticks'. Each item ending with a '_C' now consistently includes both the parent's count/time plus waited for children. That 'RTPRIO' guy was renamed/relocated as PRIORITY_RT since its original name is an implementation artifact. ___________________________________________ <STAT> api The only api change was to correct a typo ('dervied'). _________________________________________ <VMSTAT> api Even ignoring white space, this interface received the largest number of changes. Mostly, this was because of deficiencies in the proc(5) documentation. Recall that this documentation already sorely lacks any substance. Usually, just kernel releases are noted, not contents. When compared to kernel source, that proc(5) contained many non-existent fields and also omitted many others. ________________________________________ <MEMINFO> api Sadly, with this api many of the changes were simply a correction of some earlier 'human error' where several fields where hashed then tracked but never represented with an item enumerator in this meminfo.h header file. _______________________________________ <SLABINFO> api The 'SLABS' (summary) & 'SLABNODE' items were reversed since the former are derived from the separate caches. More significantly, those 'SLABNODE' guys were renamed to 'SLAB' since they concern individual caches and the concept of 'nodes' is really an implementation detail. Also, several enumerators were changed to more closely agree with official slabinfo(5) documentation referred to in what we're treating as a base document: proc(5). Lastly, while those 'SLABS' items are solely a product of our library and not represented in slabinfo(5), the names attempt to parallel those found as 'SLAB' items. ______________________________________ <DISKSTATS> api One enumeration identifier was changed so as to better reflect its relationship to that actual documentation: 'Documentation/iostats.txt', as referenced in proc(5). Reference(s): . 12/2018, item origins added (and commit msg history) commit 96d59cbf46b3ff687bd29fad4708074a0e1cea14 . 01/2019, <stat> origins tweaked commit 201e816b26ddaccc923ec40977c92037cdd0c34e Signed-off-by: Jim Warner <james.warner@comcast.net>
2019-03-12 11:30:00 +05:30
PIDS_CGROUP_V, // strv cgroup, as *str[]
library: fix some 'origin' header comments, <pids> api Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-04-20 10:30:00 +05:30
PIDS_CMD, // str stat: comm or status: Name
library: add item origin (as comments) to header files A lack of documentation seems to be the major obstacle to releasing this new library. So, in an effort to get the ball rolling again, this patch adds the origins of each item as a comment to six of the new header files. However, before reviewing how such changes may benefit that documentation objective, it seemed appropriate to first reflect on newlib's background & current status. ___________________________________________ BACKGROUND Discussions about and work on a new library began back in July 2012 but quickly died. After a lull of 2 years those discussions were resumed in August 2014 but soon died also (and no code survived the gitorious demise). With those early discussions, the recommended approach was to encapsulate all of the libprocps data offerings in individual functions. When it came to extensibility it was suggested we should rely on symbols versioning. Unfortunately that approach would have made for a huge Application Programming Interface virtually impossible to master or even document. And, runtime call overhead would have been substantial for ps and especially top. So, an alternative design was sought but there were no new suggestions/contributions via freelists or gitlab. Thus, in spite of a lack of library design experience, the procps-ng team (Craig & Jim) set out to develop an alternative API, more concise and with lower overhead. Reference(s): . 07/01/2012, begin library design discussion https://www.freelists.org/post/procps/Old-library-calls . 08/12/2014, revival of library design discussion https://www.freelists.org/post/procps/libprocs-redesign _____________________________________ DESIGN EVOLUTION Our newlib branch first appeared on June 14, 2015. And our current API actually represents the 4th generation during the past 3 years of evolution. First, there was a basic 'new', 'get' and 'unref' approach, using enums to minimize the proliferation of 'get' function calls. Then, in anticipation of other programs like ps, where multiple fields times multiple processes would greatly increase the number of 'get' function calls, a concept of 'chains' was introduced. This became generation #2. Such 'chains' proved unnecessarily complex so 'stacks' replaced them. This was considered the 3rd generation, but too many implementation details were still exposed requiring those users to 'alloc', 'read', 'fill', etc. Finally, a 4th generation emerged representing several refinements to standardize and minimize those exported functions, thus hiding all implementation details from the users. Lastly, handling of 'errno' was normalized. Reference(s): . 06/14/2015, revival of new API discussion https://www.freelists.org/post/procps/The-library-API-again . 06/24/2015, birth of the newlib branch https://www.freelists.org/post/procps/new-library . 06/29/2015, 2nd generation introduced 'chains' https://www.freelists.org/post/procps/new-library,8 . 07/22/2015, 3rd generation introduced 'stacks' https://www.freelists.org/post/procps/newlib-stacks-vs-chains . 06/18/2016, 4th generation refinements begin https://www.freelists.org/post/procps/newlib-generation-35 . 11/10/2017, 4th generation standardized 'errno' https://www.freelists.org/post/procps/some-more-master-newlib-stuff _______________________________________ CURRENT DESIGN Central to this new design is a simple 'result' struct reflecting an item plus its value (thanks to a union). As a user option, these item structures can be grouped into 'stacks', yielding many results with just 1 call. Such a 'stack' can be seen as a variable length record whose content/order is determined solely by the users. Within that 'result' structure, the union has standard C language types so there is never a doubt how a value should be used in a printf statement. Given that linux requires a least a 32-bit platform the only difference in capacity surrounds 'long' integers. And, where such types might be used, the 32-bit maximums are adequate. The items themselves are simply enumerators defined in the respective header files. A user can name any items of interest then the library magically provides result structure(s). The approach was proven to be extensible without breaking the ABI (in commit referenced below). The 6 major APIs each provide for the following calls: . 'new' ---------> always required as the first call . . 'ref' -------------------------> strictly optional . . 'unref' --------> optional, if ill-behaved program . . 'get' --------------------> retrieve a single item . . 'select' ----------------> retrieve multiple items . And the 'get' and 'select' functions provide for delta results representing the difference between successive get/select calls (or a 'new' then 'get/select' call). For the <diskstats>, <pids>, <slabinfo> & <stat> APIs, where results are unpredictable, a 'reap' function can return multiple result structures for multiple stacks. The <pids> API differs from others in that those items of interest must be provided at 'new' or 'reset' time, a function unique to this API. And the <pids> 'select' function requires PIDs or UIDs which are to be fetched which then operates as a subset of 'reap'. Lastly, the 'get' function is an iterator for successive PIDs/TIDs returning items previously identified via 'new/reset'. To provide assistance to users during development, the special header 'proc/xtra-procps-debug.h' is available to check type usage against library expectations. That check is activated by including this header explicitly or via build using: ./configure '-DXTRA_PROCPS_DEBUG'. Reference(s): . 08/05/2016, type validation introduced https://www.freelists.org/post/procps/newlib-types-validation commit e3270d463de7eebd9f5ae20c85495e3cb5b69a9f . 08/11/2016, extensibility while preserving ABI example https://www.freelists.org/post/procps/new-meminfo-fields commit 09e1886c9e731f8b8c89a55d11f72f53f030b2de _________________________ INITIAL DOCUMENTATION EFFORT The initial attempt, referenced below, dealt primarily with the <pids> interface. Separate man pages for each exported function were created. Plus there was another document describing the items, among other miscellany. Adopting such an approach encounters several problems: 1. In order to use these man pages, users are 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. 2. While we can explain what all of those <pids> items represent, that certainly isn't true for all the APIs. See the gaps in kernel documentation for <meminfo> and complete lack of documentation with that <vmstat> API. 3. Our documentation effort should take pains to avoid unnecessary implementation details. Here's an example: . "The pointer to info will have memory" . "allocated and a structure created." Alternatively, the following conveys user requirements while not offering any internal implementation detail: . "You must provide the address of a NULL" . "info structure pointer." Reference(s): . 01/04/2017, initial documentation offering https://www.freelists.org/post/procps/Using-reap-and-get commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 ___________________ RECOMMENDED DOCUMENTATION APPROACH I recommend that the newlib documentation consist of 3 man pages only. The first would cover the 5 major APIs and their common functions. The second would deal with the <pids> API exclusively, explaining how it differs. Any remaining exported libproc functions which are yet to be included could be represented in a 3rd document. For these new documents the following are are assumed: 1. Since we will not be able to document all items, we shouldn't try to document any items. We should instead rely on proc(5) or Documentation/filesystems/proc.txt. 2. Program development often involves referencing some header file(s). So, make that an absolute requirement. 3. With the addition of item origins, represented with this commit, and considering that 'types' were already present, the header file might be all some users need. 4. And who knows, when a user of our libproc complains about gaps in their documentation, it might prompt the kernel folks to correct those long standing omissions. To summarize, I suggest that we replace that libproc.3 document with a more general one explaining the basics of accessing this new library and the common calls for most of the major interfaces. We can then create a new document (libproc-pids.3?), which explains differences in using the <PIDS> application programming interface. A final document (libproc-misc.3?) covers what's left. Signed-off-by: Jim Warner <james.warner@comcast.net>
2018-12-20 11:30:00 +05:30
PIDS_CMDLINE, // str cmdline
library: refactored some header file items and origins This commit is intended as a refinement of the patches mentioned below, where origins/sources of newlib items were added to the header files for user documentation. However, if those additions are to be truly effective, along with kernel documentation (where available), the following prerequisites must also have been satisfied: . our identifiers closely align with linux field names . our derived items are documented or self-documenting Satisfying those prerequisites prompted this patch and for these changes, kernel sources were emphasized over available documentation (shame on me, it should always have been so). And, while some 'new' fields were found to be conditional, they were included unconditionally. These changes appear more extensive than they actually need be since I have attempted to enforce some spacing conventions. So, I've summarize the significant things in the sections that follow. For a proper perspective, use: 'git diff --ignore-space-change' (good as alias). ___________________________________________ <PIDS> api This api is unique in that there exists many different file/directory origins subordinate to /proc/<pid>. And our item identifiers are sometimes coerced so as to be able to group related or similar enumerators together. So, users needed more help relating our identifiers to an actual documented field. Thus, we will now also add the field names as with 'stat: delayacct_blkio_ticks'. Each item ending with a '_C' now consistently includes both the parent's count/time plus waited for children. That 'RTPRIO' guy was renamed/relocated as PRIORITY_RT since its original name is an implementation artifact. ___________________________________________ <STAT> api The only api change was to correct a typo ('dervied'). _________________________________________ <VMSTAT> api Even ignoring white space, this interface received the largest number of changes. Mostly, this was because of deficiencies in the proc(5) documentation. Recall that this documentation already sorely lacks any substance. Usually, just kernel releases are noted, not contents. When compared to kernel source, that proc(5) contained many non-existent fields and also omitted many others. ________________________________________ <MEMINFO> api Sadly, with this api many of the changes were simply a correction of some earlier 'human error' where several fields where hashed then tracked but never represented with an item enumerator in this meminfo.h header file. _______________________________________ <SLABINFO> api The 'SLABS' (summary) & 'SLABNODE' items were reversed since the former are derived from the separate caches. More significantly, those 'SLABNODE' guys were renamed to 'SLAB' since they concern individual caches and the concept of 'nodes' is really an implementation detail. Also, several enumerators were changed to more closely agree with official slabinfo(5) documentation referred to in what we're treating as a base document: proc(5). Lastly, while those 'SLABS' items are solely a product of our library and not represented in slabinfo(5), the names attempt to parallel those found as 'SLAB' items. ______________________________________ <DISKSTATS> api One enumeration identifier was changed so as to better reflect its relationship to that actual documentation: 'Documentation/iostats.txt', as referenced in proc(5). Reference(s): . 12/2018, item origins added (and commit msg history) commit 96d59cbf46b3ff687bd29fad4708074a0e1cea14 . 01/2019, <stat> origins tweaked commit 201e816b26ddaccc923ec40977c92037cdd0c34e Signed-off-by: Jim Warner <james.warner@comcast.net>
2019-03-12 11:30:00 +05:30
PIDS_CMDLINE_V, // strv cmdline, as *str[]
library: add item origin (as comments) to header files A lack of documentation seems to be the major obstacle to releasing this new library. So, in an effort to get the ball rolling again, this patch adds the origins of each item as a comment to six of the new header files. However, before reviewing how such changes may benefit that documentation objective, it seemed appropriate to first reflect on newlib's background & current status. ___________________________________________ BACKGROUND Discussions about and work on a new library began back in July 2012 but quickly died. After a lull of 2 years those discussions were resumed in August 2014 but soon died also (and no code survived the gitorious demise). With those early discussions, the recommended approach was to encapsulate all of the libprocps data offerings in individual functions. When it came to extensibility it was suggested we should rely on symbols versioning. Unfortunately that approach would have made for a huge Application Programming Interface virtually impossible to master or even document. And, runtime call overhead would have been substantial for ps and especially top. So, an alternative design was sought but there were no new suggestions/contributions via freelists or gitlab. Thus, in spite of a lack of library design experience, the procps-ng team (Craig & Jim) set out to develop an alternative API, more concise and with lower overhead. Reference(s): . 07/01/2012, begin library design discussion https://www.freelists.org/post/procps/Old-library-calls . 08/12/2014, revival of library design discussion https://www.freelists.org/post/procps/libprocs-redesign _____________________________________ DESIGN EVOLUTION Our newlib branch first appeared on June 14, 2015. And our current API actually represents the 4th generation during the past 3 years of evolution. First, there was a basic 'new', 'get' and 'unref' approach, using enums to minimize the proliferation of 'get' function calls. Then, in anticipation of other programs like ps, where multiple fields times multiple processes would greatly increase the number of 'get' function calls, a concept of 'chains' was introduced. This became generation #2. Such 'chains' proved unnecessarily complex so 'stacks' replaced them. This was considered the 3rd generation, but too many implementation details were still exposed requiring those users to 'alloc', 'read', 'fill', etc. Finally, a 4th generation emerged representing several refinements to standardize and minimize those exported functions, thus hiding all implementation details from the users. Lastly, handling of 'errno' was normalized. Reference(s): . 06/14/2015, revival of new API discussion https://www.freelists.org/post/procps/The-library-API-again . 06/24/2015, birth of the newlib branch https://www.freelists.org/post/procps/new-library . 06/29/2015, 2nd generation introduced 'chains' https://www.freelists.org/post/procps/new-library,8 . 07/22/2015, 3rd generation introduced 'stacks' https://www.freelists.org/post/procps/newlib-stacks-vs-chains . 06/18/2016, 4th generation refinements begin https://www.freelists.org/post/procps/newlib-generation-35 . 11/10/2017, 4th generation standardized 'errno' https://www.freelists.org/post/procps/some-more-master-newlib-stuff _______________________________________ CURRENT DESIGN Central to this new design is a simple 'result' struct reflecting an item plus its value (thanks to a union). As a user option, these item structures can be grouped into 'stacks', yielding many results with just 1 call. Such a 'stack' can be seen as a variable length record whose content/order is determined solely by the users. Within that 'result' structure, the union has standard C language types so there is never a doubt how a value should be used in a printf statement. Given that linux requires a least a 32-bit platform the only difference in capacity surrounds 'long' integers. And, where such types might be used, the 32-bit maximums are adequate. The items themselves are simply enumerators defined in the respective header files. A user can name any items of interest then the library magically provides result structure(s). The approach was proven to be extensible without breaking the ABI (in commit referenced below). The 6 major APIs each provide for the following calls: . 'new' ---------> always required as the first call . . 'ref' -------------------------> strictly optional . . 'unref' --------> optional, if ill-behaved program . . 'get' --------------------> retrieve a single item . . 'select' ----------------> retrieve multiple items . And the 'get' and 'select' functions provide for delta results representing the difference between successive get/select calls (or a 'new' then 'get/select' call). For the <diskstats>, <pids>, <slabinfo> & <stat> APIs, where results are unpredictable, a 'reap' function can return multiple result structures for multiple stacks. The <pids> API differs from others in that those items of interest must be provided at 'new' or 'reset' time, a function unique to this API. And the <pids> 'select' function requires PIDs or UIDs which are to be fetched which then operates as a subset of 'reap'. Lastly, the 'get' function is an iterator for successive PIDs/TIDs returning items previously identified via 'new/reset'. To provide assistance to users during development, the special header 'proc/xtra-procps-debug.h' is available to check type usage against library expectations. That check is activated by including this header explicitly or via build using: ./configure '-DXTRA_PROCPS_DEBUG'. Reference(s): . 08/05/2016, type validation introduced https://www.freelists.org/post/procps/newlib-types-validation commit e3270d463de7eebd9f5ae20c85495e3cb5b69a9f . 08/11/2016, extensibility while preserving ABI example https://www.freelists.org/post/procps/new-meminfo-fields commit 09e1886c9e731f8b8c89a55d11f72f53f030b2de _________________________ INITIAL DOCUMENTATION EFFORT The initial attempt, referenced below, dealt primarily with the <pids> interface. Separate man pages for each exported function were created. Plus there was another document describing the items, among other miscellany. Adopting such an approach encounters several problems: 1. In order to use these man pages, users are 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. 2. While we can explain what all of those <pids> items represent, that certainly isn't true for all the APIs. See the gaps in kernel documentation for <meminfo> and complete lack of documentation with that <vmstat> API. 3. Our documentation effort should take pains to avoid unnecessary implementation details. Here's an example: . "The pointer to info will have memory" . "allocated and a structure created." Alternatively, the following conveys user requirements while not offering any internal implementation detail: . "You must provide the address of a NULL" . "info structure pointer." Reference(s): . 01/04/2017, initial documentation offering https://www.freelists.org/post/procps/Using-reap-and-get commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 ___________________ RECOMMENDED DOCUMENTATION APPROACH I recommend that the newlib documentation consist of 3 man pages only. The first would cover the 5 major APIs and their common functions. The second would deal with the <pids> API exclusively, explaining how it differs. Any remaining exported libproc functions which are yet to be included could be represented in a 3rd document. For these new documents the following are are assumed: 1. Since we will not be able to document all items, we shouldn't try to document any items. We should instead rely on proc(5) or Documentation/filesystems/proc.txt. 2. Program development often involves referencing some header file(s). So, make that an absolute requirement. 3. With the addition of item origins, represented with this commit, and considering that 'types' were already present, the header file might be all some users need. 4. And who knows, when a user of our libproc complains about gaps in their documentation, it might prompt the kernel folks to correct those long standing omissions. To summarize, I suggest that we replace that libproc.3 document with a more general one explaining the basics of accessing this new library and the common calls for most of the major interfaces. We can then create a new document (libproc-pids.3?), which explains differences in using the <PIDS> application programming interface. A final document (libproc-misc.3?) covers what's left. Signed-off-by: Jim Warner <james.warner@comcast.net>
2018-12-20 11:30:00 +05:30
PIDS_ENVIRON, // str environ
library: refactored some header file items and origins This commit is intended as a refinement of the patches mentioned below, where origins/sources of newlib items were added to the header files for user documentation. However, if those additions are to be truly effective, along with kernel documentation (where available), the following prerequisites must also have been satisfied: . our identifiers closely align with linux field names . our derived items are documented or self-documenting Satisfying those prerequisites prompted this patch and for these changes, kernel sources were emphasized over available documentation (shame on me, it should always have been so). And, while some 'new' fields were found to be conditional, they were included unconditionally. These changes appear more extensive than they actually need be since I have attempted to enforce some spacing conventions. So, I've summarize the significant things in the sections that follow. For a proper perspective, use: 'git diff --ignore-space-change' (good as alias). ___________________________________________ <PIDS> api This api is unique in that there exists many different file/directory origins subordinate to /proc/<pid>. And our item identifiers are sometimes coerced so as to be able to group related or similar enumerators together. So, users needed more help relating our identifiers to an actual documented field. Thus, we will now also add the field names as with 'stat: delayacct_blkio_ticks'. Each item ending with a '_C' now consistently includes both the parent's count/time plus waited for children. That 'RTPRIO' guy was renamed/relocated as PRIORITY_RT since its original name is an implementation artifact. ___________________________________________ <STAT> api The only api change was to correct a typo ('dervied'). _________________________________________ <VMSTAT> api Even ignoring white space, this interface received the largest number of changes. Mostly, this was because of deficiencies in the proc(5) documentation. Recall that this documentation already sorely lacks any substance. Usually, just kernel releases are noted, not contents. When compared to kernel source, that proc(5) contained many non-existent fields and also omitted many others. ________________________________________ <MEMINFO> api Sadly, with this api many of the changes were simply a correction of some earlier 'human error' where several fields where hashed then tracked but never represented with an item enumerator in this meminfo.h header file. _______________________________________ <SLABINFO> api The 'SLABS' (summary) & 'SLABNODE' items were reversed since the former are derived from the separate caches. More significantly, those 'SLABNODE' guys were renamed to 'SLAB' since they concern individual caches and the concept of 'nodes' is really an implementation detail. Also, several enumerators were changed to more closely agree with official slabinfo(5) documentation referred to in what we're treating as a base document: proc(5). Lastly, while those 'SLABS' items are solely a product of our library and not represented in slabinfo(5), the names attempt to parallel those found as 'SLAB' items. ______________________________________ <DISKSTATS> api One enumeration identifier was changed so as to better reflect its relationship to that actual documentation: 'Documentation/iostats.txt', as referenced in proc(5). Reference(s): . 12/2018, item origins added (and commit msg history) commit 96d59cbf46b3ff687bd29fad4708074a0e1cea14 . 01/2019, <stat> origins tweaked commit 201e816b26ddaccc923ec40977c92037cdd0c34e Signed-off-by: Jim Warner <james.warner@comcast.net>
2019-03-12 11:30:00 +05:30
PIDS_ENVIRON_V, // strv environ, as *str[]
library: add item origin (as comments) to header files A lack of documentation seems to be the major obstacle to releasing this new library. So, in an effort to get the ball rolling again, this patch adds the origins of each item as a comment to six of the new header files. However, before reviewing how such changes may benefit that documentation objective, it seemed appropriate to first reflect on newlib's background & current status. ___________________________________________ BACKGROUND Discussions about and work on a new library began back in July 2012 but quickly died. After a lull of 2 years those discussions were resumed in August 2014 but soon died also (and no code survived the gitorious demise). With those early discussions, the recommended approach was to encapsulate all of the libprocps data offerings in individual functions. When it came to extensibility it was suggested we should rely on symbols versioning. Unfortunately that approach would have made for a huge Application Programming Interface virtually impossible to master or even document. And, runtime call overhead would have been substantial for ps and especially top. So, an alternative design was sought but there were no new suggestions/contributions via freelists or gitlab. Thus, in spite of a lack of library design experience, the procps-ng team (Craig & Jim) set out to develop an alternative API, more concise and with lower overhead. Reference(s): . 07/01/2012, begin library design discussion https://www.freelists.org/post/procps/Old-library-calls . 08/12/2014, revival of library design discussion https://www.freelists.org/post/procps/libprocs-redesign _____________________________________ DESIGN EVOLUTION Our newlib branch first appeared on June 14, 2015. And our current API actually represents the 4th generation during the past 3 years of evolution. First, there was a basic 'new', 'get' and 'unref' approach, using enums to minimize the proliferation of 'get' function calls. Then, in anticipation of other programs like ps, where multiple fields times multiple processes would greatly increase the number of 'get' function calls, a concept of 'chains' was introduced. This became generation #2. Such 'chains' proved unnecessarily complex so 'stacks' replaced them. This was considered the 3rd generation, but too many implementation details were still exposed requiring those users to 'alloc', 'read', 'fill', etc. Finally, a 4th generation emerged representing several refinements to standardize and minimize those exported functions, thus hiding all implementation details from the users. Lastly, handling of 'errno' was normalized. Reference(s): . 06/14/2015, revival of new API discussion https://www.freelists.org/post/procps/The-library-API-again . 06/24/2015, birth of the newlib branch https://www.freelists.org/post/procps/new-library . 06/29/2015, 2nd generation introduced 'chains' https://www.freelists.org/post/procps/new-library,8 . 07/22/2015, 3rd generation introduced 'stacks' https://www.freelists.org/post/procps/newlib-stacks-vs-chains . 06/18/2016, 4th generation refinements begin https://www.freelists.org/post/procps/newlib-generation-35 . 11/10/2017, 4th generation standardized 'errno' https://www.freelists.org/post/procps/some-more-master-newlib-stuff _______________________________________ CURRENT DESIGN Central to this new design is a simple 'result' struct reflecting an item plus its value (thanks to a union). As a user option, these item structures can be grouped into 'stacks', yielding many results with just 1 call. Such a 'stack' can be seen as a variable length record whose content/order is determined solely by the users. Within that 'result' structure, the union has standard C language types so there is never a doubt how a value should be used in a printf statement. Given that linux requires a least a 32-bit platform the only difference in capacity surrounds 'long' integers. And, where such types might be used, the 32-bit maximums are adequate. The items themselves are simply enumerators defined in the respective header files. A user can name any items of interest then the library magically provides result structure(s). The approach was proven to be extensible without breaking the ABI (in commit referenced below). The 6 major APIs each provide for the following calls: . 'new' ---------> always required as the first call . . 'ref' -------------------------> strictly optional . . 'unref' --------> optional, if ill-behaved program . . 'get' --------------------> retrieve a single item . . 'select' ----------------> retrieve multiple items . And the 'get' and 'select' functions provide for delta results representing the difference between successive get/select calls (or a 'new' then 'get/select' call). For the <diskstats>, <pids>, <slabinfo> & <stat> APIs, where results are unpredictable, a 'reap' function can return multiple result structures for multiple stacks. The <pids> API differs from others in that those items of interest must be provided at 'new' or 'reset' time, a function unique to this API. And the <pids> 'select' function requires PIDs or UIDs which are to be fetched which then operates as a subset of 'reap'. Lastly, the 'get' function is an iterator for successive PIDs/TIDs returning items previously identified via 'new/reset'. To provide assistance to users during development, the special header 'proc/xtra-procps-debug.h' is available to check type usage against library expectations. That check is activated by including this header explicitly or via build using: ./configure '-DXTRA_PROCPS_DEBUG'. Reference(s): . 08/05/2016, type validation introduced https://www.freelists.org/post/procps/newlib-types-validation commit e3270d463de7eebd9f5ae20c85495e3cb5b69a9f . 08/11/2016, extensibility while preserving ABI example https://www.freelists.org/post/procps/new-meminfo-fields commit 09e1886c9e731f8b8c89a55d11f72f53f030b2de _________________________ INITIAL DOCUMENTATION EFFORT The initial attempt, referenced below, dealt primarily with the <pids> interface. Separate man pages for each exported function were created. Plus there was another document describing the items, among other miscellany. Adopting such an approach encounters several problems: 1. In order to use these man pages, users are 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. 2. While we can explain what all of those <pids> items represent, that certainly isn't true for all the APIs. See the gaps in kernel documentation for <meminfo> and complete lack of documentation with that <vmstat> API. 3. Our documentation effort should take pains to avoid unnecessary implementation details. Here's an example: . "The pointer to info will have memory" . "allocated and a structure created." Alternatively, the following conveys user requirements while not offering any internal implementation detail: . "You must provide the address of a NULL" . "info structure pointer." Reference(s): . 01/04/2017, initial documentation offering https://www.freelists.org/post/procps/Using-reap-and-get commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 ___________________ RECOMMENDED DOCUMENTATION APPROACH I recommend that the newlib documentation consist of 3 man pages only. The first would cover the 5 major APIs and their common functions. The second would deal with the <pids> API exclusively, explaining how it differs. Any remaining exported libproc functions which are yet to be included could be represented in a 3rd document. For these new documents the following are are assumed: 1. Since we will not be able to document all items, we shouldn't try to document any items. We should instead rely on proc(5) or Documentation/filesystems/proc.txt. 2. Program development often involves referencing some header file(s). So, make that an absolute requirement. 3. With the addition of item origins, represented with this commit, and considering that 'types' were already present, the header file might be all some users need. 4. And who knows, when a user of our libproc complains about gaps in their documentation, it might prompt the kernel folks to correct those long standing omissions. To summarize, I suggest that we replace that libproc.3 document with a more general one explaining the basics of accessing this new library and the common calls for most of the major interfaces. We can then create a new document (libproc-pids.3?), which explains differences in using the <PIDS> application programming interface. A final document (libproc-misc.3?) covers what's left. Signed-off-by: Jim Warner <james.warner@comcast.net>
2018-12-20 11:30:00 +05:30
PIDS_EXE, // str exe
library: refactored some header file items and origins This commit is intended as a refinement of the patches mentioned below, where origins/sources of newlib items were added to the header files for user documentation. However, if those additions are to be truly effective, along with kernel documentation (where available), the following prerequisites must also have been satisfied: . our identifiers closely align with linux field names . our derived items are documented or self-documenting Satisfying those prerequisites prompted this patch and for these changes, kernel sources were emphasized over available documentation (shame on me, it should always have been so). And, while some 'new' fields were found to be conditional, they were included unconditionally. These changes appear more extensive than they actually need be since I have attempted to enforce some spacing conventions. So, I've summarize the significant things in the sections that follow. For a proper perspective, use: 'git diff --ignore-space-change' (good as alias). ___________________________________________ <PIDS> api This api is unique in that there exists many different file/directory origins subordinate to /proc/<pid>. And our item identifiers are sometimes coerced so as to be able to group related or similar enumerators together. So, users needed more help relating our identifiers to an actual documented field. Thus, we will now also add the field names as with 'stat: delayacct_blkio_ticks'. Each item ending with a '_C' now consistently includes both the parent's count/time plus waited for children. That 'RTPRIO' guy was renamed/relocated as PRIORITY_RT since its original name is an implementation artifact. ___________________________________________ <STAT> api The only api change was to correct a typo ('dervied'). _________________________________________ <VMSTAT> api Even ignoring white space, this interface received the largest number of changes. Mostly, this was because of deficiencies in the proc(5) documentation. Recall that this documentation already sorely lacks any substance. Usually, just kernel releases are noted, not contents. When compared to kernel source, that proc(5) contained many non-existent fields and also omitted many others. ________________________________________ <MEMINFO> api Sadly, with this api many of the changes were simply a correction of some earlier 'human error' where several fields where hashed then tracked but never represented with an item enumerator in this meminfo.h header file. _______________________________________ <SLABINFO> api The 'SLABS' (summary) & 'SLABNODE' items were reversed since the former are derived from the separate caches. More significantly, those 'SLABNODE' guys were renamed to 'SLAB' since they concern individual caches and the concept of 'nodes' is really an implementation detail. Also, several enumerators were changed to more closely agree with official slabinfo(5) documentation referred to in what we're treating as a base document: proc(5). Lastly, while those 'SLABS' items are solely a product of our library and not represented in slabinfo(5), the names attempt to parallel those found as 'SLAB' items. ______________________________________ <DISKSTATS> api One enumeration identifier was changed so as to better reflect its relationship to that actual documentation: 'Documentation/iostats.txt', as referenced in proc(5). Reference(s): . 12/2018, item origins added (and commit msg history) commit 96d59cbf46b3ff687bd29fad4708074a0e1cea14 . 01/2019, <stat> origins tweaked commit 201e816b26ddaccc923ec40977c92037cdd0c34e Signed-off-by: Jim Warner <james.warner@comcast.net>
2019-03-12 11:30:00 +05:30
PIDS_EXIT_SIGNAL, // s_int stat: exit_signal
PIDS_FLAGS, // ul_int stat: flags
library: fix a few source/origin notations, <pids> api After removing brackets from those 'derived' notations I was surprised to discover that several origin/source comments were wrong. So this patch fixes those errors. [ along the way a couple enumerators were renamed to ] [ better (i hope) reflect what they're representing. ] [ that, in turn, also required a little rearranging. ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_FLT_MAJ, // ul_int stat: maj_flt
library: added important new functionality, <pids> api This commit introduces some new capabilities available in libproc-2 under the <PIDS> interface. Along the way errors impacting some item values have been corrected. The following summarizes the major changes being made. 1. The PIDS_TIME_START item was represented as seconds since system boot but really held tics since boot. And some programs properly divided it by Hertz to actually yield seconds while others acted as if it already was. So, now we have a new PIDS_TICS_BEGAN field and all of the 'TIME' fields properly reflect seconds. With those 'TIME' fields, the type was changed to 'float/real' so one could convert it back to tics without loss of some centiseconds reflected in the Hertz guy (usually 100). 2. The boot_seconds was established in procps_pids_new meaning it was fixed/unchanging. As a result, one item (PIDS_TIME_ELAPSED) was rendered useless. So now, each of the three retrieval functions establishes a current boot_seconds well before the set functions are called. 3. Added a PIDS_UTILIZATION item that will provide the CPU usage over the life of a process, as a percentage. 4. Added PIDS_TIME_ALL_C for symmetry with the similar item called PIDS_TICS_ALL_C (which reflects raw tics). 5. That 'derived from' notation has been added to some additional header items to reflect their true origins. Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-02-25 11:30:00 +05:30
PIDS_FLT_MAJ_C, // ul_int derived from stat: maj_flt + cmaj_flt
library: clean 'derived' origins in header, <pids> api None of the other four new api headers use brackets on derived items. With this patch we normalize the fifth. [ it makes for a cleaner, less confusing, appearance ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_FLT_MAJ_DELTA, // s_int derived from FLT_MAJ
library: fix a few source/origin notations, <pids> api After removing brackets from those 'derived' notations I was surprised to discover that several origin/source comments were wrong. So this patch fixes those errors. [ along the way a couple enumerators were renamed to ] [ better (i hope) reflect what they're representing. ] [ that, in turn, also required a little rearranging. ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_FLT_MIN, // ul_int stat: min_flt
library: fixed some header inconsistencies, <pids> api Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-03-22 10:30:00 +05:30
PIDS_FLT_MIN_C, // ul_int derived from stat: min_flt + cmin_flt
library: clean 'derived' origins in header, <pids> api None of the other four new api headers use brackets on derived items. With this patch we normalize the fifth. [ it makes for a cleaner, less confusing, appearance ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_FLT_MIN_DELTA, // s_int derived from FLT_MIN
library: fix a few source/origin notations, <pids> api After removing brackets from those 'derived' notations I was surprised to discover that several origin/source comments were wrong. So this patch fixes those errors. [ along the way a couple enumerators were renamed to ] [ better (i hope) reflect what they're representing. ] [ that, in turn, also required a little rearranging. ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_ID_EGID, // u_int status: Gid
library: clean 'derived' origins in header, <pids> api None of the other four new api headers use brackets on derived items. With this patch we normalize the fifth. [ it makes for a cleaner, less confusing, appearance ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_ID_EGROUP, // str derived from EGID, see getgrgid(3)
library: refactored some header file items and origins This commit is intended as a refinement of the patches mentioned below, where origins/sources of newlib items were added to the header files for user documentation. However, if those additions are to be truly effective, along with kernel documentation (where available), the following prerequisites must also have been satisfied: . our identifiers closely align with linux field names . our derived items are documented or self-documenting Satisfying those prerequisites prompted this patch and for these changes, kernel sources were emphasized over available documentation (shame on me, it should always have been so). And, while some 'new' fields were found to be conditional, they were included unconditionally. These changes appear more extensive than they actually need be since I have attempted to enforce some spacing conventions. So, I've summarize the significant things in the sections that follow. For a proper perspective, use: 'git diff --ignore-space-change' (good as alias). ___________________________________________ <PIDS> api This api is unique in that there exists many different file/directory origins subordinate to /proc/<pid>. And our item identifiers are sometimes coerced so as to be able to group related or similar enumerators together. So, users needed more help relating our identifiers to an actual documented field. Thus, we will now also add the field names as with 'stat: delayacct_blkio_ticks'. Each item ending with a '_C' now consistently includes both the parent's count/time plus waited for children. That 'RTPRIO' guy was renamed/relocated as PRIORITY_RT since its original name is an implementation artifact. ___________________________________________ <STAT> api The only api change was to correct a typo ('dervied'). _________________________________________ <VMSTAT> api Even ignoring white space, this interface received the largest number of changes. Mostly, this was because of deficiencies in the proc(5) documentation. Recall that this documentation already sorely lacks any substance. Usually, just kernel releases are noted, not contents. When compared to kernel source, that proc(5) contained many non-existent fields and also omitted many others. ________________________________________ <MEMINFO> api Sadly, with this api many of the changes were simply a correction of some earlier 'human error' where several fields where hashed then tracked but never represented with an item enumerator in this meminfo.h header file. _______________________________________ <SLABINFO> api The 'SLABS' (summary) & 'SLABNODE' items were reversed since the former are derived from the separate caches. More significantly, those 'SLABNODE' guys were renamed to 'SLAB' since they concern individual caches and the concept of 'nodes' is really an implementation detail. Also, several enumerators were changed to more closely agree with official slabinfo(5) documentation referred to in what we're treating as a base document: proc(5). Lastly, while those 'SLABS' items are solely a product of our library and not represented in slabinfo(5), the names attempt to parallel those found as 'SLAB' items. ______________________________________ <DISKSTATS> api One enumeration identifier was changed so as to better reflect its relationship to that actual documentation: 'Documentation/iostats.txt', as referenced in proc(5). Reference(s): . 12/2018, item origins added (and commit msg history) commit 96d59cbf46b3ff687bd29fad4708074a0e1cea14 . 01/2019, <stat> origins tweaked commit 201e816b26ddaccc923ec40977c92037cdd0c34e Signed-off-by: Jim Warner <james.warner@comcast.net>
2019-03-12 11:30:00 +05:30
PIDS_ID_EUID, // u_int status: Uid
library: clean 'derived' origins in header, <pids> api None of the other four new api headers use brackets on derived items. With this patch we normalize the fifth. [ it makes for a cleaner, less confusing, appearance ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_ID_EUSER, // str derived from EUID, see getpwuid(3)
library: fix a few source/origin notations, <pids> api After removing brackets from those 'derived' notations I was surprised to discover that several origin/source comments were wrong. So this patch fixes those errors. [ along the way a couple enumerators were renamed to ] [ better (i hope) reflect what they're representing. ] [ that, in turn, also required a little rearranging. ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_ID_FGID, // u_int status: Gid
library: clean 'derived' origins in header, <pids> api None of the other four new api headers use brackets on derived items. With this patch we normalize the fifth. [ it makes for a cleaner, less confusing, appearance ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_ID_FGROUP, // str derived from FGID, see getgrgid(3)
library: refactored some header file items and origins This commit is intended as a refinement of the patches mentioned below, where origins/sources of newlib items were added to the header files for user documentation. However, if those additions are to be truly effective, along with kernel documentation (where available), the following prerequisites must also have been satisfied: . our identifiers closely align with linux field names . our derived items are documented or self-documenting Satisfying those prerequisites prompted this patch and for these changes, kernel sources were emphasized over available documentation (shame on me, it should always have been so). And, while some 'new' fields were found to be conditional, they were included unconditionally. These changes appear more extensive than they actually need be since I have attempted to enforce some spacing conventions. So, I've summarize the significant things in the sections that follow. For a proper perspective, use: 'git diff --ignore-space-change' (good as alias). ___________________________________________ <PIDS> api This api is unique in that there exists many different file/directory origins subordinate to /proc/<pid>. And our item identifiers are sometimes coerced so as to be able to group related or similar enumerators together. So, users needed more help relating our identifiers to an actual documented field. Thus, we will now also add the field names as with 'stat: delayacct_blkio_ticks'. Each item ending with a '_C' now consistently includes both the parent's count/time plus waited for children. That 'RTPRIO' guy was renamed/relocated as PRIORITY_RT since its original name is an implementation artifact. ___________________________________________ <STAT> api The only api change was to correct a typo ('dervied'). _________________________________________ <VMSTAT> api Even ignoring white space, this interface received the largest number of changes. Mostly, this was because of deficiencies in the proc(5) documentation. Recall that this documentation already sorely lacks any substance. Usually, just kernel releases are noted, not contents. When compared to kernel source, that proc(5) contained many non-existent fields and also omitted many others. ________________________________________ <MEMINFO> api Sadly, with this api many of the changes were simply a correction of some earlier 'human error' where several fields where hashed then tracked but never represented with an item enumerator in this meminfo.h header file. _______________________________________ <SLABINFO> api The 'SLABS' (summary) & 'SLABNODE' items were reversed since the former are derived from the separate caches. More significantly, those 'SLABNODE' guys were renamed to 'SLAB' since they concern individual caches and the concept of 'nodes' is really an implementation detail. Also, several enumerators were changed to more closely agree with official slabinfo(5) documentation referred to in what we're treating as a base document: proc(5). Lastly, while those 'SLABS' items are solely a product of our library and not represented in slabinfo(5), the names attempt to parallel those found as 'SLAB' items. ______________________________________ <DISKSTATS> api One enumeration identifier was changed so as to better reflect its relationship to that actual documentation: 'Documentation/iostats.txt', as referenced in proc(5). Reference(s): . 12/2018, item origins added (and commit msg history) commit 96d59cbf46b3ff687bd29fad4708074a0e1cea14 . 01/2019, <stat> origins tweaked commit 201e816b26ddaccc923ec40977c92037cdd0c34e Signed-off-by: Jim Warner <james.warner@comcast.net>
2019-03-12 11:30:00 +05:30
PIDS_ID_FUID, // u_int status: Uid
library: clean 'derived' origins in header, <pids> api None of the other four new api headers use brackets on derived items. With this patch we normalize the fifth. [ it makes for a cleaner, less confusing, appearance ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_ID_FUSER, // str derived from FUID, see getpwuid(3)
library: add item origin (as comments) to header files A lack of documentation seems to be the major obstacle to releasing this new library. So, in an effort to get the ball rolling again, this patch adds the origins of each item as a comment to six of the new header files. However, before reviewing how such changes may benefit that documentation objective, it seemed appropriate to first reflect on newlib's background & current status. ___________________________________________ BACKGROUND Discussions about and work on a new library began back in July 2012 but quickly died. After a lull of 2 years those discussions were resumed in August 2014 but soon died also (and no code survived the gitorious demise). With those early discussions, the recommended approach was to encapsulate all of the libprocps data offerings in individual functions. When it came to extensibility it was suggested we should rely on symbols versioning. Unfortunately that approach would have made for a huge Application Programming Interface virtually impossible to master or even document. And, runtime call overhead would have been substantial for ps and especially top. So, an alternative design was sought but there were no new suggestions/contributions via freelists or gitlab. Thus, in spite of a lack of library design experience, the procps-ng team (Craig & Jim) set out to develop an alternative API, more concise and with lower overhead. Reference(s): . 07/01/2012, begin library design discussion https://www.freelists.org/post/procps/Old-library-calls . 08/12/2014, revival of library design discussion https://www.freelists.org/post/procps/libprocs-redesign _____________________________________ DESIGN EVOLUTION Our newlib branch first appeared on June 14, 2015. And our current API actually represents the 4th generation during the past 3 years of evolution. First, there was a basic 'new', 'get' and 'unref' approach, using enums to minimize the proliferation of 'get' function calls. Then, in anticipation of other programs like ps, where multiple fields times multiple processes would greatly increase the number of 'get' function calls, a concept of 'chains' was introduced. This became generation #2. Such 'chains' proved unnecessarily complex so 'stacks' replaced them. This was considered the 3rd generation, but too many implementation details were still exposed requiring those users to 'alloc', 'read', 'fill', etc. Finally, a 4th generation emerged representing several refinements to standardize and minimize those exported functions, thus hiding all implementation details from the users. Lastly, handling of 'errno' was normalized. Reference(s): . 06/14/2015, revival of new API discussion https://www.freelists.org/post/procps/The-library-API-again . 06/24/2015, birth of the newlib branch https://www.freelists.org/post/procps/new-library . 06/29/2015, 2nd generation introduced 'chains' https://www.freelists.org/post/procps/new-library,8 . 07/22/2015, 3rd generation introduced 'stacks' https://www.freelists.org/post/procps/newlib-stacks-vs-chains . 06/18/2016, 4th generation refinements begin https://www.freelists.org/post/procps/newlib-generation-35 . 11/10/2017, 4th generation standardized 'errno' https://www.freelists.org/post/procps/some-more-master-newlib-stuff _______________________________________ CURRENT DESIGN Central to this new design is a simple 'result' struct reflecting an item plus its value (thanks to a union). As a user option, these item structures can be grouped into 'stacks', yielding many results with just 1 call. Such a 'stack' can be seen as a variable length record whose content/order is determined solely by the users. Within that 'result' structure, the union has standard C language types so there is never a doubt how a value should be used in a printf statement. Given that linux requires a least a 32-bit platform the only difference in capacity surrounds 'long' integers. And, where such types might be used, the 32-bit maximums are adequate. The items themselves are simply enumerators defined in the respective header files. A user can name any items of interest then the library magically provides result structure(s). The approach was proven to be extensible without breaking the ABI (in commit referenced below). The 6 major APIs each provide for the following calls: . 'new' ---------> always required as the first call . . 'ref' -------------------------> strictly optional . . 'unref' --------> optional, if ill-behaved program . . 'get' --------------------> retrieve a single item . . 'select' ----------------> retrieve multiple items . And the 'get' and 'select' functions provide for delta results representing the difference between successive get/select calls (or a 'new' then 'get/select' call). For the <diskstats>, <pids>, <slabinfo> & <stat> APIs, where results are unpredictable, a 'reap' function can return multiple result structures for multiple stacks. The <pids> API differs from others in that those items of interest must be provided at 'new' or 'reset' time, a function unique to this API. And the <pids> 'select' function requires PIDs or UIDs which are to be fetched which then operates as a subset of 'reap'. Lastly, the 'get' function is an iterator for successive PIDs/TIDs returning items previously identified via 'new/reset'. To provide assistance to users during development, the special header 'proc/xtra-procps-debug.h' is available to check type usage against library expectations. That check is activated by including this header explicitly or via build using: ./configure '-DXTRA_PROCPS_DEBUG'. Reference(s): . 08/05/2016, type validation introduced https://www.freelists.org/post/procps/newlib-types-validation commit e3270d463de7eebd9f5ae20c85495e3cb5b69a9f . 08/11/2016, extensibility while preserving ABI example https://www.freelists.org/post/procps/new-meminfo-fields commit 09e1886c9e731f8b8c89a55d11f72f53f030b2de _________________________ INITIAL DOCUMENTATION EFFORT The initial attempt, referenced below, dealt primarily with the <pids> interface. Separate man pages for each exported function were created. Plus there was another document describing the items, among other miscellany. Adopting such an approach encounters several problems: 1. In order to use these man pages, users are 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. 2. While we can explain what all of those <pids> items represent, that certainly isn't true for all the APIs. See the gaps in kernel documentation for <meminfo> and complete lack of documentation with that <vmstat> API. 3. Our documentation effort should take pains to avoid unnecessary implementation details. Here's an example: . "The pointer to info will have memory" . "allocated and a structure created." Alternatively, the following conveys user requirements while not offering any internal implementation detail: . "You must provide the address of a NULL" . "info structure pointer." Reference(s): . 01/04/2017, initial documentation offering https://www.freelists.org/post/procps/Using-reap-and-get commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 ___________________ RECOMMENDED DOCUMENTATION APPROACH I recommend that the newlib documentation consist of 3 man pages only. The first would cover the 5 major APIs and their common functions. The second would deal with the <pids> API exclusively, explaining how it differs. Any remaining exported libproc functions which are yet to be included could be represented in a 3rd document. For these new documents the following are are assumed: 1. Since we will not be able to document all items, we shouldn't try to document any items. We should instead rely on proc(5) or Documentation/filesystems/proc.txt. 2. Program development often involves referencing some header file(s). So, make that an absolute requirement. 3. With the addition of item origins, represented with this commit, and considering that 'types' were already present, the header file might be all some users need. 4. And who knows, when a user of our libproc complains about gaps in their documentation, it might prompt the kernel folks to correct those long standing omissions. To summarize, I suggest that we replace that libproc.3 document with a more general one explaining the basics of accessing this new library and the common calls for most of the major interfaces. We can then create a new document (libproc-pids.3?), which explains differences in using the <PIDS> application programming interface. A final document (libproc-misc.3?) covers what's left. Signed-off-by: Jim Warner <james.warner@comcast.net>
2018-12-20 11:30:00 +05:30
PIDS_ID_LOGIN, // s_int loginuid
library: refactored some header file items and origins This commit is intended as a refinement of the patches mentioned below, where origins/sources of newlib items were added to the header files for user documentation. However, if those additions are to be truly effective, along with kernel documentation (where available), the following prerequisites must also have been satisfied: . our identifiers closely align with linux field names . our derived items are documented or self-documenting Satisfying those prerequisites prompted this patch and for these changes, kernel sources were emphasized over available documentation (shame on me, it should always have been so). And, while some 'new' fields were found to be conditional, they were included unconditionally. These changes appear more extensive than they actually need be since I have attempted to enforce some spacing conventions. So, I've summarize the significant things in the sections that follow. For a proper perspective, use: 'git diff --ignore-space-change' (good as alias). ___________________________________________ <PIDS> api This api is unique in that there exists many different file/directory origins subordinate to /proc/<pid>. And our item identifiers are sometimes coerced so as to be able to group related or similar enumerators together. So, users needed more help relating our identifiers to an actual documented field. Thus, we will now also add the field names as with 'stat: delayacct_blkio_ticks'. Each item ending with a '_C' now consistently includes both the parent's count/time plus waited for children. That 'RTPRIO' guy was renamed/relocated as PRIORITY_RT since its original name is an implementation artifact. ___________________________________________ <STAT> api The only api change was to correct a typo ('dervied'). _________________________________________ <VMSTAT> api Even ignoring white space, this interface received the largest number of changes. Mostly, this was because of deficiencies in the proc(5) documentation. Recall that this documentation already sorely lacks any substance. Usually, just kernel releases are noted, not contents. When compared to kernel source, that proc(5) contained many non-existent fields and also omitted many others. ________________________________________ <MEMINFO> api Sadly, with this api many of the changes were simply a correction of some earlier 'human error' where several fields where hashed then tracked but never represented with an item enumerator in this meminfo.h header file. _______________________________________ <SLABINFO> api The 'SLABS' (summary) & 'SLABNODE' items were reversed since the former are derived from the separate caches. More significantly, those 'SLABNODE' guys were renamed to 'SLAB' since they concern individual caches and the concept of 'nodes' is really an implementation detail. Also, several enumerators were changed to more closely agree with official slabinfo(5) documentation referred to in what we're treating as a base document: proc(5). Lastly, while those 'SLABS' items are solely a product of our library and not represented in slabinfo(5), the names attempt to parallel those found as 'SLAB' items. ______________________________________ <DISKSTATS> api One enumeration identifier was changed so as to better reflect its relationship to that actual documentation: 'Documentation/iostats.txt', as referenced in proc(5). Reference(s): . 12/2018, item origins added (and commit msg history) commit 96d59cbf46b3ff687bd29fad4708074a0e1cea14 . 01/2019, <stat> origins tweaked commit 201e816b26ddaccc923ec40977c92037cdd0c34e Signed-off-by: Jim Warner <james.warner@comcast.net>
2019-03-12 11:30:00 +05:30
PIDS_ID_PGRP, // s_int stat: pgrp
PIDS_ID_PID, // s_int from /proc/<pid>
PIDS_ID_PPID, // s_int stat: ppid or status: PPid
PIDS_ID_RGID, // u_int status: Gid
library: clean 'derived' origins in header, <pids> api None of the other four new api headers use brackets on derived items. With this patch we normalize the fifth. [ it makes for a cleaner, less confusing, appearance ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_ID_RGROUP, // str derived from RGID, see getgrgid(3)
library: fix a few source/origin notations, <pids> api After removing brackets from those 'derived' notations I was surprised to discover that several origin/source comments were wrong. So this patch fixes those errors. [ along the way a couple enumerators were renamed to ] [ better (i hope) reflect what they're representing. ] [ that, in turn, also required a little rearranging. ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_ID_RUID, // u_int status: Uid
library: clean 'derived' origins in header, <pids> api None of the other four new api headers use brackets on derived items. With this patch we normalize the fifth. [ it makes for a cleaner, less confusing, appearance ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_ID_RUSER, // str derived from RUID, see getpwuid(3)
library: fix a few source/origin notations, <pids> api After removing brackets from those 'derived' notations I was surprised to discover that several origin/source comments were wrong. So this patch fixes those errors. [ along the way a couple enumerators were renamed to ] [ better (i hope) reflect what they're representing. ] [ that, in turn, also required a little rearranging. ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_ID_SESSION, // s_int stat: sid
library: refactored some header file items and origins This commit is intended as a refinement of the patches mentioned below, where origins/sources of newlib items were added to the header files for user documentation. However, if those additions are to be truly effective, along with kernel documentation (where available), the following prerequisites must also have been satisfied: . our identifiers closely align with linux field names . our derived items are documented or self-documenting Satisfying those prerequisites prompted this patch and for these changes, kernel sources were emphasized over available documentation (shame on me, it should always have been so). And, while some 'new' fields were found to be conditional, they were included unconditionally. These changes appear more extensive than they actually need be since I have attempted to enforce some spacing conventions. So, I've summarize the significant things in the sections that follow. For a proper perspective, use: 'git diff --ignore-space-change' (good as alias). ___________________________________________ <PIDS> api This api is unique in that there exists many different file/directory origins subordinate to /proc/<pid>. And our item identifiers are sometimes coerced so as to be able to group related or similar enumerators together. So, users needed more help relating our identifiers to an actual documented field. Thus, we will now also add the field names as with 'stat: delayacct_blkio_ticks'. Each item ending with a '_C' now consistently includes both the parent's count/time plus waited for children. That 'RTPRIO' guy was renamed/relocated as PRIORITY_RT since its original name is an implementation artifact. ___________________________________________ <STAT> api The only api change was to correct a typo ('dervied'). _________________________________________ <VMSTAT> api Even ignoring white space, this interface received the largest number of changes. Mostly, this was because of deficiencies in the proc(5) documentation. Recall that this documentation already sorely lacks any substance. Usually, just kernel releases are noted, not contents. When compared to kernel source, that proc(5) contained many non-existent fields and also omitted many others. ________________________________________ <MEMINFO> api Sadly, with this api many of the changes were simply a correction of some earlier 'human error' where several fields where hashed then tracked but never represented with an item enumerator in this meminfo.h header file. _______________________________________ <SLABINFO> api The 'SLABS' (summary) & 'SLABNODE' items were reversed since the former are derived from the separate caches. More significantly, those 'SLABNODE' guys were renamed to 'SLAB' since they concern individual caches and the concept of 'nodes' is really an implementation detail. Also, several enumerators were changed to more closely agree with official slabinfo(5) documentation referred to in what we're treating as a base document: proc(5). Lastly, while those 'SLABS' items are solely a product of our library and not represented in slabinfo(5), the names attempt to parallel those found as 'SLAB' items. ______________________________________ <DISKSTATS> api One enumeration identifier was changed so as to better reflect its relationship to that actual documentation: 'Documentation/iostats.txt', as referenced in proc(5). Reference(s): . 12/2018, item origins added (and commit msg history) commit 96d59cbf46b3ff687bd29fad4708074a0e1cea14 . 01/2019, <stat> origins tweaked commit 201e816b26ddaccc923ec40977c92037cdd0c34e Signed-off-by: Jim Warner <james.warner@comcast.net>
2019-03-12 11:30:00 +05:30
PIDS_ID_SGID, // u_int status: Gid
library: clean 'derived' origins in header, <pids> api None of the other four new api headers use brackets on derived items. With this patch we normalize the fifth. [ it makes for a cleaner, less confusing, appearance ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_ID_SGROUP, // str derived from SGID, see getgrgid(3)
library: fix a few source/origin notations, <pids> api After removing brackets from those 'derived' notations I was surprised to discover that several origin/source comments were wrong. So this patch fixes those errors. [ along the way a couple enumerators were renamed to ] [ better (i hope) reflect what they're representing. ] [ that, in turn, also required a little rearranging. ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_ID_SUID, // u_int status: Uid
library: clean 'derived' origins in header, <pids> api None of the other four new api headers use brackets on derived items. With this patch we normalize the fifth. [ it makes for a cleaner, less confusing, appearance ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_ID_SUSER, // str derived from SUID, see getpwuid(3)
library: refactored some header file items and origins This commit is intended as a refinement of the patches mentioned below, where origins/sources of newlib items were added to the header files for user documentation. However, if those additions are to be truly effective, along with kernel documentation (where available), the following prerequisites must also have been satisfied: . our identifiers closely align with linux field names . our derived items are documented or self-documenting Satisfying those prerequisites prompted this patch and for these changes, kernel sources were emphasized over available documentation (shame on me, it should always have been so). And, while some 'new' fields were found to be conditional, they were included unconditionally. These changes appear more extensive than they actually need be since I have attempted to enforce some spacing conventions. So, I've summarize the significant things in the sections that follow. For a proper perspective, use: 'git diff --ignore-space-change' (good as alias). ___________________________________________ <PIDS> api This api is unique in that there exists many different file/directory origins subordinate to /proc/<pid>. And our item identifiers are sometimes coerced so as to be able to group related or similar enumerators together. So, users needed more help relating our identifiers to an actual documented field. Thus, we will now also add the field names as with 'stat: delayacct_blkio_ticks'. Each item ending with a '_C' now consistently includes both the parent's count/time plus waited for children. That 'RTPRIO' guy was renamed/relocated as PRIORITY_RT since its original name is an implementation artifact. ___________________________________________ <STAT> api The only api change was to correct a typo ('dervied'). _________________________________________ <VMSTAT> api Even ignoring white space, this interface received the largest number of changes. Mostly, this was because of deficiencies in the proc(5) documentation. Recall that this documentation already sorely lacks any substance. Usually, just kernel releases are noted, not contents. When compared to kernel source, that proc(5) contained many non-existent fields and also omitted many others. ________________________________________ <MEMINFO> api Sadly, with this api many of the changes were simply a correction of some earlier 'human error' where several fields where hashed then tracked but never represented with an item enumerator in this meminfo.h header file. _______________________________________ <SLABINFO> api The 'SLABS' (summary) & 'SLABNODE' items were reversed since the former are derived from the separate caches. More significantly, those 'SLABNODE' guys were renamed to 'SLAB' since they concern individual caches and the concept of 'nodes' is really an implementation detail. Also, several enumerators were changed to more closely agree with official slabinfo(5) documentation referred to in what we're treating as a base document: proc(5). Lastly, while those 'SLABS' items are solely a product of our library and not represented in slabinfo(5), the names attempt to parallel those found as 'SLAB' items. ______________________________________ <DISKSTATS> api One enumeration identifier was changed so as to better reflect its relationship to that actual documentation: 'Documentation/iostats.txt', as referenced in proc(5). Reference(s): . 12/2018, item origins added (and commit msg history) commit 96d59cbf46b3ff687bd29fad4708074a0e1cea14 . 01/2019, <stat> origins tweaked commit 201e816b26ddaccc923ec40977c92037cdd0c34e Signed-off-by: Jim Warner <james.warner@comcast.net>
2019-03-12 11:30:00 +05:30
PIDS_ID_TGID, // s_int status: Tgid
PIDS_ID_TID, // s_int from /proc/<pid>/task/<tid>
library: fix a few source/origin notations, <pids> api After removing brackets from those 'derived' notations I was surprised to discover that several origin/source comments were wrong. So this patch fixes those errors. [ along the way a couple enumerators were renamed to ] [ better (i hope) reflect what they're representing. ] [ that, in turn, also required a little rearranging. ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_ID_TPGID, // s_int stat: tty_pgrp
library: correct sources for IO accounting, <pids> api This patch just brings 'PIDS_IO' source into alignment with the names being used in that /proc/<pid>/io file. [ i had my chance to fix them in a whitespace change ] [ made in the patch referenced below, but i blew it! ] Reference(s): commit 2dcbe71f3b8e3586acab0221b2e4c55d10cf8f76 Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-06-20 10:30:00 +05:30
PIDS_IO_READ_BYTES, // ul_int io: read_bytes
PIDS_IO_READ_CHARS, // ul_int io: rchar
PIDS_IO_READ_OPS, // ul_int io: syscr
PIDS_IO_WRITE_BYTES, // ul_int io: write_bytes
PIDS_IO_WRITE_CBYTES, // ul_int io: cancelled_write_bytes
PIDS_IO_WRITE_CHARS, // ul_int io: wchar
PIDS_IO_WRITE_OPS, // ul_int io: syscw
library: clean 'derived' origins in header, <pids> api None of the other four new api headers use brackets on derived items. With this patch we normalize the fifth. [ it makes for a cleaner, less confusing, appearance ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_LXCNAME, // str derived from CGROUP 'lxc.payload'
PIDS_MEM_CODE, // ul_int derived from MEM_CODE_PGS, as KiB
library: fix a few source/origin notations, <pids> api After removing brackets from those 'derived' notations I was surprised to discover that several origin/source comments were wrong. So this patch fixes those errors. [ along the way a couple enumerators were renamed to ] [ better (i hope) reflect what they're representing. ] [ that, in turn, also required a little rearranging. ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_MEM_CODE_PGS, // ul_int statm: trs
library: clean 'derived' origins in header, <pids> api None of the other four new api headers use brackets on derived items. With this patch we normalize the fifth. [ it makes for a cleaner, less confusing, appearance ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_MEM_DATA, // ul_int derived from MEM_DATA_PGS, as KiB
library: fix a few source/origin notations, <pids> api After removing brackets from those 'derived' notations I was surprised to discover that several origin/source comments were wrong. So this patch fixes those errors. [ along the way a couple enumerators were renamed to ] [ better (i hope) reflect what they're representing. ] [ that, in turn, also required a little rearranging. ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_MEM_DATA_PGS, // ul_int statm: drs
library: clean 'derived' origins in header, <pids> api None of the other four new api headers use brackets on derived items. With this patch we normalize the fifth. [ it makes for a cleaner, less confusing, appearance ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_MEM_RES, // ul_int derived from MEM_RES_PGS, as KiB
library: refactored some header file items and origins This commit is intended as a refinement of the patches mentioned below, where origins/sources of newlib items were added to the header files for user documentation. However, if those additions are to be truly effective, along with kernel documentation (where available), the following prerequisites must also have been satisfied: . our identifiers closely align with linux field names . our derived items are documented or self-documenting Satisfying those prerequisites prompted this patch and for these changes, kernel sources were emphasized over available documentation (shame on me, it should always have been so). And, while some 'new' fields were found to be conditional, they were included unconditionally. These changes appear more extensive than they actually need be since I have attempted to enforce some spacing conventions. So, I've summarize the significant things in the sections that follow. For a proper perspective, use: 'git diff --ignore-space-change' (good as alias). ___________________________________________ <PIDS> api This api is unique in that there exists many different file/directory origins subordinate to /proc/<pid>. And our item identifiers are sometimes coerced so as to be able to group related or similar enumerators together. So, users needed more help relating our identifiers to an actual documented field. Thus, we will now also add the field names as with 'stat: delayacct_blkio_ticks'. Each item ending with a '_C' now consistently includes both the parent's count/time plus waited for children. That 'RTPRIO' guy was renamed/relocated as PRIORITY_RT since its original name is an implementation artifact. ___________________________________________ <STAT> api The only api change was to correct a typo ('dervied'). _________________________________________ <VMSTAT> api Even ignoring white space, this interface received the largest number of changes. Mostly, this was because of deficiencies in the proc(5) documentation. Recall that this documentation already sorely lacks any substance. Usually, just kernel releases are noted, not contents. When compared to kernel source, that proc(5) contained many non-existent fields and also omitted many others. ________________________________________ <MEMINFO> api Sadly, with this api many of the changes were simply a correction of some earlier 'human error' where several fields where hashed then tracked but never represented with an item enumerator in this meminfo.h header file. _______________________________________ <SLABINFO> api The 'SLABS' (summary) & 'SLABNODE' items were reversed since the former are derived from the separate caches. More significantly, those 'SLABNODE' guys were renamed to 'SLAB' since they concern individual caches and the concept of 'nodes' is really an implementation detail. Also, several enumerators were changed to more closely agree with official slabinfo(5) documentation referred to in what we're treating as a base document: proc(5). Lastly, while those 'SLABS' items are solely a product of our library and not represented in slabinfo(5), the names attempt to parallel those found as 'SLAB' items. ______________________________________ <DISKSTATS> api One enumeration identifier was changed so as to better reflect its relationship to that actual documentation: 'Documentation/iostats.txt', as referenced in proc(5). Reference(s): . 12/2018, item origins added (and commit msg history) commit 96d59cbf46b3ff687bd29fad4708074a0e1cea14 . 01/2019, <stat> origins tweaked commit 201e816b26ddaccc923ec40977c92037cdd0c34e Signed-off-by: Jim Warner <james.warner@comcast.net>
2019-03-12 11:30:00 +05:30
PIDS_MEM_RES_PGS, // ul_int statm: resident
library: clean 'derived' origins in header, <pids> api None of the other four new api headers use brackets on derived items. With this patch we normalize the fifth. [ it makes for a cleaner, less confusing, appearance ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_MEM_SHR, // ul_int derived from MEM_SHR_PGS, as KiB
library: refactored some header file items and origins This commit is intended as a refinement of the patches mentioned below, where origins/sources of newlib items were added to the header files for user documentation. However, if those additions are to be truly effective, along with kernel documentation (where available), the following prerequisites must also have been satisfied: . our identifiers closely align with linux field names . our derived items are documented or self-documenting Satisfying those prerequisites prompted this patch and for these changes, kernel sources were emphasized over available documentation (shame on me, it should always have been so). And, while some 'new' fields were found to be conditional, they were included unconditionally. These changes appear more extensive than they actually need be since I have attempted to enforce some spacing conventions. So, I've summarize the significant things in the sections that follow. For a proper perspective, use: 'git diff --ignore-space-change' (good as alias). ___________________________________________ <PIDS> api This api is unique in that there exists many different file/directory origins subordinate to /proc/<pid>. And our item identifiers are sometimes coerced so as to be able to group related or similar enumerators together. So, users needed more help relating our identifiers to an actual documented field. Thus, we will now also add the field names as with 'stat: delayacct_blkio_ticks'. Each item ending with a '_C' now consistently includes both the parent's count/time plus waited for children. That 'RTPRIO' guy was renamed/relocated as PRIORITY_RT since its original name is an implementation artifact. ___________________________________________ <STAT> api The only api change was to correct a typo ('dervied'). _________________________________________ <VMSTAT> api Even ignoring white space, this interface received the largest number of changes. Mostly, this was because of deficiencies in the proc(5) documentation. Recall that this documentation already sorely lacks any substance. Usually, just kernel releases are noted, not contents. When compared to kernel source, that proc(5) contained many non-existent fields and also omitted many others. ________________________________________ <MEMINFO> api Sadly, with this api many of the changes were simply a correction of some earlier 'human error' where several fields where hashed then tracked but never represented with an item enumerator in this meminfo.h header file. _______________________________________ <SLABINFO> api The 'SLABS' (summary) & 'SLABNODE' items were reversed since the former are derived from the separate caches. More significantly, those 'SLABNODE' guys were renamed to 'SLAB' since they concern individual caches and the concept of 'nodes' is really an implementation detail. Also, several enumerators were changed to more closely agree with official slabinfo(5) documentation referred to in what we're treating as a base document: proc(5). Lastly, while those 'SLABS' items are solely a product of our library and not represented in slabinfo(5), the names attempt to parallel those found as 'SLAB' items. ______________________________________ <DISKSTATS> api One enumeration identifier was changed so as to better reflect its relationship to that actual documentation: 'Documentation/iostats.txt', as referenced in proc(5). Reference(s): . 12/2018, item origins added (and commit msg history) commit 96d59cbf46b3ff687bd29fad4708074a0e1cea14 . 01/2019, <stat> origins tweaked commit 201e816b26ddaccc923ec40977c92037cdd0c34e Signed-off-by: Jim Warner <james.warner@comcast.net>
2019-03-12 11:30:00 +05:30
PIDS_MEM_SHR_PGS, // ul_int statm: shared
library: clean 'derived' origins in header, <pids> api None of the other four new api headers use brackets on derived items. With this patch we normalize the fifth. [ it makes for a cleaner, less confusing, appearance ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_MEM_VIRT, // ul_int derived from MEM_VIRT_PGS, as KiB
library: refactored some header file items and origins This commit is intended as a refinement of the patches mentioned below, where origins/sources of newlib items were added to the header files for user documentation. However, if those additions are to be truly effective, along with kernel documentation (where available), the following prerequisites must also have been satisfied: . our identifiers closely align with linux field names . our derived items are documented or self-documenting Satisfying those prerequisites prompted this patch and for these changes, kernel sources were emphasized over available documentation (shame on me, it should always have been so). And, while some 'new' fields were found to be conditional, they were included unconditionally. These changes appear more extensive than they actually need be since I have attempted to enforce some spacing conventions. So, I've summarize the significant things in the sections that follow. For a proper perspective, use: 'git diff --ignore-space-change' (good as alias). ___________________________________________ <PIDS> api This api is unique in that there exists many different file/directory origins subordinate to /proc/<pid>. And our item identifiers are sometimes coerced so as to be able to group related or similar enumerators together. So, users needed more help relating our identifiers to an actual documented field. Thus, we will now also add the field names as with 'stat: delayacct_blkio_ticks'. Each item ending with a '_C' now consistently includes both the parent's count/time plus waited for children. That 'RTPRIO' guy was renamed/relocated as PRIORITY_RT since its original name is an implementation artifact. ___________________________________________ <STAT> api The only api change was to correct a typo ('dervied'). _________________________________________ <VMSTAT> api Even ignoring white space, this interface received the largest number of changes. Mostly, this was because of deficiencies in the proc(5) documentation. Recall that this documentation already sorely lacks any substance. Usually, just kernel releases are noted, not contents. When compared to kernel source, that proc(5) contained many non-existent fields and also omitted many others. ________________________________________ <MEMINFO> api Sadly, with this api many of the changes were simply a correction of some earlier 'human error' where several fields where hashed then tracked but never represented with an item enumerator in this meminfo.h header file. _______________________________________ <SLABINFO> api The 'SLABS' (summary) & 'SLABNODE' items were reversed since the former are derived from the separate caches. More significantly, those 'SLABNODE' guys were renamed to 'SLAB' since they concern individual caches and the concept of 'nodes' is really an implementation detail. Also, several enumerators were changed to more closely agree with official slabinfo(5) documentation referred to in what we're treating as a base document: proc(5). Lastly, while those 'SLABS' items are solely a product of our library and not represented in slabinfo(5), the names attempt to parallel those found as 'SLAB' items. ______________________________________ <DISKSTATS> api One enumeration identifier was changed so as to better reflect its relationship to that actual documentation: 'Documentation/iostats.txt', as referenced in proc(5). Reference(s): . 12/2018, item origins added (and commit msg history) commit 96d59cbf46b3ff687bd29fad4708074a0e1cea14 . 01/2019, <stat> origins tweaked commit 201e816b26ddaccc923ec40977c92037cdd0c34e Signed-off-by: Jim Warner <james.warner@comcast.net>
2019-03-12 11:30:00 +05:30
PIDS_MEM_VIRT_PGS, // ul_int statm: size
PIDS_NICE, // s_int stat: nice
PIDS_NLWP, // s_int stat: num_threads or status: Threads
library: bring namespaces up to date with linux kernel Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-05-05 10:30:00 +05:30
PIDS_NS_CGROUP, // ul_int ns/
PIDS_NS_IPC, // ul_int "
library: refactored some header file items and origins This commit is intended as a refinement of the patches mentioned below, where origins/sources of newlib items were added to the header files for user documentation. However, if those additions are to be truly effective, along with kernel documentation (where available), the following prerequisites must also have been satisfied: . our identifiers closely align with linux field names . our derived items are documented or self-documenting Satisfying those prerequisites prompted this patch and for these changes, kernel sources were emphasized over available documentation (shame on me, it should always have been so). And, while some 'new' fields were found to be conditional, they were included unconditionally. These changes appear more extensive than they actually need be since I have attempted to enforce some spacing conventions. So, I've summarize the significant things in the sections that follow. For a proper perspective, use: 'git diff --ignore-space-change' (good as alias). ___________________________________________ <PIDS> api This api is unique in that there exists many different file/directory origins subordinate to /proc/<pid>. And our item identifiers are sometimes coerced so as to be able to group related or similar enumerators together. So, users needed more help relating our identifiers to an actual documented field. Thus, we will now also add the field names as with 'stat: delayacct_blkio_ticks'. Each item ending with a '_C' now consistently includes both the parent's count/time plus waited for children. That 'RTPRIO' guy was renamed/relocated as PRIORITY_RT since its original name is an implementation artifact. ___________________________________________ <STAT> api The only api change was to correct a typo ('dervied'). _________________________________________ <VMSTAT> api Even ignoring white space, this interface received the largest number of changes. Mostly, this was because of deficiencies in the proc(5) documentation. Recall that this documentation already sorely lacks any substance. Usually, just kernel releases are noted, not contents. When compared to kernel source, that proc(5) contained many non-existent fields and also omitted many others. ________________________________________ <MEMINFO> api Sadly, with this api many of the changes were simply a correction of some earlier 'human error' where several fields where hashed then tracked but never represented with an item enumerator in this meminfo.h header file. _______________________________________ <SLABINFO> api The 'SLABS' (summary) & 'SLABNODE' items were reversed since the former are derived from the separate caches. More significantly, those 'SLABNODE' guys were renamed to 'SLAB' since they concern individual caches and the concept of 'nodes' is really an implementation detail. Also, several enumerators were changed to more closely agree with official slabinfo(5) documentation referred to in what we're treating as a base document: proc(5). Lastly, while those 'SLABS' items are solely a product of our library and not represented in slabinfo(5), the names attempt to parallel those found as 'SLAB' items. ______________________________________ <DISKSTATS> api One enumeration identifier was changed so as to better reflect its relationship to that actual documentation: 'Documentation/iostats.txt', as referenced in proc(5). Reference(s): . 12/2018, item origins added (and commit msg history) commit 96d59cbf46b3ff687bd29fad4708074a0e1cea14 . 01/2019, <stat> origins tweaked commit 201e816b26ddaccc923ec40977c92037cdd0c34e Signed-off-by: Jim Warner <james.warner@comcast.net>
2019-03-12 11:30:00 +05:30
PIDS_NS_MNT, // ul_int "
PIDS_NS_NET, // ul_int "
PIDS_NS_PID, // ul_int "
library: bring namespaces up to date with linux kernel Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-05-05 10:30:00 +05:30
PIDS_NS_TIME, // ul_int "
library: refactored some header file items and origins This commit is intended as a refinement of the patches mentioned below, where origins/sources of newlib items were added to the header files for user documentation. However, if those additions are to be truly effective, along with kernel documentation (where available), the following prerequisites must also have been satisfied: . our identifiers closely align with linux field names . our derived items are documented or self-documenting Satisfying those prerequisites prompted this patch and for these changes, kernel sources were emphasized over available documentation (shame on me, it should always have been so). And, while some 'new' fields were found to be conditional, they were included unconditionally. These changes appear more extensive than they actually need be since I have attempted to enforce some spacing conventions. So, I've summarize the significant things in the sections that follow. For a proper perspective, use: 'git diff --ignore-space-change' (good as alias). ___________________________________________ <PIDS> api This api is unique in that there exists many different file/directory origins subordinate to /proc/<pid>. And our item identifiers are sometimes coerced so as to be able to group related or similar enumerators together. So, users needed more help relating our identifiers to an actual documented field. Thus, we will now also add the field names as with 'stat: delayacct_blkio_ticks'. Each item ending with a '_C' now consistently includes both the parent's count/time plus waited for children. That 'RTPRIO' guy was renamed/relocated as PRIORITY_RT since its original name is an implementation artifact. ___________________________________________ <STAT> api The only api change was to correct a typo ('dervied'). _________________________________________ <VMSTAT> api Even ignoring white space, this interface received the largest number of changes. Mostly, this was because of deficiencies in the proc(5) documentation. Recall that this documentation already sorely lacks any substance. Usually, just kernel releases are noted, not contents. When compared to kernel source, that proc(5) contained many non-existent fields and also omitted many others. ________________________________________ <MEMINFO> api Sadly, with this api many of the changes were simply a correction of some earlier 'human error' where several fields where hashed then tracked but never represented with an item enumerator in this meminfo.h header file. _______________________________________ <SLABINFO> api The 'SLABS' (summary) & 'SLABNODE' items were reversed since the former are derived from the separate caches. More significantly, those 'SLABNODE' guys were renamed to 'SLAB' since they concern individual caches and the concept of 'nodes' is really an implementation detail. Also, several enumerators were changed to more closely agree with official slabinfo(5) documentation referred to in what we're treating as a base document: proc(5). Lastly, while those 'SLABS' items are solely a product of our library and not represented in slabinfo(5), the names attempt to parallel those found as 'SLAB' items. ______________________________________ <DISKSTATS> api One enumeration identifier was changed so as to better reflect its relationship to that actual documentation: 'Documentation/iostats.txt', as referenced in proc(5). Reference(s): . 12/2018, item origins added (and commit msg history) commit 96d59cbf46b3ff687bd29fad4708074a0e1cea14 . 01/2019, <stat> origins tweaked commit 201e816b26ddaccc923ec40977c92037cdd0c34e Signed-off-by: Jim Warner <james.warner@comcast.net>
2019-03-12 11:30:00 +05:30
PIDS_NS_USER, // ul_int "
PIDS_NS_UTS, // ul_int "
library: add item origin (as comments) to header files A lack of documentation seems to be the major obstacle to releasing this new library. So, in an effort to get the ball rolling again, this patch adds the origins of each item as a comment to six of the new header files. However, before reviewing how such changes may benefit that documentation objective, it seemed appropriate to first reflect on newlib's background & current status. ___________________________________________ BACKGROUND Discussions about and work on a new library began back in July 2012 but quickly died. After a lull of 2 years those discussions were resumed in August 2014 but soon died also (and no code survived the gitorious demise). With those early discussions, the recommended approach was to encapsulate all of the libprocps data offerings in individual functions. When it came to extensibility it was suggested we should rely on symbols versioning. Unfortunately that approach would have made for a huge Application Programming Interface virtually impossible to master or even document. And, runtime call overhead would have been substantial for ps and especially top. So, an alternative design was sought but there were no new suggestions/contributions via freelists or gitlab. Thus, in spite of a lack of library design experience, the procps-ng team (Craig & Jim) set out to develop an alternative API, more concise and with lower overhead. Reference(s): . 07/01/2012, begin library design discussion https://www.freelists.org/post/procps/Old-library-calls . 08/12/2014, revival of library design discussion https://www.freelists.org/post/procps/libprocs-redesign _____________________________________ DESIGN EVOLUTION Our newlib branch first appeared on June 14, 2015. And our current API actually represents the 4th generation during the past 3 years of evolution. First, there was a basic 'new', 'get' and 'unref' approach, using enums to minimize the proliferation of 'get' function calls. Then, in anticipation of other programs like ps, where multiple fields times multiple processes would greatly increase the number of 'get' function calls, a concept of 'chains' was introduced. This became generation #2. Such 'chains' proved unnecessarily complex so 'stacks' replaced them. This was considered the 3rd generation, but too many implementation details were still exposed requiring those users to 'alloc', 'read', 'fill', etc. Finally, a 4th generation emerged representing several refinements to standardize and minimize those exported functions, thus hiding all implementation details from the users. Lastly, handling of 'errno' was normalized. Reference(s): . 06/14/2015, revival of new API discussion https://www.freelists.org/post/procps/The-library-API-again . 06/24/2015, birth of the newlib branch https://www.freelists.org/post/procps/new-library . 06/29/2015, 2nd generation introduced 'chains' https://www.freelists.org/post/procps/new-library,8 . 07/22/2015, 3rd generation introduced 'stacks' https://www.freelists.org/post/procps/newlib-stacks-vs-chains . 06/18/2016, 4th generation refinements begin https://www.freelists.org/post/procps/newlib-generation-35 . 11/10/2017, 4th generation standardized 'errno' https://www.freelists.org/post/procps/some-more-master-newlib-stuff _______________________________________ CURRENT DESIGN Central to this new design is a simple 'result' struct reflecting an item plus its value (thanks to a union). As a user option, these item structures can be grouped into 'stacks', yielding many results with just 1 call. Such a 'stack' can be seen as a variable length record whose content/order is determined solely by the users. Within that 'result' structure, the union has standard C language types so there is never a doubt how a value should be used in a printf statement. Given that linux requires a least a 32-bit platform the only difference in capacity surrounds 'long' integers. And, where such types might be used, the 32-bit maximums are adequate. The items themselves are simply enumerators defined in the respective header files. A user can name any items of interest then the library magically provides result structure(s). The approach was proven to be extensible without breaking the ABI (in commit referenced below). The 6 major APIs each provide for the following calls: . 'new' ---------> always required as the first call . . 'ref' -------------------------> strictly optional . . 'unref' --------> optional, if ill-behaved program . . 'get' --------------------> retrieve a single item . . 'select' ----------------> retrieve multiple items . And the 'get' and 'select' functions provide for delta results representing the difference between successive get/select calls (or a 'new' then 'get/select' call). For the <diskstats>, <pids>, <slabinfo> & <stat> APIs, where results are unpredictable, a 'reap' function can return multiple result structures for multiple stacks. The <pids> API differs from others in that those items of interest must be provided at 'new' or 'reset' time, a function unique to this API. And the <pids> 'select' function requires PIDs or UIDs which are to be fetched which then operates as a subset of 'reap'. Lastly, the 'get' function is an iterator for successive PIDs/TIDs returning items previously identified via 'new/reset'. To provide assistance to users during development, the special header 'proc/xtra-procps-debug.h' is available to check type usage against library expectations. That check is activated by including this header explicitly or via build using: ./configure '-DXTRA_PROCPS_DEBUG'. Reference(s): . 08/05/2016, type validation introduced https://www.freelists.org/post/procps/newlib-types-validation commit e3270d463de7eebd9f5ae20c85495e3cb5b69a9f . 08/11/2016, extensibility while preserving ABI example https://www.freelists.org/post/procps/new-meminfo-fields commit 09e1886c9e731f8b8c89a55d11f72f53f030b2de _________________________ INITIAL DOCUMENTATION EFFORT The initial attempt, referenced below, dealt primarily with the <pids> interface. Separate man pages for each exported function were created. Plus there was another document describing the items, among other miscellany. Adopting such an approach encounters several problems: 1. In order to use these man pages, users are 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. 2. While we can explain what all of those <pids> items represent, that certainly isn't true for all the APIs. See the gaps in kernel documentation for <meminfo> and complete lack of documentation with that <vmstat> API. 3. Our documentation effort should take pains to avoid unnecessary implementation details. Here's an example: . "The pointer to info will have memory" . "allocated and a structure created." Alternatively, the following conveys user requirements while not offering any internal implementation detail: . "You must provide the address of a NULL" . "info structure pointer." Reference(s): . 01/04/2017, initial documentation offering https://www.freelists.org/post/procps/Using-reap-and-get commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 ___________________ RECOMMENDED DOCUMENTATION APPROACH I recommend that the newlib documentation consist of 3 man pages only. The first would cover the 5 major APIs and their common functions. The second would deal with the <pids> API exclusively, explaining how it differs. Any remaining exported libproc functions which are yet to be included could be represented in a 3rd document. For these new documents the following are are assumed: 1. Since we will not be able to document all items, we shouldn't try to document any items. We should instead rely on proc(5) or Documentation/filesystems/proc.txt. 2. Program development often involves referencing some header file(s). So, make that an absolute requirement. 3. With the addition of item origins, represented with this commit, and considering that 'types' were already present, the header file might be all some users need. 4. And who knows, when a user of our libproc complains about gaps in their documentation, it might prompt the kernel folks to correct those long standing omissions. To summarize, I suggest that we replace that libproc.3 document with a more general one explaining the basics of accessing this new library and the common calls for most of the major interfaces. We can then create a new document (libproc-pids.3?), which explains differences in using the <PIDS> application programming interface. A final document (libproc-misc.3?) covers what's left. Signed-off-by: Jim Warner <james.warner@comcast.net>
2018-12-20 11:30:00 +05:30
PIDS_OOM_ADJ, // s_int oom_score_adj
PIDS_OOM_SCORE, // s_int oom_score
library: refactored some header file items and origins This commit is intended as a refinement of the patches mentioned below, where origins/sources of newlib items were added to the header files for user documentation. However, if those additions are to be truly effective, along with kernel documentation (where available), the following prerequisites must also have been satisfied: . our identifiers closely align with linux field names . our derived items are documented or self-documenting Satisfying those prerequisites prompted this patch and for these changes, kernel sources were emphasized over available documentation (shame on me, it should always have been so). And, while some 'new' fields were found to be conditional, they were included unconditionally. These changes appear more extensive than they actually need be since I have attempted to enforce some spacing conventions. So, I've summarize the significant things in the sections that follow. For a proper perspective, use: 'git diff --ignore-space-change' (good as alias). ___________________________________________ <PIDS> api This api is unique in that there exists many different file/directory origins subordinate to /proc/<pid>. And our item identifiers are sometimes coerced so as to be able to group related or similar enumerators together. So, users needed more help relating our identifiers to an actual documented field. Thus, we will now also add the field names as with 'stat: delayacct_blkio_ticks'. Each item ending with a '_C' now consistently includes both the parent's count/time plus waited for children. That 'RTPRIO' guy was renamed/relocated as PRIORITY_RT since its original name is an implementation artifact. ___________________________________________ <STAT> api The only api change was to correct a typo ('dervied'). _________________________________________ <VMSTAT> api Even ignoring white space, this interface received the largest number of changes. Mostly, this was because of deficiencies in the proc(5) documentation. Recall that this documentation already sorely lacks any substance. Usually, just kernel releases are noted, not contents. When compared to kernel source, that proc(5) contained many non-existent fields and also omitted many others. ________________________________________ <MEMINFO> api Sadly, with this api many of the changes were simply a correction of some earlier 'human error' where several fields where hashed then tracked but never represented with an item enumerator in this meminfo.h header file. _______________________________________ <SLABINFO> api The 'SLABS' (summary) & 'SLABNODE' items were reversed since the former are derived from the separate caches. More significantly, those 'SLABNODE' guys were renamed to 'SLAB' since they concern individual caches and the concept of 'nodes' is really an implementation detail. Also, several enumerators were changed to more closely agree with official slabinfo(5) documentation referred to in what we're treating as a base document: proc(5). Lastly, while those 'SLABS' items are solely a product of our library and not represented in slabinfo(5), the names attempt to parallel those found as 'SLAB' items. ______________________________________ <DISKSTATS> api One enumeration identifier was changed so as to better reflect its relationship to that actual documentation: 'Documentation/iostats.txt', as referenced in proc(5). Reference(s): . 12/2018, item origins added (and commit msg history) commit 96d59cbf46b3ff687bd29fad4708074a0e1cea14 . 01/2019, <stat> origins tweaked commit 201e816b26ddaccc923ec40977c92037cdd0c34e Signed-off-by: Jim Warner <james.warner@comcast.net>
2019-03-12 11:30:00 +05:30
PIDS_PRIORITY, // s_int stat: priority
PIDS_PRIORITY_RT, // s_int stat: rt_priority
library: change 'PIDS_PROCESSOR' into a signed integer This change is really being made on behalf of the ps & top programs. Besides, over 2 billion CPUs are plenty! Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-12-14 11:30:00 +05:30
PIDS_PROCESSOR, // s_int stat: task_cpu
library: clean 'derived' origins in header, <pids> api None of the other four new api headers use brackets on derived items. With this patch we normalize the fifth. [ it makes for a cleaner, less confusing, appearance ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_PROCESSOR_NODE, // s_int derived from PROCESSOR, see numa(3)
library: refactored some header file items and origins This commit is intended as a refinement of the patches mentioned below, where origins/sources of newlib items were added to the header files for user documentation. However, if those additions are to be truly effective, along with kernel documentation (where available), the following prerequisites must also have been satisfied: . our identifiers closely align with linux field names . our derived items are documented or self-documenting Satisfying those prerequisites prompted this patch and for these changes, kernel sources were emphasized over available documentation (shame on me, it should always have been so). And, while some 'new' fields were found to be conditional, they were included unconditionally. These changes appear more extensive than they actually need be since I have attempted to enforce some spacing conventions. So, I've summarize the significant things in the sections that follow. For a proper perspective, use: 'git diff --ignore-space-change' (good as alias). ___________________________________________ <PIDS> api This api is unique in that there exists many different file/directory origins subordinate to /proc/<pid>. And our item identifiers are sometimes coerced so as to be able to group related or similar enumerators together. So, users needed more help relating our identifiers to an actual documented field. Thus, we will now also add the field names as with 'stat: delayacct_blkio_ticks'. Each item ending with a '_C' now consistently includes both the parent's count/time plus waited for children. That 'RTPRIO' guy was renamed/relocated as PRIORITY_RT since its original name is an implementation artifact. ___________________________________________ <STAT> api The only api change was to correct a typo ('dervied'). _________________________________________ <VMSTAT> api Even ignoring white space, this interface received the largest number of changes. Mostly, this was because of deficiencies in the proc(5) documentation. Recall that this documentation already sorely lacks any substance. Usually, just kernel releases are noted, not contents. When compared to kernel source, that proc(5) contained many non-existent fields and also omitted many others. ________________________________________ <MEMINFO> api Sadly, with this api many of the changes were simply a correction of some earlier 'human error' where several fields where hashed then tracked but never represented with an item enumerator in this meminfo.h header file. _______________________________________ <SLABINFO> api The 'SLABS' (summary) & 'SLABNODE' items were reversed since the former are derived from the separate caches. More significantly, those 'SLABNODE' guys were renamed to 'SLAB' since they concern individual caches and the concept of 'nodes' is really an implementation detail. Also, several enumerators were changed to more closely agree with official slabinfo(5) documentation referred to in what we're treating as a base document: proc(5). Lastly, while those 'SLABS' items are solely a product of our library and not represented in slabinfo(5), the names attempt to parallel those found as 'SLAB' items. ______________________________________ <DISKSTATS> api One enumeration identifier was changed so as to better reflect its relationship to that actual documentation: 'Documentation/iostats.txt', as referenced in proc(5). Reference(s): . 12/2018, item origins added (and commit msg history) commit 96d59cbf46b3ff687bd29fad4708074a0e1cea14 . 01/2019, <stat> origins tweaked commit 201e816b26ddaccc923ec40977c92037cdd0c34e Signed-off-by: Jim Warner <james.warner@comcast.net>
2019-03-12 11:30:00 +05:30
PIDS_RSS, // ul_int stat: rss
PIDS_RSS_RLIM, // ul_int stat: rsslim
PIDS_SCHED_CLASS, // s_int stat: policy
library: clean 'derived' origins in header, <pids> api None of the other four new api headers use brackets on derived items. With this patch we normalize the fifth. [ it makes for a cleaner, less confusing, appearance ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_SD_MACH, // str derived from PID/TID, see sd-login(3)
library: add item origin (as comments) to header files A lack of documentation seems to be the major obstacle to releasing this new library. So, in an effort to get the ball rolling again, this patch adds the origins of each item as a comment to six of the new header files. However, before reviewing how such changes may benefit that documentation objective, it seemed appropriate to first reflect on newlib's background & current status. ___________________________________________ BACKGROUND Discussions about and work on a new library began back in July 2012 but quickly died. After a lull of 2 years those discussions were resumed in August 2014 but soon died also (and no code survived the gitorious demise). With those early discussions, the recommended approach was to encapsulate all of the libprocps data offerings in individual functions. When it came to extensibility it was suggested we should rely on symbols versioning. Unfortunately that approach would have made for a huge Application Programming Interface virtually impossible to master or even document. And, runtime call overhead would have been substantial for ps and especially top. So, an alternative design was sought but there were no new suggestions/contributions via freelists or gitlab. Thus, in spite of a lack of library design experience, the procps-ng team (Craig & Jim) set out to develop an alternative API, more concise and with lower overhead. Reference(s): . 07/01/2012, begin library design discussion https://www.freelists.org/post/procps/Old-library-calls . 08/12/2014, revival of library design discussion https://www.freelists.org/post/procps/libprocs-redesign _____________________________________ DESIGN EVOLUTION Our newlib branch first appeared on June 14, 2015. And our current API actually represents the 4th generation during the past 3 years of evolution. First, there was a basic 'new', 'get' and 'unref' approach, using enums to minimize the proliferation of 'get' function calls. Then, in anticipation of other programs like ps, where multiple fields times multiple processes would greatly increase the number of 'get' function calls, a concept of 'chains' was introduced. This became generation #2. Such 'chains' proved unnecessarily complex so 'stacks' replaced them. This was considered the 3rd generation, but too many implementation details were still exposed requiring those users to 'alloc', 'read', 'fill', etc. Finally, a 4th generation emerged representing several refinements to standardize and minimize those exported functions, thus hiding all implementation details from the users. Lastly, handling of 'errno' was normalized. Reference(s): . 06/14/2015, revival of new API discussion https://www.freelists.org/post/procps/The-library-API-again . 06/24/2015, birth of the newlib branch https://www.freelists.org/post/procps/new-library . 06/29/2015, 2nd generation introduced 'chains' https://www.freelists.org/post/procps/new-library,8 . 07/22/2015, 3rd generation introduced 'stacks' https://www.freelists.org/post/procps/newlib-stacks-vs-chains . 06/18/2016, 4th generation refinements begin https://www.freelists.org/post/procps/newlib-generation-35 . 11/10/2017, 4th generation standardized 'errno' https://www.freelists.org/post/procps/some-more-master-newlib-stuff _______________________________________ CURRENT DESIGN Central to this new design is a simple 'result' struct reflecting an item plus its value (thanks to a union). As a user option, these item structures can be grouped into 'stacks', yielding many results with just 1 call. Such a 'stack' can be seen as a variable length record whose content/order is determined solely by the users. Within that 'result' structure, the union has standard C language types so there is never a doubt how a value should be used in a printf statement. Given that linux requires a least a 32-bit platform the only difference in capacity surrounds 'long' integers. And, where such types might be used, the 32-bit maximums are adequate. The items themselves are simply enumerators defined in the respective header files. A user can name any items of interest then the library magically provides result structure(s). The approach was proven to be extensible without breaking the ABI (in commit referenced below). The 6 major APIs each provide for the following calls: . 'new' ---------> always required as the first call . . 'ref' -------------------------> strictly optional . . 'unref' --------> optional, if ill-behaved program . . 'get' --------------------> retrieve a single item . . 'select' ----------------> retrieve multiple items . And the 'get' and 'select' functions provide for delta results representing the difference between successive get/select calls (or a 'new' then 'get/select' call). For the <diskstats>, <pids>, <slabinfo> & <stat> APIs, where results are unpredictable, a 'reap' function can return multiple result structures for multiple stacks. The <pids> API differs from others in that those items of interest must be provided at 'new' or 'reset' time, a function unique to this API. And the <pids> 'select' function requires PIDs or UIDs which are to be fetched which then operates as a subset of 'reap'. Lastly, the 'get' function is an iterator for successive PIDs/TIDs returning items previously identified via 'new/reset'. To provide assistance to users during development, the special header 'proc/xtra-procps-debug.h' is available to check type usage against library expectations. That check is activated by including this header explicitly or via build using: ./configure '-DXTRA_PROCPS_DEBUG'. Reference(s): . 08/05/2016, type validation introduced https://www.freelists.org/post/procps/newlib-types-validation commit e3270d463de7eebd9f5ae20c85495e3cb5b69a9f . 08/11/2016, extensibility while preserving ABI example https://www.freelists.org/post/procps/new-meminfo-fields commit 09e1886c9e731f8b8c89a55d11f72f53f030b2de _________________________ INITIAL DOCUMENTATION EFFORT The initial attempt, referenced below, dealt primarily with the <pids> interface. Separate man pages for each exported function were created. Plus there was another document describing the items, among other miscellany. Adopting such an approach encounters several problems: 1. In order to use these man pages, users are 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. 2. While we can explain what all of those <pids> items represent, that certainly isn't true for all the APIs. See the gaps in kernel documentation for <meminfo> and complete lack of documentation with that <vmstat> API. 3. Our documentation effort should take pains to avoid unnecessary implementation details. Here's an example: . "The pointer to info will have memory" . "allocated and a structure created." Alternatively, the following conveys user requirements while not offering any internal implementation detail: . "You must provide the address of a NULL" . "info structure pointer." Reference(s): . 01/04/2017, initial documentation offering https://www.freelists.org/post/procps/Using-reap-and-get commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 ___________________ RECOMMENDED DOCUMENTATION APPROACH I recommend that the newlib documentation consist of 3 man pages only. The first would cover the 5 major APIs and their common functions. The second would deal with the <pids> API exclusively, explaining how it differs. Any remaining exported libproc functions which are yet to be included could be represented in a 3rd document. For these new documents the following are are assumed: 1. Since we will not be able to document all items, we shouldn't try to document any items. We should instead rely on proc(5) or Documentation/filesystems/proc.txt. 2. Program development often involves referencing some header file(s). So, make that an absolute requirement. 3. With the addition of item origins, represented with this commit, and considering that 'types' were already present, the header file might be all some users need. 4. And who knows, when a user of our libproc complains about gaps in their documentation, it might prompt the kernel folks to correct those long standing omissions. To summarize, I suggest that we replace that libproc.3 document with a more general one explaining the basics of accessing this new library and the common calls for most of the major interfaces. We can then create a new document (libproc-pids.3?), which explains differences in using the <PIDS> application programming interface. A final document (libproc-misc.3?) covers what's left. Signed-off-by: Jim Warner <james.warner@comcast.net>
2018-12-20 11:30:00 +05:30
PIDS_SD_OUID, // str "
PIDS_SD_SEAT, // str "
PIDS_SD_SESS, // str "
PIDS_SD_SLICE, // str "
PIDS_SD_UNIT, // str "
PIDS_SD_UUNIT, // str "
library: refactored some header file items and origins This commit is intended as a refinement of the patches mentioned below, where origins/sources of newlib items were added to the header files for user documentation. However, if those additions are to be truly effective, along with kernel documentation (where available), the following prerequisites must also have been satisfied: . our identifiers closely align with linux field names . our derived items are documented or self-documenting Satisfying those prerequisites prompted this patch and for these changes, kernel sources were emphasized over available documentation (shame on me, it should always have been so). And, while some 'new' fields were found to be conditional, they were included unconditionally. These changes appear more extensive than they actually need be since I have attempted to enforce some spacing conventions. So, I've summarize the significant things in the sections that follow. For a proper perspective, use: 'git diff --ignore-space-change' (good as alias). ___________________________________________ <PIDS> api This api is unique in that there exists many different file/directory origins subordinate to /proc/<pid>. And our item identifiers are sometimes coerced so as to be able to group related or similar enumerators together. So, users needed more help relating our identifiers to an actual documented field. Thus, we will now also add the field names as with 'stat: delayacct_blkio_ticks'. Each item ending with a '_C' now consistently includes both the parent's count/time plus waited for children. That 'RTPRIO' guy was renamed/relocated as PRIORITY_RT since its original name is an implementation artifact. ___________________________________________ <STAT> api The only api change was to correct a typo ('dervied'). _________________________________________ <VMSTAT> api Even ignoring white space, this interface received the largest number of changes. Mostly, this was because of deficiencies in the proc(5) documentation. Recall that this documentation already sorely lacks any substance. Usually, just kernel releases are noted, not contents. When compared to kernel source, that proc(5) contained many non-existent fields and also omitted many others. ________________________________________ <MEMINFO> api Sadly, with this api many of the changes were simply a correction of some earlier 'human error' where several fields where hashed then tracked but never represented with an item enumerator in this meminfo.h header file. _______________________________________ <SLABINFO> api The 'SLABS' (summary) & 'SLABNODE' items were reversed since the former are derived from the separate caches. More significantly, those 'SLABNODE' guys were renamed to 'SLAB' since they concern individual caches and the concept of 'nodes' is really an implementation detail. Also, several enumerators were changed to more closely agree with official slabinfo(5) documentation referred to in what we're treating as a base document: proc(5). Lastly, while those 'SLABS' items are solely a product of our library and not represented in slabinfo(5), the names attempt to parallel those found as 'SLAB' items. ______________________________________ <DISKSTATS> api One enumeration identifier was changed so as to better reflect its relationship to that actual documentation: 'Documentation/iostats.txt', as referenced in proc(5). Reference(s): . 12/2018, item origins added (and commit msg history) commit 96d59cbf46b3ff687bd29fad4708074a0e1cea14 . 01/2019, <stat> origins tweaked commit 201e816b26ddaccc923ec40977c92037cdd0c34e Signed-off-by: Jim Warner <james.warner@comcast.net>
2019-03-12 11:30:00 +05:30
PIDS_SIGBLOCKED, // str status: SigBlk
PIDS_SIGCATCH, // str status: SigCgt
PIDS_SIGIGNORE, // str status: SigIgn
PIDS_SIGNALS, // str status: ShdPnd
PIDS_SIGPENDING, // str status: SigPnd
library: add support for smaps_rollup file, <pids> api A couple of people have suggested that smaps_rollup be added to the ps program and/or top program. This patch is intended to set the stage for just such extensions. There are currently 20 displayable items in the rollup file. And newlib sometimes uses sscanf when populating the target, sometimes hsearch and one customized gperf approach. None of these fit well with the smaps items. Thus, an approach using a simple table lookup was used and, by disabling 1 code line, it could be made immune from changes to the items order (unlike a sscanf call) and doesn't carry the greater cost of a hsearch/gperf. Note: The next patch will allow top to display some of these new fields. Then, it'll be possible to determine the colossal costs of accessing the smaps_rollup file. Here is a small preview of just what you will discover when using the command 'time top/top -d0 -n1000' while configured with just two fields: PID + 1 memory field. ------------------------------------ as a regular user with only PID + RES (statm) real 0m2.605s user 0m1.060s sys 0m1.377s with only PID + RSS (smaps) real 0m26.397s 10x more costly user 0m1.253s sys 0m24.915s ----------------- as a root (thus smaps for all tasks) with only PID + RES (statm) real 0m2.651s user 0m1.177s sys 0m1.286s with only PID + RSS (smaps) real 0m33.040s 12x more costly user 0m1.256s sys 0m31.533s Reference(s): . ps: expose shared/private memory separately https://gitlab.com/procps-ng/procps/-/issues/201 . top/ps: add support for PSS reporting https://gitlab.com/procps-ng/procps/-/issues/112 Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-04-26 10:30:00 +05:30
PIDS_SMAP_ANONYMOUS, // ul_int smaps_rollup: Anonymous
PIDS_SMAP_HUGE_ANON, // ul_int smaps_rollup: AnonHugePages
PIDS_SMAP_HUGE_FILE, // ul_int smaps_rollup: FilePmdMapped
PIDS_SMAP_HUGE_SHMEM, // ul_int smaps_rollup: ShmemPmdMapped
library: rename/reposition two enumerators, <pids> api The two special hugetlbfs items were misnamed. The TBL reference (table) should be TLB (transaction lookaside buffer). Besides, I never liked their position anyway! [ and one macro argument tweak is being snuck in too ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-04-30 10:30:00 +05:30
PIDS_SMAP_HUGE_TLBPRV, // ul_int smaps_rollup: Private_Hugetlb
PIDS_SMAP_HUGE_TLBSHR, // ul_int smaps_rollup: Shared_Hugetlb
library: add support for smaps_rollup file, <pids> api A couple of people have suggested that smaps_rollup be added to the ps program and/or top program. This patch is intended to set the stage for just such extensions. There are currently 20 displayable items in the rollup file. And newlib sometimes uses sscanf when populating the target, sometimes hsearch and one customized gperf approach. None of these fit well with the smaps items. Thus, an approach using a simple table lookup was used and, by disabling 1 code line, it could be made immune from changes to the items order (unlike a sscanf call) and doesn't carry the greater cost of a hsearch/gperf. Note: The next patch will allow top to display some of these new fields. Then, it'll be possible to determine the colossal costs of accessing the smaps_rollup file. Here is a small preview of just what you will discover when using the command 'time top/top -d0 -n1000' while configured with just two fields: PID + 1 memory field. ------------------------------------ as a regular user with only PID + RES (statm) real 0m2.605s user 0m1.060s sys 0m1.377s with only PID + RSS (smaps) real 0m26.397s 10x more costly user 0m1.253s sys 0m24.915s ----------------- as a root (thus smaps for all tasks) with only PID + RES (statm) real 0m2.651s user 0m1.177s sys 0m1.286s with only PID + RSS (smaps) real 0m33.040s 12x more costly user 0m1.256s sys 0m31.533s Reference(s): . ps: expose shared/private memory separately https://gitlab.com/procps-ng/procps/-/issues/201 . top/ps: add support for PSS reporting https://gitlab.com/procps-ng/procps/-/issues/112 Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-04-26 10:30:00 +05:30
PIDS_SMAP_LAZY_FREE, // ul_int smaps_rollup: LazyFree
PIDS_SMAP_LOCKED, // ul_int smaps_rollup: Locked
PIDS_SMAP_PRV_CLEAN, // ul_int smaps_rollup: Private_Clean
PIDS_SMAP_PRV_DIRTY, // ul_int smaps_rollup: Private_Dirty
library: add new derived smaps_rollup item, <pids> api That recent addition of USS to the ps program prompted this change. Rather than have it (and soon top) add 2 separate items to yield the desired value, we will let our new library perform the arithmetic when necessary. Outside of a little extra storage, there is no runtime costs for such an extension. There is, however, a real benefit to having such code in the library. Now should callers choose to sort on this new field, results will be guaranteed to be what was expected (i.e. accurate). Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-06-16 10:30:00 +05:30
PIDS_SMAP_PRV_TOTAL, // ul_int derived from SMAP_PRV_CLEAN + SMAP_PRV_DIRTY
library: add support for smaps_rollup file, <pids> api A couple of people have suggested that smaps_rollup be added to the ps program and/or top program. This patch is intended to set the stage for just such extensions. There are currently 20 displayable items in the rollup file. And newlib sometimes uses sscanf when populating the target, sometimes hsearch and one customized gperf approach. None of these fit well with the smaps items. Thus, an approach using a simple table lookup was used and, by disabling 1 code line, it could be made immune from changes to the items order (unlike a sscanf call) and doesn't carry the greater cost of a hsearch/gperf. Note: The next patch will allow top to display some of these new fields. Then, it'll be possible to determine the colossal costs of accessing the smaps_rollup file. Here is a small preview of just what you will discover when using the command 'time top/top -d0 -n1000' while configured with just two fields: PID + 1 memory field. ------------------------------------ as a regular user with only PID + RES (statm) real 0m2.605s user 0m1.060s sys 0m1.377s with only PID + RSS (smaps) real 0m26.397s 10x more costly user 0m1.253s sys 0m24.915s ----------------- as a root (thus smaps for all tasks) with only PID + RES (statm) real 0m2.651s user 0m1.177s sys 0m1.286s with only PID + RSS (smaps) real 0m33.040s 12x more costly user 0m1.256s sys 0m31.533s Reference(s): . ps: expose shared/private memory separately https://gitlab.com/procps-ng/procps/-/issues/201 . top/ps: add support for PSS reporting https://gitlab.com/procps-ng/procps/-/issues/112 Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-04-26 10:30:00 +05:30
PIDS_SMAP_PSS, // ul_int smaps_rollup: Pss
PIDS_SMAP_PSS_ANON, // ul_int smaps_rollup: Pss_Anon
PIDS_SMAP_PSS_FILE, // ul_int smaps_rollup: Pss_File
PIDS_SMAP_PSS_SHMEM, // ul_int smaps_rollup: Pss_Shmem
PIDS_SMAP_REFERENCED, // ul_int smaps_rollup: Referenced
PIDS_SMAP_RSS, // ul_int smaps_rollup: Rss
PIDS_SMAP_SHR_CLEAN, // ul_int smaps_rollup: Shared_Clean
PIDS_SMAP_SHR_DIRTY, // ul_int smaps_rollup: Shared_Dirty
PIDS_SMAP_SWAP, // ul_int smaps_rollup: Swap
PIDS_SMAP_SWAP_PSS, // ul_int smaps_rollup: SwapPss
library: refactored some header file items and origins This commit is intended as a refinement of the patches mentioned below, where origins/sources of newlib items were added to the header files for user documentation. However, if those additions are to be truly effective, along with kernel documentation (where available), the following prerequisites must also have been satisfied: . our identifiers closely align with linux field names . our derived items are documented or self-documenting Satisfying those prerequisites prompted this patch and for these changes, kernel sources were emphasized over available documentation (shame on me, it should always have been so). And, while some 'new' fields were found to be conditional, they were included unconditionally. These changes appear more extensive than they actually need be since I have attempted to enforce some spacing conventions. So, I've summarize the significant things in the sections that follow. For a proper perspective, use: 'git diff --ignore-space-change' (good as alias). ___________________________________________ <PIDS> api This api is unique in that there exists many different file/directory origins subordinate to /proc/<pid>. And our item identifiers are sometimes coerced so as to be able to group related or similar enumerators together. So, users needed more help relating our identifiers to an actual documented field. Thus, we will now also add the field names as with 'stat: delayacct_blkio_ticks'. Each item ending with a '_C' now consistently includes both the parent's count/time plus waited for children. That 'RTPRIO' guy was renamed/relocated as PRIORITY_RT since its original name is an implementation artifact. ___________________________________________ <STAT> api The only api change was to correct a typo ('dervied'). _________________________________________ <VMSTAT> api Even ignoring white space, this interface received the largest number of changes. Mostly, this was because of deficiencies in the proc(5) documentation. Recall that this documentation already sorely lacks any substance. Usually, just kernel releases are noted, not contents. When compared to kernel source, that proc(5) contained many non-existent fields and also omitted many others. ________________________________________ <MEMINFO> api Sadly, with this api many of the changes were simply a correction of some earlier 'human error' where several fields where hashed then tracked but never represented with an item enumerator in this meminfo.h header file. _______________________________________ <SLABINFO> api The 'SLABS' (summary) & 'SLABNODE' items were reversed since the former are derived from the separate caches. More significantly, those 'SLABNODE' guys were renamed to 'SLAB' since they concern individual caches and the concept of 'nodes' is really an implementation detail. Also, several enumerators were changed to more closely agree with official slabinfo(5) documentation referred to in what we're treating as a base document: proc(5). Lastly, while those 'SLABS' items are solely a product of our library and not represented in slabinfo(5), the names attempt to parallel those found as 'SLAB' items. ______________________________________ <DISKSTATS> api One enumeration identifier was changed so as to better reflect its relationship to that actual documentation: 'Documentation/iostats.txt', as referenced in proc(5). Reference(s): . 12/2018, item origins added (and commit msg history) commit 96d59cbf46b3ff687bd29fad4708074a0e1cea14 . 01/2019, <stat> origins tweaked commit 201e816b26ddaccc923ec40977c92037cdd0c34e Signed-off-by: Jim Warner <james.warner@comcast.net>
2019-03-12 11:30:00 +05:30
PIDS_STATE, // s_ch stat: state or status: State
PIDS_SUPGIDS, // str status: Groups
library: clean 'derived' origins in header, <pids> api None of the other four new api headers use brackets on derived items. With this patch we normalize the fifth. [ it makes for a cleaner, less confusing, appearance ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_SUPGROUPS, // str derived from SUPGIDS, see getgrgid(3)
library: fixed some header inconsistencies, <pids> api Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-03-22 10:30:00 +05:30
PIDS_TICS_ALL, // ull_int derived from stat: stime + utime
PIDS_TICS_ALL_C, // ull_int derived from stat: stime + utime + cstime + cutime
library: lessen chance of distortion on TICS_ALL_DELTA That old library defined this field as 'unsigned int'. However, here it was known as a 'signed int'. Thus for consistency we'll now also treat it as 'unsigned int'. [ this commit was made in pursuit of a bug involving ] [ the distortion of elapsed task tics. but, it turns ] [ out these changes had nothing to do with that bug. ] [ however, the patch is being retained as desirable. ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-04-21 10:30:00 +05:30
PIDS_TICS_ALL_DELTA, // u_int derived from TICS_ALL
library: added important new functionality, <pids> api This commit introduces some new capabilities available in libproc-2 under the <PIDS> interface. Along the way errors impacting some item values have been corrected. The following summarizes the major changes being made. 1. The PIDS_TIME_START item was represented as seconds since system boot but really held tics since boot. And some programs properly divided it by Hertz to actually yield seconds while others acted as if it already was. So, now we have a new PIDS_TICS_BEGAN field and all of the 'TIME' fields properly reflect seconds. With those 'TIME' fields, the type was changed to 'float/real' so one could convert it back to tics without loss of some centiseconds reflected in the Hertz guy (usually 100). 2. The boot_seconds was established in procps_pids_new meaning it was fixed/unchanging. As a result, one item (PIDS_TIME_ELAPSED) was rendered useless. So now, each of the three retrieval functions establishes a current boot_seconds well before the set functions are called. 3. Added a PIDS_UTILIZATION item that will provide the CPU usage over the life of a process, as a percentage. 4. Added PIDS_TIME_ALL_C for symmetry with the similar item called PIDS_TICS_ALL_C (which reflects raw tics). 5. That 'derived from' notation has been added to some additional header items to reflect their true origins. Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-02-25 11:30:00 +05:30
PIDS_TICS_BEGAN, // ull_int stat: start_time
library: fix a few source/origin notations, <pids> api After removing brackets from those 'derived' notations I was surprised to discover that several origin/source comments were wrong. So this patch fixes those errors. [ along the way a couple enumerators were renamed to ] [ better (i hope) reflect what they're representing. ] [ that, in turn, also required a little rearranging. ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_TICS_BLKIO, // ull_int stat: blkio_ticks
PIDS_TICS_GUEST, // ull_int stat: gtime
library: added important new functionality, <pids> api This commit introduces some new capabilities available in libproc-2 under the <PIDS> interface. Along the way errors impacting some item values have been corrected. The following summarizes the major changes being made. 1. The PIDS_TIME_START item was represented as seconds since system boot but really held tics since boot. And some programs properly divided it by Hertz to actually yield seconds while others acted as if it already was. So, now we have a new PIDS_TICS_BEGAN field and all of the 'TIME' fields properly reflect seconds. With those 'TIME' fields, the type was changed to 'float/real' so one could convert it back to tics without loss of some centiseconds reflected in the Hertz guy (usually 100). 2. The boot_seconds was established in procps_pids_new meaning it was fixed/unchanging. As a result, one item (PIDS_TIME_ELAPSED) was rendered useless. So now, each of the three retrieval functions establishes a current boot_seconds well before the set functions are called. 3. Added a PIDS_UTILIZATION item that will provide the CPU usage over the life of a process, as a percentage. 4. Added PIDS_TIME_ALL_C for symmetry with the similar item called PIDS_TICS_ALL_C (which reflects raw tics). 5. That 'derived from' notation has been added to some additional header items to reflect their true origins. Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-02-25 11:30:00 +05:30
PIDS_TICS_GUEST_C, // ull_int derived from stat: gtime + cgtime
library: refactored some header file items and origins This commit is intended as a refinement of the patches mentioned below, where origins/sources of newlib items were added to the header files for user documentation. However, if those additions are to be truly effective, along with kernel documentation (where available), the following prerequisites must also have been satisfied: . our identifiers closely align with linux field names . our derived items are documented or self-documenting Satisfying those prerequisites prompted this patch and for these changes, kernel sources were emphasized over available documentation (shame on me, it should always have been so). And, while some 'new' fields were found to be conditional, they were included unconditionally. These changes appear more extensive than they actually need be since I have attempted to enforce some spacing conventions. So, I've summarize the significant things in the sections that follow. For a proper perspective, use: 'git diff --ignore-space-change' (good as alias). ___________________________________________ <PIDS> api This api is unique in that there exists many different file/directory origins subordinate to /proc/<pid>. And our item identifiers are sometimes coerced so as to be able to group related or similar enumerators together. So, users needed more help relating our identifiers to an actual documented field. Thus, we will now also add the field names as with 'stat: delayacct_blkio_ticks'. Each item ending with a '_C' now consistently includes both the parent's count/time plus waited for children. That 'RTPRIO' guy was renamed/relocated as PRIORITY_RT since its original name is an implementation artifact. ___________________________________________ <STAT> api The only api change was to correct a typo ('dervied'). _________________________________________ <VMSTAT> api Even ignoring white space, this interface received the largest number of changes. Mostly, this was because of deficiencies in the proc(5) documentation. Recall that this documentation already sorely lacks any substance. Usually, just kernel releases are noted, not contents. When compared to kernel source, that proc(5) contained many non-existent fields and also omitted many others. ________________________________________ <MEMINFO> api Sadly, with this api many of the changes were simply a correction of some earlier 'human error' where several fields where hashed then tracked but never represented with an item enumerator in this meminfo.h header file. _______________________________________ <SLABINFO> api The 'SLABS' (summary) & 'SLABNODE' items were reversed since the former are derived from the separate caches. More significantly, those 'SLABNODE' guys were renamed to 'SLAB' since they concern individual caches and the concept of 'nodes' is really an implementation detail. Also, several enumerators were changed to more closely agree with official slabinfo(5) documentation referred to in what we're treating as a base document: proc(5). Lastly, while those 'SLABS' items are solely a product of our library and not represented in slabinfo(5), the names attempt to parallel those found as 'SLAB' items. ______________________________________ <DISKSTATS> api One enumeration identifier was changed so as to better reflect its relationship to that actual documentation: 'Documentation/iostats.txt', as referenced in proc(5). Reference(s): . 12/2018, item origins added (and commit msg history) commit 96d59cbf46b3ff687bd29fad4708074a0e1cea14 . 01/2019, <stat> origins tweaked commit 201e816b26ddaccc923ec40977c92037cdd0c34e Signed-off-by: Jim Warner <james.warner@comcast.net>
2019-03-12 11:30:00 +05:30
PIDS_TICS_SYSTEM, // ull_int stat: stime
library: added important new functionality, <pids> api This commit introduces some new capabilities available in libproc-2 under the <PIDS> interface. Along the way errors impacting some item values have been corrected. The following summarizes the major changes being made. 1. The PIDS_TIME_START item was represented as seconds since system boot but really held tics since boot. And some programs properly divided it by Hertz to actually yield seconds while others acted as if it already was. So, now we have a new PIDS_TICS_BEGAN field and all of the 'TIME' fields properly reflect seconds. With those 'TIME' fields, the type was changed to 'float/real' so one could convert it back to tics without loss of some centiseconds reflected in the Hertz guy (usually 100). 2. The boot_seconds was established in procps_pids_new meaning it was fixed/unchanging. As a result, one item (PIDS_TIME_ELAPSED) was rendered useless. So now, each of the three retrieval functions establishes a current boot_seconds well before the set functions are called. 3. Added a PIDS_UTILIZATION item that will provide the CPU usage over the life of a process, as a percentage. 4. Added PIDS_TIME_ALL_C for symmetry with the similar item called PIDS_TICS_ALL_C (which reflects raw tics). 5. That 'derived from' notation has been added to some additional header items to reflect their true origins. Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-02-25 11:30:00 +05:30
PIDS_TICS_SYSTEM_C, // ull_int derived from stat: stime + cstime
library: refactored some header file items and origins This commit is intended as a refinement of the patches mentioned below, where origins/sources of newlib items were added to the header files for user documentation. However, if those additions are to be truly effective, along with kernel documentation (where available), the following prerequisites must also have been satisfied: . our identifiers closely align with linux field names . our derived items are documented or self-documenting Satisfying those prerequisites prompted this patch and for these changes, kernel sources were emphasized over available documentation (shame on me, it should always have been so). And, while some 'new' fields were found to be conditional, they were included unconditionally. These changes appear more extensive than they actually need be since I have attempted to enforce some spacing conventions. So, I've summarize the significant things in the sections that follow. For a proper perspective, use: 'git diff --ignore-space-change' (good as alias). ___________________________________________ <PIDS> api This api is unique in that there exists many different file/directory origins subordinate to /proc/<pid>. And our item identifiers are sometimes coerced so as to be able to group related or similar enumerators together. So, users needed more help relating our identifiers to an actual documented field. Thus, we will now also add the field names as with 'stat: delayacct_blkio_ticks'. Each item ending with a '_C' now consistently includes both the parent's count/time plus waited for children. That 'RTPRIO' guy was renamed/relocated as PRIORITY_RT since its original name is an implementation artifact. ___________________________________________ <STAT> api The only api change was to correct a typo ('dervied'). _________________________________________ <VMSTAT> api Even ignoring white space, this interface received the largest number of changes. Mostly, this was because of deficiencies in the proc(5) documentation. Recall that this documentation already sorely lacks any substance. Usually, just kernel releases are noted, not contents. When compared to kernel source, that proc(5) contained many non-existent fields and also omitted many others. ________________________________________ <MEMINFO> api Sadly, with this api many of the changes were simply a correction of some earlier 'human error' where several fields where hashed then tracked but never represented with an item enumerator in this meminfo.h header file. _______________________________________ <SLABINFO> api The 'SLABS' (summary) & 'SLABNODE' items were reversed since the former are derived from the separate caches. More significantly, those 'SLABNODE' guys were renamed to 'SLAB' since they concern individual caches and the concept of 'nodes' is really an implementation detail. Also, several enumerators were changed to more closely agree with official slabinfo(5) documentation referred to in what we're treating as a base document: proc(5). Lastly, while those 'SLABS' items are solely a product of our library and not represented in slabinfo(5), the names attempt to parallel those found as 'SLAB' items. ______________________________________ <DISKSTATS> api One enumeration identifier was changed so as to better reflect its relationship to that actual documentation: 'Documentation/iostats.txt', as referenced in proc(5). Reference(s): . 12/2018, item origins added (and commit msg history) commit 96d59cbf46b3ff687bd29fad4708074a0e1cea14 . 01/2019, <stat> origins tweaked commit 201e816b26ddaccc923ec40977c92037cdd0c34e Signed-off-by: Jim Warner <james.warner@comcast.net>
2019-03-12 11:30:00 +05:30
PIDS_TICS_USER, // ull_int stat: utime
library: added important new functionality, <pids> api This commit introduces some new capabilities available in libproc-2 under the <PIDS> interface. Along the way errors impacting some item values have been corrected. The following summarizes the major changes being made. 1. The PIDS_TIME_START item was represented as seconds since system boot but really held tics since boot. And some programs properly divided it by Hertz to actually yield seconds while others acted as if it already was. So, now we have a new PIDS_TICS_BEGAN field and all of the 'TIME' fields properly reflect seconds. With those 'TIME' fields, the type was changed to 'float/real' so one could convert it back to tics without loss of some centiseconds reflected in the Hertz guy (usually 100). 2. The boot_seconds was established in procps_pids_new meaning it was fixed/unchanging. As a result, one item (PIDS_TIME_ELAPSED) was rendered useless. So now, each of the three retrieval functions establishes a current boot_seconds well before the set functions are called. 3. Added a PIDS_UTILIZATION item that will provide the CPU usage over the life of a process, as a percentage. 4. Added PIDS_TIME_ALL_C for symmetry with the similar item called PIDS_TICS_ALL_C (which reflects raw tics). 5. That 'derived from' notation has been added to some additional header items to reflect their true origins. Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-02-25 11:30:00 +05:30
PIDS_TICS_USER_C, // ull_int derived from stat: utime + cutime
library: annotate header with tics/jiffies, <pids> api To avoid potential user confusion, like that reflected in the previous commit message, a short narrative will be included in the header file as programmer comments, Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-04-15 10:30:00 +05:30
PIDS_TIME_ALL, // real * derived from stat: (utime + stime) / hertz
PIDS_TIME_ALL_C, // real * derived from stat: (utime + stime + cutime + cstime) / hertz
library: fix some 'origin' header comments, <pids> api Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-04-20 10:30:00 +05:30
PIDS_TIME_ELAPSED, // real * derived from stat: (/proc/uptime - start_time) / hertz
library: annotate header with tics/jiffies, <pids> api To avoid potential user confusion, like that reflected in the previous commit message, a short narrative will be included in the header file as programmer comments, Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-04-15 10:30:00 +05:30
PIDS_TIME_START, // real * derived from stat: start_time / hertz
library: refactored some header file items and origins This commit is intended as a refinement of the patches mentioned below, where origins/sources of newlib items were added to the header files for user documentation. However, if those additions are to be truly effective, along with kernel documentation (where available), the following prerequisites must also have been satisfied: . our identifiers closely align with linux field names . our derived items are documented or self-documenting Satisfying those prerequisites prompted this patch and for these changes, kernel sources were emphasized over available documentation (shame on me, it should always have been so). And, while some 'new' fields were found to be conditional, they were included unconditionally. These changes appear more extensive than they actually need be since I have attempted to enforce some spacing conventions. So, I've summarize the significant things in the sections that follow. For a proper perspective, use: 'git diff --ignore-space-change' (good as alias). ___________________________________________ <PIDS> api This api is unique in that there exists many different file/directory origins subordinate to /proc/<pid>. And our item identifiers are sometimes coerced so as to be able to group related or similar enumerators together. So, users needed more help relating our identifiers to an actual documented field. Thus, we will now also add the field names as with 'stat: delayacct_blkio_ticks'. Each item ending with a '_C' now consistently includes both the parent's count/time plus waited for children. That 'RTPRIO' guy was renamed/relocated as PRIORITY_RT since its original name is an implementation artifact. ___________________________________________ <STAT> api The only api change was to correct a typo ('dervied'). _________________________________________ <VMSTAT> api Even ignoring white space, this interface received the largest number of changes. Mostly, this was because of deficiencies in the proc(5) documentation. Recall that this documentation already sorely lacks any substance. Usually, just kernel releases are noted, not contents. When compared to kernel source, that proc(5) contained many non-existent fields and also omitted many others. ________________________________________ <MEMINFO> api Sadly, with this api many of the changes were simply a correction of some earlier 'human error' where several fields where hashed then tracked but never represented with an item enumerator in this meminfo.h header file. _______________________________________ <SLABINFO> api The 'SLABS' (summary) & 'SLABNODE' items were reversed since the former are derived from the separate caches. More significantly, those 'SLABNODE' guys were renamed to 'SLAB' since they concern individual caches and the concept of 'nodes' is really an implementation detail. Also, several enumerators were changed to more closely agree with official slabinfo(5) documentation referred to in what we're treating as a base document: proc(5). Lastly, while those 'SLABS' items are solely a product of our library and not represented in slabinfo(5), the names attempt to parallel those found as 'SLAB' items. ______________________________________ <DISKSTATS> api One enumeration identifier was changed so as to better reflect its relationship to that actual documentation: 'Documentation/iostats.txt', as referenced in proc(5). Reference(s): . 12/2018, item origins added (and commit msg history) commit 96d59cbf46b3ff687bd29fad4708074a0e1cea14 . 01/2019, <stat> origins tweaked commit 201e816b26ddaccc923ec40977c92037cdd0c34e Signed-off-by: Jim Warner <james.warner@comcast.net>
2019-03-12 11:30:00 +05:30
PIDS_TTY, // s_int stat: tty_nr
library: clean 'derived' origins in header, <pids> api None of the other four new api headers use brackets on derived items. With this patch we normalize the fifth. [ it makes for a cleaner, less confusing, appearance ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-03-09 11:30:00 +05:30
PIDS_TTY_NAME, // str derived from TTY
PIDS_TTY_NUMBER, // str derived from TTY as str
library: added important new functionality, <pids> api This commit introduces some new capabilities available in libproc-2 under the <PIDS> interface. Along the way errors impacting some item values have been corrected. The following summarizes the major changes being made. 1. The PIDS_TIME_START item was represented as seconds since system boot but really held tics since boot. And some programs properly divided it by Hertz to actually yield seconds while others acted as if it already was. So, now we have a new PIDS_TICS_BEGAN field and all of the 'TIME' fields properly reflect seconds. With those 'TIME' fields, the type was changed to 'float/real' so one could convert it back to tics without loss of some centiseconds reflected in the Hertz guy (usually 100). 2. The boot_seconds was established in procps_pids_new meaning it was fixed/unchanging. As a result, one item (PIDS_TIME_ELAPSED) was rendered useless. So now, each of the three retrieval functions establishes a current boot_seconds well before the set functions are called. 3. Added a PIDS_UTILIZATION item that will provide the CPU usage over the life of a process, as a percentage. 4. Added PIDS_TIME_ALL_C for symmetry with the similar item called PIDS_TICS_ALL_C (which reflects raw tics). 5. That 'derived from' notation has been added to some additional header items to reflect their true origins. Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-02-25 11:30:00 +05:30
PIDS_UTILIZATION, // real derived from TIME_ALL / TIME_ELAPSED, as percentage
library: introduced a 'UTILIZATION_C' item, <pids> api Some items in the <pids> API carry a '_C' suffix which implies such values include reaped children. So, we'll now extend this practice to that new UTILIZATION item. Reference(s): . Mar, 2022 - tweak PIDS_UTILIZATION commit 9c0e8e9429d232a85baef3d6fa8269963fd80741 . Feb, 2022 - added PIDS_UTILIZATION commit c69104b2b835176f9801dfd1a1d893579879a5b6 Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-03-06 11:30:00 +05:30
PIDS_UTILIZATION_C, // real derived from TIME_ALL_C / TIME_ELAPSED, as percentage
library: refactored some header file items and origins This commit is intended as a refinement of the patches mentioned below, where origins/sources of newlib items were added to the header files for user documentation. However, if those additions are to be truly effective, along with kernel documentation (where available), the following prerequisites must also have been satisfied: . our identifiers closely align with linux field names . our derived items are documented or self-documenting Satisfying those prerequisites prompted this patch and for these changes, kernel sources were emphasized over available documentation (shame on me, it should always have been so). And, while some 'new' fields were found to be conditional, they were included unconditionally. These changes appear more extensive than they actually need be since I have attempted to enforce some spacing conventions. So, I've summarize the significant things in the sections that follow. For a proper perspective, use: 'git diff --ignore-space-change' (good as alias). ___________________________________________ <PIDS> api This api is unique in that there exists many different file/directory origins subordinate to /proc/<pid>. And our item identifiers are sometimes coerced so as to be able to group related or similar enumerators together. So, users needed more help relating our identifiers to an actual documented field. Thus, we will now also add the field names as with 'stat: delayacct_blkio_ticks'. Each item ending with a '_C' now consistently includes both the parent's count/time plus waited for children. That 'RTPRIO' guy was renamed/relocated as PRIORITY_RT since its original name is an implementation artifact. ___________________________________________ <STAT> api The only api change was to correct a typo ('dervied'). _________________________________________ <VMSTAT> api Even ignoring white space, this interface received the largest number of changes. Mostly, this was because of deficiencies in the proc(5) documentation. Recall that this documentation already sorely lacks any substance. Usually, just kernel releases are noted, not contents. When compared to kernel source, that proc(5) contained many non-existent fields and also omitted many others. ________________________________________ <MEMINFO> api Sadly, with this api many of the changes were simply a correction of some earlier 'human error' where several fields where hashed then tracked but never represented with an item enumerator in this meminfo.h header file. _______________________________________ <SLABINFO> api The 'SLABS' (summary) & 'SLABNODE' items were reversed since the former are derived from the separate caches. More significantly, those 'SLABNODE' guys were renamed to 'SLAB' since they concern individual caches and the concept of 'nodes' is really an implementation detail. Also, several enumerators were changed to more closely agree with official slabinfo(5) documentation referred to in what we're treating as a base document: proc(5). Lastly, while those 'SLABS' items are solely a product of our library and not represented in slabinfo(5), the names attempt to parallel those found as 'SLAB' items. ______________________________________ <DISKSTATS> api One enumeration identifier was changed so as to better reflect its relationship to that actual documentation: 'Documentation/iostats.txt', as referenced in proc(5). Reference(s): . 12/2018, item origins added (and commit msg history) commit 96d59cbf46b3ff687bd29fad4708074a0e1cea14 . 01/2019, <stat> origins tweaked commit 201e816b26ddaccc923ec40977c92037cdd0c34e Signed-off-by: Jim Warner <james.warner@comcast.net>
2019-03-12 11:30:00 +05:30
PIDS_VM_DATA, // ul_int status: VmData
PIDS_VM_EXE, // ul_int status: VmExe
PIDS_VM_LIB, // ul_int status: VmLib
PIDS_VM_RSS, // ul_int status: VmRSS
PIDS_VM_RSS_ANON, // ul_int status: RssAnon
PIDS_VM_RSS_FILE, // ul_int status: RssFile
PIDS_VM_RSS_LOCKED, // ul_int status: VmLck
PIDS_VM_RSS_SHARED, // ul_int status: RssShmem
PIDS_VM_SIZE, // ul_int status: VmSize
PIDS_VM_STACK, // ul_int status: VmStk
PIDS_VM_SWAP, // ul_int status: VmSwap
library: added important new functionality, <pids> api This commit introduces some new capabilities available in libproc-2 under the <PIDS> interface. Along the way errors impacting some item values have been corrected. The following summarizes the major changes being made. 1. The PIDS_TIME_START item was represented as seconds since system boot but really held tics since boot. And some programs properly divided it by Hertz to actually yield seconds while others acted as if it already was. So, now we have a new PIDS_TICS_BEGAN field and all of the 'TIME' fields properly reflect seconds. With those 'TIME' fields, the type was changed to 'float/real' so one could convert it back to tics without loss of some centiseconds reflected in the Hertz guy (usually 100). 2. The boot_seconds was established in procps_pids_new meaning it was fixed/unchanging. As a result, one item (PIDS_TIME_ELAPSED) was rendered useless. So now, each of the three retrieval functions establishes a current boot_seconds well before the set functions are called. 3. Added a PIDS_UTILIZATION item that will provide the CPU usage over the life of a process, as a percentage. 4. Added PIDS_TIME_ALL_C for symmetry with the similar item called PIDS_TICS_ALL_C (which reflects raw tics). 5. That 'derived from' notation has been added to some additional header items to reflect their true origins. Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-02-25 11:30:00 +05:30
PIDS_VM_USED, // ul_int derived from status: VmRSS + VmSwap
library: change misnamed VSIZE_PGS item to VSIZE_BYTES Gosh this particular flaw originated way back in 2015. [ that was when we burdened a caller with additional ] [ responsibilities for 'stacks_alloc', 'stacks_fill' ] [ and 'stacks_dealloc'. damn implementation details. ] Reference(s): . Aug, 2015 - introduced<pids> api commit 7e6a371d8a36b250a2edddff9f5d059640b8132e Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-07-28 10:30:00 +05:30
PIDS_VSIZE_BYTES, // ul_int stat: vsize
library: add item origin (as comments) to header files A lack of documentation seems to be the major obstacle to releasing this new library. So, in an effort to get the ball rolling again, this patch adds the origins of each item as a comment to six of the new header files. However, before reviewing how such changes may benefit that documentation objective, it seemed appropriate to first reflect on newlib's background & current status. ___________________________________________ BACKGROUND Discussions about and work on a new library began back in July 2012 but quickly died. After a lull of 2 years those discussions were resumed in August 2014 but soon died also (and no code survived the gitorious demise). With those early discussions, the recommended approach was to encapsulate all of the libprocps data offerings in individual functions. When it came to extensibility it was suggested we should rely on symbols versioning. Unfortunately that approach would have made for a huge Application Programming Interface virtually impossible to master or even document. And, runtime call overhead would have been substantial for ps and especially top. So, an alternative design was sought but there were no new suggestions/contributions via freelists or gitlab. Thus, in spite of a lack of library design experience, the procps-ng team (Craig & Jim) set out to develop an alternative API, more concise and with lower overhead. Reference(s): . 07/01/2012, begin library design discussion https://www.freelists.org/post/procps/Old-library-calls . 08/12/2014, revival of library design discussion https://www.freelists.org/post/procps/libprocs-redesign _____________________________________ DESIGN EVOLUTION Our newlib branch first appeared on June 14, 2015. And our current API actually represents the 4th generation during the past 3 years of evolution. First, there was a basic 'new', 'get' and 'unref' approach, using enums to minimize the proliferation of 'get' function calls. Then, in anticipation of other programs like ps, where multiple fields times multiple processes would greatly increase the number of 'get' function calls, a concept of 'chains' was introduced. This became generation #2. Such 'chains' proved unnecessarily complex so 'stacks' replaced them. This was considered the 3rd generation, but too many implementation details were still exposed requiring those users to 'alloc', 'read', 'fill', etc. Finally, a 4th generation emerged representing several refinements to standardize and minimize those exported functions, thus hiding all implementation details from the users. Lastly, handling of 'errno' was normalized. Reference(s): . 06/14/2015, revival of new API discussion https://www.freelists.org/post/procps/The-library-API-again . 06/24/2015, birth of the newlib branch https://www.freelists.org/post/procps/new-library . 06/29/2015, 2nd generation introduced 'chains' https://www.freelists.org/post/procps/new-library,8 . 07/22/2015, 3rd generation introduced 'stacks' https://www.freelists.org/post/procps/newlib-stacks-vs-chains . 06/18/2016, 4th generation refinements begin https://www.freelists.org/post/procps/newlib-generation-35 . 11/10/2017, 4th generation standardized 'errno' https://www.freelists.org/post/procps/some-more-master-newlib-stuff _______________________________________ CURRENT DESIGN Central to this new design is a simple 'result' struct reflecting an item plus its value (thanks to a union). As a user option, these item structures can be grouped into 'stacks', yielding many results with just 1 call. Such a 'stack' can be seen as a variable length record whose content/order is determined solely by the users. Within that 'result' structure, the union has standard C language types so there is never a doubt how a value should be used in a printf statement. Given that linux requires a least a 32-bit platform the only difference in capacity surrounds 'long' integers. And, where such types might be used, the 32-bit maximums are adequate. The items themselves are simply enumerators defined in the respective header files. A user can name any items of interest then the library magically provides result structure(s). The approach was proven to be extensible without breaking the ABI (in commit referenced below). The 6 major APIs each provide for the following calls: . 'new' ---------> always required as the first call . . 'ref' -------------------------> strictly optional . . 'unref' --------> optional, if ill-behaved program . . 'get' --------------------> retrieve a single item . . 'select' ----------------> retrieve multiple items . And the 'get' and 'select' functions provide for delta results representing the difference between successive get/select calls (or a 'new' then 'get/select' call). For the <diskstats>, <pids>, <slabinfo> & <stat> APIs, where results are unpredictable, a 'reap' function can return multiple result structures for multiple stacks. The <pids> API differs from others in that those items of interest must be provided at 'new' or 'reset' time, a function unique to this API. And the <pids> 'select' function requires PIDs or UIDs which are to be fetched which then operates as a subset of 'reap'. Lastly, the 'get' function is an iterator for successive PIDs/TIDs returning items previously identified via 'new/reset'. To provide assistance to users during development, the special header 'proc/xtra-procps-debug.h' is available to check type usage against library expectations. That check is activated by including this header explicitly or via build using: ./configure '-DXTRA_PROCPS_DEBUG'. Reference(s): . 08/05/2016, type validation introduced https://www.freelists.org/post/procps/newlib-types-validation commit e3270d463de7eebd9f5ae20c85495e3cb5b69a9f . 08/11/2016, extensibility while preserving ABI example https://www.freelists.org/post/procps/new-meminfo-fields commit 09e1886c9e731f8b8c89a55d11f72f53f030b2de _________________________ INITIAL DOCUMENTATION EFFORT The initial attempt, referenced below, dealt primarily with the <pids> interface. Separate man pages for each exported function were created. Plus there was another document describing the items, among other miscellany. Adopting such an approach encounters several problems: 1. In order to use these man pages, users are 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. 2. While we can explain what all of those <pids> items represent, that certainly isn't true for all the APIs. See the gaps in kernel documentation for <meminfo> and complete lack of documentation with that <vmstat> API. 3. Our documentation effort should take pains to avoid unnecessary implementation details. Here's an example: . "The pointer to info will have memory" . "allocated and a structure created." Alternatively, the following conveys user requirements while not offering any internal implementation detail: . "You must provide the address of a NULL" . "info structure pointer." Reference(s): . 01/04/2017, initial documentation offering https://www.freelists.org/post/procps/Using-reap-and-get commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 ___________________ RECOMMENDED DOCUMENTATION APPROACH I recommend that the newlib documentation consist of 3 man pages only. The first would cover the 5 major APIs and their common functions. The second would deal with the <pids> API exclusively, explaining how it differs. Any remaining exported libproc functions which are yet to be included could be represented in a 3rd document. For these new documents the following are are assumed: 1. Since we will not be able to document all items, we shouldn't try to document any items. We should instead rely on proc(5) or Documentation/filesystems/proc.txt. 2. Program development often involves referencing some header file(s). So, make that an absolute requirement. 3. With the addition of item origins, represented with this commit, and considering that 'types' were already present, the header file might be all some users need. 4. And who knows, when a user of our libproc complains about gaps in their documentation, it might prompt the kernel folks to correct those long standing omissions. To summarize, I suggest that we replace that libproc.3 document with a more general one explaining the basics of accessing this new library and the common calls for most of the major interfaces. We can then create a new document (libproc-pids.3?), which explains differences in using the <PIDS> application programming interface. A final document (libproc-misc.3?) covers what's left. Signed-off-by: Jim Warner <james.warner@comcast.net>
2018-12-20 11:30:00 +05:30
PIDS_WCHAN_NAME // str wchan
library: implement task/thread support via the new api This commit is the culmination of efforts to modernize the library api. It should be treated as a first blush attempt, especially since I have absolutely no library design experience. But I did have a very strong desire to lessen the new library's impact on the top program. Under this new api, a 'stack' is the equivalent of the old proc_t. It can be seen as a variable length record whose contents & order is under complete user control. That initial stack/record configuration is established at procps_pids_new() time and will probably serve most program needs. But, a dynamic & demanding program like top will later change a stack via procps_pids_reset(). For programs like top & ps, procps_pids_reap() will be the function that will retrieve all tasks and threads. Any program that needs to filter / select only certain processes or users have available other functions that can be used: procps_pids_stacks_alloc, fill & dealloc. This implementation attempts to maximize that existing proven libprocps code base. As we gain more experience such actual code can be migrated into the pids.c file. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-08-19 10:30:00 +05:30
};
library: annotate header with tics/jiffies, <pids> api To avoid potential user confusion, like that reflected in the previous commit message, a short narrative will be included in the header file as programmer comments, Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-04-15 10:30:00 +05:30
// * while these are all expressed as seconds, each can be
// converted into tics/jiffies with no loss of precision
// when multiplied by hertz obtained via procps_misc(3).
library: standardize portions of interface, <PIDS> api This represents a rather major interface redesign. The following highlights most of the changes/enhancements. . The 'read' interface (employed by pgrep & pidof) saw the biggest change. The 'open', 'next' and 'shut' guys all went bye-bye, replaced by a single 'get' function. . The items specified at 'new' time no longer serve as the maximum. In fact, items & numitems are now treated as optional, should callers prefer to wait until later when the 'reset' function would then become mandatory. . Even at 'reset' time, the stacks are not tied to any sort of maximum. They will grow dynamically as needed. . The order of some parameters was changed to parallel that found in our other APIs. Specifically, when items & numitems are needed they're specified in that order. . A user will no longer be prevented from concurrently employing any accessor functions. In other words, that 'get' (old 'read') won't preclude 'reap' and 'select'. . A duplicate enumerator was found dealing with locked resident pages. So, the name VM_LOCK was eliminated in favor of VM_RSS_LOCKED, which is way more descriptive. . The struct address returned to callers following any reap() or select() is now more sharable as pids_fetch. . Some input parameter names were changed to make them more descriptive of the intended purpose/requirements. ------------------------------------------------------ Internally, there were numerous implementation changes made that did not directly impact any potential users. . That #define FPRINT_STACKS was eliminated along with the associated supporting function and its invocation. . Addresses returned following 'reap' or 'select' will now be NULL delimited, so one has the option of stacks access via the total count or this new NULL fencepost. . Input params were simplified and generalized in both oldproc_open() & close() to enable more than 1 PROCTAB to be open simultaneously, which was required for get. . The PROCPS_PIDS_logical_end enum was relocated after the Item_table making the need to keep it synchronized more apparent (if the table expands it's right there). . The 'Public function' section of the source file was subdivided into 1) the three basic required functions; and 2) functions that can sometimes vary between APIs. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-05-14 10:30:00 +05:30
enum pids_fetch_type {
library: removed all the 'PROCPS_' enumerator prefixes Many of our item enumerator identifiers are very long, especially in that <VMSTAT> module. Additionally, they all contain the exact same universal 'PROCPS_' prefix. The origins for this are likely found in the desire to avoid name clashes with other potential include files. But with procps-ng newlib, we've probably gone way too far. Did 'PROCPS_PIDS_TICS_SYSTEM' actually offer more protection against clash than 'PIDS_TICS_SYSTEM' does? I don't think so. Besides, no matter how big that name becomes, one can never guarantee they'll never be some clash. And, conversely, extremely short names will not always create conflict. Of course, in either case when some clash occurs, one can always #undef that problem. Thus, this commit will eliminate that 'PROCPS_' prefix making all of those enum identifiers a little shorter. And, we'll still be well above some ridiculously short (criminally short) names found in some common headers: - - - - - - - - - - <term.h> - 'tab', 'TTY', etc - - - - - - - - - - - - - - - - <search.h> - 'ENTER', ENTRY', 'FIND', etc ------------------------------------------------------ Finally, with this as a last of the wholesale changes, we will have established the naming conventions below: . only functions will begin with that 'procps_' prefix . exposed structures begin with the module/header name . item enumerators begin like structs, but capitalized . other enumerators work exactly like item enumerators . macros and constants begin just like the enumerators ------------------------------------------------------ Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-21 10:30:00 +05:30
PIDS_FETCH_TASKS_ONLY,
PIDS_FETCH_THREADS_TOO
library: standardize portions of interface, <PIDS> api This represents a rather major interface redesign. The following highlights most of the changes/enhancements. . The 'read' interface (employed by pgrep & pidof) saw the biggest change. The 'open', 'next' and 'shut' guys all went bye-bye, replaced by a single 'get' function. . The items specified at 'new' time no longer serve as the maximum. In fact, items & numitems are now treated as optional, should callers prefer to wait until later when the 'reset' function would then become mandatory. . Even at 'reset' time, the stacks are not tied to any sort of maximum. They will grow dynamically as needed. . The order of some parameters was changed to parallel that found in our other APIs. Specifically, when items & numitems are needed they're specified in that order. . A user will no longer be prevented from concurrently employing any accessor functions. In other words, that 'get' (old 'read') won't preclude 'reap' and 'select'. . A duplicate enumerator was found dealing with locked resident pages. So, the name VM_LOCK was eliminated in favor of VM_RSS_LOCKED, which is way more descriptive. . The struct address returned to callers following any reap() or select() is now more sharable as pids_fetch. . Some input parameter names were changed to make them more descriptive of the intended purpose/requirements. ------------------------------------------------------ Internally, there were numerous implementation changes made that did not directly impact any potential users. . That #define FPRINT_STACKS was eliminated along with the associated supporting function and its invocation. . Addresses returned following 'reap' or 'select' will now be NULL delimited, so one has the option of stacks access via the total count or this new NULL fencepost. . Input params were simplified and generalized in both oldproc_open() & close() to enable more than 1 PROCTAB to be open simultaneously, which was required for get. . The PROCPS_PIDS_logical_end enum was relocated after the Item_table making the need to keep it synchronized more apparent (if the table expands it's right there). . The 'Public function' section of the source file was subdivided into 1) the three basic required functions; and 2) functions that can sometimes vary between APIs. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-05-14 10:30:00 +05:30
};
library: changed use of 'fill' to 'select', <pids> API Remove a remnant of this new API's evolution. Here we no longer fill stacks, rather we reap and select them. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-04-18 10:30:00 +05:30
enum pids_select_type {
library: repair <pids> api boo-boo in the 'select' i/f The patch referenced below corrected some flaws in the procps_pids_select implementation. But, there remained one flaw which this commit will now hopefully address. Rather than assume callers wished to select only tasks and not threads meant a command like 'top -H -p 10329' works differently under newlib than release 3.3.17. It fails to honor the '-H' (threads) switch under newlib. So, to fix that oops, we'll allow that select function to get threads or tasks depending on its 'which' parm. Reference(s): . Oct 2015, some flaws corrected commit bc616b361596bc3008800de839b88446508cfdd0 Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-08-07 10:30:00 +05:30
PIDS_SELECT_PID = 0x10000,
PIDS_SELECT_PID_THREADS = 0x10001,
PIDS_SELECT_UID = 0x20000,
PIDS_SELECT_UID_THREADS = 0x20001
library: implement task/thread support via the new api This commit is the culmination of efforts to modernize the library api. It should be treated as a first blush attempt, especially since I have absolutely no library design experience. But I did have a very strong desire to lessen the new library's impact on the top program. Under this new api, a 'stack' is the equivalent of the old proc_t. It can be seen as a variable length record whose contents & order is under complete user control. That initial stack/record configuration is established at procps_pids_new() time and will probably serve most program needs. But, a dynamic & demanding program like top will later change a stack via procps_pids_reset(). For programs like top & ps, procps_pids_reap() will be the function that will retrieve all tasks and threads. Any program that needs to filter / select only certain processes or users have available other functions that can be used: procps_pids_stacks_alloc, fill & dealloc. This implementation attempts to maximize that existing proven libprocps code base. As we gain more experience such actual code can be migrated into the pids.c file. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-08-19 10:30:00 +05:30
};
enum pids_sort_order {
library: removed all the 'PROCPS_' enumerator prefixes Many of our item enumerator identifiers are very long, especially in that <VMSTAT> module. Additionally, they all contain the exact same universal 'PROCPS_' prefix. The origins for this are likely found in the desire to avoid name clashes with other potential include files. But with procps-ng newlib, we've probably gone way too far. Did 'PROCPS_PIDS_TICS_SYSTEM' actually offer more protection against clash than 'PIDS_TICS_SYSTEM' does? I don't think so. Besides, no matter how big that name becomes, one can never guarantee they'll never be some clash. And, conversely, extremely short names will not always create conflict. Of course, in either case when some clash occurs, one can always #undef that problem. Thus, this commit will eliminate that 'PROCPS_' prefix making all of those enum identifiers a little shorter. And, we'll still be well above some ridiculously short (criminally short) names found in some common headers: - - - - - - - - - - <term.h> - 'tab', 'TTY', etc - - - - - - - - - - - - - - - - <search.h> - 'ENTER', ENTRY', 'FIND', etc ------------------------------------------------------ Finally, with this as a last of the wholesale changes, we will have established the naming conventions below: . only functions will begin with that 'procps_' prefix . exposed structures begin with the module/header name . item enumerators begin like structs, but capitalized . other enumerators work exactly like item enumerators . macros and constants begin just like the enumerators ------------------------------------------------------ Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-21 10:30:00 +05:30
PIDS_SORT_ASCEND = +1,
PIDS_SORT_DESCEND = -1
library: implement task/thread support via the new api This commit is the culmination of efforts to modernize the library api. It should be treated as a first blush attempt, especially since I have absolutely no library design experience. But I did have a very strong desire to lessen the new library's impact on the top program. Under this new api, a 'stack' is the equivalent of the old proc_t. It can be seen as a variable length record whose contents & order is under complete user control. That initial stack/record configuration is established at procps_pids_new() time and will probably serve most program needs. But, a dynamic & demanding program like top will later change a stack via procps_pids_reset(). For programs like top & ps, procps_pids_reap() will be the function that will retrieve all tasks and threads. Any program that needs to filter / select only certain processes or users have available other functions that can be used: procps_pids_stacks_alloc, fill & dealloc. This implementation attempts to maximize that existing proven libprocps code base. As we gain more experience such actual code can be migrated into the pids.c file. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-08-19 10:30:00 +05:30
};
struct pids_result {
enum pids_item item;
union {
library: more tweaks for code and/or comments, 3rd gen Following is a summary of significant changes (if any) to each of these now upgraded 3rd gen library modules. <meminfo> ............................................ . eliminated duplicate decl of 'struct procps_meminfo' . standardized/normalized results struct union members . added 'std' & 'var' dividers in .c file, like <pids> . how did i miss relocating all these friggin' #undefs . cleanup 'get' return logic (remove a redundant 'if') <pids> ............................................... . repositioned the procps_pidsinfo structure in header . removed the extra trailing comma from enum pids_item . standardized/normalized results struct union members <slabinfo> ........................................... . corrected comment typo (jeeze, in an 'aligned' para) . standardized/normalized results struct union members . added 'std' & 'var' dividers in .c file, like <pids> . removed an obsolete #undef from procps_slabinfo_sort . cleanup 'get' return logic (remove a redundant 'if') <stat> ............................................... . how did i miss relocating all these friggin' #undefs . corrected an initialization fencepost used with numa <=== see Craig, here's a bug fix . removed the extra trailing comma from enum stat_item . standardized/normalized results struct union members . added 'std' & 'var' dividers in .c file, like <pids> . strengthen those parm checks in procps_stat_get func . cleanup 'get' return logic (remove a redundant 'if') <vmstat> ............................................. . standardized/normalized results struct union members . added 'std' & 'var' dividers in .c file, like <pids> . cleanup 'get' return logic (remove a redundant 'if') [ virtually all of these tweaks reflect the author's ] [ continuing pursuit of an unreasonable goal -- that ] [ of a 'perfect' (plus 'pretty') C language program! ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-06-14 10:30:00 +05:30
signed char s_ch;
signed int s_int;
unsigned int u_int;
unsigned long ul_int;
unsigned long long ull_int;
char *str;
char **strv;
library: trade 'float' type for a 'double', <pids> api While we really do not need the extra precision, we'll trade that recently introduced float type for a double for efficiency on a 64 bit platform. Additionally, the UTILIZATION algorithm was tweaked producing less code. The net result is four fewer machine instructions with a reduction of 14 total bytes in that function's size. Reference(s): . introduced 'real' type & 'utilization' item commit c69104b2b835176f9801dfd1a1d893579879a5b6 Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-02-27 11:30:00 +05:30
double real;
library: implement task/thread support via the new api This commit is the culmination of efforts to modernize the library api. It should be treated as a first blush attempt, especially since I have absolutely no library design experience. But I did have a very strong desire to lessen the new library's impact on the top program. Under this new api, a 'stack' is the equivalent of the old proc_t. It can be seen as a variable length record whose contents & order is under complete user control. That initial stack/record configuration is established at procps_pids_new() time and will probably serve most program needs. But, a dynamic & demanding program like top will later change a stack via procps_pids_reset(). For programs like top & ps, procps_pids_reap() will be the function that will retrieve all tasks and threads. Any program that needs to filter / select only certain processes or users have available other functions that can be used: procps_pids_stacks_alloc, fill & dealloc. This implementation attempts to maximize that existing proven libprocps code base. As we gain more experience such actual code can be migrated into the pids.c file. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-08-19 10:30:00 +05:30
} result;
};
struct pids_stack {
struct pids_result *head;
};
struct pids_counts {
int total;
library: account for idle state ('I') threads in total With the documentation update in the commit referenced below, we should also account for such threads as they will already be represented in the task/thread totals. [ and do it in a way that might avoid future changes ] Reference(s): commit 91df65b9e778b9d7da7952d766e129f58423b807 Signed-off-by: Jim Warner <james.warner@comcast.net>
2018-01-13 11:30:00 +05:30
int running, sleeping, stopped, zombied, other;
library: implement task/thread support via the new api This commit is the culmination of efforts to modernize the library api. It should be treated as a first blush attempt, especially since I have absolutely no library design experience. But I did have a very strong desire to lessen the new library's impact on the top program. Under this new api, a 'stack' is the equivalent of the old proc_t. It can be seen as a variable length record whose contents & order is under complete user control. That initial stack/record configuration is established at procps_pids_new() time and will probably serve most program needs. But, a dynamic & demanding program like top will later change a stack via procps_pids_reset(). For programs like top & ps, procps_pids_reap() will be the function that will retrieve all tasks and threads. Any program that needs to filter / select only certain processes or users have available other functions that can be used: procps_pids_stacks_alloc, fill & dealloc. This implementation attempts to maximize that existing proven libprocps code base. As we gain more experience such actual code can be migrated into the pids.c file. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-08-19 10:30:00 +05:30
};
library: standardize portions of interface, <PIDS> api This represents a rather major interface redesign. The following highlights most of the changes/enhancements. . The 'read' interface (employed by pgrep & pidof) saw the biggest change. The 'open', 'next' and 'shut' guys all went bye-bye, replaced by a single 'get' function. . The items specified at 'new' time no longer serve as the maximum. In fact, items & numitems are now treated as optional, should callers prefer to wait until later when the 'reset' function would then become mandatory. . Even at 'reset' time, the stacks are not tied to any sort of maximum. They will grow dynamically as needed. . The order of some parameters was changed to parallel that found in our other APIs. Specifically, when items & numitems are needed they're specified in that order. . A user will no longer be prevented from concurrently employing any accessor functions. In other words, that 'get' (old 'read') won't preclude 'reap' and 'select'. . A duplicate enumerator was found dealing with locked resident pages. So, the name VM_LOCK was eliminated in favor of VM_RSS_LOCKED, which is way more descriptive. . The struct address returned to callers following any reap() or select() is now more sharable as pids_fetch. . Some input parameter names were changed to make them more descriptive of the intended purpose/requirements. ------------------------------------------------------ Internally, there were numerous implementation changes made that did not directly impact any potential users. . That #define FPRINT_STACKS was eliminated along with the associated supporting function and its invocation. . Addresses returned following 'reap' or 'select' will now be NULL delimited, so one has the option of stacks access via the total count or this new NULL fencepost. . Input params were simplified and generalized in both oldproc_open() & close() to enable more than 1 PROCTAB to be open simultaneously, which was required for get. . The PROCPS_PIDS_logical_end enum was relocated after the Item_table making the need to keep it synchronized more apparent (if the table expands it's right there). . The 'Public function' section of the source file was subdivided into 1) the three basic required functions; and 2) functions that can sometimes vary between APIs. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-05-14 10:30:00 +05:30
struct pids_fetch {
library: more pids_fetch struct opaqueness, <PIDS> api With all our 3rd generation interfaces, we're now well positioned to preserve binary compatibility should new fields be added to any public structure (assuming that the 'result' union already contains its largest type). This remains true even for the <pids> interface, which unlike the others, has one structure embedded within a separate struct rather than declaring a pointer to it. The counts struct was positioned after the stacks ptrs array so as to preserve that ABI if ever new ints were added. Logically, however, the counts (especially that total) should precede the stacks array if we wished to properly place a horse (total) before a cart (stacks). So to enable relocating those counts we will no longer embed that structure, but provide a pointer to it. And this will make accessing syntax feel more natural too. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-06-23 10:30:00 +05:30
struct pids_counts *counts;
library: miscellaneous tweaks to pid code and comments . traded a complex misaligned memory allocation scheme in the make_hist function for a simple aligned scheme. plus memory allocation increases are globally defined. . changed 1 parameter for procps_pids_stacks_sort() to better reflect the 'array of pointers', not an address of a pointer as is used with guys such as 'new/unref'. . the pids_reap struct was changed slightly to make it more reflective of it's actual implementation details. . the Item_table member .mustfree is now .needfree and that .makehist was now made .needhist for consistency. . reduced the number of separate 'return NULL;' source statements in that primary procps_pids_reap() routine. . ensured consistent reference to sizeof(void *) & not occasional reference to sizeof(void*) without a space. . rather than enable/disable validate_stacks via a #if in the function body, it is now handled via a #define. . some comments in the procps_pids_reset function were adjusted to reflect this current implementation. shown originally, they reflected an aborted attempt to avoid a testing aberration not fully understood at the time. . added a summary of the memory overhead cost of HST_t processing to that UNREF_RPTHASH output at unref time. . a 'PIDs at max depth:' portion of that UNREF_RPTHASH enabled #define is now published only when the maximum depth of hash table entry chains exceed depths of one. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-08-20 10:30:00 +05:30
struct pids_stack **stacks;
library: implement task/thread support via the new api This commit is the culmination of efforts to modernize the library api. It should be treated as a first blush attempt, especially since I have absolutely no library design experience. But I did have a very strong desire to lessen the new library's impact on the top program. Under this new api, a 'stack' is the equivalent of the old proc_t. It can be seen as a variable length record whose contents & order is under complete user control. That initial stack/record configuration is established at procps_pids_new() time and will probably serve most program needs. But, a dynamic & demanding program like top will later change a stack via procps_pids_reset(). For programs like top & ps, procps_pids_reap() will be the function that will retrieve all tasks and threads. Any program that needs to filter / select only certain processes or users have available other functions that can be used: procps_pids_stacks_alloc, fill & dealloc. This implementation attempts to maximize that existing proven libprocps code base. As we gain more experience such actual code can be migrated into the pids.c file. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-08-19 10:30:00 +05:30
};
library: reposition those 'info' structures in headers For some unknown reason all the 'info' structures were declared between macros and function prototypes rather than right after all the other structure declarations. Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-12-15 11:30:00 +05:30
struct pids_info;
library: implement task/thread support via the new api This commit is the culmination of efforts to modernize the library api. It should be treated as a first blush attempt, especially since I have absolutely no library design experience. But I did have a very strong desire to lessen the new library's impact on the top program. Under this new api, a 'stack' is the equivalent of the old proc_t. It can be seen as a variable length record whose contents & order is under complete user control. That initial stack/record configuration is established at procps_pids_new() time and will probably serve most program needs. But, a dynamic & demanding program like top will later change a stack via procps_pids_reset(). For programs like top & ps, procps_pids_reap() will be the function that will retrieve all tasks and threads. Any program that needs to filter / select only certain processes or users have available other functions that can be used: procps_pids_stacks_alloc, fill & dealloc. This implementation attempts to maximize that existing proven libprocps code base. As we gain more experience such actual code can be migrated into the pids.c file. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-08-19 10:30:00 +05:30
library: expand VAL macros to include the context parm This patch will set the stage for validating the types referenced in the result union. For now, the parameter representing that 'info' structure will remain unused. [ and while we're at it, let us correct a faulty GET ] [ macro in the diskstats header. that puppy missed a ] [ parm which ain't so good if that guy is ever used! ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-08-05 10:30:00 +05:30
#define PIDS_VAL( relative_enum, type, stack, info ) \
library: a couple of miscellaneous changes, <PIDS> api This patch represents the following minor adjustments: . old PROCTAB used with select & reap more descriptive . reformatted PROCPS_PIDS_VAL macro like other 3rd gen Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-06-18 10:30:00 +05:30
stack -> head [ relative_enum ] . result . type
library: introduce pids 'value extractor' helper macro As an experiment a helper macro used to extract values from a result stack has been added to the header file. Don't force callers to reinvent that particular wheel. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-08-26 10:30:00 +05:30
library: standardize all the 'context' structure names This patch attempts to standardize the naming of those most important (declared not defined) context structs. The present practice represents a hodge podge of names only some of which reflect the source /proc file name. And 2 of those file names embed a literal 'info' which is likely the origin of that required parm identifier. Now we'll append a universal '_info' to such structure names, while including the names of those /proc pseudo files where possible. In any case, that context struct will *always* begin with the actual module/header file name. And only the following two sound a little weird! ---------> 'meminfo_info' + 'slabinfo_info' <--------- Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-21 10:30:00 +05:30
int procps_pids_new (struct pids_info **info, enum pids_item *items, int numitems);
int procps_pids_ref (struct pids_info *info);
int procps_pids_unref (struct pids_info **info);
library: standardize portions of interface, <PIDS> api This represents a rather major interface redesign. The following highlights most of the changes/enhancements. . The 'read' interface (employed by pgrep & pidof) saw the biggest change. The 'open', 'next' and 'shut' guys all went bye-bye, replaced by a single 'get' function. . The items specified at 'new' time no longer serve as the maximum. In fact, items & numitems are now treated as optional, should callers prefer to wait until later when the 'reset' function would then become mandatory. . Even at 'reset' time, the stacks are not tied to any sort of maximum. They will grow dynamically as needed. . The order of some parameters was changed to parallel that found in our other APIs. Specifically, when items & numitems are needed they're specified in that order. . A user will no longer be prevented from concurrently employing any accessor functions. In other words, that 'get' (old 'read') won't preclude 'reap' and 'select'. . A duplicate enumerator was found dealing with locked resident pages. So, the name VM_LOCK was eliminated in favor of VM_RSS_LOCKED, which is way more descriptive. . The struct address returned to callers following any reap() or select() is now more sharable as pids_fetch. . Some input parameter names were changed to make them more descriptive of the intended purpose/requirements. ------------------------------------------------------ Internally, there were numerous implementation changes made that did not directly impact any potential users. . That #define FPRINT_STACKS was eliminated along with the associated supporting function and its invocation. . Addresses returned following 'reap' or 'select' will now be NULL delimited, so one has the option of stacks access via the total count or this new NULL fencepost. . Input params were simplified and generalized in both oldproc_open() & close() to enable more than 1 PROCTAB to be open simultaneously, which was required for get. . The PROCPS_PIDS_logical_end enum was relocated after the Item_table making the need to keep it synchronized more apparent (if the table expands it's right there). . The 'Public function' section of the source file was subdivided into 1) the three basic required functions; and 2) functions that can sometimes vary between APIs. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-05-14 10:30:00 +05:30
library: introduce a fatal 'proc not mounted' function Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-09-11 10:30:00 +05:30
struct pids_stack *fatal_proc_unmounted (
library: standardize all the 'context' structure names This patch attempts to standardize the naming of those most important (declared not defined) context structs. The present practice represents a hodge podge of names only some of which reflect the source /proc file name. And 2 of those file names embed a literal 'info' which is likely the origin of that required parm identifier. Now we'll append a universal '_info' to such structure names, while including the names of those /proc pseudo files where possible. In any case, that context struct will *always* begin with the actual module/header file name. And only the following two sound a little weird! ---------> 'meminfo_info' + 'slabinfo_info' <--------- Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-21 10:30:00 +05:30
struct pids_info *info,
library: introduce a fatal 'proc not mounted' function Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-09-11 10:30:00 +05:30
int return_self);
library: standardize portions of interface, <PIDS> api This represents a rather major interface redesign. The following highlights most of the changes/enhancements. . The 'read' interface (employed by pgrep & pidof) saw the biggest change. The 'open', 'next' and 'shut' guys all went bye-bye, replaced by a single 'get' function. . The items specified at 'new' time no longer serve as the maximum. In fact, items & numitems are now treated as optional, should callers prefer to wait until later when the 'reset' function would then become mandatory. . Even at 'reset' time, the stacks are not tied to any sort of maximum. They will grow dynamically as needed. . The order of some parameters was changed to parallel that found in our other APIs. Specifically, when items & numitems are needed they're specified in that order. . A user will no longer be prevented from concurrently employing any accessor functions. In other words, that 'get' (old 'read') won't preclude 'reap' and 'select'. . A duplicate enumerator was found dealing with locked resident pages. So, the name VM_LOCK was eliminated in favor of VM_RSS_LOCKED, which is way more descriptive. . The struct address returned to callers following any reap() or select() is now more sharable as pids_fetch. . Some input parameter names were changed to make them more descriptive of the intended purpose/requirements. ------------------------------------------------------ Internally, there were numerous implementation changes made that did not directly impact any potential users. . That #define FPRINT_STACKS was eliminated along with the associated supporting function and its invocation. . Addresses returned following 'reap' or 'select' will now be NULL delimited, so one has the option of stacks access via the total count or this new NULL fencepost. . Input params were simplified and generalized in both oldproc_open() & close() to enable more than 1 PROCTAB to be open simultaneously, which was required for get. . The PROCPS_PIDS_logical_end enum was relocated after the Item_table making the need to keep it synchronized more apparent (if the table expands it's right there). . The 'Public function' section of the source file was subdivided into 1) the three basic required functions; and 2) functions that can sometimes vary between APIs. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-05-14 10:30:00 +05:30
struct pids_stack *procps_pids_get (
library: standardize all the 'context' structure names This patch attempts to standardize the naming of those most important (declared not defined) context structs. The present practice represents a hodge podge of names only some of which reflect the source /proc file name. And 2 of those file names embed a literal 'info' which is likely the origin of that required parm identifier. Now we'll append a universal '_info' to such structure names, while including the names of those /proc pseudo files where possible. In any case, that context struct will *always* begin with the actual module/header file name. And only the following two sound a little weird! ---------> 'meminfo_info' + 'slabinfo_info' <--------- Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-21 10:30:00 +05:30
struct pids_info *info,
library: standardize portions of interface, <PIDS> api This represents a rather major interface redesign. The following highlights most of the changes/enhancements. . The 'read' interface (employed by pgrep & pidof) saw the biggest change. The 'open', 'next' and 'shut' guys all went bye-bye, replaced by a single 'get' function. . The items specified at 'new' time no longer serve as the maximum. In fact, items & numitems are now treated as optional, should callers prefer to wait until later when the 'reset' function would then become mandatory. . Even at 'reset' time, the stacks are not tied to any sort of maximum. They will grow dynamically as needed. . The order of some parameters was changed to parallel that found in our other APIs. Specifically, when items & numitems are needed they're specified in that order. . A user will no longer be prevented from concurrently employing any accessor functions. In other words, that 'get' (old 'read') won't preclude 'reap' and 'select'. . A duplicate enumerator was found dealing with locked resident pages. So, the name VM_LOCK was eliminated in favor of VM_RSS_LOCKED, which is way more descriptive. . The struct address returned to callers following any reap() or select() is now more sharable as pids_fetch. . Some input parameter names were changed to make them more descriptive of the intended purpose/requirements. ------------------------------------------------------ Internally, there were numerous implementation changes made that did not directly impact any potential users. . That #define FPRINT_STACKS was eliminated along with the associated supporting function and its invocation. . Addresses returned following 'reap' or 'select' will now be NULL delimited, so one has the option of stacks access via the total count or this new NULL fencepost. . Input params were simplified and generalized in both oldproc_open() & close() to enable more than 1 PROCTAB to be open simultaneously, which was required for get. . The PROCPS_PIDS_logical_end enum was relocated after the Item_table making the need to keep it synchronized more apparent (if the table expands it's right there). . The 'Public function' section of the source file was subdivided into 1) the three basic required functions; and 2) functions that can sometimes vary between APIs. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-05-14 10:30:00 +05:30
enum pids_fetch_type which);
library: add sequential access to that pids collection To ease the transition to the new interface, for other than that top program, individual read provisions have been added to the <proc/pids.h> API. This represents a refinement of a position stated in a post noted below. Reference(s): http://www.freelists.org/post/procps/newlib-ps-fix Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-08-26 10:30:00 +05:30
library: standardize portions of interface, <PIDS> api This represents a rather major interface redesign. The following highlights most of the changes/enhancements. . The 'read' interface (employed by pgrep & pidof) saw the biggest change. The 'open', 'next' and 'shut' guys all went bye-bye, replaced by a single 'get' function. . The items specified at 'new' time no longer serve as the maximum. In fact, items & numitems are now treated as optional, should callers prefer to wait until later when the 'reset' function would then become mandatory. . Even at 'reset' time, the stacks are not tied to any sort of maximum. They will grow dynamically as needed. . The order of some parameters was changed to parallel that found in our other APIs. Specifically, when items & numitems are needed they're specified in that order. . A user will no longer be prevented from concurrently employing any accessor functions. In other words, that 'get' (old 'read') won't preclude 'reap' and 'select'. . A duplicate enumerator was found dealing with locked resident pages. So, the name VM_LOCK was eliminated in favor of VM_RSS_LOCKED, which is way more descriptive. . The struct address returned to callers following any reap() or select() is now more sharable as pids_fetch. . Some input parameter names were changed to make them more descriptive of the intended purpose/requirements. ------------------------------------------------------ Internally, there were numerous implementation changes made that did not directly impact any potential users. . That #define FPRINT_STACKS was eliminated along with the associated supporting function and its invocation. . Addresses returned following 'reap' or 'select' will now be NULL delimited, so one has the option of stacks access via the total count or this new NULL fencepost. . Input params were simplified and generalized in both oldproc_open() & close() to enable more than 1 PROCTAB to be open simultaneously, which was required for get. . The PROCPS_PIDS_logical_end enum was relocated after the Item_table making the need to keep it synchronized more apparent (if the table expands it's right there). . The 'Public function' section of the source file was subdivided into 1) the three basic required functions; and 2) functions that can sometimes vary between APIs. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-05-14 10:30:00 +05:30
struct pids_fetch *procps_pids_reap (
library: standardize all the 'context' structure names This patch attempts to standardize the naming of those most important (declared not defined) context structs. The present practice represents a hodge podge of names only some of which reflect the source /proc file name. And 2 of those file names embed a literal 'info' which is likely the origin of that required parm identifier. Now we'll append a universal '_info' to such structure names, while including the names of those /proc pseudo files where possible. In any case, that context struct will *always* begin with the actual module/header file name. And only the following two sound a little weird! ---------> 'meminfo_info' + 'slabinfo_info' <--------- Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-21 10:30:00 +05:30
struct pids_info *info,
library: standardize portions of interface, <PIDS> api This represents a rather major interface redesign. The following highlights most of the changes/enhancements. . The 'read' interface (employed by pgrep & pidof) saw the biggest change. The 'open', 'next' and 'shut' guys all went bye-bye, replaced by a single 'get' function. . The items specified at 'new' time no longer serve as the maximum. In fact, items & numitems are now treated as optional, should callers prefer to wait until later when the 'reset' function would then become mandatory. . Even at 'reset' time, the stacks are not tied to any sort of maximum. They will grow dynamically as needed. . The order of some parameters was changed to parallel that found in our other APIs. Specifically, when items & numitems are needed they're specified in that order. . A user will no longer be prevented from concurrently employing any accessor functions. In other words, that 'get' (old 'read') won't preclude 'reap' and 'select'. . A duplicate enumerator was found dealing with locked resident pages. So, the name VM_LOCK was eliminated in favor of VM_RSS_LOCKED, which is way more descriptive. . The struct address returned to callers following any reap() or select() is now more sharable as pids_fetch. . Some input parameter names were changed to make them more descriptive of the intended purpose/requirements. ------------------------------------------------------ Internally, there were numerous implementation changes made that did not directly impact any potential users. . That #define FPRINT_STACKS was eliminated along with the associated supporting function and its invocation. . Addresses returned following 'reap' or 'select' will now be NULL delimited, so one has the option of stacks access via the total count or this new NULL fencepost. . Input params were simplified and generalized in both oldproc_open() & close() to enable more than 1 PROCTAB to be open simultaneously, which was required for get. . The PROCPS_PIDS_logical_end enum was relocated after the Item_table making the need to keep it synchronized more apparent (if the table expands it's right there). . The 'Public function' section of the source file was subdivided into 1) the three basic required functions; and 2) functions that can sometimes vary between APIs. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-05-14 10:30:00 +05:30
enum pids_fetch_type which);
library: implement task/thread support via the new api This commit is the culmination of efforts to modernize the library api. It should be treated as a first blush attempt, especially since I have absolutely no library design experience. But I did have a very strong desire to lessen the new library's impact on the top program. Under this new api, a 'stack' is the equivalent of the old proc_t. It can be seen as a variable length record whose contents & order is under complete user control. That initial stack/record configuration is established at procps_pids_new() time and will probably serve most program needs. But, a dynamic & demanding program like top will later change a stack via procps_pids_reset(). For programs like top & ps, procps_pids_reap() will be the function that will retrieve all tasks and threads. Any program that needs to filter / select only certain processes or users have available other functions that can be used: procps_pids_stacks_alloc, fill & dealloc. This implementation attempts to maximize that existing proven libprocps code base. As we gain more experience such actual code can be migrated into the pids.c file. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-08-19 10:30:00 +05:30
int procps_pids_reset (
library: standardize all the 'context' structure names This patch attempts to standardize the naming of those most important (declared not defined) context structs. The present practice represents a hodge podge of names only some of which reflect the source /proc file name. And 2 of those file names embed a literal 'info' which is likely the origin of that required parm identifier. Now we'll append a universal '_info' to such structure names, while including the names of those /proc pseudo files where possible. In any case, that context struct will *always* begin with the actual module/header file name. And only the following two sound a little weird! ---------> 'meminfo_info' + 'slabinfo_info' <--------- Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-21 10:30:00 +05:30
struct pids_info *info,
library: standardize portions of interface, <PIDS> api This represents a rather major interface redesign. The following highlights most of the changes/enhancements. . The 'read' interface (employed by pgrep & pidof) saw the biggest change. The 'open', 'next' and 'shut' guys all went bye-bye, replaced by a single 'get' function. . The items specified at 'new' time no longer serve as the maximum. In fact, items & numitems are now treated as optional, should callers prefer to wait until later when the 'reset' function would then become mandatory. . Even at 'reset' time, the stacks are not tied to any sort of maximum. They will grow dynamically as needed. . The order of some parameters was changed to parallel that found in our other APIs. Specifically, when items & numitems are needed they're specified in that order. . A user will no longer be prevented from concurrently employing any accessor functions. In other words, that 'get' (old 'read') won't preclude 'reap' and 'select'. . A duplicate enumerator was found dealing with locked resident pages. So, the name VM_LOCK was eliminated in favor of VM_RSS_LOCKED, which is way more descriptive. . The struct address returned to callers following any reap() or select() is now more sharable as pids_fetch. . Some input parameter names were changed to make them more descriptive of the intended purpose/requirements. ------------------------------------------------------ Internally, there were numerous implementation changes made that did not directly impact any potential users. . That #define FPRINT_STACKS was eliminated along with the associated supporting function and its invocation. . Addresses returned following 'reap' or 'select' will now be NULL delimited, so one has the option of stacks access via the total count or this new NULL fencepost. . Input params were simplified and generalized in both oldproc_open() & close() to enable more than 1 PROCTAB to be open simultaneously, which was required for get. . The PROCPS_PIDS_logical_end enum was relocated after the Item_table making the need to keep it synchronized more apparent (if the table expands it's right there). . The 'Public function' section of the source file was subdivided into 1) the three basic required functions; and 2) functions that can sometimes vary between APIs. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-05-14 10:30:00 +05:30
enum pids_item *newitems,
int newnumitems);
library: implement task/thread support via the new api This commit is the culmination of efforts to modernize the library api. It should be treated as a first blush attempt, especially since I have absolutely no library design experience. But I did have a very strong desire to lessen the new library's impact on the top program. Under this new api, a 'stack' is the equivalent of the old proc_t. It can be seen as a variable length record whose contents & order is under complete user control. That initial stack/record configuration is established at procps_pids_new() time and will probably serve most program needs. But, a dynamic & demanding program like top will later change a stack via procps_pids_reset(). For programs like top & ps, procps_pids_reap() will be the function that will retrieve all tasks and threads. Any program that needs to filter / select only certain processes or users have available other functions that can be used: procps_pids_stacks_alloc, fill & dealloc. This implementation attempts to maximize that existing proven libprocps code base. As we gain more experience such actual code can be migrated into the pids.c file. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-08-19 10:30:00 +05:30
library: standardize portions of interface, <PIDS> api This represents a rather major interface redesign. The following highlights most of the changes/enhancements. . The 'read' interface (employed by pgrep & pidof) saw the biggest change. The 'open', 'next' and 'shut' guys all went bye-bye, replaced by a single 'get' function. . The items specified at 'new' time no longer serve as the maximum. In fact, items & numitems are now treated as optional, should callers prefer to wait until later when the 'reset' function would then become mandatory. . Even at 'reset' time, the stacks are not tied to any sort of maximum. They will grow dynamically as needed. . The order of some parameters was changed to parallel that found in our other APIs. Specifically, when items & numitems are needed they're specified in that order. . A user will no longer be prevented from concurrently employing any accessor functions. In other words, that 'get' (old 'read') won't preclude 'reap' and 'select'. . A duplicate enumerator was found dealing with locked resident pages. So, the name VM_LOCK was eliminated in favor of VM_RSS_LOCKED, which is way more descriptive. . The struct address returned to callers following any reap() or select() is now more sharable as pids_fetch. . Some input parameter names were changed to make them more descriptive of the intended purpose/requirements. ------------------------------------------------------ Internally, there were numerous implementation changes made that did not directly impact any potential users. . That #define FPRINT_STACKS was eliminated along with the associated supporting function and its invocation. . Addresses returned following 'reap' or 'select' will now be NULL delimited, so one has the option of stacks access via the total count or this new NULL fencepost. . Input params were simplified and generalized in both oldproc_open() & close() to enable more than 1 PROCTAB to be open simultaneously, which was required for get. . The PROCPS_PIDS_logical_end enum was relocated after the Item_table making the need to keep it synchronized more apparent (if the table expands it's right there). . The 'Public function' section of the source file was subdivided into 1) the three basic required functions; and 2) functions that can sometimes vary between APIs. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-05-14 10:30:00 +05:30
struct pids_fetch *procps_pids_select (
library: standardize all the 'context' structure names This patch attempts to standardize the naming of those most important (declared not defined) context structs. The present practice represents a hodge podge of names only some of which reflect the source /proc file name. And 2 of those file names embed a literal 'info' which is likely the origin of that required parm identifier. Now we'll append a universal '_info' to such structure names, while including the names of those /proc pseudo files where possible. In any case, that context struct will *always* begin with the actual module/header file name. And only the following two sound a little weird! ---------> 'meminfo_info' + 'slabinfo_info' <--------- Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-21 10:30:00 +05:30
struct pids_info *info,
library: normalize the <pids> fill/selection interface After wrestling with the conversion of both top and ps the differences between reap (all) & fill (select) has become increasingly inconvenient. So this patch simply normalizes that API making returned results identical. The former procps_pids_stacks_fill identifier will now be known as procps_pids_select which serves as logical counterpart to the existing procps_pids_reap function. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-10-01 10:30:00 +05:30
unsigned *these,
library: standardize portions of interface, <PIDS> api This represents a rather major interface redesign. The following highlights most of the changes/enhancements. . The 'read' interface (employed by pgrep & pidof) saw the biggest change. The 'open', 'next' and 'shut' guys all went bye-bye, replaced by a single 'get' function. . The items specified at 'new' time no longer serve as the maximum. In fact, items & numitems are now treated as optional, should callers prefer to wait until later when the 'reset' function would then become mandatory. . Even at 'reset' time, the stacks are not tied to any sort of maximum. They will grow dynamically as needed. . The order of some parameters was changed to parallel that found in our other APIs. Specifically, when items & numitems are needed they're specified in that order. . A user will no longer be prevented from concurrently employing any accessor functions. In other words, that 'get' (old 'read') won't preclude 'reap' and 'select'. . A duplicate enumerator was found dealing with locked resident pages. So, the name VM_LOCK was eliminated in favor of VM_RSS_LOCKED, which is way more descriptive. . The struct address returned to callers following any reap() or select() is now more sharable as pids_fetch. . Some input parameter names were changed to make them more descriptive of the intended purpose/requirements. ------------------------------------------------------ Internally, there were numerous implementation changes made that did not directly impact any potential users. . That #define FPRINT_STACKS was eliminated along with the associated supporting function and its invocation. . Addresses returned following 'reap' or 'select' will now be NULL delimited, so one has the option of stacks access via the total count or this new NULL fencepost. . Input params were simplified and generalized in both oldproc_open() & close() to enable more than 1 PROCTAB to be open simultaneously, which was required for get. . The PROCPS_PIDS_logical_end enum was relocated after the Item_table making the need to keep it synchronized more apparent (if the table expands it's right there). . The 'Public function' section of the source file was subdivided into 1) the three basic required functions; and 2) functions that can sometimes vary between APIs. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-05-14 10:30:00 +05:30
int numthese,
library: changed use of 'fill' to 'select', <pids> API Remove a remnant of this new API's evolution. Here we no longer fill stacks, rather we reap and select them. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-04-18 10:30:00 +05:30
enum pids_select_type which);
library: normalize the <pids> fill/selection interface After wrestling with the conversion of both top and ps the differences between reap (all) & fill (select) has become increasingly inconvenient. So this patch simply normalizes that API making returned results identical. The former procps_pids_stacks_fill identifier will now be known as procps_pids_select which serves as logical counterpart to the existing procps_pids_reap function. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-10-01 10:30:00 +05:30
library: rename the 'procps_pids_stacks_sort' function The above function was the sole public function in the <pids> interface to use the word 'stacks' in its name. All of the others dealt exclusively with their duties, So this commit normalizes that outlier by renaming it. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-10-11 10:30:00 +05:30
struct pids_stack **procps_pids_sort (
library: standardize all the 'context' structure names This patch attempts to standardize the naming of those most important (declared not defined) context structs. The present practice represents a hodge podge of names only some of which reflect the source /proc file name. And 2 of those file names embed a literal 'info' which is likely the origin of that required parm identifier. Now we'll append a universal '_info' to such structure names, while including the names of those /proc pseudo files where possible. In any case, that context struct will *always* begin with the actual module/header file name. And only the following two sound a little weird! ---------> 'meminfo_info' + 'slabinfo_info' <--------- Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-21 10:30:00 +05:30
struct pids_info *info,
library: miscellaneous tweaks to pid code and comments . traded a complex misaligned memory allocation scheme in the make_hist function for a simple aligned scheme. plus memory allocation increases are globally defined. . changed 1 parameter for procps_pids_stacks_sort() to better reflect the 'array of pointers', not an address of a pointer as is used with guys such as 'new/unref'. . the pids_reap struct was changed slightly to make it more reflective of it's actual implementation details. . the Item_table member .mustfree is now .needfree and that .makehist was now made .needhist for consistency. . reduced the number of separate 'return NULL;' source statements in that primary procps_pids_reap() routine. . ensured consistent reference to sizeof(void *) & not occasional reference to sizeof(void*) without a space. . rather than enable/disable validate_stacks via a #if in the function body, it is now handled via a #define. . some comments in the procps_pids_reset function were adjusted to reflect this current implementation. shown originally, they reflected an aborted attempt to avoid a testing aberration not fully understood at the time. . added a summary of the memory overhead cost of HST_t processing to that UNREF_RPTHASH output at unref time. . a 'PIDs at max depth:' portion of that UNREF_RPTHASH enabled #define is now published only when the maximum depth of hash table entry chains exceed depths of one. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-08-20 10:30:00 +05:30
struct pids_stack *stacks[],
library: implement task/thread support via the new api This commit is the culmination of efforts to modernize the library api. It should be treated as a first blush attempt, especially since I have absolutely no library design experience. But I did have a very strong desire to lessen the new library's impact on the top program. Under this new api, a 'stack' is the equivalent of the old proc_t. It can be seen as a variable length record whose contents & order is under complete user control. That initial stack/record configuration is established at procps_pids_new() time and will probably serve most program needs. But, a dynamic & demanding program like top will later change a stack via procps_pids_reset(). For programs like top & ps, procps_pids_reap() will be the function that will retrieve all tasks and threads. Any program that needs to filter / select only certain processes or users have available other functions that can be used: procps_pids_stacks_alloc, fill & dealloc. This implementation attempts to maximize that existing proven libprocps code base. As we gain more experience such actual code can be migrated into the pids.c file. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-08-19 10:30:00 +05:30
int numstacked,
library: standardize portions of interface, <PIDS> api This represents a rather major interface redesign. The following highlights most of the changes/enhancements. . The 'read' interface (employed by pgrep & pidof) saw the biggest change. The 'open', 'next' and 'shut' guys all went bye-bye, replaced by a single 'get' function. . The items specified at 'new' time no longer serve as the maximum. In fact, items & numitems are now treated as optional, should callers prefer to wait until later when the 'reset' function would then become mandatory. . Even at 'reset' time, the stacks are not tied to any sort of maximum. They will grow dynamically as needed. . The order of some parameters was changed to parallel that found in our other APIs. Specifically, when items & numitems are needed they're specified in that order. . A user will no longer be prevented from concurrently employing any accessor functions. In other words, that 'get' (old 'read') won't preclude 'reap' and 'select'. . A duplicate enumerator was found dealing with locked resident pages. So, the name VM_LOCK was eliminated in favor of VM_RSS_LOCKED, which is way more descriptive. . The struct address returned to callers following any reap() or select() is now more sharable as pids_fetch. . Some input parameter names were changed to make them more descriptive of the intended purpose/requirements. ------------------------------------------------------ Internally, there were numerous implementation changes made that did not directly impact any potential users. . That #define FPRINT_STACKS was eliminated along with the associated supporting function and its invocation. . Addresses returned following 'reap' or 'select' will now be NULL delimited, so one has the option of stacks access via the total count or this new NULL fencepost. . Input params were simplified and generalized in both oldproc_open() & close() to enable more than 1 PROCTAB to be open simultaneously, which was required for get. . The PROCPS_PIDS_logical_end enum was relocated after the Item_table making the need to keep it synchronized more apparent (if the table expands it's right there). . The 'Public function' section of the source file was subdivided into 1) the three basic required functions; and 2) functions that can sometimes vary between APIs. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-05-14 10:30:00 +05:30
enum pids_item sortitem,
library: implement task/thread support via the new api This commit is the culmination of efforts to modernize the library api. It should be treated as a first blush attempt, especially since I have absolutely no library design experience. But I did have a very strong desire to lessen the new library's impact on the top program. Under this new api, a 'stack' is the equivalent of the old proc_t. It can be seen as a variable length record whose contents & order is under complete user control. That initial stack/record configuration is established at procps_pids_new() time and will probably serve most program needs. But, a dynamic & demanding program like top will later change a stack via procps_pids_reset(). For programs like top & ps, procps_pids_reap() will be the function that will retrieve all tasks and threads. Any program that needs to filter / select only certain processes or users have available other functions that can be used: procps_pids_stacks_alloc, fill & dealloc. This implementation attempts to maximize that existing proven libprocps code base. As we gain more experience such actual code can be migrated into the pids.c file. Signed-off-by: Jim Warner <james.warner@comcast.net>
2015-08-19 10:30:00 +05:30
enum pids_sort_order order);
library: refactor the XTRA_PROCPS_DEBUG implementation If we ever were to eliminate the procps.h header file, as discussed in the thread referenced below, then that would impair the current XTRA_PROCPS_DEBUG provisions. The only remaining way to verify result types would be to explicitly include that <proc/xtra-procps-debug.h>. So, this commit will once again enable the ./configure provision for defining the -DXTRA_PROCPS_DEBUG option. Reference(s): https://www.freelists.org/post/procps/newlib-Qualys-patches,6 Signed-off-by: Jim Warner <james.warner@comcast.net>
2018-09-01 10:30:00 +05:30
#ifdef XTRA_PROCPS_DEBUG
library: ensure 'XTRA_PROCPS_DEBUG' works in real life This commit attempts to smooth some wrinkles impacting any future libprocps user exploitation. The 2 problems relate exclusively to our XTRA_PROCPS_DEBUG provision. 1. The 'xtra-procps-debug.h' header had an include for 'procps-private.h', which was not an installed header. So the STRINGIFY macros will now be embedded directly. 2. Each of the new api headers referenced '<proc/...>' rather than '<procps/...>' for the debugging #include. So, we must drop that prefix in favor of a quoted file name so that debugging builds work regardless of where that 'xtra-procps-debug.h' header happens to be found. Reference(s): . Jun, 2020 - changed target install directory commit d64755ea5f48295f5b064da0ea667ee3503b4cd8 . Sep, 2018 - #include migrated from procps.h commit fab37662efe92650063a45e6b20eda09afe07e14 Signed-off-by: Jim Warner <james.warner@comcast.net>
2020-07-25 10:30:00 +05:30
# include "xtra-procps-debug.h"
library: refactor the XTRA_PROCPS_DEBUG implementation If we ever were to eliminate the procps.h header file, as discussed in the thread referenced below, then that would impair the current XTRA_PROCPS_DEBUG provisions. The only remaining way to verify result types would be to explicitly include that <proc/xtra-procps-debug.h>. So, this commit will once again enable the ./configure provision for defining the -DXTRA_PROCPS_DEBUG option. Reference(s): https://www.freelists.org/post/procps/newlib-Qualys-patches,6 Signed-off-by: Jim Warner <james.warner@comcast.net>
2018-09-01 10:30:00 +05:30
#endif
library: replace the troublesome '__BEGIN_DECLS' macro When 'newlib' was introduced, in the commit referenced below, the use of that glibc '__BEGIN_DECLS' macro was standardized. However, as issue #88 revealed, this may result in a fatal build error with other environments. So, this patch just trades that macro for the standard '#ifdef __cplusplus' conventions (thus avoiding use of all those '#include <features.h>' directives as well). Reference(s): . newlib introduced commit a410e236abb47c7c43194e61d0566686f81513af . procps-ng-3.3.13 issue https://gitlab.com/procps-ng/procps/issues/88 . some additional discussion https://www.freelists.org/post/procps/PATCH-Replace-glibcspecific-macros-in-procnumah,1 . musl wiki (see: sys/cdefs.h error messages) https://wiki.musl-libc.org/faq.html Signed-off-by: Jim Warner <james.warner@comcast.net>
2018-04-06 10:30:00 +05:30
#ifdef __cplusplus
}
#endif
library: strictly cosmetic, absolutely no code changes This commit just contains some tweaks to comments plus a few adjustments to whitespace for alignment purposes and a normalization of the header inclusion #define's. [ plus a spelling error in one header file was fixed ] Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-09-28 20:40:10 +05:30
#endif
Reference in New Issue Copy Permalink