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