From ec323af47892048489d6a4812e57aa51c036d7e7 Mon Sep 17 00:00:00 2001
From: simonb <simonb@NetBSD.org>
Date: Tue, 13 Jun 2000 15:48:56 +0000
Subject: [PATCH] Document KVM_NO_FILES and kvm_get{proc,argv,envv}2().  Better
 wording kindly accepted!

XXX: Need to update distrib lists.  Tomorrow...
---
 lib/libkvm/Makefile       |  4 ++-
 lib/libkvm/kvm_getprocs.3 | 66 ++++++++++++++++++++++++++++++++++++---
 lib/libkvm/kvm_open.3     | 31 +++++++++++++++---
 3 files changed, 91 insertions(+), 10 deletions(-)

diff --git a/lib/libkvm/Makefile b/lib/libkvm/Makefile
index 800f926a4102..40c685284d94 100644
--- a/lib/libkvm/Makefile
+++ b/lib/libkvm/Makefile
@@ -1,4 +1,4 @@
-#	$NetBSD: Makefile,v 1.31 2000/05/09 21:55:53 bjh21 Exp $
+#	$NetBSD: Makefile,v 1.32 2000/06/13 15:48:56 simonb Exp $
 #	from: @(#)Makefile	8.1 (Berkeley) 6/4/93
 
 LIB=	kvm
@@ -28,6 +28,8 @@ MAN=	kvm.3 kvm_dump.3 kvm_geterr.3 kvm_getfiles.3 kvm_getloadavg.3 \
 	kvm_getprocs.3 kvm_nlist.3 kvm_open.3 kvm_read.3
 
 MLINKS+=kvm_getprocs.3 kvm_getargv.3 kvm_getprocs.3 kvm_getenvv.3
+MLINKS+=kvm_getprocs.3 kvm_getproc2.3
+MLINKS+=kvm_getprocs.3 kvm_getargv2.3 kvm_getprocs.3 kvm_getenvv2.3
 MLINKS+=kvm_open.3 kvm_openfiles.3 kvm_open.3 kvm_close.3
 MLINKS+=kvm_read.3 kvm_write.3
 MLINKS+=kvm_dump.3 kvm_dump_mkheader.3 kvm_dump.3 kvm_dump_wrtheader.3
diff --git a/lib/libkvm/kvm_getprocs.3 b/lib/libkvm/kvm_getprocs.3
index 154d840051b4..dce89c861380 100644
--- a/lib/libkvm/kvm_getprocs.3
+++ b/lib/libkvm/kvm_getprocs.3
@@ -1,4 +1,4 @@
-.\"	$NetBSD: kvm_getprocs.3,v 1.6 2000/04/15 04:38:47 simonb Exp $
+.\"	$NetBSD: kvm_getprocs.3,v 1.7 2000/06/13 15:48:57 simonb Exp $
 .\"
 .\" Copyright (c) 1992, 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -58,6 +58,12 @@
 .Fn kvm_getargv "kvm_t *kd" "const struct kinfo_proc *p" "int nchr"
 .Ft char **
 .Fn kvm_getenvv "kvm_t *kd" "const struct kinfo_proc *p" "int nchr"
+.Ft struct kinfo_proc2 *
+.Fn kvm_getproc2 "kvm_t *kd" "int op" "int arg" "int elemsize" "int *cnt"
+.Ft char **
+.Fn kvm_getargv2 "kvm_t *kd" "const struct kinfo_proc2 *p" "int nchr"
+.Ft char **
+.Fn kvm_getenvv2 "kvm_t *kd" "const struct kinfo_proc2 *p" "int nchr"
 .Sh DESCRIPTION
 .Fn kvm_getprocs
 returns a (sub-)set of active processes in the kernel indicated by
@@ -81,10 +87,10 @@ processes with process id
 processes with process group
 .Fa arg
 .It Sy KERN_PROC_SESSION
-processes with session
+processes with sessiod id
 .Fa arg
 .It Sy KERN_PROC_TTY
-processes with tty
+processes with tty device
 .Fa arg
 .It Sy KERN_PROC_UID
 processes with effective user id
@@ -92,11 +98,19 @@ processes with effective user id
 .It Sy KERN_PROC_RUID
 processes with real user id
 .Fa arg
+.It Sy KERN_PROC_GID
+processes with effective group id
+.Fa arg
+.It Sy KERN_PROC_RGID
+processes with real group id
+.Fa arg
 .El
 .Pp
 The number of processes found is returned in the reference parameter
 .Fa cnt .
-The processes are returned as a contiguous array of kinfo_proc structures.
+The processes are returned as a contiguous array of
+.Sy kinfo_proc
+structures.
 This memory is locally allocated, and subsequent calls to
 .Fn kvm_getprocs
 and
@@ -158,11 +172,53 @@ function is similar to
 .Fn kvm_getargv
 but returns the vector of environment strings.  This data is
 also alterable by the process.
+.Pp
+.Fn kvm_getproc2
+is similar to
+.Fn kvm_getprocs
+but returns an array of
+.Sy kinfo_proc2
+structures.  Additionally, only the first
+.Fa elemsize
+bytes of each array entry are returned.
+If the size of the
+.Sy kinfo_proc2
+structure increases in size in a future release of
+.Nx
+the kernel will only return the requested amount of data for
+each array entry and programs that use
+.Fn kvm_getproc2
+will continue to function without the need for recompilation.
+.Pp
+The
+.Fn kvm_getargv2
+and
+.Fn kvm_getenvv2
+are equivalents to the
+.Fn kvm_getargv
+and
+.Fn kvm_getenvv
+functions but use a
+.Sy kinfo_proc2
+structure to specify the process.
+.Pp
+If called against an active kernel, the
+.Fn kvm_getproc2 ,
+.Fn kvm_getargv2 ,
+and
+.Fn kvm_getenvv2  
+functions will use the
+.Xr sysctl 3
+interface and do not require access to the kernel memory device
+file or swap device.
 .Sh RETURN VALUES
 .Fn kvm_getprocs ,
 .Fn kvm_getargv ,
-and
 .Fn kvm_getenvv ,
+.Fn kvm_getproc2 ,
+.Fn kvm_getargv2 ,
+and
+.Fn kvm_getenvv2
 all return
 .Dv NULL
 on failure.
diff --git a/lib/libkvm/kvm_open.3 b/lib/libkvm/kvm_open.3
index 7d64182fc417..ff6eb3586d6d 100644
--- a/lib/libkvm/kvm_open.3
+++ b/lib/libkvm/kvm_open.3
@@ -1,4 +1,4 @@
-.\"	$NetBSD: kvm_open.3,v 1.6 1999/07/02 15:28:50 simonb Exp $
+.\"	$NetBSD: kvm_open.3,v 1.7 2000/06/13 15:48:57 simonb Exp $
 .\"
 .\" Copyright (c) 1992, 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -107,12 +107,35 @@ The
 argument indicates read/write access as in
 .Xr open 2
 and applies only to the core file.
-Only
+The only permitted flags from
+.Xr open 2
+are
 .Dv O_RDONLY ,
 .Dv O_WRONLY ,
 and
-.Dv O_RDWR
-are permitted.
+.Dv O_RDWR .
+.Pp
+As a special case, a
+.Fa flags
+argument of
+.Dv KVM_NO_FILES
+will initialse the
+.Xr kvm 3
+library for use on active kernels only using
+.Xr sysctl 3
+for retrieving kernel data and ignores the
+.Fa execfile ,
+.Fa corefile
+and
+.Fa swapfile
+arguments.  Only a small subset of the
+.Xr kvm 3
+library functions are available using this method.  These
+are currently
+.Xr kvm_getproc2 3 ,
+.Xr kvm_getargv2 3
+and
+.Xr kvm_getenvv2 3 .
 .Pp
 There are two open routines which differ only with respect to
 the error mechanism.