lib/libkvm/kvm_getprocs.3

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