lib/libkvm/kvm_getprocs.3

   1 .\"     $NetBSD: kvm_getprocs.3,v 1.14 2004/02/10 12:48:48 jmmv Exp $
   2 .\"
   3 .\" Copyright (c) 1992, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software developed by the Computer Systems
   7 .\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract
   8 .\" BG 91-66 and contributed to Berkeley.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)kvm_getprocs.3      8.1 (Berkeley) 6/4/93
  35 .\"
  36 .Dd February 10, 2004
  37 .Dt KVM_GETPROCS 3
  38 .Os
  39 .Sh NAME
  40 .Nm kvm_getprocs ,
  41 .Nm kvm_getargv ,
  42 .Nm kvm_getenvv
  43 .Nd access user process state
  44 .Sh LIBRARY
  45 .Lb libkvm
  46 .Sh SYNOPSIS
  47 .In kvm.h
  48 .In sys/param.h
  49 .In sys/sysctl.h
  50 .\" .Fa kvm_t *kd
  51 .Ft struct kinfo_proc *
  52 .Fn kvm_getprocs "kvm_t *kd" "int op" "int arg" "int *cnt"
  53 .Ft char **
  54 .Fn kvm_getargv "kvm_t *kd" "const struct kinfo_proc *p" "int nchr"
  55 .Ft char **
  56 .Fn kvm_getenvv "kvm_t *kd" "const struct kinfo_proc *p" "int nchr"
  57 .Ft struct kinfo_proc2 *
  58 .Fn kvm_getproc2 "kvm_t *kd" "int op" "int arg" "int elemsize" "int *cnt"
  59 .Ft char **
  60 .Fn kvm_getargv2 "kvm_t *kd" "const struct kinfo_proc2 *p" "int nchr"
  61 .Ft char **
  62 .Fn kvm_getenvv2 "kvm_t *kd" "const struct kinfo_proc2 *p" "int nchr"
  63 .Sh DESCRIPTION
  64 .Fn kvm_getprocs
  65 returns a (sub-)set of active processes in the kernel indicated by
  66 .Fa kd .
  67 The
  68 .Fa op
  69 and
  70 .Fa arg
  71 arguments constitute a predicate
  72 which limits the set of processes returned.
  73 The value of
  74 .Fa op
  75 describes the filtering predicate as follows:
  76 .Pp
  77 .Bl -tag -width 20n -offset indent -compact
  78 .It Sy KERN_PROC_ALL
  79 all processes
  80 .It Sy KERN_PROC_PID
  81 processes with process id
  82 .Fa arg
  83 .It Sy KERN_PROC_PGRP
  84 processes with process group
  85 .Fa arg
  86 .It Sy KERN_PROC_SESSION
  87 processes with session id
  88 .Fa arg
  89 .It Sy KERN_PROC_TTY
  90 processes with tty device
  91 .Fa arg
  92 .It Sy KERN_PROC_UID
  93 processes with effective user id
  94 .Fa arg
  95 .It Sy KERN_PROC_RUID
  96 processes with real user id
  97 .Fa arg
  98 .It Sy KERN_PROC_GID
  99 processes with effective group id
 100 .Fa arg
 101 .It Sy KERN_PROC_RGID
 102 processes with real group id
 103 .Fa arg
 104 .El
 105 .Pp
 106 The number of processes found is returned in the reference parameter
 107 .Fa cnt .
 108 The processes are returned as a contiguous array of
 109 .Sy kinfo_proc
 110 structures.
 111 This memory is locally allocated, and subsequent calls to
 112 .Fn kvm_getprocs
 113 and
 114 .Fn kvm_close
 115 will overwrite this storage.
 116 .Pp
 117 If the
 118 .Fa op
 119 argument for
 120 .Fn kvm_getprocs
 121 is
 122 .Sy KERN_PROC_TTY ,
 123 .Fa arg
 124 can also be
 125 .Sy KERN_PROC_TTY_NODEV
 126 to select processes with no controlling tty and
 127 .Sy KERN_PROC_TTY_REVOKE
 128 to select processes which have had their controlling tty
 129 revoked.
 130 .Pp
 131 .Fn kvm_getargv
 132 returns a null-terminated argument vector that corresponds to the
 133 command line arguments passed to process indicated by
 134 .Fa p .
 135 Most likely, these arguments correspond to the values passed to
 136 .Xr exec 3
 137 on process creation.
 138 This information is, however,
 139 deliberately under control of the process itself.
 140 Note that the original command name can be found, unaltered,
 141 in the p_comm field of the process structure returned by
 142 .Fn kvm_getprocs .
 143 .Pp
 144 The
 145 .Fa nchr
 146 argument indicates the maximum number of characters, including null bytes,
 147 to use in building the strings.
 148 If this amount is exceeded, the string
 149 causing the overflow is truncated and the partial result is returned.
 150 This is handy for programs like
 151 .Xr ps 1
 152 and
 153 .Xr w 1
 154 that print only a one line summary of a command and should not copy
 155 out large amounts of text only to ignore it.
 156 If
 157 .Fa nchr
 158 is zero, no limit is imposed and all argument strings are returned in
 159 their entirety.
 160 .Pp
 161 The memory allocated to the argv pointers and string storage
 162 is owned by the kvm library.
 163 Subsequent
 164 .Fn kvm_getprocs
 165 and
 166 .Xr kvm_close 3
 167 calls will clobber this storage.
 168 .Pp
 169 The
 170 .Fn kvm_getenvv
 171 function is similar to
 172 .Fn kvm_getargv
 173 but returns the vector of environment strings.
 174 This data is also alterable by the process.
 175 .Pp
 176 .Fn kvm_getproc2
 177 is similar to
 178 .Fn kvm_getprocs
 179 but returns an array of
 180 .Sy kinfo_proc2
 181 structures.
 182 Additionally, only the first
 183 .Fa elemsize
 184 bytes of each array entry are returned.
 185 If the size of the
 186 .Sy kinfo_proc2
 187 structure increases in size in a future release of
 188 .Nx
 189 the kernel will only return the requested amount of data for
 190 each array entry and programs that use
 191 .Fn kvm_getproc2
 192 will continue to function without the need for recompilation.
 193 .Pp
 194 The
 195 .Fn kvm_getargv2
 196 and
 197 .Fn kvm_getenvv2
 198 are equivalents to the
 199 .Fn kvm_getargv
 200 and
 201 .Fn kvm_getenvv
 202 functions but use a
 203 .Sy kinfo_proc2
 204 structure to specify the process.
 205 .Pp
 206 If called against an active kernel, the
 207 .Fn kvm_getproc2 ,
 208 .Fn kvm_getargv2 ,
 209 and
 210 .Fn kvm_getenvv2
 211 functions will use the
 212 .Xr sysctl 3
 213 interface and do not require access to the kernel memory device
 214 file or swap device.
 215 .Sh RETURN VALUES
 216 .Fn kvm_getprocs ,
 217 .Fn kvm_getargv ,
 218 .Fn kvm_getenvv ,
 219 .Fn kvm_getproc2 ,
 220 .Fn kvm_getargv2 ,
 221 and
 222 .Fn kvm_getenvv2
 223 all return
 224 .Dv NULL
 225 on failure.
 226 .Sh SEE ALSO
 227 .Xr kvm 3 ,
 228 .Xr kvm_close 3 ,
 229 .Xr kvm_geterr 3 ,
 230 .Xr kvm_nlist 3 ,
 231 .Xr kvm_open 3 ,
 232 .Xr kvm_openfiles 3 ,
 233 .Xr kvm_read 3 ,
 234 .Xr kvm_write 3
 235 .Sh BUGS
 236 These routines do not belong in the kvm interface.