PROCPS(3)

💅 PROCPS(3) — Library Functions Manual ✨

okay so bestie, welcome to procps from the Library Functions Manual 💖 this is the one, the icon, the main character of /proc access. grab a snack, we're going in 🍓

---

🌸 NAME 🌸

procps — the API to access system level information in the /proc filesystem. periodt. no cap, that's literally the whole job 👑

---

🦋 SYNOPSIS 🦋

so there are five distinct interfaces up in here, and they're all named after the files they access in the /proc pseudo filesystem: diskstats, meminfo, slabinfo, stat and vmstat. cute, right? named after their own little homes 🏠

#include <libproc2/named_interface.h>

int procps_new   (struct info **info);
int procps_ref   (struct info  *info);
int procps_unref (struct info **info);

struct result *procps_get (
    struct info *info,
[   const char *name,      ]   diskstats api only
    enum item item);

struct stack *procps_select (
    struct info *info,
[   const char *name,      ]   diskstats api only
    enum item *items,
    int numitems);

struct reaped *procps_reap (
    struct info *info,
[   enum reap_type what,   ]   stat api only
    enum item *items,
    int numitems);

struct stack **procps_sort (
    struct info *info,
    struct stack *stacks[],
    int numstacked,
    enum item sortitem,
    enum sort_order order);

so like, the functions and structures above are generic, but the specific named_interface would also be part of any identifiers. for example, 'procps_new' would actually be 'procps_meminfo_new' and 'info' would really be 'diskstats_info', etc. it's giving build-a-bear but for function names 🧸

the same named_interface is used in each header file name with an appended '.h' suffix.

and don't forget to link with -lproc2 or nothing works, bestie, and we'd simply perish 😭

---

🌈 DESCRIPTION 🌈

✨ Overview ✨

central to these interfaces is a simple 'result' structure reflecting an 'item' plus its value (in a union with standard C language types as members). all 'result' structures are automatically allocated and provided by the library. you don't have to malloc them, she did that for you 💅

by specifying an array of 'items', these structures can be organized as a 'stack', potentially yielding many results with a single function call. so a 'stack' is basically a variable length record whose content and order is determined solely by the user. your stack, your rules 👑

as part of each interface there are two unique enumerators. the 'noop' and 'extra' items exist to hold user values. they are never set by the library, but the 'extra' result will be zeroed with each library interaction. (not me getting reset every single time 🙈)

the named_interface header file will be an essential document during user program development. there you will find available items, their return type (the 'result' struct member name) and the source for such values. additional enumerators and structures are also documented there. it's the wiki, the lore doc, the whole iceberg 🧊

🎀 Usage 🎀

the following would be a typical sequence of calls to these interfaces.

1. procps_new()
2. procps_get(), procps_select() or procps_reap()
3. procps_unref()

the get function is used to retrieve a 'result' structure for a single 'item'. alternatively, a GET macro is available when only the return value is of interest. lowkey convenient.

the select function can retrieve multiple 'result' structures in a single 'stack'.

for unpredictable variable outcomes, the diskstats, slabinfo and stat interfaces export a reap function. it is used to retrieve multiple 'stacks' each containing multiple 'result' structures. optionally, a user may choose to sort those results. chaos, but make it organized ✨

to exploit any 'stack', and access individual 'result' structures, a relative_enum is required as shown in the VAL macro defined in the header file. such values could be hard coded as: 0 through numitems-1. however, this need is typically satisfied by creating your own enumerators corresponding to the order of the 'items' array. iykyk 🌟

💀 Caveats 💀

listen bestie, this part matters, don't skip it 🙏

the new, ref, unref, get and select functions are available in all five interfaces.

for the new and unref functions, the address of an info struct pointer must be supplied. with new it must have been initialized to NULL. with unref it will be reset to NULL if the reference count reaches zero. so like, handle your pointers fr fr 🫶

in the case of the diskstats interface, a name parameter on the get and select functions identifies a disk or partition name.

with the slabinfo interface, select results are only meaningful with 'SLABS' (plural) enumerators while reap results are only meaningful with 'SLAB' (singular) enumerators. plural for select, singular for reap, do not mix them up or you will be sad 😭

for the stat interface, a what parameter on the reap function identifies whether data for just CPUs or both CPUs and NUMA nodes is to be gathered.

when using the sort function, the parameters stacks and numstacked would normally be those returned in the 'reaped' structure.

---

⭐ RETURN VALUE ⭐

💜 Functions Returning an 'int' 💜

an error will be indicated by a negative number that is always the inverse of some well known errno.h value.

success is indicated by a zero return value. however, the ref and unref functions return the current info structure reference count.

🩵 Functions Returning an 'address' 🩵

an error will be indicated by a NULL return pointer with the reason found in the formal errno value.

success is indicated by a pointer to the named structure.

---

🔍 DEBUGGING 🔍

to aid in program development, there is a provision that can help ensure 'result' member references agree with library expectations. it assumes that a supplied macro in the header file is used to access the 'result' value. it's basically a vibe check for your structs 🌸

this feature can be activated through either of the following methods and any discrepancies will be written to stderr.

1. add CFLAGS='-DXTRA_PROCPS_DEBUG' to any other ./configure options employed.
2. add #include <libproc2/xtra-procps-debug.h> to any program after the named interface includes.

⚠️ heads up bestie: this verification feature incurs substantial overhead. therefore, it is important that it not be activated for a production/release build. do not ship it. do not. i'm serious. 😤

---

👑 SEE ALSO 👑

• procps_misc(3)
• procps_pids(3)
• proc(5)

---

and that's the whole page, bestie, you ate it up 💅✨ this little love letter came to you from procps-ng, dated 2026-03-03, living its best life as page PROCPS(3) 🦋 mwah, go read your header file, it has all the lore 💖🎀🫶