procps/proc/diskstats.h

138 lines
4.5 KiB
C
Raw Normal View History

/*
* diskstat.c - disk I/O related declarations for libprocps
*
* Copyright (c) 2003 Fabian Frederick
* Copyright (C) 2003 Albert Cahalan
2021-01-21 12:07:48 +05:30
* Copyright (C) 2015 Craig Small <csmall@dropbear.xyz>
* Copyright (C) 2016-2022 Jim Warner <james.warner@comcast.net>
*
* 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
*/
#ifndef PROCPS_DISKSTATS_H
#define PROCPS_DISKSTATS_H
#ifdef __cplusplus
extern "C" {
#endif
library: normalize/standardize an i/f, <DISKSTATS> api This patch will bring this interface up to our 3rd gen standards. The following summarizes the major changes. * New delta provisions have been added to most fields. There are, of course, some fields for which a delta is inappropriate. They include the identifying items such as name, type, major and minor. Plus the io_inprogress field which already acts, in effect, as a delta value. * To provide delta support, dev_node historical values have become persistent. By the same token, the library must provide for future removal of disks/partitions. A timestamp is used to detect 'stale' data which will be deleted so as not to satisfy some get, select or reap. * Such persistent support is provided by a linked list which, by default, grows from the bottom down so as to maintain compatibility with the /proc/diskstats order. Initially, I was tempted to use the GNU tsearch (tree) provisions until I discovered the overhead of building that tree plus costs of a subsequent 'twalk'. Besides, walking such a tree means retrieval order would differ from an order required/expected by the vmstat program. * The '/sys/block' directory is no longer scanned with every refresh cycle. Rather, it's only accessed when a node is first encountered. Then, that node's 'type' is persistent for its lifetime like several other fields. * A sort provision was included, at virtually no cost, even though such a provision was not currently needed. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-20 10:30:00 +05:30
enum diskstats_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
DISKSTATS_noop, // ( never altered )
DISKSTATS_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: 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
DISKSTATS_NAME, // str /proc/diskstats
DISKSTATS_TYPE, // s_int "
DISKSTATS_MAJOR, // s_int "
DISKSTATS_MINOR, // s_int "
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: 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
DISKSTATS_READS, // ul_int "
DISKSTATS_READS_MERGED, // ul_int "
DISKSTATS_READ_SECTORS, // ul_int "
DISKSTATS_READ_TIME, // ul_int "
DISKSTATS_WRITES, // ul_int "
DISKSTATS_WRITES_MERGED, // ul_int "
DISKSTATS_WRITE_SECTORS, // ul_int "
DISKSTATS_WRITE_TIME, // ul_int "
DISKSTATS_IO_TIME, // ul_int "
DISKSTATS_WEIGHTED_TIME, // ul_int "
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: 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
DISKSTATS_IO_INPROGRESS, // s_int "
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: 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
DISKSTATS_DELTA_READS, // s_int derived from above
DISKSTATS_DELTA_READS_MERGED, // s_int "
DISKSTATS_DELTA_READ_SECTORS, // s_int "
DISKSTATS_DELTA_READ_TIME, // s_int "
DISKSTATS_DELTA_WRITES, // s_int "
DISKSTATS_DELTA_WRITES_MERGED, // s_int "
DISKSTATS_DELTA_WRITE_SECTORS, // s_int "
DISKSTATS_DELTA_WRITE_TIME, // s_int "
DISKSTATS_DELTA_IO_TIME, // s_int "
DISKSTATS_DELTA_WEIGHTED_TIME // s_int "
library: normalize/standardize an i/f, <DISKSTATS> api This patch will bring this interface up to our 3rd gen standards. The following summarizes the major changes. * New delta provisions have been added to most fields. There are, of course, some fields for which a delta is inappropriate. They include the identifying items such as name, type, major and minor. Plus the io_inprogress field which already acts, in effect, as a delta value. * To provide delta support, dev_node historical values have become persistent. By the same token, the library must provide for future removal of disks/partitions. A timestamp is used to detect 'stale' data which will be deleted so as not to satisfy some get, select or reap. * Such persistent support is provided by a linked list which, by default, grows from the bottom down so as to maintain compatibility with the /proc/diskstats order. Initially, I was tempted to use the GNU tsearch (tree) provisions until I discovered the overhead of building that tree plus costs of a subsequent 'twalk'. Besides, walking such a tree means retrieval order would differ from an order required/expected by the vmstat program. * The '/sys/block' directory is no longer scanned with every refresh cycle. Rather, it's only accessed when a node is first encountered. Then, that node's 'type' is persistent for its lifetime like several other fields. * A sort provision was included, at virtually no cost, even though such a provision was not currently needed. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-20 10:30:00 +05:30
};
enum diskstats_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
DISKSTATS_SORT_ASCEND = +1,
DISKSTATS_SORT_DESCEND = -1
library: normalize/standardize an i/f, <DISKSTATS> api This patch will bring this interface up to our 3rd gen standards. The following summarizes the major changes. * New delta provisions have been added to most fields. There are, of course, some fields for which a delta is inappropriate. They include the identifying items such as name, type, major and minor. Plus the io_inprogress field which already acts, in effect, as a delta value. * To provide delta support, dev_node historical values have become persistent. By the same token, the library must provide for future removal of disks/partitions. A timestamp is used to detect 'stale' data which will be deleted so as not to satisfy some get, select or reap. * Such persistent support is provided by a linked list which, by default, grows from the bottom down so as to maintain compatibility with the /proc/diskstats order. Initially, I was tempted to use the GNU tsearch (tree) provisions until I discovered the overhead of building that tree plus costs of a subsequent 'twalk'. Besides, walking such a tree means retrieval order would differ from an order required/expected by the vmstat program. * The '/sys/block' directory is no longer scanned with every refresh cycle. Rather, it's only accessed when a node is first encountered. Then, that node's 'type' is persistent for its lifetime like several other fields. * A sort provision was included, at virtually no cost, even though such a provision was not currently needed. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-20 10:30:00 +05:30
};
struct diskstats_result {
enum diskstats_item item;
union {
signed int s_int;
unsigned long ul_int;
char *str;
} result;
};
library: normalize/standardize an i/f, <DISKSTATS> api This patch will bring this interface up to our 3rd gen standards. The following summarizes the major changes. * New delta provisions have been added to most fields. There are, of course, some fields for which a delta is inappropriate. They include the identifying items such as name, type, major and minor. Plus the io_inprogress field which already acts, in effect, as a delta value. * To provide delta support, dev_node historical values have become persistent. By the same token, the library must provide for future removal of disks/partitions. A timestamp is used to detect 'stale' data which will be deleted so as not to satisfy some get, select or reap. * Such persistent support is provided by a linked list which, by default, grows from the bottom down so as to maintain compatibility with the /proc/diskstats order. Initially, I was tempted to use the GNU tsearch (tree) provisions until I discovered the overhead of building that tree plus costs of a subsequent 'twalk'. Besides, walking such a tree means retrieval order would differ from an order required/expected by the vmstat program. * The '/sys/block' directory is no longer scanned with every refresh cycle. Rather, it's only accessed when a node is first encountered. Then, that node's 'type' is persistent for its lifetime like several other fields. * A sort provision was included, at virtually no cost, even though such a provision was not currently needed. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-20 10:30:00 +05:30
struct diskstats_stack {
struct diskstats_result *head;
};
struct diskstats_reaped {
library: normalize/standardize an i/f, <DISKSTATS> api This patch will bring this interface up to our 3rd gen standards. The following summarizes the major changes. * New delta provisions have been added to most fields. There are, of course, some fields for which a delta is inappropriate. They include the identifying items such as name, type, major and minor. Plus the io_inprogress field which already acts, in effect, as a delta value. * To provide delta support, dev_node historical values have become persistent. By the same token, the library must provide for future removal of disks/partitions. A timestamp is used to detect 'stale' data which will be deleted so as not to satisfy some get, select or reap. * Such persistent support is provided by a linked list which, by default, grows from the bottom down so as to maintain compatibility with the /proc/diskstats order. Initially, I was tempted to use the GNU tsearch (tree) provisions until I discovered the overhead of building that tree plus costs of a subsequent 'twalk'. Besides, walking such a tree means retrieval order would differ from an order required/expected by the vmstat program. * The '/sys/block' directory is no longer scanned with every refresh cycle. Rather, it's only accessed when a node is first encountered. Then, that node's 'type' is persistent for its lifetime like several other fields. * A sort provision was included, at virtually no cost, even though such a provision was not currently needed. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-20 10:30:00 +05:30
int total;
struct diskstats_stack **stacks;
};
struct diskstats_info;
library: normalize/standardize an i/f, <DISKSTATS> api This patch will bring this interface up to our 3rd gen standards. The following summarizes the major changes. * New delta provisions have been added to most fields. There are, of course, some fields for which a delta is inappropriate. They include the identifying items such as name, type, major and minor. Plus the io_inprogress field which already acts, in effect, as a delta value. * To provide delta support, dev_node historical values have become persistent. By the same token, the library must provide for future removal of disks/partitions. A timestamp is used to detect 'stale' data which will be deleted so as not to satisfy some get, select or reap. * Such persistent support is provided by a linked list which, by default, grows from the bottom down so as to maintain compatibility with the /proc/diskstats order. Initially, I was tempted to use the GNU tsearch (tree) provisions until I discovered the overhead of building that tree plus costs of a subsequent 'twalk'. Besides, walking such a tree means retrieval order would differ from an order required/expected by the vmstat program. * The '/sys/block' directory is no longer scanned with every refresh cycle. Rather, it's only accessed when a node is first encountered. Then, that node's 'type' is persistent for its lifetime like several other fields. * A sort provision was included, at virtually no cost, even though such a provision was not currently needed. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-20 10:30:00 +05:30
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
#define DISKSTATS_TYPE_DISK -11111
#define DISKSTATS_TYPE_PARTITION -22222
library: normalize/standardize an i/f, <DISKSTATS> api This patch will bring this interface up to our 3rd gen standards. The following summarizes the major changes. * New delta provisions have been added to most fields. There are, of course, some fields for which a delta is inappropriate. They include the identifying items such as name, type, major and minor. Plus the io_inprogress field which already acts, in effect, as a delta value. * To provide delta support, dev_node historical values have become persistent. By the same token, the library must provide for future removal of disks/partitions. A timestamp is used to detect 'stale' data which will be deleted so as not to satisfy some get, select or reap. * Such persistent support is provided by a linked list which, by default, grows from the bottom down so as to maintain compatibility with the /proc/diskstats order. Initially, I was tempted to use the GNU tsearch (tree) provisions until I discovered the overhead of building that tree plus costs of a subsequent 'twalk'. Besides, walking such a tree means retrieval order would differ from an order required/expected by the vmstat program. * The '/sys/block' directory is no longer scanned with every refresh cycle. Rather, it's only accessed when a node is first encountered. Then, that node's 'type' is persistent for its lifetime like several other fields. * A sort provision was included, at virtually no cost, even though such a provision was not currently needed. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-20 10:30:00 +05:30
#define DISKSTATS_GET( info, name, actual_enum, type ) ( { \
struct diskstats_result *r = procps_diskstats_get( info, name, actual_enum ); \
r ? r->result . type : 0; } )
library: normalize/standardize an i/f, <DISKSTATS> api This patch will bring this interface up to our 3rd gen standards. The following summarizes the major changes. * New delta provisions have been added to most fields. There are, of course, some fields for which a delta is inappropriate. They include the identifying items such as name, type, major and minor. Plus the io_inprogress field which already acts, in effect, as a delta value. * To provide delta support, dev_node historical values have become persistent. By the same token, the library must provide for future removal of disks/partitions. A timestamp is used to detect 'stale' data which will be deleted so as not to satisfy some get, select or reap. * Such persistent support is provided by a linked list which, by default, grows from the bottom down so as to maintain compatibility with the /proc/diskstats order. Initially, I was tempted to use the GNU tsearch (tree) provisions until I discovered the overhead of building that tree plus costs of a subsequent 'twalk'. Besides, walking such a tree means retrieval order would differ from an order required/expected by the vmstat program. * The '/sys/block' directory is no longer scanned with every refresh cycle. Rather, it's only accessed when a node is first encountered. Then, that node's 'type' is persistent for its lifetime like several other fields. * A sort provision was included, at virtually no cost, even though such a provision was not currently needed. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-20 10:30:00 +05:30
#define DISKSTATS_VAL( relative_enum, type, stack, info ) \
library: normalize/standardize an i/f, <DISKSTATS> api This patch will bring this interface up to our 3rd gen standards. The following summarizes the major changes. * New delta provisions have been added to most fields. There are, of course, some fields for which a delta is inappropriate. They include the identifying items such as name, type, major and minor. Plus the io_inprogress field which already acts, in effect, as a delta value. * To provide delta support, dev_node historical values have become persistent. By the same token, the library must provide for future removal of disks/partitions. A timestamp is used to detect 'stale' data which will be deleted so as not to satisfy some get, select or reap. * Such persistent support is provided by a linked list which, by default, grows from the bottom down so as to maintain compatibility with the /proc/diskstats order. Initially, I was tempted to use the GNU tsearch (tree) provisions until I discovered the overhead of building that tree plus costs of a subsequent 'twalk'. Besides, walking such a tree means retrieval order would differ from an order required/expected by the vmstat program. * The '/sys/block' directory is no longer scanned with every refresh cycle. Rather, it's only accessed when a node is first encountered. Then, that node's 'type' is persistent for its lifetime like several other fields. * A sort provision was included, at virtually no cost, even though such a provision was not currently needed. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-20 10:30:00 +05:30
stack -> head [ relative_enum ] . result . type
int procps_diskstats_new (struct diskstats_info **info);
int procps_diskstats_ref (struct diskstats_info *info);
int procps_diskstats_unref (struct diskstats_info **info);
library: normalize/standardize an i/f, <DISKSTATS> api This patch will bring this interface up to our 3rd gen standards. The following summarizes the major changes. * New delta provisions have been added to most fields. There are, of course, some fields for which a delta is inappropriate. They include the identifying items such as name, type, major and minor. Plus the io_inprogress field which already acts, in effect, as a delta value. * To provide delta support, dev_node historical values have become persistent. By the same token, the library must provide for future removal of disks/partitions. A timestamp is used to detect 'stale' data which will be deleted so as not to satisfy some get, select or reap. * Such persistent support is provided by a linked list which, by default, grows from the bottom down so as to maintain compatibility with the /proc/diskstats order. Initially, I was tempted to use the GNU tsearch (tree) provisions until I discovered the overhead of building that tree plus costs of a subsequent 'twalk'. Besides, walking such a tree means retrieval order would differ from an order required/expected by the vmstat program. * The '/sys/block' directory is no longer scanned with every refresh cycle. Rather, it's only accessed when a node is first encountered. Then, that node's 'type' is persistent for its lifetime like several other fields. * A sort provision was included, at virtually no cost, even though such a provision was not currently needed. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-20 10:30:00 +05:30
struct diskstats_result *procps_diskstats_get (
struct diskstats_info *info,
library: normalize/standardize an i/f, <DISKSTATS> api This patch will bring this interface up to our 3rd gen standards. The following summarizes the major changes. * New delta provisions have been added to most fields. There are, of course, some fields for which a delta is inappropriate. They include the identifying items such as name, type, major and minor. Plus the io_inprogress field which already acts, in effect, as a delta value. * To provide delta support, dev_node historical values have become persistent. By the same token, the library must provide for future removal of disks/partitions. A timestamp is used to detect 'stale' data which will be deleted so as not to satisfy some get, select or reap. * Such persistent support is provided by a linked list which, by default, grows from the bottom down so as to maintain compatibility with the /proc/diskstats order. Initially, I was tempted to use the GNU tsearch (tree) provisions until I discovered the overhead of building that tree plus costs of a subsequent 'twalk'. Besides, walking such a tree means retrieval order would differ from an order required/expected by the vmstat program. * The '/sys/block' directory is no longer scanned with every refresh cycle. Rather, it's only accessed when a node is first encountered. Then, that node's 'type' is persistent for its lifetime like several other fields. * A sort provision was included, at virtually no cost, even though such a provision was not currently needed. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-20 10:30:00 +05:30
const char *name,
enum diskstats_item item);
struct diskstats_reaped *procps_diskstats_reap (
struct diskstats_info *info,
library: normalize/standardize an i/f, <DISKSTATS> api This patch will bring this interface up to our 3rd gen standards. The following summarizes the major changes. * New delta provisions have been added to most fields. There are, of course, some fields for which a delta is inappropriate. They include the identifying items such as name, type, major and minor. Plus the io_inprogress field which already acts, in effect, as a delta value. * To provide delta support, dev_node historical values have become persistent. By the same token, the library must provide for future removal of disks/partitions. A timestamp is used to detect 'stale' data which will be deleted so as not to satisfy some get, select or reap. * Such persistent support is provided by a linked list which, by default, grows from the bottom down so as to maintain compatibility with the /proc/diskstats order. Initially, I was tempted to use the GNU tsearch (tree) provisions until I discovered the overhead of building that tree plus costs of a subsequent 'twalk'. Besides, walking such a tree means retrieval order would differ from an order required/expected by the vmstat program. * The '/sys/block' directory is no longer scanned with every refresh cycle. Rather, it's only accessed when a node is first encountered. Then, that node's 'type' is persistent for its lifetime like several other fields. * A sort provision was included, at virtually no cost, even though such a provision was not currently needed. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-20 10:30:00 +05:30
enum diskstats_item *items,
int numitems);
library: normalize/standardize an i/f, <DISKSTATS> api This patch will bring this interface up to our 3rd gen standards. The following summarizes the major changes. * New delta provisions have been added to most fields. There are, of course, some fields for which a delta is inappropriate. They include the identifying items such as name, type, major and minor. Plus the io_inprogress field which already acts, in effect, as a delta value. * To provide delta support, dev_node historical values have become persistent. By the same token, the library must provide for future removal of disks/partitions. A timestamp is used to detect 'stale' data which will be deleted so as not to satisfy some get, select or reap. * Such persistent support is provided by a linked list which, by default, grows from the bottom down so as to maintain compatibility with the /proc/diskstats order. Initially, I was tempted to use the GNU tsearch (tree) provisions until I discovered the overhead of building that tree plus costs of a subsequent 'twalk'. Besides, walking such a tree means retrieval order would differ from an order required/expected by the vmstat program. * The '/sys/block' directory is no longer scanned with every refresh cycle. Rather, it's only accessed when a node is first encountered. Then, that node's 'type' is persistent for its lifetime like several other fields. * A sort provision was included, at virtually no cost, even though such a provision was not currently needed. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-20 10:30:00 +05:30
struct diskstats_stack *procps_diskstats_select (
struct diskstats_info *info,
library: normalize/standardize an i/f, <DISKSTATS> api This patch will bring this interface up to our 3rd gen standards. The following summarizes the major changes. * New delta provisions have been added to most fields. There are, of course, some fields for which a delta is inappropriate. They include the identifying items such as name, type, major and minor. Plus the io_inprogress field which already acts, in effect, as a delta value. * To provide delta support, dev_node historical values have become persistent. By the same token, the library must provide for future removal of disks/partitions. A timestamp is used to detect 'stale' data which will be deleted so as not to satisfy some get, select or reap. * Such persistent support is provided by a linked list which, by default, grows from the bottom down so as to maintain compatibility with the /proc/diskstats order. Initially, I was tempted to use the GNU tsearch (tree) provisions until I discovered the overhead of building that tree plus costs of a subsequent 'twalk'. Besides, walking such a tree means retrieval order would differ from an order required/expected by the vmstat program. * The '/sys/block' directory is no longer scanned with every refresh cycle. Rather, it's only accessed when a node is first encountered. Then, that node's 'type' is persistent for its lifetime like several other fields. * A sort provision was included, at virtually no cost, even though such a provision was not currently needed. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-20 10:30:00 +05:30
const char *name,
enum diskstats_item *items,
int numitems);
library: normalize/standardize an i/f, <DISKSTATS> api This patch will bring this interface up to our 3rd gen standards. The following summarizes the major changes. * New delta provisions have been added to most fields. There are, of course, some fields for which a delta is inappropriate. They include the identifying items such as name, type, major and minor. Plus the io_inprogress field which already acts, in effect, as a delta value. * To provide delta support, dev_node historical values have become persistent. By the same token, the library must provide for future removal of disks/partitions. A timestamp is used to detect 'stale' data which will be deleted so as not to satisfy some get, select or reap. * Such persistent support is provided by a linked list which, by default, grows from the bottom down so as to maintain compatibility with the /proc/diskstats order. Initially, I was tempted to use the GNU tsearch (tree) provisions until I discovered the overhead of building that tree plus costs of a subsequent 'twalk'. Besides, walking such a tree means retrieval order would differ from an order required/expected by the vmstat program. * The '/sys/block' directory is no longer scanned with every refresh cycle. Rather, it's only accessed when a node is first encountered. Then, that node's 'type' is persistent for its lifetime like several other fields. * A sort provision was included, at virtually no cost, even though such a provision was not currently needed. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-20 10:30:00 +05:30
struct diskstats_stack **procps_diskstats_sort (
struct diskstats_info *info,
library: normalize/standardize an i/f, <DISKSTATS> api This patch will bring this interface up to our 3rd gen standards. The following summarizes the major changes. * New delta provisions have been added to most fields. There are, of course, some fields for which a delta is inappropriate. They include the identifying items such as name, type, major and minor. Plus the io_inprogress field which already acts, in effect, as a delta value. * To provide delta support, dev_node historical values have become persistent. By the same token, the library must provide for future removal of disks/partitions. A timestamp is used to detect 'stale' data which will be deleted so as not to satisfy some get, select or reap. * Such persistent support is provided by a linked list which, by default, grows from the bottom down so as to maintain compatibility with the /proc/diskstats order. Initially, I was tempted to use the GNU tsearch (tree) provisions until I discovered the overhead of building that tree plus costs of a subsequent 'twalk'. Besides, walking such a tree means retrieval order would differ from an order required/expected by the vmstat program. * The '/sys/block' directory is no longer scanned with every refresh cycle. Rather, it's only accessed when a node is first encountered. Then, that node's 'type' is persistent for its lifetime like several other fields. * A sort provision was included, at virtually no cost, even though such a provision was not currently needed. Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-20 10:30:00 +05:30
struct diskstats_stack *stacks[],
int numstacked,
enum diskstats_item sortitem,
enum diskstats_sort_order order);
#ifdef XTRA_PROCPS_DEBUG
# include "xtra-procps-debug.h"
#endif
#ifdef __cplusplus
}
#endif
#endif