git: cdd9629921c6 - main - sysctl.3: document missing oids from kern.proc. node

The branch main has been updated by kib:

URL: https://cgit.FreeBSD.org/src/commit/?id=cdd9629921c6551abac583aeafc5c6bd380ccac2

commit cdd9629921c6551abac583aeafc5c6bd380ccac2
Author:     Konstantin Belousov <kib@FreeBSD.org>
AuthorDate: 2024-09-27 03:32:15 +0000
Commit:     Konstantin Belousov <kib@FreeBSD.org>
CommitDate: 2024-10-07 10:50:00 +0000

    sysctl.3: document missing oids from kern.proc. node
    
    Reviewed by:    olce
    Sponsored by:   The FreeBSD Foundation
    MFC after:      1 week
    Differential revision:  https://reviews.freebsd.org/D46823
---
 lib/libc/gen/sysctl.3 | 114 +++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 98 insertions(+), 16 deletions(-)

diff --git a/lib/libc/gen/sysctl.3 b/lib/libc/gen/sysctl.3
index 92e30cd6cdb4..bf526169a4ce 100644
--- a/lib/libc/gen/sysctl.3
+++ b/lib/libc/gen/sysctl.3
@@ -477,31 +477,113 @@ whose size depends on the current number of such objects in the system.
 .It Dv KERN_PROC_ALL Ta None
 .It Dv KERN_PROC_PID Ta A process ID
 .It Dv KERN_PROC_PGRP Ta A process group
+.It Dv KERN_PROC_SESSION Ta A session
 .It Dv KERN_PROC_TTY Ta A tty device
-.It Dv KERN_PROC_UID Ta A user ID
+.It Dv KERN_PROC_UID Ta An effective user ID
 .It Dv KERN_PROC_RUID Ta A real user ID
+.It Dv KERN_PROC_GID Ta An effective group ID
+.It Dv KERN_PROC_RGID Ta A real group ID
 .El
 .Pp
-If the third level name is
-.Dv KERN_PROC_ARGS
-then the command line argument
+For the following names, the miscellaneous information about the target
+process, which is specified by the fourth level of the oid name,
+is returned.
+A process ID of
+.Li \-1
+specifies the current process.
+.Bl -column "Third Level NameXXXXXX" "TypeXXXXXX" -offset indent
+.It Sy Third Level Name Ta Sy Fourth Level
+.It Dv KERN_PROC_ARGS Ta "Set of strings"
+.It Dv KERN_PROC_PATHNAME Ta "String"
+.It Dv KERN_PROC_KSTACK Ta "struct kinfo_stack []"
+.It Dv KERN_PROC_VMMAP Ta "struct kinfo_vmentry []"
+.It Dv KERN_PROC_FILEDESC Ta "struct kinfo_file []"
+.It Dv KERN_PROC_GROUPS Ta "gid_t []"
+.It Dv KERN_PROC_ENV Ta "Set of strings"
+.It Dv KERN_PROC_AUXV Ta "Elf_Auxinfo []"
+.It Dv KERN_PROC_RLIMIT Ta "Integer"
+.It Dv KERN_PROC_RLIMIT_USAGE Ta "rlim_t []"
+.It Dv KERN_PROC_PS_STRINGS Ta "Integer"
+.It Dv KERN_PROC_UMASK Ta "Integer/short"
+.It Dv KERN_PROC_OSREL Ta "Integer"
+.It Dv KERN_PROC_SIGTRAMP Ta "Integer"
+.It Dv KERN_PROC_CWD Ta "String"
+.It Dv KERN_PROC_NFDS Ta "Integer"
+.It Dv KERN_PROC_SIGFASTBLK Ta "Integer"
+.It Dv KERN_PROC_VM_LAYOUT Ta "struct kinfo_vm_layout"
+.El
+.Pp
+.Bl -tag -compact
+.It Dv KERN_PROC_ARGS
+The command line argument
 array is returned in a flattened form, i.e., zero-terminated arguments
 follow each other.
 The total size of array is returned.
 It is also possible for a process to set its own process title this way.
-If the third level name is
-.Dv KERN_PROC_PATHNAME ,
-the path of the
-process' text file is stored.
-For
-.Dv KERN_PROC_PATHNAME ,
-a process ID of
+.It Dv KERN_PROC_PATHNAME
+The path of the process' text file is returned.
+.It Dv KERN_PROC_KSTACK
+The in-kernel call stacks for the threads of the specified process.
+.It Dv KERN_PROC_VMMAP
+The description of the map entries for the process.
+.It Dv KERN_PROC_FILEDESC
+The file descriptors for files opened in the specified process.
+.It Dv KERN_PROC_GROUPS
+Groups associated with the process.
+.It Dv KERN_PROC_ENV
+The set of strings representing the environment of the specified process.
+.Pp
+Note that from the kernel point of view, environment exists only at the
+time of
+.Xr execve 2
+system call.
+This node method tries to reconstruct the environment from the known
+breadcrumbs left in the process address space, but it is not guaranteed
+to succeed or to represent the current value as maintained by the program.
+.It Dv KERN_PROC_AUXV
+The set of ELF auxv entries.
+See the note above about environment, which is also applicable to auxv.
+.It Dv KERN_PROC_RLIMIT
+Additinal OID name element must be supplied, specifiing the resource name
+as in
+.Xr getrlimit 2 .
+The call returns the given resource limit for the process.
+.It Dv KERN_PROC_RLIMIT_USAGE
+Like
+.Dv KERN_PROC_RLIMIT ,
+but instead of the limit, returns the accounted resource usage.
+For resources which do not have a meaningful current value,
 .Li \-1
-implies the current process.
-.Bl -column "Third Level NameXXXXXX" "Fourth LevelXXXXXX" -offset indent
-.It Sy Third Level Name Ta Sy Fourth Level
-.It Dv KERN_PROC_ARGS Ta "A process ID"
-.It Dv KERN_PROC_PATHNAME Ta "A process ID"
+is returned.
+.It Dv KERN_PROC_PS_STRINGS
+Returns the location of the
+.Vt ps_strings
+structure at the time of the last call to
+.Xr execve 2
+in the specified process.
+.It Dv KERN_PROC_UMASK
+The current umask value, see
+.Xr umask 2 .
+.It Dv KERN_PROC_OSREL
+The value of osrel for the process, that is the osrel the currently executed
+image was compiled for.
+Read from the note of the elf executable at
+.Xr execve 2
+time.
+Might be modified by the process.
+.It Dv KERN_PROC_SIGTRAMP
+Address of the signal trampoline in the process address space,
+where, simplifying, the kernel passes control for signal delivery.
+.It Dv KERN_PROC_CWD
+Returns the current working directory for the process.
+.It Dv KERN_PROC_NFDS
+Returns the total number of opened file descriptors for the process.
+.It Dv KERN_PROC_SIGFASTBLK
+Returns the address of the
+.Xr sigfastblock 2
+location, if active.
+.It Dv KERN_PROC_VM_LAYOUT
+Fills a structure describing process virtual address space layout.
 .El
 .It Li KERN_PS_STRINGS
 Reports the location of the process