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.3 (Berkeley) 05/26/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 owned by kvm and is not guaranteed to be persistent across 72subsequent kvm library calls. Data should be copied out if it needs to be 73saved. 74.Pp 75.Fn kvm_getargv 76returns a null-terminated argument vector that corresponds to the 77command line arguments passed to process indicated by 78.Fa p . 79Most likely, these arguments correspond to the values passed to 80.Xr exec 3 81on process creation. This information is, however, 82deliberately under control of the process itself. 83Note that the original command name can be found, unaltered, 84in the p_comm field of the process structure returned by 85.Fn kvm_getprocs . 86.Pp 87The 88.Fa nchr 89argument indicates the maximum number of characters, including null bytes, 90to use in building the strings. If this amount is exceeded, the string 91causing the overflow is truncated and the partial result is returned. 92This is handy for programs like 93.Xr ps 1 94and 95.Xr w 1 96that print only a one line summary of a command and should not copy 97out large amounts of text only to ignore it. 98If 99.Fa nchr 100is zero, no limit is imposed and all argument strings are returned in 101their entirety. 102.Pp 103The memory allocated to the argv pointers and string storage 104is owned by the kvm library. Since subsequent kvm calls may clobber 105this storage, data must be copied out if it needs to be saved. 106.Pp 107The 108.Fn kvm_getenvv 109function is similar to 110.Fn kvm_getargv 111but returns the vector of environment strings. This is data is 112also alterable by the process. 113.Sh RETURN VALUES 114.Fn kvm_getprocs , 115.Fn kvm_getargv , 116and 117.Fn kvm_getenvv , 118all return 119.Dv NULL 120on failure. 121.Pp 122.Sh BUGS 123These routines do not belong in the kvm interface. 124.Sh SEE ALSO 125.Xr kvm 3 , 126.Xr kvm_close 3 , 127.Xr kvm_geterr 3 , 128.Xr kvm_nlist 3 , 129.Xr kvm_open 3 , 130.Xr kvm_openfiles 3 , 131.Xr kvm_read 3 , 132.Xr kvm_write 3 133