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. 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 57The 58.Fn kvm_getprocs 59function returns a (sub-)set of active processes in the kernel indicated by 60.Fa kd . 61The 62.Fa op 63and 64.Fa arg 65arguments constitute a predicate which limits the set of processes 66returned. 67The value of 68.Fa op 69describes the filtering predicate as follows: 70.Pp 71.Bl -tag -width 20n -offset indent -compact 72.It Dv KERN_PROC_ALL 73all processes and kernel visible threads 74.It Dv KERN_PROC_PROC 75all processes, without threads 76.It Dv KERN_PROC_PID 77processes with process ID 78.Fa arg 79.It Dv KERN_PROC_PGRP 80processes with process group 81.Fa arg 82.It Dv KERN_PROC_SESSION 83processes with session 84.Fa arg 85.It Dv KERN_PROC_TTY 86processes with TTY 87.Fa arg 88.It Dv KERN_PROC_UID 89processes with effective user ID 90.Fa arg 91.It Dv KERN_PROC_RUID 92processes with real user ID 93.Fa arg 94.It Dv KERN_PROC_INC_THREAD 95modifier to return all kernel visible threads when filtering 96by process ID, process group, TTY, user ID, and real user ID 97.El 98.Pp 99The number of processes found is returned in the reference parameter 100.Fa cnt . 101The processes are returned as a contiguous array of kinfo_proc structures. 102This memory is locally allocated, and subsequent calls to 103.Fn kvm_getprocs 104and 105.Fn kvm_close 106will overwrite this storage. 107.Pp 108The 109.Fn kvm_getargv 110function returns a null-terminated argument vector that corresponds to the 111command line arguments passed to process indicated by 112.Fa p . 113Most likely, these arguments correspond to the values passed to 114.Xr exec 3 115on process creation. 116This information is, however, 117deliberately under control of the process itself. 118Note that the original command name can be found, unaltered, 119in the p_comm field of the process structure returned by 120.Fn kvm_getprocs . 121.Pp 122The 123.Fa nchr 124argument indicates the maximum number of characters, including null bytes, 125to use in building the strings. 126If this amount is exceeded, the string 127causing the overflow is truncated and the partial result is returned. 128This is handy for programs like 129.Xr ps 1 130and 131.Xr w 1 132that print only a one line summary of a command and should not copy 133out large amounts of text only to ignore it. 134If 135.Fa nchr 136is zero, no limit is imposed and all argument strings are returned in 137their entirety. 138.Pp 139The memory allocated to the argv pointers and string storage 140is owned by the kvm library. 141Subsequent 142.Fn kvm_getprocs 143and 144.Xr kvm_close 3 145calls will clobber this storage. 146.Pp 147The 148.Fn kvm_getenvv 149function is similar to 150.Fn kvm_getargv 151but returns the vector of environment strings. 152This data is 153also alterable by the process. 154.Sh RETURN VALUES 155The 156.Fn kvm_getprocs , 157.Fn kvm_getargv , 158and 159.Fn kvm_getenvv 160functions return 161.Dv NULL 162on 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 173These routines do not belong in the kvm interface. 174