1.\" Copyright (c) 1992 The Regents of the University of California. 2.\" 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.\" %sccs.include.redist.man% 9.\" 10.\" @(#)kvm_getprocs.3 5.5 (Berkeley) 07/22/92 11.\" 12.Dd 13.Dt KVM_GETPROCS 3 14.Os 15.Sh NAME 16.Nm kvm_getprocs , 17.Nm kvm_getargv , 18.Nm kvm_getenvv 19.Nd access user process state 20.Sh SYNOPSIS 21.Fd #include <kvm.h> 22.Fd #include <sys/kinfo.h> 23.Fd #include <sys/kinfo_proc.h> 24.\" .Fa kvm_t *kd 25.br 26.Ft struct kinfo_proc * 27.Fn kvm_getprocs "kvm_t *kd" "int op" "int arg" "int *cnt" 28.Ft char ** 29.Fn kvm_getargv "kvm_t *kd" "const struct kinfo_proc *p" "int nchr" 30.Ft char ** 31.Fn kvm_getenvv "kvm_t *kd" "const struct kinfo_proc *p" "int nchr" 32.Sh DESCRIPTION 33.Fn kvm_getprocs 34returns a (sub-)set of active processes in the kernel indicated by 35.Fa kd. 36The 37.Fa op 38and 39.Fa arg 40arguments constitute a predicate which limits the set of processes 41returned. The value of 42.Fa op 43describes the filtering predicate as follows: 44.Pp 45.Bl -tag -width 20n -offset indent -compact 46.It Sy KINFO_PROC_ALL 47all processes 48.It Sy KINFO_PROC_PID 49processes with process id 50.Fa arg 51.It Sy KINFO_PROC_PGRP 52processes with process group 53.Fa arg 54.It Sy KINFO_PROC_SESSION 55processes with session 56.Fa arg 57.It Sy KINFO_PROC_TTY 58processes with tty 59.Fa arg 60.It Sy KINFO_PROC_UID 61processes with effective user id 62.Fa arg 63.It Sy KINFO_PROC_RUID 64processes with real user id 65.Fa arg 66.El 67.Pp 68The number of processes found is returned in the reference parameter 69.Fa cnt . 70The processes are returned as a contiguous array of kinfo_proc structures. 71This memory is locally allocated, and subsequent calls to 72.Fn kvm_getprocs 73and 74.Fn kvm_close 75will overwrite this storage. 76.Pp 77.Fn kvm_getargv 78returns a null-terminated argument vector that corresponds to the 79command line arguments passed to process indicated by 80.Fa p . 81Most likely, these arguments correspond to the values passed to 82.Xr exec 3 83on process creation. This information is, however, 84deliberately under control of the process itself. 85Note that the original command name can be found, unaltered, 86in the p_comm field of the process structure returned by 87.Fn kvm_getprocs . 88.Pp 89The 90.Fa nchr 91argument indicates the maximum number of characters, including null bytes, 92to use in building the strings. If this amount is exceeded, the string 93causing the overflow is truncated and the partial result is returned. 94This is handy for programs like 95.Xr ps 1 96and 97.Xr w 1 98that print only a one line summary of a command and should not copy 99out large amounts of text only to ignore it. 100If 101.Fa nchr 102is zero, no limit is imposed and all argument strings are returned in 103their entirety. 104.Pp 105The memory allocated to the argv pointers and string storage 106is owned by the kvm library. Subsequent 107.Fn kvm_getprocs 108and 109.Xr kvm_close 3 110calls will clobber this storage. 111.Pp 112The 113.Fn kvm_getenvv 114function is similar to 115.Fn kvm_getargv 116but returns the vector of environment strings. This data is 117also alterable by the process. 118.Sh RETURN VALUES 119.Fn kvm_getprocs , 120.Fn kvm_getargv , 121and 122.Fn kvm_getenvv , 123all return 124.Dv NULL 125on failure. 126.Pp 127.Sh BUGS 128These routines do not belong in the kvm interface. 129.Sh SEE ALSO 130.Xr kvm 3 , 131.Xr kvm_close 3 , 132.Xr kvm_geterr 3 , 133.Xr kvm_nlist 3 , 134.Xr kvm_open 3 , 135.Xr kvm_openfiles 3 , 136.Xr kvm_read 3 , 137.Xr kvm_write 3 138