{ "mode": "man", "parameter": "procps_pids", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/procps_pids/3/json", "generated": "2026-10-05T17:07:52Z", "synopsis": "#include \nint procpspidsnew (struct pidsinfo info, enum pidsitem *items, int numitems);\nint procpspidsref (struct pidsinfo *info);\nint procpspidsunref (struct pidsinfo info);\nstruct pidsstack *procpspidsget (\nstruct pidsinfo *info,\nenum pidsfetchtype which);\nstruct pidsfetch *procpspidsreap (\nstruct pidsinfo *info,\nenum pidsfetchtype which);\nstruct pidsfetch *procpspidsselect (\nstruct pidsinfo *info,\nunsigned *these,\nint numthese,\nenum pidsselecttype which);\nstruct pidsstack procpspidssort (\nstruct pidsinfo *info,\nstruct pidsstack *stacks[],\nint numstacked,\nenum pidsitem sortitem,\nenum pidssortorder order);\nint procpspidsreset (\nstruct pidsinfo *info,\nenum pidsitem *newitems,\nint newnumitems);\nstruct pidsstack *fatalprocunmounted (\nstruct pidsinfo *info,\nint returnself);\nLink with -lproc2.", "sections": { "NAME": { "content": "procpspids - API to access process information in the /proc filesystem\n\n", "subsections": [] }, "SYNOPSIS": { "content": "#include \n\nint procpspidsnew (struct pidsinfo info, enum pidsitem *items, int numitems);\nint procpspidsref (struct pidsinfo *info);\nint procpspidsunref (struct pidsinfo info);\n\n\nstruct pidsstack *procpspidsget (\nstruct pidsinfo *info,\nenum pidsfetchtype which);\n\nstruct pidsfetch *procpspidsreap (\nstruct pidsinfo *info,\nenum pidsfetchtype which);\n\nstruct pidsfetch *procpspidsselect (\nstruct pidsinfo *info,\nunsigned *these,\nint numthese,\nenum pidsselecttype which);\n\nstruct pidsstack procpspidssort (\nstruct pidsinfo *info,\nstruct pidsstack *stacks[],\nint numstacked,\nenum pidsitem sortitem,\nenum pidssortorder order);\n\nint procpspidsreset (\nstruct pidsinfo *info,\nenum pidsitem *newitems,\nint newnumitems);\n\nstruct pidsstack *fatalprocunmounted (\nstruct pidsinfo *info,\nint returnself);\n\n\nLink with -lproc2.\n\n", "subsections": [] }, "DESCRIPTION": { "content": "", "subsections": [ { "name": "Overview", "content": "Central to this interface is a simple `result' structure reflecting an `item' plus its value\n(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 this 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 pids.h file will be an essential document during user program development. There you\nwill find available items, their return type (the `result' struct member name) and the source\nfor such values. Additional enumerators and structures are also documented there.\n\n" }, { "name": "Usage", "content": "The following would be a typical sequence of calls to this interface.\n\n1. fatalprocunmounted()\n2. procpspidsnew()\n3. procpspidsget(), procpspidsreap() or procpspidsselect()\n4. procpspidsunref()\n\nThe get function is an iterator for successive PIDs/TIDs, returning those `items' previously\nidentified via new or reset.\n\nTwo functions support unpredictable variable outcomes. The reap function gathers data for\nall processes while the select function deals with specific PIDs or UIDs. Both can return\nmultiple `stacks' each containing multiple `result' structures. Optionally, a user may\nchoose to sort such 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 API differs from others in that those items of interest must be provided at new or\nreset time, the latter being unique to this API. If either the items or numitems parameter\nis zero at new time, then reset becomes mandatory before issuing any other call.\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\nThe get and reap functions use the which parameter to specify whether just tasks or both\ntasks and threads are to be fetched.\n\nThe select function requires an array of PIDs or UIDs as these along with numthese to\nidentify which processes are to be fetched. This function then operates as a subset of reap.\n\nWhen using the sort function, the parameters stacks and numstacked would normally be those\nreturned in the `pidsfetch' structure.\n\nLastly, a fatalprocunmounted function may be called before any other function to ensure\nthat the /proc/ directory is mounted. As such, the info parameter would be NULL and the\nreturnself parameter zero. If, however, some items are desired for the issuing program (a\nreturnself other than zero) then the new call must precede it to identify the items and\nobtain the required info pointer.\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. However, if one survives the\nfatalprocunmounted call, NULL is always returned when returnself is zero.\n\n" } ] }, "DEBUGGING": { "content": "To aid in program development, there are two procps-ng provisions that can be exploited.\n\nThe first is a supplied file named `libproc.supp' which may be useful when developing a\nmulti-threaded application. When used with the valgrind `--suppressions=' option, warnings\nassociated with the procps library itself are avoided.\n\nSuch warnings arise because the library handles heap based allocations in a thread-safe\nmanner. A single-threaded application will not receive those warnings.\n\nThe second provision can help ensure `result' member references agree with library\nexpectations. It assumes that a supplied macro in the header file is used to access the\n`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 your project may employ.\n\n\n2) Add #include to any program after the #include\n.\n\n\nThis verification feature incurs substantial overhead. Therefore, it is important that it\nnot be activated for a production/release build.\n\n\nENVIRONMENT VARIABLE(S)\nThe value set for the following is unimportant, just its presence.\n\n\nLIBPROCHIDEKERNEL\nThis will hide kernel threads which would otherwise be returned with a\nprocpspidsget, procpspidsselect or procpspidsreap call.\n\n", "subsections": [] }, "SEE ALSO": { "content": "procps(3), procpsmisc(3), proc(5).\n\nlibproc2 August 2022 PROCPSPIDS(3)", "subsections": [] } }, "summary": "procpspids - API to access process information in the /proc filesystem", "flags": [], "examples": [], "see_also": [ { "name": "procps", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/procps/3/json" }, { "name": "procpsmisc", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/procpsmisc/3/json" }, { "name": "proc", "section": "5", "url": "https://www.chedong.com/phpMan.php/man/proc/5/json" } ] }