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