{
    "mode": "man",
    "parameter": "procps",
    "section": "3",
    "url": "https://www.chedong.com/phpMan.php/man/procps/3/json",
    "generated": "2026-10-04T08:52:10Z",
    "synopsis": "Five  distinct  interfaces  are  represented  in this synopsis and named after the files they\naccess in the /proc pseudo filesystem: diskstats, meminfo, slabinfo, stat and vmstat.\n#include <libproc2/namedinterface.h>\nint procpsnew   (struct info info);\nint procpsref   (struct info  *info);\nint procpsunref (struct info info);\nstruct result *procpsget (\nstruct info *info,\n[   const char *name,      ]   diskstats api only\nenum item item);\nstruct stack *procpsselect (\nstruct info *info,\n[   const char *name,      ]   diskstats api only\nenum item *items,\nint numitems);\nstruct reaped *procpsreap (\nstruct info *info,\n[   enum reaptype what,   ]   stat api only\nenum item *items,\nint numitems);\nstruct stack procpssort (\nstruct info *info,\nstruct stack *stacks[],\nint numstacked,\nenum item sortitem,\nenum sortorder order);\nThe above functions and structures are generic but  the  specific  namedinterface  would\nalso   be  part  of  any  identifiers.   For  example,  `procpsnew'  would  actually  be\n`procpsmeminfonew' and `info' would really be `diskstatsinfo', etc.\nThe same namedinterface is used in each header file name with an appended `.h' suffix.\nLink with -lproc2.",
    "sections": {
        "NAME": {
            "content": "procps - API to access system level information in the /proc filesystem\n\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "Five  distinct  interfaces  are  represented  in this synopsis and named after the files they\naccess in the /proc pseudo filesystem: diskstats, meminfo, slabinfo, stat and vmstat.\n\n#include <libproc2/namedinterface.h>\n\nint procpsnew   (struct info info);\nint procpsref   (struct info  *info);\nint procpsunref (struct info info);\n\nstruct result *procpsget (\nstruct info *info,\n[   const char *name,      ]   diskstats api only\nenum item item);\n\nstruct stack *procpsselect (\nstruct info *info,\n[   const char *name,      ]   diskstats api only\nenum item *items,\nint numitems);\n\nstruct reaped *procpsreap (\nstruct info *info,\n[   enum reaptype what,   ]   stat api only\nenum item *items,\nint numitems);\n\nstruct stack procpssort (\nstruct info *info,\nstruct stack *stacks[],\nint numstacked,\nenum item sortitem,\nenum sortorder order);\n\n\nThe above functions and structures are generic but  the  specific  namedinterface  would\nalso   be  part  of  any  identifiers.   For  example,  `procpsnew'  would  actually  be\n`procpsmeminfonew' and `info' would really be `diskstatsinfo', etc.\n\nThe same namedinterface is used in each header file name with an appended `.h' suffix.\n\nLink with -lproc2.\n\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "",
            "subsections": [
                {
                    "name": "Overview",
                    "content": "Central to these interfaces is a simple `result' structure  reflecting  an  `item'  plus  its\nvalue  (in  a  union with standard C language types as members).  All `result' structures are\nautomatically allocated and provided by the library.\n\nBy specifying an  array  of  `items',  these  structures  can  be  organized  as  a  `stack',\npotentially yielding many results with a single function call.  Thus, a `stack' can be viewed\nas a variable length record whose content and order is determined solely by the user.\n\nAs  part  of  each  interface there are two unique enumerators.  The `noop' and `extra' items\nexist to hold user values.  They are never set by the library, but the `extra' result will be\nzeroed with each library interaction.\n\nThe  namedinterface  header  file  will  be  an  essential  document  during  user   program\ndevelopment.   There  you  will  find available items, their return type (the `result' struct\nmember name) and the source for such values.  Additional enumerators and structures are  also\ndocumented there.\n\n"
                },
                {
                    "name": "Usage",
                    "content": "The following would be a typical sequence of calls to these interfaces.\n\n1. procpsnew()\n2. procpsget(), procpsselect() or procpsreap()\n3. procpsunref()\n\nThe   get   function  is  used  to  retrieve  a  `result'  structure  for  a  single  `item'.\nAlternatively, a GET macro is available when only the return value is of interest.\n\nThe select function can retrieve multiple `result' structures in a single `stack'.\n\nFor unpredictable variable outcomes, the diskstats, slabinfo and  stat  interfaces  export  a\nreap  function.   It  is used to retrieve multiple `stacks' each containing multiple `result'\nstructures.  Optionally, a user may choose to sort those results.\n\nTo exploit any `stack',  and  access  individual  `result'  structures,  a  relativeenum  is\nrequired  as  shown  in  the VAL macro defined in the header file.  Such values could be hard\ncoded as: 0 through numitems-1.  However, this need is typically satisfied by  creating  your\nown enumerators corresponding to the order of the `items' array.\n\n"
                },
                {
                    "name": "Caveats",
                    "content": "The new, ref, unref, get and select functions are available in all five interfaces.\n\nFor  the  new  and  unref  functions, the address of an info struct pointer must be supplied.\nWith new it must have been initialized to NULL.  With unref it will be reset to NULL  if  the\nreference count reaches zero.\n\nIn  the  case  of  the  diskstats interface, a name parameter on the get and select functions\nidentifies a disk or partition name\n\nFor the stat interface, a what parameter on the reap function  identifies  whether  data  for\njust CPUs or both CPUs and NUMA nodes is to be gathered.\n\nWhen  using  the  sort function, the parameters stacks and numstacked would normally be those\nreturned in the `reaped' structure.\n\n"
                }
            ]
        },
        "RETURN VALUE": {
            "content": "",
            "subsections": [
                {
                    "name": "Functions Returning an `int'",
                    "content": "An error will be indicated by a negative number that is always the inverse of some well known\nerrno.h value.\n\nSuccess is indicated by a zero return value.  However, the ref and unref functions return the\ncurrent info structure reference count.\n\n"
                },
                {
                    "name": "Functions Returning an `address'",
                    "content": "An error will be indicated by a NULL return pointer with the reason found in the formal errno\nvalue.\n\nSuccess is indicated by a pointer to the named structure.\n\n"
                }
            ]
        },
        "DEBUGGING": {
            "content": "To aid in program development, there is a provision that  can  help  ensure  `result'  member\nreferences  agree  with library expectations.  It assumes that a supplied macro in the header\nfile is used to access the `result' value.\n\nThis feature can be activated through either of the following methods and  any  discrepancies\nwill be written to stderr.\n\n\n1) Add CFLAGS='-DXTRAPROCPSDEBUG' to any other ./configure options employed.\n\n\n2) Add  #include  <procps/xtra-procps-debug.h>  to  any  program  after  the  named interface\nincludes.\n\n\nThis verification feature incurs substantial overhead.  Therefore, it is  important  that  it\nnot be activated for a production/release build.\n\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "procpsmisc(3), procpspids(3), proc(5).\n\nlibproc2                                     August 2022                                   PROCPS(3)",
            "subsections": []
        }
    },
    "summary": "procps - API to access system level information in the /proc filesystem",
    "flags": [],
    "examples": [],
    "see_also": [
        {
            "name": "procpsmisc",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/procpsmisc/3/json"
        },
        {
            "name": "procpspids",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/procpspids/3/json"
        },
        {
            "name": "proc",
            "section": "5",
            "url": "https://www.chedong.com/phpMan.php/man/proc/5/json"
        }
    ]
}