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