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.\" 38.Dd June 4, 1993 39.Dt KVM_GETPROCS 3 40.Os 41.Sh NAME 42.Nm kvm_getprocs , 43.Nm kvm_getargv , 44.Nm kvm_getenvv 45.Nd access user process state 46.Sh SYNOPSIS 47.Fd #include <kvm.h> 48.Fd #include <sys/kinfo.h> 49.Fd #include <sys/kinfo_proc.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.Sh DESCRIPTION 59.Fn kvm_getprocs 60returns a (sub-)set of active processes in the kernel indicated by 61.Fa kd. 62The 63.Fa op 64and 65.Fa arg 66arguments constitute a predicate which limits the set of processes 67returned. The value of 68.Fa op 69describes the filtering predicate as follows: 70.Pp 71.Bl -tag -width 20n -offset indent -compact 72.It Sy KINFO_PROC_ALL 73all processes 74.It Sy KINFO_PROC_PID 75processes with process id 76.Fa arg 77.It Sy KINFO_PROC_PGRP 78processes with process group 79.Fa arg 80.It Sy KINFO_PROC_SESSION 81processes with session 82.Fa arg 83.It Sy KINFO_PROC_TTY 84processes with tty 85.Fa arg 86.It Sy KINFO_PROC_UID 87processes with effective user id 88.Fa arg 89.It Sy KINFO_PROC_RUID 90processes with real user id 91.Fa arg 92.El 93.Pp 94The number of processes found is returned in the reference parameter 95.Fa cnt . 96The processes are returned as a contiguous array of kinfo_proc structures. 97This memory is locally allocated, and subsequent calls to 98.Fn kvm_getprocs 99and 100.Fn kvm_close 101will overwrite this storage. 102.Pp 103.Fn kvm_getargv 104returns a null-terminated argument vector that corresponds to the 105command line arguments passed to process indicated by 106.Fa p . 107Most likely, these arguments correspond to the values passed to 108.Xr exec 3 109on process creation. This information is, however, 110deliberately under control of the process itself. 111Note that the original command name can be found, unaltered, 112in the p_comm field of the process structure returned by 113.Fn kvm_getprocs . 114.Pp 115The 116.Fa nchr 117argument indicates the maximum number of characters, including null bytes, 118to use in building the strings. If this amount is exceeded, the string 119causing the overflow is truncated and the partial result is returned. 120This is handy for programs like 121.Xr ps 1 122and 123.Xr w 1 124that print only a one line summary of a command and should not copy 125out large amounts of text only to ignore it. 126If 127.Fa nchr 128is zero, no limit is imposed and all argument strings are returned in 129their entirety. 130.Pp 131The memory allocated to the argv pointers and string storage 132is owned by the kvm library. Subsequent 133.Fn kvm_getprocs 134and 135.Xr kvm_close 3 136calls will clobber this storage. 137.Pp 138The 139.Fn kvm_getenvv 140function is similar to 141.Fn kvm_getargv 142but returns the vector of environment strings. This data is 143also alterable by the process. 144.Sh RETURN VALUES 145.Fn kvm_getprocs , 146.Fn kvm_getargv , 147and 148.Fn kvm_getenvv , 149all return 150.Dv NULL 151on failure. 152.Pp 153.Sh BUGS 154These routines do not belong in the kvm interface. 155.Sh SEE ALSO 156.Xr kvm 3 , 157.Xr kvm_close 3 , 158.Xr kvm_geterr 3 , 159.Xr kvm_nlist 3 , 160.Xr kvm_open 3 , 161.Xr kvm_openfiles 3 , 162.Xr kvm_read 3 , 163.Xr kvm_write 3 164