[src/trunk]: src/lib/libkvm Document KVM_NO_FILES and kvm_get{proc, argv, envv}...

[simonb <simonb%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/4cb9a4704e49
branches:  trunk
changeset: 487837:4cb9a4704e49
user:      simonb <simonb%NetBSD.org@localhost>
date:      Tue Jun 13 15:48:56 2000 +0000

description:
Document KVM_NO_FILES and kvm_get{proc,argv,envv}2().  Better wording
kindly accepted!

XXX: Need to update distrib lists.  Tomorrow...

diffstat:

 lib/libkvm/Makefile       |   4 ++-
 lib/libkvm/kvm_getprocs.3 |  66 +++++++++++++++++++++++++++++++++++++++++++---
 lib/libkvm/kvm_open.3     |  31 +++++++++++++++++++--
 3 files changed, 91 insertions(+), 10 deletions(-)

diffs (177 lines):

diff -r d8d208c2b259 -r 4cb9a4704e49 lib/libkvm/Makefile
--- a/lib/libkvm/Makefile       Tue Jun 13 15:39:07 2000 +0000
+++ b/lib/libkvm/Makefile       Tue Jun 13 15:48:56 2000 +0000
@@ -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 @@
        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 -r d8d208c2b259 -r 4cb9a4704e49 lib/libkvm/kvm_getprocs.3
--- a/lib/libkvm/kvm_getprocs.3 Tue Jun 13 15:39:07 2000 +0000
+++ b/lib/libkvm/kvm_getprocs.3 Tue Jun 13 15:48:56 2000 +0000
@@ -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 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 @@
 .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 @@
 .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 ,
+.Fn kvm_getenvv ,
+.Fn kvm_getproc2 ,
+.Fn kvm_getargv2 ,
 and
-.Fn kvm_getenvv ,
+.Fn kvm_getenvv2
 all return
 .Dv NULL
 on failure.
diff -r d8d208c2b259 -r 4cb9a4704e49 lib/libkvm/kvm_open.3
--- a/lib/libkvm/kvm_open.3     Tue Jun 13 15:39:07 2000 +0000
+++ b/lib/libkvm/kvm_open.3     Tue Jun 13 15:48:56 2000 +0000
@@ -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 @@
 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.