LIBPROCSTAT(3)

💖 LIBPROCSTAT(3) — library interface for file and process information retrieval 💖

okay so bestie, this is the LIBPROCSTAT(3) page from the Library Functions Manual, and it is literally the backstage pass to file and process information retrieval. No cap, the vibe is library-interface excellence.

✨ NAME ✨

The whole squad, in order: procstat_close, procstat_freeadvlock, procstat_freeargv, procstat_freeauxv, procstat_freeenvv, procstat_freefiles, procstat_freegroups, procstat_freekstack, procstat_freeprocs, procstat_freeptlwpinfo, procstat_freevmmap, procstat_get_pipe_info, procstat_get_pts_info, procstat_get_sem_info, procstat_get_shm_info, procstat_get_socket_info, procstat_get_vnode_info, procstat_getadvlock, procstat_getargv, procstat_getauxv, procstat_getenvv, procstat_getfiles, procstat_getgroups, procstat_getkstack, procstat_getosrel, procstat_getpathname, procstat_getprocs, procstat_getptlwpinfo, procstat_getrlimit, procstat_getumask, procstat_getvmmap, procstat_open_core, procstat_open_kvm, and procstat_open_sysctl.

They are all here for the library interface for file and process information retrieval. Every single one is invited to the group chat, periodt.

📚 LIBRARY 📚

Library: libprocstat — yes, that is the one, bestie. 🫶

🛠️ SYNOPSIS 🛠️

okay, here is the include stack and the full prototype lineup, copied exactly because we do not mess with code:

#include <sys/param.h>
#include <sys/queue.h>
#include <sys/socket.h>
#include <libprocstat.h>

void
procstat_close(struct procstat *procstat);

void
procstat_freeadvlock(struct procstat *procstat,
    struct advlock_list *list);

void
procstat_freeargv(struct procstat *procstat);

void
procstat_freeauxv(struct procstat *procstat, Elf_Auxinfo *auxv);

void
procstat_freeenvv(struct procstat *procstat);

void
procstat_freefiles(struct procstat *procstat,
    struct filestat_list *head);

void
procstat_freegroups(struct procstat *procstat, gid_t *groups);

void
procstat_freekstack(struct procstat *procstat,
    struct kinfo_kstack *kkstp);

void
procstat_freeprocs(struct procstat *procstat, struct kinfo_proc *p);

void
procstat_freevmmap(struct procstat *procstat,
    struct kinfo_vmentry *vmmap);

void
procstat_freeptlwpinfo(struct procstat *procstat,
    struct ptrace_lwpinfo *pl);

int
procstat_get_pipe_info(struct procstat *procstat, struct filestat *fst,
    struct pipestat *pipe, char *errbuf);

int
procstat_get_pts_info(struct procstat *procstat, struct filestat *fst,
    struct ptsstat *pts, char *errbuf);

int
procstat_get_sem_info(struct procstat *procstat, struct filestat *fst,
    struct semstat *sem, char *errbuf);

int
procstat_get_shm_info(struct procstat *procstat, struct filestat *fst,
    struct shmstat *shm, char *errbuf);

int
procstat_get_socket_info(struct procstat *procstat,
    struct filestat *fst, struct sockstat *sock, char *errbuf);

int
procstat_get_vnode_info(struct procstat *procstat, struct filestat *fst,
    struct vnstat *vn, char *errbuf);

struct advlock_list *
procstat_getadvlock(struct procstat *procstat);

char **
procstat_getargv(struct procstat *procstat, const struct kinfo_proc *kp,
    size_t nchr);

Elf_Auxinfo *
procstat_getauxv(struct procstat *procstat, struct kinfo_proc *kp,
    unsigned int *count);

char **
procstat_getenvv(struct procstat *procstat, const struct kinfo_proc *kp,
    size_t nchr);

struct filestat_list *
procstat_getfiles(struct procstat *procstat, struct kinfo_proc *kp,
    int mmapped);

gid_t *
procstat_getgroups(struct procstat *procstat, struct kinfo_proc *kp,
    unsigned int *count);

struct kinfo_kstack *
procstat_getkstack(struct procstat *procstat, struct kinfo_proc *kp,
    unsigned int *count);

int
procstat_getosrel(struct procstat *procstat, struct kinfo_proc *kp,
    int *osrelp);

int
procstat_getpathname(struct procstat *procstat, struct kinfo_proc *kp,
    char *pathname, size_t maxlen);

struct kinfo_proc *
procstat_getprocs(struct procstat *procstat, int what, int arg,
    unsigned int *count);

struct ptrace_lwpinfo *
procstat_getptlwpinfo(struct procstat *procstat, unsigned int *count);

int
procstat_getrlimit(struct procstat *procstat, struct kinfo_proc *kp,
    int which, struct rlimit* rlimit);

int
procstat_getumask(struct procstat *procstat, struct kinfo_proc *kp,
    unsigned short *maskp);

struct kinfo_vmentry *
procstat_getvmmap(struct procstat *procstat, struct kinfo_proc *kp,
    unsigned int *count);

struct procstat *
procstat_open_core(const char *filename);

struct procstat *
procstat_open_kvm(const char *nlistf, const char *memf);

struct procstat *
procstat_open_sysctl(void);

That is the synopsis, and it ate. 💅

🌸 DESCRIPTION 🌸

Okay bestie, gather round, because libprocstat is the moment ✨. This library is literally the whole API for snatching up file and process info at runtime from the running kernel — it does that through the sysctl(3) library backend — and it also does post-mortem analysis through the kvm(3) library backend, or straight out of a process core(5) file, where it goes digging for statistics in those special elf(3) note sections. iykyk 💅

The procstat_open_kvm() and procstat_open_sysctl() functions use the kvm(3) or sysctl(3) library routines, respectively, to access the kernel state information that's used to retrieve process and file states. And procstat_open_core() uses elf(3) routines to get at the statistics stored as a set of notes in a process core(5) file — the kernel writes those at the exact moment the process terminates abnormally 😭.

• The filename argument is the process core file name.
• The nlistf argument is the executable image of the kernel being examined. If this argument is NULL, the currently running kernel is assumed (convenient, honestly 🫶).
• The memf argument is the kernel memory device file. If this argument is NULL, then /dev/mem is assumed.

See kvm_open(3) for more details, bestie.

These functions dynamically allocate and return a procstat structure pointer, and you use that pointer in the rest of the libprocstat library routines until the corresponding procstat_close() call comes through and cleans up all the resources allocated by the procstat_open_*() functions. Close your loops, babes ✨

---

The procstat_getprocs() function takes a pointer to the procstat structure from one of the procstat_open_*() functions and returns a dynamically allocated (sub-)set of the active processes in the kernel, filled into an array of kinfo_proc structures. The what and arg arguments make up a filtering predicate, exactly as described in the kvm_getprocs(3) function. The number of processes found comes back in the reference parameter cnt. And listen — the caller is responsible for freeing that allocated memory with a subsequent procstat_freeprocs() function call. No leaking on my watch 🙈

The procstat_getptlwpinfo() function takes a pointer to the procstat structure from the procstat_open_core() function and returns a dynamically allocated set of signals intercepted by a process in that process's core file. The number of processes found is returned in the reference parameter cnt. The caller is responsible for freeing the allocated memory with a subsequent procstat_freeptlwpinfo() function call. 🎀

The procstat_getargv() function takes a pointer to the procstat structure from one of the procstat_open_*() functions plus a pointer to a kinfo_proc structure from the array you got from procstat_getprocs(), and returns a null-terminated argument vector that corresponds to the command line arguments passed to the process. Here's the tea on nchr: it indicates the maximum number of characters, including null bytes, to use in building the strings. If that amount gets exceeded, the string causing the overflow is truncated and the partial result is returned. This is handy for programs that print only a one line summary of a command and should not copy out large amounts of text only to ignore it. If nchr is zero, no limit is imposed and all argument strings are returned. 🦋

Heads up: the values of the returned argument vector refer to strings stored in the procstat internal buffer. A subsequent call of the function with the same procstat argument will reuse that buffer.

To free the allocated memory, the procstat_freeargv() function call can be used, or it will be released on procstat_close(). Either way, you're covered 💖

The procstat_getenvv() function is similar to procstat_getargv() but returns the vector of environment strings. The caller may free the allocated memory with a subsequent procstat_freeenvv() function call.

The procstat_getauxv() function takes a pointer to the procstat structure plus a pointer to a kinfo_proc structure, and returns the auxiliary vector as a dynamically allocated array of Elf_Auxinfo elements. The caller is responsible for freeing the allocated memory with a subsequent procstat_freeauxv() function call. ✨

The procstat_getfiles() function takes a pointer to the procstat structure initialized with one of the procstat_open_*() functions plus a pointer to a kinfo_proc structure from the array obtained from procstat_getprocs(), and returns a dynamically allocated linked list of filled-in filestat_list structures, using the STAILQ macros defined in queue(3). The caller is responsible for freeing the allocated memory with a subsequent procstat_freefiles() function call. 🍓

The procstat_getgroups() function takes a pointer to the procstat structure plus a pointer to a kinfo_proc structure, and returns the process groups as a dynamically allocated array of gid_t elements. The caller is responsible for freeing the allocated memory with a subsequent procstat_freegroups() function call.

The procstat_getkstack() function takes a pointer to the procstat structure initialized with one of the procstat_open_*() functions plus a pointer to a kinfo_proc structure, and returns the kernel stacks of the process as a dynamically allocated array of kinfo_kstack structures. The caller is responsible for freeing the allocated memory with a subsequent procstat_freekstack() function call. 💜

The procstat_getosrel() function takes a pointer to the procstat structure plus a pointer to a kinfo_proc structure, and returns the osrel date in the 3rd reference parameter.

The procstat_getpathname() function takes a pointer to the procstat structure plus a pointer to a kinfo_proc structure, and copies the path of the process executable into the pathname buffer, limiting it to maxlen characters. Keep it contained, queen 👑

The procstat_getrlimit() function takes a pointer to the procstat structure plus a pointer to a kinfo_proc structure plus the resource index which, and returns the actual resource limit in the 4th reference parameter.

The procstat_getumask() function takes a pointer to the procstat structure plus a pointer to a kinfo_proc structure, and returns the process umask in the 3rd reference parameter.

The procstat_getvmmap() function takes a pointer to the procstat structure initialized with one of the procstat_open_*() functions plus a pointer to a kinfo_proc structure, and returns the VM layout of the process as a dynamically allocated array of kinfo_vmentry structures. The caller is responsible for freeing the allocated memory with a subsequent procstat_freevmmap() function call. 🌈

The procstat_getadvlock() function returns a dynamically allocated list of struct advlock structures, giving you a snapshot of the currently acquired advisory locks in the system. Both locally acquired POSIX (fcntl(2)) and BSD-style (flock(2)) locks are reported, plus locks established by remote file system protocols — all of them 🔥. For each lock, unique identifiers for the locked file and its mount point are guaranteed to be provided. And if a path for the locked file can be reconstructed, it's provided as well. The returned list must be freed with the procstat_freeadvlock() function.

---

🫶 the procstat_get_*_info family 🫶

The procstat_get_pipe_info(), procstat_get_pts_info(), procstat_get_sem_info(), procstat_get_shm_info(), procstat_get_socket_info() and procstat_get_vnode_info() functions are the ones you call to retrieve information about pipes, pseudo-terminals, semaphores, shared memory objects, sockets, and vnodes, respectively. Each of them has a similar interface API, so once you learn one you've basically learned them all, slay 💅

• The procstat argument is a pointer obtained from one of the procstat_open_*() functions.
• The filestat fst argument is an element of the STAILQ linked list as obtained from the procstat_getfiles() function.
• The filestat structure contains a fs_type field that specifies a file type, plus a corresponding function to be called among the procstat_get_*_info function family.
• The actual object is returned in the 3rd reference parameter.
• The errbuf argument indicates an actual error message in case of failure.

And here's the iconic little matching chart, bestie — match your fs_type to the right function:

• PS_FST_TYPE_FIFO → procstat_get_vnode_info
• PS_FST_TYPE_VNODE → procstat_get_vnode_info
• PS_FST_TYPE_SOCKET → procstat_get_socket_info
• PS_FST_TYPE_PIPE → procstat_get_pipe_info
• PS_FST_TYPE_PTS → procstat_get_pts_info
• PS_FST_TYPE_SEM → procstat_get_sem_info
• PS_FST_TYPE_SHM → procstat_get_shm_info

---

👑 SEE ALSO 👑

fstat(1), fuser(1), pipe(2), shm_open(2), socket(2), elf(3), kvm(3), queue(3), sem_open(3), sysctl(3), pts(4), core(5), vnode(9)

go read them, they're all main character energy fr fr 📚✨

🦋 HISTORY 🦋

The libprocstat library appeared in FreeBSD 9.0. A classic, a legend, an era 💖

💜 AUTHORS 💜

The libprocstat library was written by Stanislav Sedov <stas@FreeBSD.org>.

This manual page was written by Sergey Kandaurov <pluknet@FreeBSD.org>.

---

okay that's the whole page bestie, go forth and inspect some processes 🧚‍♀️💅 — this diva of a manpage comes from the Debian source, dated April 3, 2022, and it's filed under LIBPROCSTAT(3). periodt. ⭐