libutil: Improve kinfo_getproc(3) manual page

Add comprehensive documentation for struct kinfo_proc:

- Add complete C-style struct definition with types and inline comments
  showing all user-accessible fields
- Document key fields including process identifiers, credentials, memory
  statistics, runtime information, and flags
- Clarify process flag fields (ki_flag, ki_kiflag, ki_flag2) with
  examples and header file references
- Add complete, compilable example program demonstrating memory usage
  reporting
- Add CAVEATS section documenting ABI stability, machine-dependent
  fields, and portability considerations across BSD systems
- Clarify description of function behavior and memory allocation
- Add cross-references to related manual pages

The struct definition excludes internal kernel pointers and uses a
single ellipsis for additional fields, following the style of other
system structure documentation.

Signed-off-by: Vsevolod Stakhov <[email protected]>

Author: vstakhov

lib/libutil/kinfo_getproc.3

@@ -23,7 +23,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd May 10, 2020
+.Dd November 4, 2025
 .Dt KINFO_GETPROC 3
 .Os
 .Sh NAME
@@ -42,15 +42,176 @@ This function is used for obtaining process information from the kernel.
 .Pp
 The
 .Ar pid
-field contains the process identifier.
+argument specifies the process identifier.
 This should be a process that you have privilege to access.
+.Pp
 This function is a wrapper around
 .Xr sysctl 3
 with the
 .Dv KERN_PROC_PID
 mib.
-While the kernel returns a packed structure, this function expands the
-data into a fixed record format.
+It retrieves the process information from the kernel and returns it as a
+.Vt struct kinfo_proc
+allocated with
+.Xr malloc 3 .
+.Ss Process Information Structure
+The
+.Vt struct kinfo_proc
+contains numerous fields describing a process:
+.Bd -literal
+struct kinfo_proc {
+	int	ki_structsize;		/* size of this structure */
+	int	ki_layout;		/* reserved: layout identifier */
+	pid_t	ki_pid;			/* process identifier */
+	pid_t	ki_ppid;		/* parent process identifier */
+	pid_t	ki_pgid;		/* process group identifier */
+	pid_t	ki_tpgid;		/* tty process group identifier */
+	pid_t	ki_sid;			/* session identifier */
+	pid_t	ki_tsid;		/* terminal session identifier */
+	sigset_t ki_siglist;		/* signals arrived but not delivered */
+	sigset_t ki_sigmask;		/* current signal mask */
+	sigset_t ki_sigignore;		/* signals being ignored */
+	sigset_t ki_sigcatch;		/* signals being caught by user */
+	uid_t	ki_uid;			/* effective user id */
+	uid_t	ki_ruid;		/* real user id */
+	uid_t	ki_svuid;		/* saved effective user id */
+	gid_t	ki_rgid;		/* real group id */
+	gid_t	ki_svgid;		/* saved effective group id */
+	short	ki_ngroups;		/* number of groups */
+	gid_t	ki_groups[KI_NGROUPS];	/* groups */
+	vm_size_t ki_size;		/* virtual size */
+	segsz_t	ki_rssize;		/* resident set size in pages */
+	segsz_t	ki_swrss;		/* resident set size before last swap */
+	segsz_t	ki_tsize;		/* text size (pages) */
+	segsz_t	ki_dsize;		/* data size (pages) */
+	segsz_t	ki_ssize;		/* stack size (pages) */
+	u_short	ki_xstat;		/* exit status for wait & stop signal */
+	u_short	ki_acflag;		/* accounting flags */
+	fixpt_t	ki_pctcpu;		/* %cpu for process during ki_swtime */
+	u_int64_t ki_runtime;		/* real time in microsec */
+	struct	timeval ki_start;	/* starting time */
+	struct	timeval ki_childtime;	/* time used by process children */
+	long	ki_flag;		/* P_* flags */
+	long	ki_kiflag;		/* KI_* flags */
+	int	ki_traceflag;		/* kernel trace points */
+	char	ki_stat;		/* S* process status */
+	signed char ki_nice;		/* process "nice" value */
+	char	ki_lock;		/* process lock (prevent swap) count */
+	char	ki_tdname[TDNAMLEN+1];	/* thread name */
+	char	ki_wmesg[WMESGLEN+1];	/* wchan message */
+	char	ki_login[LOGNAMELEN+1];	/* setlogin name */
+	char	ki_lockname[LOCKNAMELEN+1]; /* lock name */
+	char	ki_comm[COMMLEN+1];	/* command name */
+	char	ki_emul[KI_EMULNAMELEN+1]; /* emulation name */
+	char	ki_loginclass[LOGINCLASSLEN+1]; /* login class */
+	uint64_t ki_tdev;		/* controlling tty dev */
+	int	ki_oncpu;		/* which cpu we are on (machdep) */
+	int	ki_lastcpu;		/* last cpu we were on (machdep) */
+	int	ki_tracer;		/* pid of tracing process */
+	int	ki_flag2;		/* P2_* flags */
+	int	ki_fibnum;		/* default FIB number */
+	int	ki_jid;			/* process jail ID */
+	int	ki_numthreads;		/* number of threads in total */
+	lwpid_t	ki_tid;			/* thread id */
+	struct	priority ki_pri;	/* process priority */
+	struct	rusage ki_rusage;	/* process rusage statistics */
+	struct	rusage ki_rusage_ch;	/* rusage of children processes */
+	long	ki_sflag;		/* PS_* flags */
+	...				/* additional fields */
+};
+.Ed
+.Pp
+Key fields include:
+.Bl -tag -width ".Va ki_rusage"
+.It Va ki_pid
+Process identifier.
+.It Va ki_ppid
+Parent process identifier.
+.It Va ki_pgid
+Process group identifier.
+.It Va ki_sid
+Session identifier.
+.It Va ki_uid
+Effective user ID.
+.It Va ki_ruid
+Real user ID.
+.It Va ki_rgid
+Real group ID.
+.It Va ki_comm
+Command name (up to
+.Dv COMMLEN
+characters).
+.It Va ki_stat
+Process status character.
+See
+.Xr ps 1
+for status character meanings (e.g., R=runnable, S=sleeping, Z=zombie).
+.It Va ki_flag
+Process flags indicating process state and attributes.
+Flags include
+.Dv P_TRACED
+(being traced),
+.Dv P_WEXIT
+(exiting),
+.Dv P_SUGID
+(had set-id privileges),
+.Dv P_JAILED
+(in jail), and others defined in
+.In sys/proc.h .
+.It Va ki_kiflag
+Additional kernel information flags defined in
+.In sys/user.h ,
+such as
+.Dv KI_CTTY
+(has controlling tty) and
+.Dv KI_SLEADER
+(session leader).
+.It Va ki_flag2
+Extended process flags (P2_* flags) defined in
+.In sys/proc.h ,
+including security and tracing-related flags.
+.It Va ki_nice
+Process scheduling priority.
+.It Va ki_size
+Virtual memory size in bytes.
+.It Va ki_rssize
+Resident set size in pages.
+.It Va ki_tsize
+Text (code) size in pages.
+.It Va ki_dsize
+Data size in pages.
+.It Va ki_ssize
+Stack size in pages.
+.It Va ki_start
+Process start time as a
+.Vt struct timeval .
+.It Va ki_runtime
+Accumulated runtime in microseconds.
+.It Va ki_rusage
+Resource usage statistics as a
+.Vt struct rusage .
+See
+.Xr getrusage 2
+for details.
+.It Va ki_pctcpu
+CPU usage percentage (fixed point value).
+.It Va ki_numthreads
+Number of threads in the process.
+.It Va ki_jid
+Jail ID, or 0 if not jailed.
+.It Va ki_sflag
+Process session flags.
+.It Va ki_oncpu , Va ki_lastcpu
+Current and last CPU the process ran on.
+These fields are machine-dependent.
+.El
+.Pp
+Additional fields provide signal masks, credentials, kernel addresses,
+and internal state.
+Some fields contain kernel pointers and are only meaningful within the
+kernel.
+Some fields are machine-dependent and their layout may vary across
+architectures.
 .Sh RETURN VALUES
 On success the
 .Fn kinfo_getproc
@@ -66,12 +227,91 @@ On failure the
 .Fn kinfo_getproc
 function returns
 .Dv NULL .
+.Sh EXAMPLES
+The following example retrieves and displays process memory information:
+.Bd -literal -offset indent
+#include <sys/types.h>
+#include <sys/user.h>
+#include <err.h>
+#include <libutil.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+
+int
+main(int argc, char *argv[])
+{
+	struct kinfo_proc *kp;
+	int pagesize;
+	pid_t pid;
+
+	if (argc != 2)
+		errx(1, "usage: %s pid", argv[0]);
+
+	pid = atoi(argv[1]);
+	pagesize = getpagesize();
+
+	kp = kinfo_getproc(pid);
+	if (kp == NULL)
+		err(1, "kinfo_getproc");
+
+	printf("Process %d (%s) memory usage:\\n",
+	    kp->ki_pid, kp->ki_comm);
+	printf("  Virtual size: %zu bytes\\n",
+	    (size_t)kp->ki_size);
+	printf("  Resident size: %zu KB\\n",
+	    (size_t)(kp->ki_rssize * pagesize) / 1024);
+	printf("  Text size: %zu KB\\n",
+	    (size_t)(kp->ki_tsize * pagesize) / 1024);
+	printf("  Data size: %zu KB\\n",
+	    (size_t)(kp->ki_dsize * pagesize) / 1024);
+	printf("  Stack size: %zu KB\\n",
+	    (size_t)(kp->ki_ssize * pagesize) / 1024);
+
+	free(kp);
+	return (0);
+}
+.Ed
 .Sh SEE ALSO
+.Xr ps 1 ,
+.Xr getpagesize 2 ,
+.Xr getrusage 2 ,
 .Xr free 3 ,
+.Xr kinfo_getallproc 3 ,
 .Xr malloc 3 ,
 .Xr sysctl 3
 .Sh HISTORY
 The
 .Fn kinfo_getproc
 function first appeared in
 .Fx 7.0 .
+.Sh CAVEATS
+The
+.Vt struct kinfo_proc
+structure is not a stable ABI.
+Fields may be added, removed, or reordered between
+.Fx
+releases.
+The
+.Va ki_structsize
+field should be checked to detect changes.
+.Pp
+Some structure fields are machine-dependent and may not be present
+or may have different sizes on all architectures.
+Applications that use machine-dependent fields are not portable
+across architectures.
+.Pp
+The
+.Vt struct kinfo_proc
+structure and its field names are specific to
+.Fx .
+Other BSD systems provide similar functionality but with different
+structure definitions and field names.
+Portable applications should avoid relying on the structure layout.
+.Pp
+Many fields contain kernel virtual addresses which are only meaningful
+within the kernel and should not be dereferenced by user programs.
+.Pp
+The resource usage information in
+.Va ki_rusage
+may be updated asynchronously and may not reflect instantaneous values.