lib/libkvm/kvm_getprocs.3

   1 .\"     $NetBSD: kvm_getprocs.3,v 1.13 2003/08/07 16:44:37 agc 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 .br
  52 .Ft struct kinfo_proc *
  53 .Fn kvm_getprocs "kvm_t *kd" "int op" "int arg" "int *cnt"
  54 .Ft char **
  55 .Fn kvm_getargv "kvm_t *kd" "const struct kinfo_proc *p" "int nchr"
  56 .Ft char **
  57 .Fn kvm_getenvv "kvm_t *kd" "const struct kinfo_proc *p" "int nchr"
  58 .Ft struct kinfo_proc2 *
  59 .Fn kvm_getproc2 "kvm_t *kd" "int op" "int arg" "int elemsize" "int *cnt"
  60 .Ft char **
  61 .Fn kvm_getargv2 "kvm_t *kd" "const struct kinfo_proc2 *p" "int nchr"
  62 .Ft char **
  63 .Fn kvm_getenvv2 "kvm_t *kd" "const struct kinfo_proc2 *p" "int nchr"
  64 .Sh DESCRIPTION
  65 .Fn kvm_getprocs
  66 returns a (sub-)set of active processes in the kernel indicated by
  67 .Fa kd .
  68 The
  69 .Fa op
  70 and
  71 .Fa arg
  72 arguments constitute a predicate
  73 which limits the set of processes returned.
  74 The value of
  75 .Fa op
  76 describes the filtering predicate as follows:
  77 .Pp
  78 .Bl -tag -width 20n -offset indent -compact
  79 .It Sy KERN_PROC_ALL
  80 all processes
  81 .It Sy KERN_PROC_PID
  82 processes with process id
  83 .Fa arg
  84 .It Sy KERN_PROC_PGRP
  85 processes with process group
  86 .Fa arg
  87 .It Sy KERN_PROC_SESSION
  88 processes with session id
  89 .Fa arg
  90 .It Sy KERN_PROC_TTY
  91 processes with tty device
  92 .Fa arg
  93 .It Sy KERN_PROC_UID
  94 processes with effective user id
  95 .Fa arg
  96 .It Sy KERN_PROC_RUID
  97 processes with real user id
  98 .Fa arg
  99 .It Sy KERN_PROC_GID
 100 processes with effective group id
 101 .Fa arg
 102 .It Sy KERN_PROC_RGID
 103 processes with real group id
 104 .Fa arg
 105 .El
 106 .Pp
 107 The number of processes found is returned in the reference parameter
 108 .Fa cnt .
 109 The processes are returned as a contiguous array of
 110 .Sy kinfo_proc
 111 structures.
 112 This memory is locally allocated, and subsequent calls to
 113 .Fn kvm_getprocs
 114 and
 115 .Fn kvm_close
 116 will overwrite this storage.
 117 .Pp
 118 If the
 119 .Fa op
 120 argument for
 121 .Fn kvm_getprocs
 122 is
 123 .Sy KERN_PROC_TTY ,
 124 .Fa arg
 125 can also be
 126 .Sy KERN_PROC_TTY_NODEV
 127 to select processes with no controlling tty and
 128 .Sy KERN_PROC_TTY_REVOKE
 129 to select processes which have had their controlling tty
 130 revoked.
 131 .Pp
 132 .Fn kvm_getargv
 133 returns a null-terminated argument vector that corresponds to the
 134 command line arguments passed to process indicated by
 135 .Fa p .
 136 Most likely, these arguments correspond to the values passed to
 137 .Xr exec 3
 138 on process creation.
 139 This information is, however,
 140 deliberately under control of the process itself.
 141 Note that the original command name can be found, unaltered,
 142 in the p_comm field of the process structure returned by
 143 .Fn kvm_getprocs .
 144 .Pp
 145 The
 146 .Fa nchr
 147 argument indicates the maximum number of characters, including null bytes,
 148 to use in building the strings.
 149 If this amount is exceeded, the string
 150 causing the overflow is truncated and the partial result is returned.
 151 This is handy for programs like
 152 .Xr ps 1
 153 and
 154 .Xr w 1
 155 that print only a one line summary of a command and should not copy
 156 out large amounts of text only to ignore it.
 157 If
 158 .Fa nchr
 159 is zero, no limit is imposed and all argument strings are returned in
 160 their entirety.
 161 .Pp
 162 The memory allocated to the argv pointers and string storage
 163 is owned by the kvm library.
 164 Subsequent
 165 .Fn kvm_getprocs
 166 and
 167 .Xr kvm_close 3
 168 calls will clobber this storage.
 169 .Pp
 170 The
 171 .Fn kvm_getenvv
 172 function is similar to
 173 .Fn kvm_getargv
 174 but returns the vector of environment strings.
 175 This data is also alterable by the process.
 176 .Pp
 177 .Fn kvm_getproc2
 178 is similar to
 179 .Fn kvm_getprocs
 180 but returns an array of
 181 .Sy kinfo_proc2
 182 structures.
 183 Additionally, only the first
 184 .Fa elemsize
 185 bytes of each array entry are returned.
 186 If the size of the
 187 .Sy kinfo_proc2
 188 structure increases in size in a future release of
 189 .Nx
 190 the kernel will only return the requested amount of data for
 191 each array entry and programs that use
 192 .Fn kvm_getproc2
 193 will continue to function without the need for recompilation.
 194 .Pp
 195 The
 196 .Fn kvm_getargv2
 197 and
 198 .Fn kvm_getenvv2
 199 are equivalents to the
 200 .Fn kvm_getargv
 201 and
 202 .Fn kvm_getenvv
 203 functions but use a
 204 .Sy kinfo_proc2
 205 structure to specify the process.
 206 .Pp
 207 If called against an active kernel, the
 208 .Fn kvm_getproc2 ,
 209 .Fn kvm_getargv2 ,
 210 and
 211 .Fn kvm_getenvv2
 212 functions will use the
 213 .Xr sysctl 3
 214 interface and do not require access to the kernel memory device
 215 file or swap device.
 216 .Sh RETURN VALUES
 217 .Fn kvm_getprocs ,
 218 .Fn kvm_getargv ,
 219 .Fn kvm_getenvv ,
 220 .Fn kvm_getproc2 ,
 221 .Fn kvm_getargv2 ,
 222 and
 223 .Fn kvm_getenvv2
 224 all return
 225 .Dv NULL
 226 on failure.
 227 .Sh SEE ALSO
 228 .Xr kvm 3 ,
 229 .Xr kvm_close 3 ,
 230 .Xr kvm_geterr 3 ,
 231 .Xr kvm_nlist 3 ,
 232 .Xr kvm_open 3 ,
 233 .Xr kvm_openfiles 3 ,
 234 .Xr kvm_read 3 ,
 235 .Xr kvm_write 3
 236 .Sh BUGS
 237 These routines do not belong in the kvm interface.