PROCPS_PIDS(3)

💖 PROCPS_PIDS(3) 💖

okay bestie, gather round, because this is the procps_pids page from the Library Functions Manual (section 3, obvi) and it's literally the API to access process information in the /proc filesystem. it's giving sysadmin main character energy and i'm obsessed. let's go 🫶

---

✨ NAME ✨

procps_pids — API to access process information in the /proc filesystem

---

🌸 SYNOPSIS 🌸

#include <libproc2/pids.h>

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);

struct pids_stack *procps_pids_get (
    struct pids_info *info,
    enum pids_fetch_type which);

struct pids_fetch *procps_pids_reap (
    struct pids_info *info,
    enum pids_fetch_type which);

struct pids_fetch *procps_pids_select (
    struct pids_info *info,
    unsigned *these,
    int numthese,
    enum pids_select_type which);

struct pids_stack **procps_pids_sort (
    struct pids_info *info,
    struct pids_stack *stacks[],
    int numstacked,
    enum pids_item sortitem,
    enum pids_sort_order order);

int procps_pids_reset (
    struct pids_info *info,
    enum pids_item *newitems,
    int newnumitems);

struct pids_stack *fatal_proc_unmounted (
    struct pids_info *info,
    int return_self);

and when you link it, bestie: link with -lproc2. that's the whole vibe check right there 💅

---

🦋 DESCRIPTION 🦋

🌟 Overview 🌟

so the whole glow-up of this interface revolves around one lil 'result' structure — it's holding an 'item' plus its value (and that value lives in a union with standard C language types as members, cute right?). every single 'result' structure is automatically allocated and handed to you by the library. you don't malloc, you don't free, you just vibe. ✨

now here's the slay part: if you hand over an array of 'items', those structures get organized as a 'stack', and that stack can potentially yield so many results with just a single function call. so like, a 'stack' is basically a variable length record whose content and order is determined solely by you, the user. you're the main character of your own data structure fr fr 👑

and as part of this whole interface there are two unique enumerators — the 'noop' and 'extra' items — and they exist purely to hold user values. the library never sets them, BUT the 'extra' result will be zeroed with each library interaction. noted. 📝

the pids.h file is gonna be your essential document while you're developing, no cap. that's where you'll find the available items, their return type (that's the 'result' struct member name) and the source for such values. plus additional enumerators and structures are documented in there too. keep it open in another tab, bestie 🎀

💫 Usage 💫

here's a typical sequence of calls to this interface, in order:

1. fatal_proc_unmounted()
2. procps_pids_new()
3. procps_pids_get(), procps_pids_reap() or procps_pids_select()
4. procps_pids_unref()

the get function is an iterator for successive PIDs/TIDs, returning those 'items' you previously identified via new or reset. it's giving little conveyor belt of processes 🚂

two functions support unpredictable variable outcomes. the reap function gathers data for all processes while the select function deals with specific PIDs or UIDs. both can return multiple 'stacks', each containing multiple 'result' structures. and optionally? you can choose to sort such results. cute! 💖

to exploit any 'stack', and to access individual 'result' structures, you need a relative_enum — exactly like 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. do it the nice way, bestie 🌸

🙈 Caveats 🙈

the <pids> API differs from others in that those items of interest must be provided at new or reset time, the latter being unique to this API. and listen: if either the items or numitems parameter is zero at new time, then reset becomes mandatory before issuing any other call. otherwise, procps_pids_reset() should only be called when the order or number of items in your stacks is changed.

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 clean. so tidy. we love a well-behaved pointer 🧚

the get and reap functions use the which parameter to specify whether just tasks or both tasks and threads are to be fetched. pick your fighter.

the select function requires an array of PIDs or UIDs, since these — along with numthese — identify which processes are to be fetched. this function then operates as a subset of reap. it's reap's little sibling, lowkey 💜

when using the sort function, the parameters stacks and numstacked would normally be those returned in the 'pids_fetch' structure. like, that's just the natural flow.

lastly, a fatal_proc_unmounted function may be called before any other function to ensure that the /proc/ directory is mounted. as such, the info parameter would be NULL and the return_self parameter zero. if, however, some items are desired for the issuing program (a return_self other than zero) then the new call must precede it, to identify the items and obtain the required info pointer. got it? good. 😌

---

⭐ 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. slay. however, the ref and unref functions return the current info structure reference count — so don't get it twisted, those two are giving you a count, not just a yes/no 💅

🔥 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. however, if one survives the fatal_proc_unmounted call, NULL is always returned when return_self is zero. periodt.

---

🎀 DEBUGGING 🎀

to aid in program development, there are two procps-ng provisions that can be exploited. yes bestie, you get little helper features. we love to see it 🫶

the first is a supplied file named libproc.supp which may be useful when developing a multi-threaded application. when used with the valgrind --suppressions= option, warnings associated with the procps library itself are avoided.

such warnings arise because the library handles heap based allocations in a thread-safe manner. a single-threaded application will not receive those warnings. so if you're single-threaded and confused about where the warnings went — that's why, babe 💀

the second provision 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.

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 your project may employ.
2. Add #include <libproc2/xtra-procps-debug.h> to any program after the #include <libproc2/pids.h>.

⚠️ okay this next part is important 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. i'm serious. 🙅‍♀️

---

🌈 ENVIRONMENT VARIABLE(S) 🌈

the value set for the following is unimportant — just its presence. literally just show up, the number doesn't matter, it's giving "attend the party, don't bring a gift" energy ✨

• LIBPROC_HIDE_KERNEL — this will hide kernel threads which would otherwise be returned with a procps_pids_get, procps_pids_select or procps_pids_reap call.

---

💜 SEE ALSO 💜

procps(3), procps_misc(3), proc(5).

---

and that's the whole page, bestie 🦋 go forth and read your /proc like the icon you are. this was brought to you by procps-ng, dated 2004-09-03 — vintage, but still serving looks, just like this manual. mwah 💅💖